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
+8 -8
View File
@@ -52,7 +52,7 @@
**验收标准**
1. 支持 `text/xml``application/xml``text/plain`,默认 UTF-8;空报文、超过 10MB 的请求和畸形 XML 返回规范错误,不落信。XML 校验禁用 DTD、外部实体与外部资源访问。
1. 支持 `text/xml``application/xml``text/plain`,默认 UTF-8;空报文、超过请求体上限(见 `C-28`的请求和畸形 XML 返回规范错误,不落信。XML 校验禁用 DTD、外部实体与外部资源访问。
2. 信箱确认落信后返回 ID;PG 入队失败不把已落信伪装成未接收,由 US-01 补建。信箱写入未确认时不返回成功。
3. 目标为兼容 `ResponseDto`;固定成功/失败样例、HTTP 状态码、响应媒体类型和错误码表后加入契约测试,见 Q3。成功只承诺信箱落信,不承诺业务处理或下游完成。
4. 生产保持内网信任边界,由网关限制来源并审计;外露或跨网络必须先落实认证,不能把免密入口直接暴露。
@@ -78,9 +78,9 @@
1. 只取最小未完成 ID`PENDING / FAILED` 均占队头;退避未到期不得越过。维护作业由独立线程执行,不参与消息 FIFO;作业必须有界,且不得因争用资源使已到期消息无限饥饿。
2. 安全解码 XML,至少覆盖 META、SCHD、FLOP、参考应答与忽略类路由;合法但能力未支持是 `UNSUPPORTED`,不能一律归为非法报文。保留原文以支持诊断和回放。
3. 解码后首次绑定 `SNDR|TYPE|STYP|SEQN`;冲突转 `SKIPPED` 并记录原 ID;自身重试保留绑定。生产 `include-day-boundary=false`,更改算法须另行评审上游序号规则
3. 解码后首次绑定 `SNDR|TYPE|STYP|SEQN`;冲突转 `SKIPPED` 并记录原 ID;自身重试保留绑定。生产 `PARAM:msgx.identity.include-day-boundary` 配置(当前口径不含日期边界);更改算法须先确认 `Q11`
4. `MALFORMED` 直接 `DEAD``CODEC_ERROR / UNSUPPORTED / INFRA` 按次数和退避处理,耗尽转 `DEAD(EXHAUSTED)`。不能无限重试未实现类型,也不能立即当非法报文丢弃。
5. 终态判据只有尝试上限(默认 5 次),**没有按时间的毒丸**;调度判断注入 `Clock`积压与人工重放的边界按 Q6 验证
5. 终态判据只有尝试上限(`PARAM:msgx.pipeline.max-attempts`),**没有按时间的毒丸**;调度判断注入 `Clock`。人工重放的可重放范围以 Q6 决定的 `R_keep` 下界为准
6. 主泵在同一 PG 事务提交航班主表/明细、事件与处理结果;终态回填意图通过 US-09 同事务保存。任一步失败整体回滚;提交后只重试外部回填,不重复生成业务事件。
7. 领域决策逻辑只读取当前完整态与已解码报文,返回下一完整态和待发事件,不执行 I/O;Processor 作为事务协调器,将状态写入、事件、处理终态与回填意图收敛在同一事务边界内,不直接触碰 Kafka。失败只在持有消息上下文的边界落账,中断向上传递,不作为普通失败吞掉。
8. 权威存储不可用或未完成恢复时停止业务处理;不能把“整个状态丢失”误判为“单航班不存在”而批量成功结束增量报文。
@@ -149,7 +149,7 @@
**验收标准**
1. `KAFKA:msg` 按目标内 `EVENT_ID` 顺序发送,确认后才标 `SENT`;队头退避时不跳过,发送有超时上限。
2. `KAFKA:schd` 只通过 `flushSchd` 聚合,默认 3 秒/500 条;同一 FLID 取批内最新状态,成功确认覆盖对应原事件,失败保持批次可恢复并退避,耗尽可见为 `DEAD`
2. `KAFKA:schd` 只通过 `flushSchd` 聚合,聚合周期与批上限见 reference;同一 FLID 取批内最新状态,成功确认覆盖对应原事件,失败保持批次可恢复并退避,耗尽可见为 `DEAD`
3. 外部接收成功、本地确认失败或进程重启后允许重发;事件标识跨重发稳定,消费者有去重约定,不宣称端到端恰好一次。
4. 当前 `KAFKA:msg``KAFKA:schd` 的分区键均为 `FLID`schd 逐 `FLID` 发送最新状态,不再是 legacy 的多航班数组。`msg` 是否需按 `SNDR` 分区、发送粒度与去重标识的放置以 Q4 定案为准;定案前不宣称单分区之外的顺序保证。
5. 生产强制 `acks=all``enable.idempotence=true``max.in.flight.requests.per.connection=1`;Broker 支持幂等生产协议并完成实际验证,不允许非幂等降级通过验收。
@@ -190,7 +190,7 @@
4. 重复补偿效果幂等,保留稳定的完成时间与审计;重放后的新处理结果不能被旧回填任务覆盖。非法报文缺 META 时也有明确回填方式。
5. 影子模式禁写,双跑仅一个系统持有标记写权;暴露 PG 终态、回填状态、积压、最老年龄与持续失败告警。
**当前基础与落点**:回填意图与处理终态同体同行(`PROC_STATE.BACKFILL_*`),随业务事务提交,`BACKFILL_TODO` 已随 V2 迁移下线;终态落库后回填一律由扫描驱动(`BackfillService.sweep` 每 30 秒、指数退避 30 秒起步封顶 15 分钟,处理关键路径不做跨库写),接收时间超过超期期限 `R` 时强制补写(§5.2)。死信同样可补写——回填只需消息 ID,不依赖 META。剩余:Q7 的标记值集与写权限书面确认;影子环境禁写尚未实装。
**当前基础与落点**:回填意图与处理终态同体同行(`PROC_STATE.BACKFILL_*`),随业务事务提交,`BACKFILL_TODO` 已随 V2 迁移下线;终态落库后回填一律由定时扫描驱动(`BackfillService.sweep`,扫描周期与退避取值见 [reference.md](reference.md);独立退避键尚未落地 `[G-BACKFILL-BACKOFF]`),处理关键路径不做跨库写;本地入队时间(`ENQUEUED_AT`超过超期期限 `R` 时强制补写(见 design「回填」)。死信同样可补写——回填只需消息 ID,不依赖 META。剩余:Q7 的标记值集与写权限书面确认;影子环境禁写尚未实装。
**前置**:US-03 终态接口;Q7、共享库更新权限。覆盖四类终态、事务回滚、重复补偿和重放竞争;生命周期与超期补写以 [design.md](design.md)「中断恢复」「回填」为准,清除口径以 [contracts.md](contracts.md)「保留与清除」为准。
@@ -216,10 +216,10 @@
**验收标准**
1. 默认归档接收时间早于 1 天的 SUCCEEDED/SKIPPED/DEAD,保留期可配置 17 天;PENDING/FAILED 禁止归档。明确接收时间字段来源,不混用 UPDATED_AT 或本地入队时间
1. 终态记录在入队后经过的时间(`ENQUEUED_AT`)达到 `PARAM:msgx.proc-state.archive-after` 时列为归档候选;PENDING/FAILED 禁止归档
2. 归档到自有 PG `PROC_STATE_HST`;关联 `MSG_EVENT` 的历史目标和保留规则一并设计。仍有未完成投递、回填或恢复依赖时,不移除所需记录。
3. 迁移与删除在自有库事务内完成,重复执行幂等;失败保留源记录并报告计数。归档后同信箱 ID/业务身份再次到达,仍能按约定去重。
4. 本系统不写共享 MySQL `CMINMSGS_HST`、不清理外部信箱;由库方按 `Q9` 执行的清除与历史归档见 [contracts.md](contracts.md)「保留与清除」。原文可用性与重放保留期由 Q7/Q8 关联确认。
4. 本系统不写共享 MySQL `CMINMSGS_HST`、不清理外部信箱;由库方按 `Q9` 执行的清除与历史归档见 [contracts.md](contracts.md)「保留与清除」。原文可用性与重放保留期由 Q6/Q7 关联确认。
**当前基础与落点**`PROC_STATE_HST` 未建表,也没有归档处理记录的作业;先确定去重记录保留与关联策略,再补迁移与归档中断测试。航班历史清理(`HistorySweepJob`,属 US-15 红线范围)与本文档处理记录归档不是同一件事,不能混为一谈。
@@ -231,7 +231,7 @@
**验收标准**
1. 保留 `GET /all/flights`,直接从自有 PostgreSQL `FLIGHT_SCHD` 查询,过滤 `MAID != NULL` 的共享航班;不改写业务状态。
1. 保留 `GET /all/flights`,直接从自有 PostgreSQL `FLIGHT_SCHD` 查询,排除共享航班(`MAID != NULL`,定义见 [flight-state.md](flight-state.md)「字段与集合」);不改写业务状态。
2. 固定响应样例、空结果、排序、大小限制及一致性时点。现役未分页时不能无声改为只返回第一页;分页或响应结构变更按 Q3 决定。
3. 依赖异常不能伪装为空数组成功;影子只读影子状态,入口有约定的访问控制、限流与审计。