138 lines
7.1 KiB
Markdown
138 lines
7.1 KiB
Markdown
# 本体覆盖度审计（Ontology Coverage Audit）
|
||
|
||
> 本体条目 ↔ 文档章节 ↔ 代码路径 ↔ 测试用例 三方对齐审计。
|
||
> 证据强度：`anchored`（三处对齐）/ `documented`（仅文档）/ `implemented`（仅代码）/ `gap`（缺失）。
|
||
>
|
||
> **刷新时间**：2026-08-01（BusinessEvent 落库、工作台事件漏斗、StoreCustomer 主档与身份语义收口后刷新）
|
||
|
||
## 审计方法
|
||
|
||
对 `graph/ontology.jsonl` 的每个条目，核对：
|
||
1. **文档**：`doc` 字段指向的 docs 路径是否存在且描述一致
|
||
2. **代码**：`code` 字段指向的源码路径是否存在且实现一致
|
||
3. **测试**：`test` 字段指向的测试用例是否存在且覆盖该条目
|
||
|
||
任一缺失则降级证据强度。
|
||
|
||
## 当前规模（以 validate 为准）
|
||
|
||
| 类型 | 数量 |
|
||
|------|------|
|
||
| Entity | 25 |
|
||
| Action | 64 |
|
||
| Event | 26 |
|
||
| Rule | 40 |
|
||
| Relation | 81 |
|
||
| **合计** | **236** |
|
||
|
||
证据强度：`anchored` 185（78.4%）/ `documented` 37 / `gap` 12 / `implemented` 2。
|
||
|
||
> anchored 占比相对 Batch 2 下降，是因为主动录入了 P1/P2 `gap` 占位与客户端埋点 `documented` 条目；端点漂移仍为 0。
|
||
|
||
校验：
|
||
|
||
```bash
|
||
python3 docs/graph/validate_ontology.py docs
|
||
python3 docs/graph/audit_drift.py
|
||
```
|
||
|
||
当前结果：校验通过；HTTP 端点 55/55、JPA Entity 13/13 对齐；非 JPA 领域实体 12 个。
|
||
|
||
## 元数据卫生
|
||
|
||
| 项 | 状态 |
|
||
|----|------|
|
||
| Action / Relation `domain` | ✅ 已回填（0 缺失） |
|
||
| gap 入口 `deprecated` | ✅ `register_store`、`wechat_authorize`、`wechat_callback` |
|
||
| 寄语事件独立化 | ✅ `event:testimonial_saved`（不再误挂 `report_submitted`） |
|
||
| `video_*` emittedBy | ✅ 挂到 `action:track_video_play` / `track_video_save` |
|
||
|
||
## 核心实体覆盖
|
||
|
||
| 实体 | 文档 | 代码 | 测试 | 证据 | 备注 |
|
||
|------|------|------|------|------|------|
|
||
| store | ✅ | ✅ | StoreControllerTest | anchored | BR-STORE-003 公开字段裁剪已落地 |
|
||
| user | ✅ | ✅ | UserServiceLoginStrategyTest + UserJsonIgnoreTest | anchored | password/openid/unionid 均 @JsonIgnore |
|
||
| appointment | ✅ | ✅ | AppointmentServiceTest / DetailTest | anchored | |
|
||
| report | ✅ | ✅ | ReportServiceTest / ControllerTest | anchored | uk 上线需清重 |
|
||
| report_lead | ✅ | ✅ | ReportLeadControllerTest | anchored | |
|
||
| pet | ✅ | ✅ | PetControllerTest | anchored | |
|
||
| service_type | ✅ | ✅ | ServiceTypeControllerTest | anchored | |
|
||
| schedule_block | ✅ | ✅ | ScheduleControllerTest | anchored | |
|
||
| report_image | ✅ | ✅ | 间接 ReportServiceTest | anchored | 建议补独立类型用例 |
|
||
| highlight_video | ✅ | ✅ | ReportHighlightVideoServiceTest | anchored | 状态机/归类单测；真 FFmpeg E2E 仍可选 |
|
||
| session_token | ✅ | ✅ | SessionTokenServiceTest | anchored | jpa:false |
|
||
| report_testimonial | ✅ | ✅ | ReportTestimonialServiceTest | anchored | |
|
||
| service_interval | ✅ | ✅ | 间接 ReportLeadControllerTest | anchored | |
|
||
| store_customer | ✅ | ✅ | StoreCustomerServiceTest / IdentityOwnershipQueryTest | anchored | 稳定门店客户关系 |
|
||
| business_event | ✅ | ✅ | BusinessEventServiceTest / MigrationTest | anchored | 不可变低敏事件；工作台去重统计 |
|
||
| highlight_fail_reason | ✅ | ✅ 枚举 | ReportHighlightVideoServiceTest | anchored | jpa:false |
|
||
| current_user | ✅ | ✅ record | SessionTokenServiceTest | anchored | jpa:false |
|
||
| membership 等 5 个 | 方向库 | — | — | gap | roadmap 占位 |
|
||
|
||
## 规则覆盖度（40 条）
|
||
|
||
| 规则 | 测试 | 证据 |
|
||
|------|------|------|
|
||
| BR-AUTH-001/002 | SessionTokenServiceTest / UserServiceLoginStrategyTest | anchored |
|
||
| BR-STORE-001/002 | StoreControllerTest | anchored |
|
||
| BR-STORE-003 公开门店字段裁剪 | StoreControllerTest#publicGet/List… | anchored |
|
||
| BR-APPT-001..003 | Appointment*Test | anchored |
|
||
| BR-APPT-004 时段校验 | 间接 | anchored |
|
||
| BR-RPT-001..006 | Report*Test | anchored |
|
||
| BR-RPT-007 token hash | 间接 | anchored |
|
||
| BR-LEAD-001..003 | ReportLeadControllerTest（001 显式；002/003 建议加强断言） | anchored |
|
||
| BR-UPLOAD-001/002 | 间接 | anchored |
|
||
| BR-HL-001/002 | ReportHighlightVideoServiceTest | anchored |
|
||
| BR-SCH-001 / BR-ST-001 / BR-PET-001 | 对应 ControllerTest | anchored |
|
||
| BR-USER-001/002 | 间接 | anchored |
|
||
| BR-USER-003 敏感字段 JsonIgnore | UserJsonIgnoreTest | anchored |
|
||
| BR-CONFIG-001/002 | —（配置） | anchored |
|
||
| BR-TST-001 一报告一寄语 | ReportTestimonialServiceTest | anchored |
|
||
| BR-UNSUB-001 / BR-INT-001 | ReportLeadControllerTest | anchored |
|
||
| BR-SC-001 / BR-BE-001 | StoreCustomerServiceTest / BusinessEventServiceTest / MigrationTest | anchored |
|
||
|
||
## 待补 gap 清单
|
||
|
||
| 优先级 | gap | 状态 |
|
||
|--------|-----|------|
|
||
| ~~高~~ | ~~User.password @JsonIgnore~~ | ✅ |
|
||
| ~~高~~ | ~~domain 回填 / 覆盖审计过期~~ | ✅ |
|
||
| ~~中~~ | ~~寄语/退订/周期规则连通~~ | ✅ |
|
||
| ~~高~~ | ~~成片三态 / 失败归类单测~~ | ✅ `ReportHighlightVideoServiceTest` |
|
||
| ~~高~~ | ~~寄语幂等独立用例~~ | ✅ `ReportTestimonialServiceTest` |
|
||
| ~~中~~ | ~~`rule:BR-STORE-003` 公开 Store 字段裁剪~~ | ✅ `toPublicStoreView` |
|
||
| 中 | `uk_report_appointment` 上线迁移 | 🟡 运维 |
|
||
| ~~中~~ | ~~预约/履约/报告打开/留资事件可统计落地~~ | ✅ BusinessEvent；成片/播放/保存事件另行接入 |
|
||
| 中 | production profile 实测启动 | 🟡 |
|
||
| 低 | 成片真 FFmpeg 端到端集成测（本机有 ffmpeg） | 🟡 单测已覆盖状态机与归类 |
|
||
| 低 | `action:logout` / `event:session_revoked` 服务端吊销 | 🟡 gap |
|
||
| 低 | 废弃 `register_store` / wechat OAuth demo 代码路径 | 🟡 deprecated 已标 |
|
||
| — | 会员/储值/套餐/历史报告/看板 | gap 占位，不展开 |
|
||
|
||
## P1/P2 方向（jsonl 已占位）
|
||
|
||
- `entity:membership` / `stored_value` / `service_package` — P1/P2
|
||
- `entity:report_history` / `analytics_dashboard` — P2
|
||
|
||
本期不实现，仅 `evidence=gap` + `jpa=false`，避免本体膨胀成未实现产品说明书。受 `rule:BR-ADMIN-004` 约束，**不得写入 Phase A 门店后台设计**。
|
||
|
||
## 门店 Web 后台 Phase A 状态（2026-08-01）
|
||
|
||
> 产品：`docs/门店管理后台升级方案-对标宠老板.md`。后台工程已建立；各对象按当前 anchored/documented/gap 证据维护。
|
||
|
||
| ID | 类型 | 用途 |
|
||
|----|------|------|
|
||
| `entity:admin_console` | Entity | Web 管理端壳 |
|
||
| `entity:workbench` / `workbench_todo_item` | Entity | 今日工作台与待办；报告事件漏斗已 anchored |
|
||
| `entity:store_customer` | Entity | 门店客户稳定主档（非会员卡） |
|
||
| `action:view_workbench` 等 8 个 admin_* | Action | 工作台/列表/设置/排班 |
|
||
| `rule:BR-ADMIN-001`…`004` | Rule | 角色、店范围、内部字段、范围闸门 |
|
||
| `event:workbench_viewed` | Event | 可选埋点（gap） |
|
||
|
||
设计阶段每个页面 brief 应带 `ontologyRefs`（例：`[entity:workbench, action:view_workbench, rule:BR-ADMIN-001]`）。
|
||
|
||
**页面清单 PRD（已写）**：`docs/门店管理后台-PhaseA-页面清单PRD.md`（A0–A7 全页字段/筛选/API/验收）。
|
||
|
||
当前 validate 规模以脚本输出为准（236 条目）。
|