# 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、门店数据范围。
- 必跑验证命令和手工验收路径。

## 推荐验证

后端：

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

前端：

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

文档：

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

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

```bash
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 漂移。