82 lines
4.0 KiB
Markdown
82 lines
4.0 KiB
Markdown
# 宠小它 — 知识本体（Ontology）
|
||
|
||
> 知识库的单一事实源（SSOT）。所有产品文档与代码改动都应向本本体对齐；冲突以本本体为准。
|
||
|
||
## 这是什么
|
||
|
||
本目录用本体论框架把宠小它的领域知识建模为 5 类原子：
|
||
|
||
| 原子类型 | 文件 | 含义 |
|
||
|---------|------|------|
|
||
| **Object（实体）** | `objects.md` | 持久名词 + 字段 + 归属系统 |
|
||
| **Action（动作）** | `actions.md` | 读写实体的命令/用例 |
|
||
| **Event（事件）** | `events.md` | 动作或状态变更后发生的事实（过去时） |
|
||
| **Rule（规则/不变量）** | `rules.md` | 业务约束、决策条件、权限边界 |
|
||
| **Relation（关系）** | `relations.md` | 实体/动作/事件/规则之间的边 |
|
||
|
||
机器可读版本在 `../graph/ontology.jsonl`，三方对齐审计在 `../coverage/ontology-coverage-audit.md`。
|
||
|
||
## 为什么要本体论
|
||
|
||
现有文档是主题/文档类型导向的，同一概念（如「报告」）的规则散落在 `产品设计文档.md §5.3`、`P0-研发落地清单.md`、`架构与产品评估报告`、代码里的 `ReportController`/`ReportService`/`Report.vue` 等多处，导致：
|
||
|
||
1. 文档与代码状态不同步（架构评估报告已直接指出）。
|
||
2. 改一处要全仓 grep 才能确认是否同步。
|
||
3. Agent 协作靠人肉读长文档找上下文，无机器可读索引。
|
||
|
||
本体论把这些概念收口为 SSOT，做**双向引用**：本体条目写「落地于 `ReportController#create` / `docs/产品设计文档.md §5.3` / 测试 `ReportControllerTest`」，反过来文档/代码改动时回溯本体 ID。
|
||
|
||
## 证据强度
|
||
|
||
每条本体条目标注证据强度，用于覆盖度审计：
|
||
|
||
| 强度 | 含义 |
|
||
|------|------|
|
||
| `anchored` | 有代码路径 + 测试 + 文档三处对齐 |
|
||
| `documented` | 只在文档里，代码未实现或未对齐 |
|
||
| `implemented` | 只在代码里，文档未更新 |
|
||
| `gap` | 明确缺失（如真实短信服务商、production profile 实测） |
|
||
|
||
## ID 规则
|
||
|
||
稳定的、可读的 ID：
|
||
|
||
```text
|
||
entity:snake_case_name # entity:appointment
|
||
action:snake_case_name # action:create_appointment
|
||
event:snake_case_name # event:appointment_created
|
||
rule:BR-DOM-001 # rule:BR-RPT-001
|
||
rel:subject_predicate_object # rel:report_belongs_to_appointment
|
||
```
|
||
|
||
每个 JSONL 条目里引用的 `subject`/`object`/`inputs`/`outputs`/`appliesTo` ID 必须在 `ontology.jsonl` 中存在。
|
||
|
||
## 与现有体系的关系
|
||
|
||
- **既有文档不删除、不重写**：只在顶部加「本文档与 `ontology/objects.md#xxx` 对齐，冲突以本体为准」。
|
||
- **`.agents/` 协作体系不动**：本体论是它的知识基座；`common-context.md` 的术语表、`rules/api-contract-boundary.md` 的规则可引用本体 ID。
|
||
- **角色写入锁**：`ontology/` 归 `Docs Agent` + `System Architect` 共建，其他角色只读引用。
|
||
|
||
## 范围
|
||
|
||
已覆盖 P0 主闭环实体与动作，并补录：`Pet`、`ServiceType`、`ScheduleBlock`、`HighlightVideo`、`SessionToken`、`ReportImage`、`ReportTestimonial`、`ServiceInterval`、`HighlightFailReason`、`CurrentUser`，以及成片/上传/鉴权/寄语/退订相关规则。
|
||
|
||
**门店 Web 后台 Phase A**：`AdminConsole`、`Workbench`、`WorkbenchTodoItem` 仍是非 JPA 读模型；`StoreCustomer` 已落为 JPA 稳定主档。`BR-ADMIN-001`…`004` 与 admin actions 继续约束后台；收银/会员资产仍为 gap。
|
||
|
||
P1/P2 方向（会员/储值/套餐/历史报告/看板）以 `gap` 证据条目录入，不展开字段；受 `rule:BR-ADMIN-004` 约束不得偷渡进 Phase A 设计。
|
||
|
||
当前规模以 `python3 docs/graph/validate_ontology.py docs` 输出为准；覆盖审计见 `../coverage/ontology-coverage-audit.md`。
|
||
|
||
## 校验
|
||
|
||
```bash
|
||
python3 docs/graph/validate_ontology.py docs
|
||
python3 docs/graph/audit_drift.py
|
||
```
|
||
|
||
校验：
|
||
- JSONL 引用完整性（每个被引用的 ID 都存在）
|
||
- 证据强度分布
|
||
- 本体—代码端点/实体漂移
|
||
- 文档反向引用（本体条目里写的 doc 路径存在）
|