windyboy
8093d20f9b
含：MAFL 派生投影与 SRVT/VIPF 无界集合口径、schd EVENT_ID 写代次与 DEAD 代次替换、运营日时区 fail-fast、缺口索引增删（G-MAFL/G-SRVT-VIPF/G-COMPAT-HTTP/G-REQ-OPEN-UNIQUE，移除 G-JOB-HEARTBEAT）、job 心跳/扫描积压/最近失败指标登记、INV-18 验证映射改为实际测试名。
设计文档入口
实现核对日期：2026-09-11（代码基线以 git log -- docs/ 为准）。文档描述目标设计，不等于已实现；测试通过不等于现场已发布。进度与缺口在 Plane（ACM2）跟踪；文档只记录「对外主张当前是否可声明」，见 invariants.md 声明边界。
1. 按读者选入口
| 你是谁 | 从哪读起 |
|---|---|
| 新开发者 | invariants.md（前提 / 不变量 / 声明边界）→ design.md（机制）→ reference.md（参数 / 指标 / 模块） |
| 库方 / 上游接口人 | contracts.md（条款 C-x 与待确认 Q） |
| 值班主任 / 运维 | reference.md（参数与指标）→ invariants.md（哪些主张当前不可声明）。执行规程在上线/切流前另立，设计阶段只保留前置条件与红线 |
| 评审 / PR 作者 | invariants.md + 本文 §5 评审清单 |
2. 文档职责（一个事实只有一处定义）
| 文档 | 唯一职责 |
|---|---|
| architecture.md | 系统边界、模块职责、存储归属、架构决策（D1–D4）。 |
| invariants.md | 前提 PRE-x、不变量 INV-x、声明边界 CLM-x、验证映射。 |
| design.md | 管道机制：收报·水位、主泵·处理·事务边界、回填、投递、作业与归档。 |
| contracts.md | 对外承诺与要求（C-x）、待确认事项（Q）。 |
| reference.md | 参数注册表、指标与健康、模块入口、错误分类。 |
| flight-state.md | 航班域模型与合并语义。 |
| user-stories.md | US / OPS 验收目标。 |
| legacy/ | 现役行为基线与外部协议事实（SIS 规范、XSD）。外部协议事实（报文结构、字段语义、上游行为）以 SIS/XSD 为准；legacy 现役行为只是基线，已知缺陷不作依据；与本系统目标设计的已知差异见 C-25/C-26，确认状态见 Q13/Q14。 |
message-lifecycle.md 已并入 design.md，文件仅保留跳转说明。
3. 事实归属表
| 事实 | 唯一归属 | 其他文档怎么写 |
|---|---|---|
水位 W、空洞判定与推进条件 |
design「收报与水位」 | contracts 写对库方的承诺 C-1–C-3；reference 写参数 |
保留期下界 R_keep、清除前置条件 |
contracts「保留与清除」 | design 只引 C-x；执行步骤在上线前另立 |
| 处理标记值集与写权限 | contracts C-5 |
design 只写行为约束「只写空标记、不回撤、不覆盖」（INV-7） |
回填四结果、放弃语义、R 的作用 |
design「回填」 | invariants 记结论与可声明性 |
退避 / claim-batch / 回填期限等取值 |
reference「参数」 | design 只引 PARAM:x |
| 消费权排他、ID 不复位、报文不可变、时钟、单实例 | invariants「前提」 | 其他文档只引 PRE-x |
航班身份、合并语义、STATE_VERSION、OPERATION_DAY |
flight-state.md | design 只引域规则 |
| 对外术语（落信 / 入站 / 库方 / 处理标记） | contracts「术语」 | — |
4. 引用与写作纪律
- 引用只用稳定 ID：
PRE-x、INV-x、CLM-x、C-x、D-x、OPS-x、PARAM:x、[G-x]、[Q-x]、US-xx、ACM2-nn。不再用章节号做跨文档引用。 本条取代旧版 README 的「其他文档引用章节号」规则：章节号随增删章节腐烂，指针失效后必然被改写为复述——重构前实测有 30 处「唯一定义处」与 33 处跨文档章节引用。 - 指针之后不再复述被指内容。若两处需要同一段话，说明它放错了位置。
- 文档不记进度，只记「主张是否可对外声明」。进度在 Plane。
- 机制段只写「是什么 / 为什么」。验收 → invariants 验证映射；前置条件、红线与库方方案 → contracts / invariants；参数默认值 → reference；操作步骤在上线/切流前另立规程，设计阶段不写。一句话一个主张；只强调关键结论，避免整段加粗。
- 数值只有两个家：参数默认值与指标名在 reference.md；契约数值（保留期、值集、下界）在 contracts.md。
5. 维护清单
Q 答复落地（4 步）：① 在 contracts.md 就地补结论与日期 → ② 改 reference.md 的默认值与「依据」列 → ③ 机制有变才改 design.md → ④ 在 invariants.md 的 CLM 上划掉挂起。
PR 评审 4 问：新事实是否已有归属？是否复述了别处？是否用了稳定 ID？是否把运维 / 验收写进了机制段？
尺寸触发器：design.md 超过约 800 行才按子系统再拆；invariants.md 超过两页先怀疑混进了机制。
6. 当前状态
- 2026-09-11 文档体系重构：新增 invariants.md / contracts.md / reference.md；design.md 由 design.md + message-lifecycle.md 合并（后者保留跳转 stub）；跨文档引用由章节号改为稳定 ID。
- 不建 runbooks.md：设计阶段没有可执行的运行环境，操作步骤在上线/切流前另立（见 Plane ACM2-48）；设计阶段需要的只有前置条件与红线，它们分别在 contracts（
C-7–C-12）与 invariants（CLM-x）。 - 目标设计与交付状态分离：未交付、未确认、不可声明的主张见 invariants.md 的声明边界与 Plane ACM2，不在正文里逐段标注。