# 宠小它 — 知识本体（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（documented 预录入）**：`AdminConsole`、`Workbench`、`WorkbenchTodoItem`、`ServiceCustomer` 与 `BR-ADMIN-001`…`004`、对应 admin actions。设计须引用这些 ID；收银/会员资产仍为 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 路径存在）