Files

T

windyboy 6eade95a97 docs: 拆分契约/前提/参数文档，合并消息生命周期并收敛设计裁决

- design.md 合并 message-lifecycle.md（后者保留跳转 stub），去重并改用稳定 ID 引用
- 新增 invariants.md（前提/不变量/声明边界/验证映射）、contracts.md（对外条款与 Q 台账）、
  reference.md（参数/指标/模块/错误分类）
- architecture/flight-state/user-stories/README 同步重划引用；README 废止「引用章节号」
- 裁决收敛：R 按超期而非次数放弃、清除前提含放弃清单、航班表写者互斥、head-deadline 仅告警、
  超期判据用本地入队时间、投递批次读取时刻冻结、schd 只进不退与条件标记、FLID 复用为前提
- 删除 runbooks 与 CI 防漂移校验：设计阶段不产出面向执行期的产物

Refs: ACM2-42..51

2026-09-11 15:48:14 +08:00

5.2 KiB

Raw Blame History

设计文档入口

实现核对日期：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 为准。

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-6`）
回填四结果、放弃语义、`R` 的作用	design「回填」	invariants 记结论与可声明性
`head-deadline` / 退避 / `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、PARAM:x、[G-x]、[Q-x]、US-xx、ACM2-nn。不再用章节号做跨文档引用。 本条取代旧版 README 的「其他文档引用章节号」规则：章节号随增删章节腐烂，指针失效后必然被改写为复述——重构前实测有 30 处「唯一定义处」与 33 处跨文档章节引用。
指针之后不再复述被指内容。若两处需要同一段话，说明它放错了位置。
文档不记进度，只记「主张是否可对外声明」。进度在 Plane。
机制段只写「是什么 / 为什么」。验收 → invariants 验证映射；前置条件、红线与库方方案 → contracts / invariants；参数默认值 → reference；操作步骤在上线/切流前另立规程，设计阶段不写。一句话一个主张；加粗每节 ≤ 3 处。
数值只有两个家：参数默认值与指标名在 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，不在正文里逐段标注。

5.2 KiB Raw Blame History Unescape Escape