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
This commit is contained in:
windyboy
+19
-26
@@ -4,9 +4,9 @@
|
||||
|
||||
本文定义阶段 A 的实施范围与验收口径：**故事定义要交付什么，验收标准定义怎样证明完成，代码落点说明从哪里改起**。保留 US-01～US-15、OPS-1～OPS-4 编号，便于关联已有任务和测试。
|
||||
|
||||
- 系统边界见 [architecture.md](architecture.md)，模块流程见 [design.md](design.md)。本文不重复设计全文，也不以工单状态代替代码验收。消息生命周期与信箱清除见 [message-lifecycle.md](message-lifecycle.md)，航班规则见 [flight-state.md](flight-state.md)。
|
||||
- 系统边界见 [architecture.md](architecture.md)，模块流程见 [design.md](design.md)，前提与不变量见 [invariants.md](invariants.md)，对外契约见 [contracts.md](contracts.md)，航班规则见 [flight-state.md](flight-state.md)。不以工单状态代替代码验收。
|
||||
- “当前基础”来自本轮代码核对，只表示有接口或部分实现，不表示故事完成。`KEEP` 是保留业务兼容，`FIX` 是明确修正旧缺陷，`DEFERRED` 不进入阶段 A。
|
||||
- 五个独立事实（落信、入队、处理完成、回填、投递确认）的定义与判定见 [message-lifecycle.md](message-lifecycle.md) §1；接口、日志和测试必须分开表达，投递确认不等于业务消费者已消费。
|
||||
- 五个独立事实（落信、入队、处理完成、回填、投递确认）的定义与判定见 [design.md](design.md)「术语与持久化记录」；接口、日志和测试必须分开表达，投递确认不等于业务消费者已消费。
|
||||
- 所有内部迁移只落自有 PG；共享 MySQL 不建表、不增列、不写历史表。本文用 `DATE_PROCESSED / STATUS` 表示逻辑字段，实际列名以库方契约为准。
|
||||
- 验收条目可按 `US-xx/条目号` 引用。故事较大时按下文子范围拆成小 PR，不把一个故事等同于一个提交。
|
||||
|
||||
@@ -36,7 +36,7 @@
|
||||
|
||||
**验收标准**
|
||||
|
||||
1. 按配置周期、ID 升序、有限批次采集信箱行；扫描谓词以 message-lifecycle.md §5.1 为准（按 ID 区间，不以处理标记为谓词）。接收层只入队，不解析业务、不回填已处理标记。
|
||||
1. 按配置周期、ID 升序、有限批次采集信箱行；扫描谓词以 [design.md](design.md)「收报与水位」为准（按 ID 区间，不以处理标记为谓词）。接收层只入队，不解析业务、不回填已处理标记。
|
||||
2. 按信箱 ID 幂等建立 PG `PENDING`；重复扫描、并发兼容入队和进程重启都不能重置已有终态。
|
||||
3. 快路径用持久水位，补偿路径受控重扫遗漏；本批 PG 入队全部确认后才推进水位。补偿可分页推进，不能被已入队但尚未回填的前一批永久挡住。
|
||||
4. PG 不可用或批次中途失败时不改信箱标记；恢复后补建遗漏，记录失败次数与扫描进度。
|
||||
@@ -44,7 +44,7 @@
|
||||
|
||||
**当前基础与落点**：`ingress/InboxPoller.kt` 按 ID 区间扫描（`ID > W`，不以处理标记为谓词），水位落 `INBOX_CURSOR` 并与入队同事务推进；`JdbcCminmsgInboxRepository.readRange/maxId` 与 `ProcStateRepository.insertIfAbsent` 承担发现与幂等入队。空洞老化阈值取 `msgx.pipeline.max-commit-delay`。剩余：Q2 未书面确认前，老化阈值与严格顺序仍是假定口径；真实 MySQL 的中断恢复与迟提交联合测试待现场环境。
|
||||
|
||||
**前置**：共享库读契约；Q2 决定严格顺序的端到端验收。水位与扫描谓词口径以 [message-lifecycle.md](message-lifecycle.md) §5.1 为准。
|
||||
**前置**：共享库读契约；Q2 决定严格顺序的端到端验收。水位与扫描谓词口径以 [design.md](design.md)「收报与水位」为准。
|
||||
|
||||
### US-02 兼容 HTTP 注入报文（KEEP）
|
||||
|
||||
@@ -112,8 +112,8 @@
|
||||
1. `SCHD-ADFT` 与 29 个 FLOP 子类型逐项列入覆盖矩阵，每项有对应的处理器规则与回归测试；未知类型可恢复失败。RESP/DNLD 不计入这批处理器，走 US-06。
|
||||
2. 每类固定“输入与前态 → 后态 → msg → schd → 终态”五面样例；区分字段缺失、显式清空、重复报文和主/共享航班。清单和 golden 样例按 Q8 补齐，不以“已写 29 个类”替代验收。
|
||||
3. 对按 KEEP 规则需忽略的不存在航班，以 `SUCCEEDED` 无副作用结束，并由 US-09 回填；ADFT 建航班等行为按各类型矩阵执行。航班当前态以自有 PG 为唯一权威，重启即恢复，不存在 Redis 全损后白名单无法找回的损坏路径。
|
||||
4. 共享航班更新与删除级联语义以 flight-state.md §3.3 为唯一规范（共享航班通知、主航班 `MAFL` 更新、级联删除、原子变更；不出现主已删、子残留）；本条目验收实现不偏离该规范，目标不存在时幂等成功。
|
||||
5. ADFT/FDEL 的值相等比较与半状态禁止规则见 flight-state.md §3.3。
|
||||
4. 共享航班更新与删除级联语义以 [flight-state.md](flight-state.md)「删除与重建」为规范（共享航班通知、主航班 `MAFL` 更新、级联删除、原子变更；不出现主已删、子残留）；本条目验收实现不偏离该规范，目标不存在时幂等成功。
|
||||
5. ADFT/FDEL 的值相等比较与半状态禁止规则见 [flight-state.md](flight-state.md)「删除与重建」。
|
||||
6. PSDT 通过 US-14 的只读映射计算 `abdg`，处理器不直接调用 admin-api。
|
||||
|
||||
**当前基础与落点**：落点已变为 `processing/DynamicProcessors.kt`（`FlopProcessor`/`FdelProcessor`/`AdftProcessor`）与 `domain/flight/FlightStateEngine`、`FlightStateRepository`。FDEL/ADFT 与通用 FLOP 处理器已接入（含 DELETED 幂等与重激活、tombstone 同事务登记）；29 类逐类语义矩阵与 golden 样例仍未补全，不能因处理器存在就视为覆盖完成。
|
||||
@@ -192,7 +192,7 @@
|
||||
|
||||
**当前基础与落点**：回填意图与处理终态同体同行（`PROC_STATE.BACKFILL_*`），随业务事务提交，`BACKFILL_TODO` 已随 V2 迁移下线；终态落库后回填一律由扫描驱动（`BackfillService.sweep` 每 30 秒、指数退避 30 秒起步封顶 15 分钟，处理关键路径不做跨库写），接收时间超过超期期限 `R` 时强制补写（§5.2）。死信同样可补写——回填只需消息 ID，不依赖 META。剩余：Q7 的标记值集与写权限书面确认；影子环境禁写尚未实装。
|
||||
|
||||
**前置**：US-03 终态接口；Q7、共享库更新权限。覆盖四类终态、事务回滚、重复补偿和重放竞争；生命周期、超期补写与清除口径以 [message-lifecycle.md](message-lifecycle.md) §4/§5.2/§6 为准。
|
||||
**前置**：US-03 终态接口；Q7、共享库更新权限。覆盖四类终态、事务回滚、重复补偿和重放竞争；生命周期与超期补写以 [design.md](design.md)「中断恢复」「回填」为准，清除口径以 [contracts.md](contracts.md)「保留与清除」为准。
|
||||
|
||||
### US-10 安全重放与故障处置
|
||||
|
||||
@@ -219,11 +219,11 @@
|
||||
1. 默认归档接收时间早于 1 天的 SUCCEEDED/SKIPPED/DEAD，保留期可配置 1～7 天；PENDING/FAILED 禁止归档。明确接收时间字段来源，不混用 UPDATED_AT 或本地入队时间。
|
||||
2. 归档到自有 PG `PROC_STATE_HST`；关联 `MSG_EVENT` 的历史目标和保留规则一并设计。仍有未完成投递、回填或恢复依赖时，不移除所需记录。
|
||||
3. 迁移与删除在自有库事务内完成，重复执行幂等；失败保留源记录并报告计数。归档后同信箱 ID/业务身份再次到达，仍能按约定去重。
|
||||
4. 本系统不写共享 MySQL `CMINMSGS_HST`、不清理外部信箱；由库方按 Q9 执行的清除与历史归档见 message-lifecycle.md §6。原文可用性与重放保留期由 Q7/Q8 关联确认。
|
||||
4. 本系统不写共享 MySQL `CMINMSGS_HST`、不清理外部信箱；由库方按 `Q9` 执行的清除与历史归档见 [contracts.md](contracts.md)「保留与清除」。原文可用性与重放保留期由 Q7/Q8 关联确认。
|
||||
|
||||
**当前基础与落点**：`PROC_STATE_HST` 未建表，也没有归档处理记录的作业；先确定去重记录保留与关联策略，再补迁移与归档中断测试。航班历史清理（`HistorySweepJob`，属 US-15 红线范围）与本文档处理记录归档不是同一件事，不能混为一谈。
|
||||
|
||||
**前置**：US-03、US-09；US-07 提供事件终态规则，US-10 提供恢复保留要求。不依赖 US-15。自有记录归档与信箱保留期的关系以 [message-lifecycle.md](message-lifecycle.md) §8/§9 为准。
|
||||
**前置**：US-03、US-09；US-07 提供事件终态规则，US-10 提供恢复保留要求。不依赖 US-15。自有记录归档见 [design.md](design.md)「维护作业与归档」，重放与原文可用性见 [design.md](design.md)「失败、重试与重放」。
|
||||
|
||||
### US-12 查询实时航班（KEEP）
|
||||
|
||||
@@ -275,7 +275,7 @@
|
||||
|
||||
历史存储确认成功后，才允许删除对应实时航班；逐条隔离坏数据，不能删除写历史失败的集合。判史规则与保留期（`HistoryProps`）、业务时区 `Asia/Shanghai`、历史写入与删除事件之间的恢复协议需在启用前完成 golden 对拍。
|
||||
|
||||
阶段 A 不依赖 ES，不启用 `PROJECTION_REBUILD`。`HistorySweepJob` 已作为每日清理脚手架接入，但历史存储未接通（或 `msgx.history.history-store-enabled=false`）时删除 0 条；脚手架存在不等于清场已交付，红线见 flight-state.md §6。
|
||||
阶段 A 不依赖 ES，不启用 `PROJECTION_REBUILD`。`HistorySweepJob` 已作为每日清理脚手架接入，但历史存储未接通（或 `msgx.history.history-store-enabled=false`）时删除 0 条；脚手架存在不等于清场已交付，红线见 [flight-state.md](flight-state.md)「生命周期与开放项」。
|
||||
|
||||
## 5. 运行与切流验收
|
||||
|
||||
@@ -302,22 +302,15 @@
|
||||
|
||||
这些是**阻塞相应实现的具体问题**，不是已完成的验收项。保留原有目标值，但不把矛盾或外部未确认内容写成事实。
|
||||
|
||||
| 编号 | 问题与当前口径 | 解除阻塞的产物 |
|
||||
|---|---|---|
|
||||
| Q1 权威存储（方向已定） | 当前 PG 单库权威，主表 + 无损明细；现场供库目标为 Oracle 11g。 | 单库决策已采纳，Oracle 完整适配与部署验收仍待交付；不得退回 Redis 双写。 |
|
||||
| Q2 入队顺序 | 空洞老化阈值取自"最大提交时延"，但库方尚未书面承诺 ID 单调与提交时延，因此迟提交不越序仍无端到端保证。取值可参照 SIS：报文在 CIIMS 的 `Expiry` 为 480 分钟，断连 120–480 分钟按 Level 2 处理，CIIMS 在成功接收或过期前保序保存（SIS §2.4.2.3.3、§3.16、§5.2）。 | 库方 ID/提交顺序约束，或明确的发现完整性与暂停/恢复协议；晚提交、空洞、兼容入口与重扫联合测试。不能凭空假定 ID 连续。 |
|
||||
| Q3 HTTP 契约 | 目标 ResponseDto 与现有 text/plain ID 不同；请求媒体类型目标已列出，错误码、状态码、查询格式等仍需对拍。 | 每个保留接口的真实请求/响应样例、错误表和契约测试；10MB 的字节口径、字符集及兼容变更说明一起固定。 |
|
||||
| Q4 Kafka wire | 当前 msg/schd 均按 `FLID` 逐航班发送（schd 由 `flushSchd` 合并为每个 FLID 的最新状态），与 legacy“多 FLID 数组”形态不同；msg 是否需按 `SNDR` 分区尚未接线。 | 下游确认发送粒度、key、去重标识放置、分区内顺序及批次确认策略；未定案前不改动现役消费契约。 |
|
||||
| Q5 请求匹配 | 目标优先 SEQN 回显，但回显是否可靠需确认；DTTM 降级存在跨代误匹配，尤其旧应答到达新请求期间。 | 15 类请求/响应样例、回显字段与时间格式；降级风险是否接受及拒绝条件。默认超时仍为 RQFD 60 秒、RQRD 30 秒。 |
|
||||
| Q6 deadline 与重放 | 入队时间作为稳定锚点会把长期排队消息计入滞留；历史重放保留 CREATED_AT 后可能立即过期。外部参照：SIS 报文 `Expiry` 480 分钟（SIS §3.16），legacy 现役按接收超 1 天归档并删除（legacy 基线 §3.6）。 | 明确首次处理/排队过期策略与“本次恢复尝试”计时方式，保留原始时间审计；测试积压恢复和旧 DEAD 重放，不用刷新 UPDATED_AT 绕过超时。 |
|
||||
| Q7 信箱外部契约 | 原目标为成功→SUCCESS、忽略→SKIPPED、重复→DUPLICATE、死信→DEAD；当前 JDBC 写 PROCESSED。新 STATUS 值尚不能假定库方支持。 | 库方认可的状态值、META/缺失字段、权限、原文保留期、出站去重与处理时间语义；若只允许 legacy 集合，显式映射内部原因，不新增外部枚举。 |
|
||||
| Q8 业务覆盖清单 | “29 FLOP、14 RQRD、21 参考类、2 机位类”只是数量，不能直接当字段规范。 | 将 SIS/XSD、现役 KEEP/FIX 基线整理为逐类矩阵与脱敏样例，列明路由、字段、缺失/清空、通知、数据来源优先级、多桥规则及测试文件。资料不全的类型不标完成。 |
|
||||
| Q9 信箱清除契约 | 清除由谁执行与 DDL 授权、方案 A/B 选型、现场 MySQL 版本与分区 DDL 能力（message-lifecycle.md §6）。 | 库方书面确认清除授权与方案选型。 |
|
||||
| Q10 出站信箱契约 | `COUTMSGS` 消费方与顺序、`COUTMSGS_ACK_DATE_RECV / COUTMSGS_ACK_RESEND_TIMES / COUTMSGS_DATE_SENT / COUTMSGS_ERROR` 等列语义与写入方、出站清理责任与去重契约（message-lifecycle.md §7；SIS §2.4.2.2.2、§2.4.2.2.4、§2.4.2.3）。 | 库方书面确认出站消费、清理与去重契约。 |
|
||||
| Q11 上游序号重置 | `SEQN` 的取值范围与回绕已由 SIS §2.8.1 定义（`Number(6)`、1–999999、由发送方设置），未知的是重置周期；它决定业务身份是否加入日期边界（design.md §2.2，默认关闭）。`SNDR` 取值域也需对拍：SIS 为 AODB/RMS，legacy 实发 OSH5 等。 | 上游确认重置周期与 `SNDR` 值域；身份算法变更须另行评审。 |
|
||||
| Q12 积压跳过授权 | 历史积压批次中“不再处理”的确认主体、审批留痕与跳过值集（message-lifecycle.md §5.3）。 | 业务与库方书面确认该批跳过范围；`PROC_STATE=SKIPPED` 记录原因并保留审计，不允许整段 DELETE。 |
|
||||
| Q13 日计划字段缺失语义 | SIS 要求最新日计划中未发送的可选字段视为 AODB 已无该数据、子系统应删除本地已有值（SIS §3.16 注释 4，RESP 同格式见 SIS §3.17），与现行"未携带字段保留"相反（flight-state.md §3.1、message-lifecycle.md §5.3）。 | 与 AODB/库方书面确认字段级删除语义；确认前不得按任一方向验收对拍差异。 |
|
||||
| Q14 主/共享删除顺序与 EROR | SIS 要求删主航班前先删子共享航班，顺序不符时 RMS 向 AODB 回发 EROR（SIS §1.6.1-1.d，事件定义 SIS §4.8）。现行设计为自动原子级联，未定义回报路径（flight-state.md §3.3）。 | 确认上游删除顺序约定，并选定"回发 EROR"或"幂等自动级联"；出站事件类型随之纳入 US-08 范围。 |
|
||||
**Q 台账已迁至 [contracts.md](contracts.md)「待确认事项台账」**（唯一出处，覆盖 Q1–Q16）。本文件只保留与验收直接相关的依赖关系，不重复问题正文：
|
||||
|
||||
- US-01 / US-09 的验收依赖 `Q2`（发现完整性）与 `C-8`（清除前提）；
|
||||
- US-06 / US-13 / US-14 依赖 `Q8`（逐类清单）与 `Q13`（字段缺失语义）；
|
||||
- US-08 依赖 `Q3`（HTTP 契约）、`Q4`（Kafka wire）、`Q5`（请求匹配）、`Q10`（出站契约）；
|
||||
- US-10 依赖重放白名单与 CLM-3（重放安全，见 [invariants.md](invariants.md)）；
|
||||
- US-15 依赖 `Q9`（清除授权与 DDL）。
|
||||
|
||||
编号、当前口径与解除阻塞产物的完整表述见 contracts.md。
|
||||
|
||||
业务日期/日计划采用 `Asia/Shanghai`；持久化与比较使用明确的时间类型和转换规则，不靠服务器默认时区，也不直接比较不同单位的数字。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user