docs(acm2-52): 修正跨文档事实冲突 F1–F9 与错引编号

- F1/F6 HTTP 契约:C-28 目标 ResponseDto + 请求体上限暂定 10MB,Q3 指向 C-28
- F2 legacy 与 SIS 的优先级限定;F3 超期判据对齐 ENQUEUED_AT;F4 改引 D1
- F5 参数默认值改引 reference/PARAM;F7 补 4 条契约状态词;F8 定义 MAID/MAFL 并明确排除共享航班;F9 补 INV-20
- N1/N2 错配编号改引;N3 迁移链指针;N4/M5 白名单补 D-x/OPS-x;N6 补 INV-16/17 映射;N7 加粗规则
- M1 回填退避事实与论证;M2 Q6/Q7;M4 Q4 假定标注;M7 去复述
纯文档,不改代码/迁移/配置/legacy。
This commit is contained in:
windyboy
2026-09-12 09:57:26 +08:00
parent 817236ca26
commit 69c2cf219f
8 changed files with 34 additions and 30 deletions
+5 -5
View File
@@ -24,7 +24,7 @@
| 记录 | 用途 | 关键约束 |
|---|---|---|
| `PROC_STATE` | 入站消息的处理状态、身份、尝试次数、错误原因与回填事实 | `MSG_ID = CMINMSGS_ID` 主键防重复入队;`IDENTITY_KEY` 唯一约束防业务重复;按最小未完成 `MSG_ID` 取队头;`BACKFILL_NEXT_AT` 非空 = 还欠一次回填,`BACKFILL_AT` 非空 = 标记已确认,`BACKFILL_ABANDONED_AT/REASON` 非空 = 已停止自动重试(**不等于**标记已确认);`RECEIVED_AT` 复制自信箱接收时间、**可能为 NULL**、仅用于对账与展示;`ENQUEUED_AT` 是本地入队时间、非空、是超期判据的唯一依据。 |
| `MSG_EVENT` | 等待投递的事件(outbox) | `EVENT_ID` 决定投递顺序(全局串行分配,见投递);`TARGET` 区分 `KAFKA:msg` / `KAFKA:schd``PARTITION_KEY` 恒为 `FLID``EVENT_TYPE` 区分 UPSERT 与 TOMBSTONE。`KAFKA:schd``FLID` 单行 upsert,只保留最新 `STATE_VERSION`。 |
| `MSG_EVENT` | 等待投递的事件(outbox) | `EVENT_ID` 决定投递顺序(全局串行分配,见投递);`TARGET` 区分 `KAFKA:msg` / `KAFKA:schd``PARTITION_KEY` 当前取 `FLID``Q4` 定案前为假定,见 `C-29``EVENT_TYPE` 区分 UPSERT 与 TOMBSTONE。`KAFKA:schd``FLID` 单行 upsert,只保留最新 `STATE_VERSION`。 |
| `REQ_TRACK` | 上游请求及应答关联 | 状态 `PENDING / SENT / DONE / EXPIRED`;保存请求类型、覆盖运营日、发送方、出站信箱 ID 与发送/完成时间;**「同类只允许一个开放请求」的唯一键 = `(请求类型, 覆盖运营日, 发送方)`,且仅对开放状态生效**。登记、超时与应答匹配尚未实现 `[G-REQ-TRACK]`。 |
| `REF_MASTER` | 静态参考数据(目标表) | `(RTYPE, RKEY)` 唯一;尚未建表,客户端与刷新流程见 user-stories US-13/US-14US-14 两类映射的存储落点未定。 |
| `FLIGHT_SCHD` | 航班标量及单值异常字段 | `FLID` 主键;`OPERATION_DAY` 一经确定不可变;版本与最近消息 ID 用于追踪。变长集合存于 8 张资源明细表与 `FLIGHT_ROUTE_POINT`,规则见 flight-state.md。 |
@@ -32,13 +32,13 @@
| `SCHD_SNAP_LOG` | 日计划处理留痕 | 只追加、可重建,不参与状态决策;保留期见 reference。 |
| `PROC_STATE_HST` | 终态处理记录的归档目标 | 尚未建表 `[G-PROC-HST]`;只归档到自有 PG 的目标表,不落共享库历史表。 |
字段与索引以 `src/main/resources/db/migration/` 下的 V1 基线为准(Oracle 11g 目录为占位,未接入 Flyway)。报文原文仍从共享信箱读取,原文保留期必须覆盖处理与重放窗口(`C-7`)。
字段与索引以 `src/main/resources/db/migration/` 的迁移链为准(Oracle 11g 目录为占位,未接入 Flyway)。报文原文仍从共享信箱读取,原文保留期必须覆盖处理与重放窗口(`C-7`)。
## 2. 消息、身份与决策
`XmlCodec`(实装 `JacksonXmlCodec`)把 XML 解码为 `DecodedMessage`,包含 `SNDR / TYPE / STYP / SEQN / DTTM` 元数据、`MsgKind` 与业务载荷。解码失败区分 `MALFORMED`(报文非法,不重试)与可随 codec 修复的 `CODEC_ERROR``MsgKind` 是一等分派键:`Schd(RESP/DNLD/ADFT)``Flop``Fdel``Unsupported`
业务身份统一由 `Identity.of` 生成:`SNDR | TYPE | STYP | SEQN`。接收时只按信箱 ID 去重,解码后才首次绑定业务身份;重试保留原有绑定,因此自身重试不会被判为重复。身份被另一条记录占用时,当前消息转 `SKIPPED`,记录 `duplicate-of:<id>`。是否加入日期边界取决于上游 `SEQN` 重置周期(见 `C-20`/`Q11`,默认关闭;上线后不能随意更换身份算法。
业务身份统一由 `Identity.of` 生成:`SNDR | TYPE | STYP | SEQN`。接收时只按信箱 ID 去重,解码后才首次绑定业务身份;重试保留原有绑定,因此自身重试不会被判为重复。身份被另一条记录占用时,当前消息转 `SKIPPED`,记录 `duplicate-of:<id>`。是否加入日期边界取决于上游 `SEQN` 重置周期(见 `C-20`/`Q11``PARAM:msgx.identity.include-day-boundary`);上线后不能随意更换身份算法。
**身份绑定是独立的幂等单语句**`WHERE IDENTITY_KEY IS NULL`),不参与业务事务。它的前提是「报文不可变」(`PRE-7`):同一身份的重发不会被比对内容,若上游改发正文会被判为重复并跳过(`Q15`)。
@@ -218,7 +218,7 @@ LIMIT PARAM:msgx.pipeline.backfill-batch
1. **取消退避**:已终态但超期未打标的行,每轮扫描都被尝试,不再等退避到期;
2. **暂时性故障的放弃期限**:超时、连接失败这类暂时性故障**在 `R` 之前只退避重试、不放弃**;到 `R` 仍未打标才停止自动重试、记入放弃清单并告警。
放弃判据用**时间**而不是**尝试次数**:按退避表(档位 ≤ 8 秒)与扫描周期,固定次数的实际上限只有几十分钟,一次小时级的共享库故障会把全部待回填行一次性判死,随后必须成批人工恢复——这是必须避免的失败模式。`PARAM:msgx.pipeline.backfill-max-attempts` 因此不再是放弃判据,只保留为单行重试的告警阈值
放弃判据用**时间**而不是**尝试次数**:固定次数不能稳定表达允许的故障持续时间,因此按 `R` 判断放弃,`PARAM:msgx.pipeline.backfill-max-attempts` 只用于告警
关于「最终一定打标」,准确表述是三段,缺一不可:
@@ -322,7 +322,7 @@ PENDING → SENT → DONE
`JobRunner` 用独立 daemon 线程按周期触发回填扫描、航班历史清理与留痕清理;作业不参与消息 FIFO,也不使到期消息饥饿。`INV-18` 要求历史清理的删除与主泵处理互斥。
- **航班历史清理**:按保留期与终态/静默判据选候选(含 `DELETED`),先写历史存储,成功后物理删除主行与明细;历史存储未接通或开关关闭时删除 0 条。未经 FDEL、由生命周期直接清除的航班,清除前补发一次删除事件。语义与红线见 flight-state.md。
- **航班历史清理**:按 reference 的历史判据选候选(含 `DELETED`),先成功归档再删除;未经 FDEL生命周期清除需先补发删除事件。语义与红线见 flight-state.md。
- **留痕清理**`SCHD_SNAP_LOG` 按保留期与 `(SCOPE_END, RECV_AT)` 删除,不依赖历史存储开关。
- **处理终态归档**`PROC_STATE` 终态记录归档至 `PROC_STATE_HST`(尚未建表 `[G-PROC-HST]`)。归档范围只含终态;归档后仍须保留业务去重能力。
- **出站事件清理**:见投递清理规则。