History

malei c3ee206419 docs: retire unfinished web oauth contract		2026-08-02 02:45:23 +08:00
..
actions.md	docs: retire unfinished web oauth contract	2026-08-02 02:45:23 +08:00
events.md	docs: define follow-up task and rebook contracts	2026-08-02 02:11:28 +08:00
objects.md	docs: define follow-up task and rebook contracts	2026-08-02 02:11:28 +08:00
README.md	docs: define follow-up task and rebook contracts	2026-08-02 02:11:28 +08:00
relations.md	docs: define follow-up task and rebook contracts	2026-08-02 02:11:28 +08:00
rules.md	docs: define follow-up task and rebook contracts	2026-08-02 02:11:28 +08:00

README.md

宠小它 — 知识本体（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 等多处，导致：

文档与代码状态不同步（架构评估报告已直接指出）。
改一处要全仓 grep 才能确认是否同步。
Agent 协作靠人肉读长文档找上下文，无机器可读索引。

本体论把这些概念收口为 SSOT，做双向引用：本体条目写「落地于 ReportController#create / docs/产品设计文档.md §5.3 / 测试 ReportControllerTest」，反过来文档/代码改动时回溯本体 ID。

证据强度

每条本体条目标注证据强度，用于覆盖度审计：

强度	含义
`anchored`	有代码路径 + 测试 + 文档三处对齐
`documented`	只在文档里，代码未实现或未对齐
`implemented`	只在代码里，文档未更新
`gap`	明确缺失（如真实短信服务商、production profile 实测）

ID 规则

稳定的、可读的 ID：

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、FollowUpTask，以及成片/上传/鉴权/寄语/退订/回访状态机/真实再次预约相关规则。

门店 Web 后台 Phase A：AdminConsole、Workbench、WorkbenchTodoItem 仍是非 JPA 读模型；StoreCustomer 与 FollowUpTask 已落为 JPA 稳定业务对象。BR-ADMIN-001…004、BR-FU-001/002 与 admin actions 继续约束后台；收银/会员资产仍为 gap。

P1/P2 方向（会员/储值/套餐/历史报告/看板）以 gap 证据条目录入，不展开字段；受 rule:BR-ADMIN-004 约束不得偷渡进 Phase A 设计。

当前规模以 python3 docs/graph/validate_ontology.py docs 输出为准；覆盖审计见 ../coverage/ontology-coverage-audit.md。

校验

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

校验：

JSONL 引用完整性（每个被引用的 ID 都存在）
证据强度分布
本体—代码端点/实体漂移
文档反向引用（本体条目里写的 doc 路径存在）

README.md Unescape Escape