zixun-github project-discover-modules-contracts（Step4：模块单页 SSOT + 契约段落 + 证据链）
概览
模块页是 Discover 的“权威入口”。它的目标不是写全细节，而是让 AI/人能在需要时 快速判断边界与不变量，并且能沿着证据链定位到代码/契约/测试/CI/ops。
开始时宣布：「我正在使用 project-discover-modules-contracts 技能为模块建立单页 SSOT（含契约段落与证据链）。」
硬规则（P0 必须满足）
- 模块页路径固定
.aidlc/project/components/{module}.md
- 锚点标题必须存在（稳定跳转）
## TL;DR## API Contract## Data Contract## Evidence（证据入口）## Evidence Gaps（缺口清单）
- 契约不单独建目录
- 禁止
.aidlc/project/contracts/**
- 禁止
- 缺口必须结构化
- 所有缺口只写到
## Evidence Gaps（缺口清单）（不允许散落“待补/未发现/TODO”）
- 所有缺口只写到
- 禁止“占位句”冒充内容
- 在
API Contract/Data Contract/Evidence等正文里，禁止写“待补齐后填写/待确认/未发现/以后再补”等占位句。 - 如果缺证据或缺结论：只允许写入
## Evidence Gaps（缺口清单），并保持正文段落简短、可追溯。
- 在
模块页 Frontmatter（必填）
---
module: <module-short-name>
priority: P0|P1|P2
change_frequency: high|medium|low
last_verified_at: <YYYY-MM-DD>
source_files:
- <path/to/key/file1>
- <path/to/key/file2>
---
提示：
change_frequency可用 git log 的经验判断或简单统计；source_files只选“最能代表模块边界/契约/状态机”的关键源文件。
模块页推荐结构（最小可用）
# <模块中文名>（<module>）
## TL;DR
<3–5 句话：做什么、边界、关键不变量、最关键的证据入口>
## 模块定位
- In：
- Out：
## Owner
- 团队/负责人/值班入口：
## 入口
- 代码入口：
- 运行入口（如有）：../ops/...
## 协作场景（1–2 个）
- 谁调用谁 + 关键边界（细节时序下沉到 spec）
## State Machines & Domain Events
- 状态机摘要：
- 领域事件摘要：
## API Contract
- 权威入口（必须可定位）：
- 不变量摘要（3–7 条）：
- 证据入口（最小粒度）：
## Data Contract
- 数据主责（Ownership）：
- 核心对象与主键：
- 权威入口（必须可定位）：
- 不变量摘要（3–7 条）：
- 证据入口（最小粒度）：
## Evidence（证据入口）
- Code：
- Tests：
- CI：
- Ops：
## Evidence Gaps（缺口清单）
- 缺口：
- 期望补齐到的粒度：
- 候选证据位置：
- 影响：
契约段落写法（避免“字段大全”）
## API Contract 最小要求（P0）
- 权威入口（必须可点击/可定位）
- OpenAPI/Proto/Schema 的源文件路径或生成物路径
- 若有生成/校验命令或 CI job，写入口（不写长说明）
- 不变量摘要（3–7 条）
- 例如：鉴权方式、幂等语义、版本策略、错误码族、审计要求、超时/重试策略
- 证据入口（最小粒度）
- 至少 N 个关键 handler/router/controller 文件路径
- 至少 1 个代表性测试入口（没有就进入 Evidence Gaps）
- 至少 1 个 CI job/命令入口（能证明“有没有跑测试/有没有做契约校验”）
## Data Contract 最小要求（P0）
- 数据主责（Ownership）
- 主写/只读/同步来源（边界明确）
- 核心对象与主键
- 对象名 + 主键/唯一标识 + 生命周期一句话
- 权威入口（必须可定位）
- migrations/DDL/Schema/ORM model 的证据入口
- 不变量摘要（3–7 条）
- 例如：唯一性约束、状态口径、关键枚举、不可变字段、对账口径入口
- 证据入口（最小粒度）
- 关键 repository/mapper/service 路径
- 测试/CI 证据入口（无则进 Evidence Gaps）
Evidence Gaps（缺口清单）模板（强制结构化）
任何“找不到/不确定/待补”都必须按这个结构写，避免缺口散落导致永远补不齐。
特别提醒： 如果你暂时无法给出“3–7 条不变量摘要”，不要在正文里写“待补齐后填写”。 正确做法：在 Evidence Gaps 里新增缺口条目（例如“缺口：未提取 API 不变量摘要”），并写清候选证据位置与影响。 该模块此时不得在索引中打勾。
## Evidence Gaps（缺口清单）
- 缺口：未发现 OpenAPI/Proto 权威入口（无法确认接口字段与错误码族）
- 期望补齐到的粒度：定位到具体 schema 文件路径或生成 job 名
- 候选证据位置：`docs/`、`api/`、`openapi/`、CI workflow 中的 build-docs job
- 影响：需求设计与实现阶段会猜接口契约，容易破坏兼容性与回归成本高
P1/P2 的降级规则（避免范围失控）
- P1：模块页必须存在；API 或 Data 允许缺失其一，但必须在 Evidence Gaps 写清缺口与影响
- P2：默认不创建模块页，只在索引占位；需要时再升级到 P1/P0
红旗清单
- 契约段落写成字段大全（应改为：权威入口 + 不变量摘要 + 证据入口）
- “缺口”用 TODO/待补散落在正文（必须集中到 Evidence Gaps）
- 在正文里写“待补齐后填写/未发现/以后再补”这种占位句（必须改为 Evidence Gaps）
- 在索引里重复模块页内容（索引只导航）
常见错误
- 把“证据入口”写成“你应该怎么做”（要写在哪里、而不是怎么操作）
- 把一次性交付细节写进项目级模块页（应下沉 spec 或外部 runbook）