# 本体覆盖度审计（Ontology Coverage Audit）

> 本体条目 ↔ 文档章节 ↔ 代码路径 ↔ 测试用例 三方对齐审计。
> 证据强度：`anchored`（三处对齐）/ `documented`（仅文档）/ `implemented`（仅代码）/ `gap`（缺失）。
>
> **刷新时间**：2026-08-02（智能预约 M0 Batch 0 契约冻结后刷新）

## 审计方法

对 `graph/ontology.jsonl` 的每个条目，核对：
1. **文档**：`doc` 字段指向的 docs 路径是否存在且描述一致
2. **代码**：`code` 字段指向的源码路径是否存在且实现一致
3. **测试**：`test` 字段指向的测试用例是否存在且覆盖该条目

任一缺失则降级证据强度。

## 当前规模（以 validate 为准）

| 类型 | 数量 |
|------|------|
| Entity | 30 |
| Action | 80 |
| Event | 36 |
| Rule | 55 |
| Relation | 112 |
| **合计** | **313** |

证据强度：`anchored` 250（79.9%）/ `documented` 52 / `gap` 9 / `implemented` 2。

> anchored 占比相对早期快照下降，是因为主动录入了 P1/P2 `gap`、客户端埋点和智能预约 Batch 0 `documented` 条目；端点漂移仍为 0。

校验：

```bash
python3 docs/graph/validate_ontology.py docs
python3 docs/graph/audit_drift.py
```

当前结果：校验通过；HTTP 端点 68/68、JPA Entity 16/16 对齐；非 JPA/计划领域实体 14 个；代码与本体均无单边漂移。智能预约五个未实现端点以 `planned METHOD /path` 建模，不冒充当前代码端点。

## 元数据卫生

| 项 | 状态 |
|----|------|
| 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 |
| booking_agent_session | ✅ | —（Batch 0 设计） | — | documented | M0 短期会话；实现批创建 JPA/迁移/测试后才可改 anchored |
| membership 等 5 个 | 方向库 | — | — | gap | roadmap 占位 |

## 规则覆盖度（55 条）

| 规则 | 测试 | 证据 |
|------|------|------|
| 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 |
| BR-BA-001..005 智能预约 M0 边界 | 实现前；ADR + OpenAPI + JSON Schema 已冻结 | documented |

## 待补 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 已标 |
| 高 | 智能预约 M0 会话、五个 endpoint、三个事件和五条规则实现证据 | 🟡 documented / Ready；代码+测试同批才转 anchored |
| — | 会员/储值/套餐/历史报告/看板 | 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 规模以脚本输出为准（313 条目）。

## 智能预约 M0 Batch 0 状态（2026-08-02）

| 类型 | 已冻结 ID | 证据 |
|------|------|------|
| Entity | `entity:booking_agent_session` | documented |
| Action | `create/submit/transcribe/handoff/cancel_booking_agent_*` 共 5 条 | documented |
| Event | `booking_agent_started/draft_ready/fallback` | documented |
| Rule | `BR-BA-001..005` | documented |
| Relation | owner/store/session 读写与三条 EMITS 共 10 条 | documented |

契约评审已通过，尚未实现。下一实现批必须以真实 code/test 路径替换空证据，并将 `BookingAgentSession` 从计划对象切换为真实 JPA 实体；禁止仅修改 `evidence` 文字。
