windyboy
e57152dd83
specification.md 按新需求重写： - 扫描模型反转：水位/ID 区间 → 处理标记为谓词（C-30 取代 C-1/C-2/C-13；INV-2b 替代 INV-2/4/5） - Redis 回归为查询投影：处理完成门（INV-23）、投影治理与同源读取（INV-24），INV-11b 扩充非权威清单 - 日计划快照语义反转：缺席航班删除、未携带字段清除（INV-15b），增量报文语义另立（INV-14b） - 终态记录归档 → 到期删除（INV-25），G-PROC-HST/G-HST-RETENTION/G-REPLAY-CHANNEL/G-FLOP-DIRECTION 关闭并清扫全仓引用 - 重放移出交付范围：R_keep 公式收窄、CLM-3 重定义为重处理幂等、Q6 删除 - 新增 INV-23~28：Redis 完成门、投影治理、清理谓词、参考数据逐类保存/门控、历史先行红线 - C-25/C-26 定案（原子级联不回发 EROR；快照未携带字段清除），Q13/Q14 关闭，Q6/Q12 删除，新增 C-30/C-31 联动：implementation.md 收报/回填/快照/生命周期/FLOP 方向各章按新口径重写；architecture.md D1/D4 改删除语义；reference.md 退役 archive-after；requirements.md OPS 表改为注册表定义 语法；AGENTS.md 状态边界随新口径更新；check-docs.py OPS 注册表节名同步。 scripts/check-docs.sh 全部通过。
7.3 KiB
7.3 KiB
设计文档入口
docs/ 是本系统目标设计的唯一依据：只记录「设计是什么」与「对外主张当前是否可声明」。实现进度、缺口处置与排期在 Plane（ACM2），不在本文档体系内。
1. 文档职责（一个事实只有一处定义）
| 文档 | 唯一职责 |
|---|---|
| README.md | 入口、阅读顺序、文件职责、事实归属、ID 语法与引用纪律。 |
| requirements.md | 阶段范围与非目标、US-xx / OPS-x 验收目标、需求覆盖与依赖。 |
| architecture.md | 系统边界、模块职责、存储归属、总体流程与 D1–D4 决策。 |
| specification.md | 术语、外部契约 C-x、前提 PRE-x、不变量 INV-x、声明边界 CLM-x、待确认 Qn、当前已知偏差 G-NAME、验证映射。 |
| implementation.md | 数据模型、状态机、管道机制、事务、投递、作业与恢复；航班域与静态参考数据的权威模型和合并语义。 |
| reference.md | 参数 PARAM:<key>、指标与健康、模块与代码入口、错误分类。 |
| legacy/ | 外部协议与旧系统基线：现役行为对拍、SIS 规范、XSD、历史决策记录。外部协议事实（报文结构、字段语义、上游行为）以 SIS/XSD 为准；legacy 现役行为只是基线，已知缺陷不作依据。 |
2. 按读者选入口
| 你是谁 | 从哪读起 |
|---|---|
| 新开发者 | specification.md（前提 / 不变量 / 声明边界）→ implementation.md（机制、航班域与静态参考数据）→ reference.md（参数 / 指标 / 代码入口） |
| 库方 / 上游接口人 | specification.md（C-x 与 Q） |
| 值班主任 / 运维 | reference.md（参数与指标）→ specification.md（哪些主张当前不可声明）。执行规程在上线/切流前另立（docs/runbooks/），设计阶段只保留前置条件与红线 |
| 评审 / PR 作者 | specification.md + 本文「维护清单」 |
3. 事实归属表
| 事实 | 唯一归属 | 其他文档怎么写 |
|---|---|---|
| 收报扫描谓词与幂等登记 | implementation.md「收报」 | specification.md 写对库方的承诺 C-30；reference.md 写参数 |
保留期下界 R_keep、清除前置条件 |
specification.md「契约」 | implementation.md 只写行为约束；执行步骤在上线前另立 |
| 处理标记值集与写权限 | specification.md C-5 |
implementation.md 只写行为约束「只写空标记、不回撤、不覆盖」（INV-7） |
回填四结果、放弃语义、R 的作用 |
implementation.md「回填」 | specification.md 记结论与可声明性 |
退避 / claim-batch / 回填期限等取值 |
reference.md「参数」 | 其余文档只引 PARAM:<key> |
| 消费权排他、ID 不复位、报文不可变、时钟、单实例 | specification.md「前提」 | 其他文档只引 PRE-x |
航班身份、合并语义、STATE_VERSION、OPERATION_DAY |
implementation.md「航班域」 | 其余文档只引域规则与 INV-x |
| 航班动态逐类语义与空标签规则（FLOP） | implementation.md「动态运行事件」 | specification.md 记 Q8 与 G-*；requirements.md 写验收口径 |
| SIS 消息中的参考数据类别、结构与资源状态 | implementation.md「静态参考数据」 | requirements.md 写取数与刷新验收；admin-api 只从处理后的业务数据库读取 |
| 对外术语（落信 / 入站 / 库方 / 处理标记） | specification.md「术语」 | — |
| 管道内部术语（队头 / 终态 / 待标记 / 回填意图） | implementation.md「术语与持久化记录」 | — |
4. ID 定义语法与引用纪律
持久规范 ID 族：US-nn、OPS-n、Dn、C-n、PRE-n、INV-n、CLM-n、Qn、G-NAME、PARAM:<key>。
- 定义只能出现在所属文件，并采用固定语法：
US-xx用三级标题（### US-01 …）；C-x、INV-x用加粗定义行（- **C-5** …）；CLM-n、OPS-n、Dn、PRE-n、Qn、G-NAME与PARAM:<key>用注册表首列；首列必须是单个裸 ID （`ID`或ID）。成组登记（`a` / `b`）、带括注的首列与写成`ID`的引用行都不算定义。- 同一行登记多个 ID（如验证映射的
INV-20 / CLM-3）是引用行，不构成定义。 其他位置一律是引用。
- 编号稳定：条款被取代时标
[作废 by C-y]并保留原文；不静默改写，不重编号。 - 引用只用稳定 ID，不用章节号：写
INV-3、C-8、PARAM:msgx.pipeline.claim-batch，或「见 implementation.md『收报』」这类文件名 + 小节名指针。章节号随增删章节腐烂，指针失效后必然被改写为复述。 - 指针之后不再复述被指内容。若两处需要同一段话，说明它放错了位置。
- 外部 SIS 证据统一写
SIS:<section>（如SIS:3.16-note-4），解析到 legacy/SIS_AODB_RMS-V0.1.md 的章节；它不属于本项目规范 ID，不参与唯一定义检查。 G-NAME是活跃偏差 ID：定义只在 specification.md「当前已知偏差」注册表，其他位置只写标记；偏差闭合时在同一变更中删除定义与全仓引用，历史与关闭证据只留 Plane。
数值只有两个家：参数默认值与指标名在 reference.md；契约数值（保留期、值集、下界）在 specification.md。
文档不记进度：不写日期式状态、完成记录与 changelog；只记「主张是否可对外声明」（CLM-x）。
5. 维护清单
Q 答复落地（4 步）：① 在 specification.md 就地补结论与日期 → ② 改 reference.md 的默认值与「依据」列 → ③ 机制有变才改 implementation.md → ④ 在 specification.md 的 CLM 上划掉挂起。
偏差闭合：在 specification.md 删除该 G 定义，并删除全仓 G-NAME 引用；关闭证据留在 Plane。
PR 评审 4 问：新事实是否已有归属？是否复述了别处？是否用了稳定 ID？是否把运维 / 验收写进了机制段？
日常维护：运行 scripts/check-docs.sh，校验顶层六文件、ID 定义唯一性与全仓引用、旧文件名与章节号零命中、活跃 G、仓库内链接。合并或重命名文档时传入迁移前 Git 基线（scripts/check-docs.sh <基线>），额外比较持久 ID 与活跃 G 集合。
尺寸触发器：implementation.md 的管道与航班域两章各自超过约 500 行才考虑拆入 docs/ 专题目录。
6. 不建的文件
- 顶层不再增加 Markdown：
docs/顶层固定为上述 6 个文件加允许的专题目录。 - 不建运行规程文件：设计阶段没有可执行的运行环境，操作步骤在上线/切流前另立（
docs/runbooks/*.md）；设计阶段需要的只有前置条件与红线，它们分别在 specification.md（C-7–C-12）与 specification.md 的CLM-x。 - 声明边界与 Plane 分离：未交付、未确认、不可声明的主张记在 specification.md，逐项处置在 Plane（ACM2），不在正文逐段标注。