docs: message-lifecycle 审查修正——消解跨文档冲突、口径归口并登记 Q12

message-lifecycle.md:
- §5.3 日计划改为现行合并语义(缺席不删、缺失保留,引 flight-state §3.1),类型粒度统一 TYPE-STYP
- §5.1 明确两条扫描路径按 ID 区间取行、不以处理标记为谓词;水位定义与 Q2 绑定
- §4 两个缺口改与 design §10 同措辞;§5.2 的 R 构成挂 Q6/Q9,新增 Q12 积压跳过授权
- §6 方案 B 对账补“只补缺失行、标记单调不回退”;删除能力声明标注待 Q9 确认
- §7 改为“尚未实现”、统一 COUTMSGS_* 列名;§11 ID 不断链改为条件式不变量

user-stories.md:US-11 第 4 条限定为“本系统不写共享历史表/不清除外部信箱”;US-01 扫描谓词指向 lifecycle §5.1;US-01/09/11 前置补口径指针;新增 Q12;OPS-2 补积压与最老未处理信龄;Q10 列名统一。

architecture.md:共享 MySQL 红线限定主体;§6 中断恢复表改为指向 message-lifecycle §4;收报步骤补扫描谓词指针。

design.md:水位定义、回填死信处理、维护作业、归档、缺口恢复统一指向 message-lifecycle。

README.md:核对日期更新至 2026-09-10(代码基线 99a0f5f,文档基线 328bbf8);维护规则补规范类文档一档。
This commit is contained in:
windyboy
2026-09-10 09:00:53 +08:00
parent 328bbf88d2
commit ffd3abd655
5 changed files with 48 additions and 49 deletions
+9 -8
View File
@@ -4,7 +4,7 @@
本文定义阶段 A 的实施范围与验收口径:**故事定义要交付什么,验收标准定义怎样证明完成,代码落点说明从哪里改起**。保留 US-01US-15、OPS-1OPS-4 编号,便于关联已有任务和测试。
- 系统边界见 [architecture.md](architecture.md),模块流程见 [design.md](design.md)。本文不重复设计全文,也不以工单状态代替代码验收。
- 系统边界见 [architecture.md](architecture.md),模块流程见 [design.md](design.md)。本文不重复设计全文,也不以工单状态代替代码验收。消息生命周期与信箱清除见 [message-lifecycle.md](message-lifecycle.md),航班规则见 [flight-state.md](flight-state.md)。
- “当前基础”来自本轮代码核对,只表示有接口或部分实现,不表示故事完成。`KEEP` 是保留业务兼容,`FIX` 是明确修正旧缺陷,`DEFERRED` 不进入阶段 A。
- “信箱落信、PG 入队、业务处理完成、信箱回填、下游确认”是五个独立事实,接口、日志和测试必须分开表达。
- 所有内部迁移只落自有 PG;共享 MySQL 不建表、不增列、不写历史表。本文用 `DATE_PROCESSED / STATUS` 表示逻辑字段,实际列名以库方契约为准。
@@ -36,7 +36,7 @@
**验收标准**
1. 按配置周期、ID 升序、有限批次采集未处理记录;接收层只入队,不解析业务、不回填已处理标记。
1. 按配置周期、ID 升序、有限批次采集信箱行;扫描谓词以 message-lifecycle.md §5.1 为准(按 ID 区间,不以处理标记为谓词)。接收层只入队,不解析业务、不回填已处理标记。
2. 按信箱 ID 幂等建立 PG `PENDING`;重复扫描、并发兼容入队和进程重启都不能重置已有终态。
3. 快路径用持久水位,补偿路径受控重扫遗漏;本批 PG 入队全部确认后才推进水位。补偿可分页推进,不能被已入队但尚未回填的前一批永久挡住。
4. PG 不可用或批次中途失败时不改信箱标记;恢复后补建遗漏,记录失败次数与扫描进度。
@@ -44,7 +44,7 @@
**当前基础与落点**`ingress/InboxPoller.kt``InboxEnqueue.kt``infra/persistence/jdbc/JdbcCminmsgInboxRepository.kt` 已有轮询与判重;固定 `afterId=0` 全量扫描,水位与补扫策略未实现(每轮顺带对账回填待办,见 US-09)。扩展 `InboxPollerTest`,补真实 PG/MySQL 中断恢复测试。
**前置**:共享库读契约;Q2 决定严格顺序的端到端验收。
**前置**:共享库读契约;Q2 决定严格顺序的端到端验收。水位与扫描谓词口径以 [message-lifecycle.md](message-lifecycle.md) §5.1 为准。
### US-02 兼容 HTTP 注入报文(KEEP
@@ -192,7 +192,7 @@
**当前基础与落点**:回填意图已在业务事务内预登记到自有 `BACKFILL_TODO`;提交后同步回填(写 `DATE_PROCESSED``PROCESSED`),失败由 `BackfillSweepJob` 到期重试(每 30 秒、指数退避)。剩余缺口:缺 META 或解码失败的死信回填方式,以及“待办落账后再失败 / 提交后崩溃”两个窗口的补偿闭环。
**前置**:US-03 终态接口;Q7、共享库更新权限。测试覆盖四类终态、事务回滚、重复补偿和重放竞争。
**前置**:US-03 终态接口;Q7、共享库更新权限。覆盖四类终态、事务回滚、重复补偿和重放竞争;生命周期、超期补写与清除口径以 [message-lifecycle.md](message-lifecycle.md) §4/§5.2/§6 为准
### US-10 安全重放与故障处置
@@ -219,11 +219,11 @@
1. 默认归档接收时间早于 1 天的 SUCCEEDED/SKIPPED/DEAD,保留期可配置 17 天;PENDING/FAILED 禁止归档。明确接收时间字段来源,不混用 UPDATED_AT 或本地入队时间。
2. 归档到自有 PG `PROC_STATE_HST`;关联 `MSG_EVENT` 的历史目标和保留规则一并设计。仍有未完成投递、回填或恢复依赖时,不移除所需记录。
3. 迁移与删除在自有库事务内完成,重复执行幂等;失败保留源记录并报告计数。归档后同信箱 ID/业务身份再次到达,仍能按约定去重。
4. 不写共享 MySQL `CMINMSGS_HST`不清理外部信箱;原文可用性与重放保留期由 Q7/Q8 关联确认。
4. 本系统不写共享 MySQL `CMINMSGS_HST`不清理外部信箱;由库方按 Q9 执行的清除与历史归档见 message-lifecycle.md §6。原文可用性与重放保留期由 Q7/Q8 关联确认。
**当前基础与落点**`PROC_STATE_HST` 未建表,也没有归档处理记录的作业;先确定去重记录保留与关联策略,再补迁移与归档中断测试。航班历史清理(`HistorySweepJob`,属 US-15 红线范围)与本文档处理记录归档不是同一件事,不能混为一谈。
**前置**US-03、US-09US-07 提供事件终态规则,US-10 提供恢复保留要求。不依赖 US-15。
**前置**US-03、US-09US-07 提供事件终态规则,US-10 提供恢复保留要求。不依赖 US-15。自有记录归档与信箱保留期的关系以 [message-lifecycle.md](message-lifecycle.md) §8/§9 为准。
### US-12 查询实时航班(KEEP
@@ -282,7 +282,7 @@
| 编号 | 必须交付的能力 | 验证证据 |
|---|---|---|
| OPS-1 单写者与启动安全 | 生产缺真实适配器、误用 stub、未启用必需管道时拒启;第二活动写者不能启动,失去写权后不得继续写;中断与停机能正确退出。 | 配置拒启、双实例/失去写权及停机测试。单靠副本数配置不算运行期保护。 |
| OPS-2 可观测与安全 | 真实依赖健康、队列/队头年龄、投递/回填滞后、DEAD 和一致性异常有指标、告警与处理入口;敏感管理操作有访问控制,日志不泄漏口令或完整敏感报文。 | 故障注入触发真实告警,消息到事件可关联;日志出口断开不阻塞业务。 |
| OPS-2 可观测与安全 | 真实依赖健康、队列/队头年龄、投递/回填滞后、积压与最老未处理信龄、DEAD 和一致性异常有指标、告警与处理入口;敏感管理操作有访问控制,日志不泄漏口令或完整敏感报文。 | 故障注入触发真实告警,消息到事件可关联;日志出口断开不阻塞业务。 |
| OPS-3 影子隔离 | 自有数据库/schema、topic、服务注册身份隔离;输入只读水位或回放,禁生产回填、真实出站和误注册。 | 配置与集成测试证明生产信箱、状态、topic 未被影子修改。 |
| OPS-4 切流与恢复 | 对拍不少于 7 天,未解释业务字段差异为 0,DLQ 积压为 0MSG_EVENT 最老滞留 < 5 秒;切流后 48 小时观察,24 小时内具备经演练的回滚能力。 | 明确负载与统计口径的对拍报告;Runbook 含停写、排空/水位、状态恢复、写权交接和失败回退,不能只回滚程序版本。 |
@@ -313,8 +313,9 @@
| 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` 消费方与顺序、`ACK_DATE_RECV / DATE_SENT / ERROR` 等列语义与写入方、出站清理责任与去重契约(message-lifecycle.md §7legacy 参考见 SIS 规范 COUTMSGS 机制章节)。 | 库方书面确认出站消费、清理与去重契约。 |
| Q10 出站信箱契约 | `COUTMSGS` 消费方与顺序、`COUTMSGS_ACK_DATE_RECV / COUTMSGS_ACK_RESEND_TIMES / COUTMSGS_DATE_SENT / COUTMSGS_ERROR` 等列语义与写入方、出站清理责任与去重契约(message-lifecycle.md §7legacy 参考见 SIS 规范 COUTMSGS 机制章节)。 | 库方书面确认出站消费、清理与去重契约。 |
| Q11 上游序号重置 | 上游 `SEQN` 重置规则决定业务身份是否加入日期边界(design.md §2.2,默认关闭)。 | 上游确认重置规则;身份算法变更须另行评审。 |
| Q12 积压跳过授权 | 历史积压批次中“不再处理”的确认主体、审批留痕与跳过值集(message-lifecycle.md §5.3)。 | 业务与库方书面确认该批跳过范围;`PROC_STATE=SKIPPED` 记录原因并保留审计,不允许整段 DELETE。 |
业务日期/日计划采用 `Asia/Shanghai`;持久化与比较使用明确的时间类型和转换规则,不靠服务器默认时区,也不直接比较不同单位的数字。