148 lines
8.5 KiB
Markdown
148 lines
8.5 KiB
Markdown
# 本体覆盖度审计（Ontology Coverage Audit）
|
||
|
||
> 本体条目 ↔ 文档章节 ↔ 代码路径 ↔ 测试用例 三方对齐审计。
|
||
> 证据强度：`anchored`（三处对齐）/ `documented`（仅文档）/ `implemented`（仅代码）/ `gap`（缺失）。
|
||
>
|
||
> **刷新时间**：2026-08-02（FollowUpTask 回访闭环收口后刷新）
|
||
|
||
## 审计方法
|
||
|
||
对 `graph/ontology.jsonl` 的每个条目，核对：
|
||
1. **文档**：`doc` 字段指向的 docs 路径是否存在且描述一致
|
||
2. **代码**：`code` 字段指向的源码路径是否存在且实现一致
|
||
3. **测试**：`test` 字段指向的测试用例是否存在且覆盖该条目
|
||
|
||
任一缺失则降级证据强度。
|
||
|
||
## 当前规模（以 validate 为准）
|
||
|
||
| 类型 | 数量 |
|
||
|------|------|
|
||
| Entity | 29 |
|
||
| Action | 75 |
|
||
| Event | 33 |
|
||
| Rule | 49 |
|
||
| Relation | 102 |
|
||
| **合计** | **288** |
|
||
|
||
证据强度：`anchored` 249（86.5%）/ `documented` 28 / `gap` 9 / `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 端点 68/68、JPA Entity 16/16 对齐；非 JPA 领域实体 13 个；代码与本体均无单边漂移。
|
||
|
||
## 元数据卫生
|
||
|
||
| 项 | 状态 |
|
||
|----|------|
|
||
| Action / Relation `domain` | ✅ 已回填（0 缺失） |
|
||
| gap 入口 `deprecated` | ✅ `register_store`；未实现的网页 OAuth demo 已删除，不再作为入口建模 |
|
||
| 寄语事件独立化 | ✅ `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 | |
|
||
| follow_up_task | ✅ | ✅ | FollowUpTaskServiceTest / MigrationTest / ControllerTest | 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 | 不可变低敏事件；工作台去重统计 |
|
||
| staff_invitation | ✅ | ✅ | StaffInvitationServiceTest / StoreOnboardingMigrationTest | anchored | 原始 token 只显一次；库内 hash、限时、可撤销、手机号绑定 |
|
||
| audit_log | ✅ | ✅ | AuditLogServiceTest / StoreOnboardingMigrationTest | anchored | 低敏不可变安全/配置审计 |
|
||
| customer_timeline | ✅ | ✅ read model | StoreCustomerTimelineServiceTest | anchored | StoreCustomer + BusinessEvent 的同店低敏事实投影；jpa:false |
|
||
| highlight_fail_reason | ✅ | ✅ 枚举 | ReportHighlightVideoServiceTest | anchored | jpa:false |
|
||
| current_user | ✅ | ✅ record | SessionTokenServiceTest | anchored | jpa:false |
|
||
| membership 等 5 个 | 方向库 | — | — | gap | roadmap 占位 |
|
||
|
||
## 规则覆盖度（49 条）
|
||
|
||
| 规则 | 测试 | 证据 |
|
||
|------|------|------|
|
||
| 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 | ProductionConfigurationValidatorTest（002） | anchored |
|
||
| BR-CONFIG-003 生产发布只读门禁 | 配置单测 + release/smoke 脚本；live 证据待发布 | anchored |
|
||
| BR-TST-001 一报告一寄语 | ReportTestimonialServiceTest | anchored |
|
||
| BR-UNSUB-001 / BR-INT-001 | ReportLeadControllerTest | anchored |
|
||
| BR-SC-001 / BR-BE-001 | StoreCustomerServiceTest / BusinessEventServiceTest / StoreCustomerTimelineMigrationTest | anchored |
|
||
| BR-ONBOARD-001 | MerchantOnboardingServiceTest / StoreOnboardingServiceTest / StoreServiceTest | anchored |
|
||
| BR-INVITE-001 | StaffInvitationServiceTest / AuthInterceptorActiveUserTest | anchored |
|
||
| BR-AUDIT-001 | AuditLogServiceTest / StoreOnboardingMigrationTest | anchored |
|
||
| BR-SC-002 客户时间线低敏投影 | StoreCustomerTimelineServiceTest / AdminServiceCustomerControllerTest | anchored |
|
||
| BR-FU-001/002 回访状态机与真实再次预约 | FollowUpTaskServiceTest / AppointmentServiceTest / 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_* 与 3 个回访命令 | 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 规模以脚本输出为准（288 条目）。
|