90 lines
3.9 KiB
Markdown
90 lines
3.9 KiB
Markdown
# 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 漂移。
|