petstore-docs/.agents/rules/api-contract-boundary.md

API / 数据 / 隐私边界规则

本规则适用于任一任务触碰后端 controller/service/entity/repository、frontend/src/api、报告 token、媒体 URL、手机号、门店数据范围或发布配置。

本体对齐：本规则的边界约束与 docs/ontology/rules.md 的规则条目对齐：

• 公开报告字段裁剪 → rule:BR-RPT-006
• 公开门店字段裁剪 → rule:BR-STORE-003
• 跨店/跨用户 403 → rule:BR-APPT-002/rule:BR-APPT-003/rule:BR-RPT-005/rule:BR-LEAD-003/rule:BR-SCH-001/rule:BR-ST-001/rule:BR-PET-001
• session token 鉴权 → rule:BR-AUTH-001
• token hash 日志 → rule:BR-RPT-007
• 留资脱敏 → rule:BR-LEAD-002 改动这些规则时同步更新 docs/ontology/rules.md + graph/ontology.jsonl。

归属边界

领域	Owner Agent	典型路径
预约、日程、门店、用户、宠物、服务类型	Backend Core	Appointment*、Schedule*、Store*、User*、Pet*、ServiceType*
报告、媒体、成片、留资、评价	Report Media Backend	Report*、FileController、ReportHighlightVideoService
门店端页面调用	Store Miniapp FE	frontend/src/pages/home、appointment、report、mine
宠主公开体验调用	Customer Experience FE	frontend/src/pages/report-view、video-player、宠主预约页、公开分享 utils
表结构、索引、状态字段、幂等	Data Model	JPA entity、repository query、数据说明文档

Controller / Service 规则

• Controller 只做入口、参数校验、登录/上下文读取和响应映射。
• Service 承载领域规则：状态机、数据范围、幂等、权限判断、异步任务状态。
• 不要在 Controller 中直接拼复杂业务状态或绕过 Service 改库。
• 任何状态更新都必须校验前置状态；预约状态不得直接无条件赋值。
• 公开报告接口必须只返回公开页需要的字段，不得透出调试字段、内部权限字段或不必要手机号。

Frontend API 规则

• 新增或修改 API 时，优先在 frontend/src/api/index.js 或对应业务 utils 中统一封装。
• 页面不直接散落硬编码 URL、token 拼接或错误码判断。
• 前端错误态必须有用户可理解文案；不能展示后端堆栈、SQL、Java exception 或未翻译错误。
• H5 与小程序若共享报告语义，字段名、三态文案和重试行为必须一致。

Data / Privacy 规则

• report_token 是敏感公开链接，不在日志、报告、截图中展示完整值。
• 手机号、宠主留资、门店数据范围和媒体 URL 必须有最小化返回原则。
• 软删除字段、store_id 数据范围和状态字段变更必须通过 Data Model review。
• 成片任务需要记录任务状态、失败原因和用户可读映射；不能只依赖日志排查。

变更清单

接口或数据变更的任务 brief 必须写清：

• 受影响 endpoint / 前端调用点。
• 请求参数和响应字段变化。
• 错误码或业务码变化。
• 数据表 / entity / repository query 变化。
• 是否影响公开访问、report token、手机号、媒体 URL、门店数据范围。
• 必跑验证命令和手工验收路径。

推荐验证

后端：

cd /Users/apple/_src/petstore/backend
mvn test

前端：

cd /Users/apple/_src/petstore/frontend
npm run build:h5
npm run build:mp-weixin

文档：

git -C /Users/apple/_src/petstore/docs diff --check
rg -n "report_token|手机号|状态机|预约|成片" /Users/apple/_src/petstore/docs

本体（改了 controller/service/entity 后必跑）：

cd /Users/apple/_src/petstore
python3 docs/graph/validate_ontology.py docs   # 引用完整性
python3 docs/graph/audit_drift.py              # 本体—代码漂移审计

期望：validate_ontology 通过 + audit_drift 无 code-only / ontology-only 漂移。