From 72c282bcffd578d3e07873be57b5885e89e49129 Mon Sep 17 00:00:00 2001 From: windyboy Date: Wed, 16 Sep 2026 10:32:27 +0800 Subject: [PATCH] =?UTF-8?q?docs(acm2-75):=20=E6=8C=89=E5=A4=8D=E5=AE=A1?= =?UTF-8?q?=E7=BB=93=E8=AE=BA=E4=BF=AE=E6=AD=A3=E6=8A=95=E5=BD=B1=E5=8F=AF?= =?UTF-8?q?=E8=A7=81=E6=80=A7=E3=80=81=E9=87=8D=E5=A4=8D=E8=BA=AB=E4=BB=BD?= =?UTF-8?q?=E4=B8=8E=E5=9B=9E=E9=80=80=E4=BA=A4=E6=8E=A5=E5=8F=A3=E5=BE=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/architecture.md | 2 +- docs/contracts/interface-contract.md | 2 +- docs/specification.md | 27 ++++++++++++++------------- 3 files changed, 16 insertions(+), 15 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index bb17464..162c794 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -76,7 +76,7 @@ delivery 投递 jobs 作业：回填 / 出站重试 / 历史清理 / | 类别 | 与主干的差异 | 完成判据 | 失败时 | |---|---|---|---| | 日计划（`DNLD`/`RESP`） | 第 3 步改为每批一个事务，第 5 步在整包完成后 | 整包成功，含 Redis 刷新（`US-07` AC4/AC5） | 不标记已处理，下轮整包重处理（`US-07` AC4） | -| 静态参考数据 | 无第 4 步；一个事务完成落库、终态与回填意图 | 该类落库成功（`US-13` AC2） | 校验不过整类不动，其他类照常（`US-13` AC2） | +| 静态参考数据 | 无第 4 步；一个事务完成落库、终态与回填意图 | 该类落库成功（`US-13` AC1/AC5） | 校验不过整类不动，其他类照常（`US-13` AC2） | | 出站请求 | 不走收报队列：登记新请求并作废同子类型旧请求；`RQRD` 与 `RQFD` 各自最多一条在途，后续请求待前一条结案再写入 `COUTMSGS` | 请求已写入信箱（`US-09` AC1） | `jobs` 按 `REQ_TRACK` 重试仍有效且确认未落信的请求；写入结果不明时记录并告警，不直接重发；交付承诺只到落信（`C-24`） | | 航班历史清理（作业） | 不走消息队列：历史写入成功后物理删除 | 实时数据已删（`US-14` AC3） | 历史写不成功不删，下轮重来（`US-14` AC3） | diff --git a/docs/contracts/interface-contract.md b/docs/contracts/interface-contract.md index 53e5b9a..c0591b0 100644 --- a/docs/contracts/interface-contract.md +++ b/docs/contracts/interface-contract.md @@ -127,7 +127,7 @@ AODB 经 CIIMS adapter 把 XML 报文写入 `CMINMSGS`，格式以架构指定 ## 待决事项 -由本系统与需求方确定的事项见 [specification.md](../specification.md)「本系统与需求方待决」（`Q17`～`Q19`）。 +由本系统与需求方确定的事项见 [specification.md](../specification.md)「本系统与需求方待决」。 ## 定稿所需证据 diff --git a/docs/specification.md b/docs/specification.md index dbc46dd..8991628 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -18,7 +18,7 @@ | 处理标记 | 信箱行上表示已处理的值。读取条件是「处理时间为空」；处理完成时写入完成时刻。本系统只填空值，不回撤、不覆盖。 | | 落信 | 报文写入信箱成为一行；入站由 CIIMS adapter 或兼容入口写入，出站由本系统写入 `COUTMSGS`；入站报文写进信箱后可能尚未登记。 | | 登记 | 本系统在自有 PG 为这条报文建立处理记录，排队等待处理。 | -| 处理完成 | 该消息的全部本地副作用已持久化、对外投影（若有）已写成功；此后才允许回填与投递（`US-03` AC4）。判据按类别：航班增量与删除＝写入自有 PG 且 Redis 投影成功（`US-05` AC4、`US-06` AC1）；日计划＝整包写入完成且按快照刷新 Redis（`INV-31`）；静态参考数据＝该类落库成功，无投影步骤（`US-13` AC2）；非法或不支持的报文＝终态留档，无业务副作用（`US-03` AC2）。 | +| 处理完成 | 该消息的全部本地副作用已持久化、对外投影（若有）已写成功；此后才允许回填与投递（`US-03` AC4）。判据按类别：航班增量与删除＝写入自有 PG 且 Redis 投影成功（`US-05` AC4、`US-06` AC1）；日计划＝整包写入完成且按快照刷新 Redis（`INV-31`）；静态参考数据＝该类落库成功，无投影步骤（`US-13` AC1/AC5）；非法或不支持的报文＝终态留档，无业务副作用（`US-03` AC2）。 | | 回填 | 把处理标记写回信箱行。 | | 投递 | 读待发事件发 Kafka。 | | Redis 投影 | 供页面与 `GET /all/flights` 查询的航班数据；只由本系统写入和移除，不作权威。 | @@ -43,13 +43,12 @@ - **C-9** 清除的方案与 DDL 授权由库方定，本系统不参与选型。`（待确认 Q9）` - **C-10** 信箱时间列由写入方写入，其时钟基准须可解释（`PRE-4`）。 待确认：时区与允许偏斜（`Q7`）。 -- **C-12** 原文被提前清除时，本系统不补造原文，也不把这类消息当成功：原文不可得即无法处理，按不可处理的死信处置并告警（`US-03` AC2），队头不因不可恢复的消息永久停滞（`INV-3`）；信箱行一并消失时只能靠告警与对账发现。 - 待确认：是否在自有 PG 留存入站原文副本作为恢复依据（`Q22`）。`（本系统单方承诺）` +- **C-12** 原文被提前清除时，本系统不补造原文，也不把这类消息当成功。已登记的消息无法解码，也不能按 `US-03` AC2 判为非法——原文不可得不等于报文非法；未定前按处理失败保持未完成并告警（`US-03` AC3），队头因此阻塞是显式接受的代价，处置口径待 `Q22` 定案。信箱行在登记前整行消失时，扫描谓词对该行不可见，本系统无法发现其存在；防线只剩 `C-7` 的保留期下界由库方遵守（`Q9`）。`（本系统单方承诺）` - **C-14** 本系统不建表、不改表结构、不迁移 schema、不清数据，也不写共享历史表。 - **C-15** 处理标记只在空值上写入处理完成时刻，写完不回撤、不覆盖已有值。`（本系统单方承诺）` - **C-16** 回填失败的行保留记录并告警，记录在对应信箱行被清除前保持可查。`（本系统单方承诺）` - **C-30** 信箱读取口径：按配置周期读取「处理时间为空」的行，按编号升序、每批有上限；单活动实例运行，不引入并行消费者。 -- **C-34** 切换与回退以信箱处理标记交接（`OPS-4`、`PRE-1`）：切回旧系统前，已终态消息的回填必须了结——标记写上，或放弃行经人工对账确认；否则「处理时间为空」的行会被旧系统再处理一次，产生第二次业务效果。已登记、未到处理完成的消息没有跨系统幂等保障。 +- **C-34** 切换与回退以信箱处理标记交接（`OPS-4`、`PRE-1`）：切回旧系统前，「已终态且已回填」必须清零——标记写上的行才算交接完成。放弃自动重试的行标记仍为空（放弃不等于标记已确认），本系统没有任何能阻止旧系统消费它的可观察状态（`C-15` 只填空值、不覆盖）：必须先人工恢复重试至打标，或与库方另行定处置（`Q9`）；否则这些行切回后会被旧系统再处理。已登记、未到处理完成的消息同样没有交接状态。 待确认：在途消息的回退处置（`Q21`）。 ### 2.2 上游（AODB / SIS） @@ -78,6 +77,7 @@ - **C-31** admin-api 直接读取本系统写入的静态参考数据表；本系统不调用 admin-api，也不从它拉取、补全或合并数据。 - **C-32** Redis 航班投影的读取口径：网页客户端与 `GET /all/flights` 读同一份投影，返回当前全部动态航班（不含共享航班）、不分页；投影只由本系统写入和移除，不是权威、也不存处理状态；Redis 异常时报错，不返回空列表（`INV-24`）。 待确认：投影 key/value 结构与网页客户端读取约定（`Q20`）。 +- **C-35** 测试环境的实例使用独立的数据库、Redis 与 Kafka 主题，不连接生产信箱（`OPS-3`）。`（本系统单方承诺）` ### 2.5 已作废条款 @@ -114,10 +114,10 @@ - **INV-6** 处理终态不可逆：已提交的成功不因回填或投递失败回改。 - **INV-7** 处理标记单调：任何路径只把空标记写成已处理值，不回撤、不覆盖。 - **INV-8** 回填只针对已有终态的消息；「还欠一次回填」与终态由同一条语句落库，不存在第二处落账。 -- **INV-9** 一信一行、一身份一记录：处理记录按信箱编号唯一，同一业务身份至多绑定一条有效记录。第二个携带相同身份的信箱行按重复跳过留档：`PRE-7` 下同身份重发是同一内容，跳过不丢业务效果；`Q11`/`Q15` 定案前跳过是唯一与 `PRE-7` 相容的处置。 +- **INV-9** 一信一行、一身份一记录：处理记录按信箱编号唯一，同一业务身份至多绑定一条有效记录。再次发现同一身份的信箱行时不得直接跳过：须与既有记录比对内容，一致才按重复跳过留档（`PRE-7`：重发是同一内容）；不一致即 `PRE-7` 失效信号，留档、告警、不产生业务效果，处置待 `Q15` 定案。 - **INV-10** 对外投递至少一次；端到端恰好一次不在交付范围。 - **INV-16** 回填与 Kafka 投递失败可重试，不回滚已提交的本地业务结果；出站请求写入结果不明时记录告警、不直接重发（`C-24`）。 -- **INV-17b** 状态变更与待发事件在同一事务提交；处理终态与回填意图在另一事务提交，且晚于 Redis 投影写成功。待发事件在处理完成前不可投递（`US-03` AC4）。日计划的分批与静态参考数据的单事务见架构「主流程」。 +- **INV-17b** 航班类消息（增量、删除）的状态变更与待发事件在同一事务提交；处理终态与回填意图在另一事务提交，且晚于 Redis 投影写成功。待发事件在处理完成前不可投递（`US-03` AC4），本句对所有类别生效。日计划的分批与静态参考数据的单事务见架构「主流程」。 - **INV-19** 日计划整包校验失败时整包不落地，既有状态与版本不变（`US-07` AC1）。运营日冲突时的处置未在需求与架构定案（`Q23`）。 - **INV-20b** 处理器幂等（目标不变量，被 `G-FLOP-IDEMPOTENT` 阻断，当前不成立）：同一消息在失败重处理与重复发现下都只产生一次业务效果。身份唯一只防「重复记录」，不防「重新执行」；逐类幂等规则补齐并回归前，依赖本条的收敛声明（`CLM-3`、`INV-31`）都不可作出。 - **INV-30** 非法报文进死信、合法但不支持的类型跳过留档，两者都无业务副作用、按已处理回填（`US-03` AC2）；处理错误记在对应消息的处理记录上，不被外层吞掉（`US-03` AC5）。 @@ -133,7 +133,7 @@ - **INV-21** 主航班与其共享航班不出现只删一半的状态：删除共享航班时联动更新其主航班，删除主航班级联删除其共享航班（`US-06` AC2）。 - **INV-22** 主航班与共享航班的删除在同一 PG 事务内提交。被删除的航班从 Redis 投影移除；删除共享航班时，主航班的投影随更新结果刷新。移除与刷新都成功后才算这次处理完成（`INV-17b`、`INV-23`）；任一失败即未完成，下轮重做两步——移除可重复执行，刷新以重做时的结果为准。共享航班在 Redis 投影中的呈现方式、删除通知使用共享还是主航班 `FLID`，待 `Q20`、`Q4`。 - **INV-29** 已删除航班收到 `ADFT` 时按报文内容恢复为有效航班（`US-04` AC3）：恢复走正常处理路径，推进版本、刷新投影并登记事件，不因已删除而跳过或拒绝。 -- **INV-31** 日计划以整包为完成单位：每批提交只是持久化进度，处理完成在整包写入完成且 Redis 按快照刷新成功后判定（`US-07` AC4/AC5）；刷新成功前查询读到上一份投影。失败后整包重处理，部分进度由重处理收敛到同一目标，收敛依赖逐航班写入幂等与版本只进不退（`INV-13`、`INV-20b`）。 +- **INV-31** 日计划以整包为完成单位：每批提交只是持久化进度，处理完成在整包写入完成且 Redis 按快照刷新成功后判定（`US-07` AC4/AC5）。刷新在整包写入完成后才开始（架构「主流程」），开始前投影未被本包触碰；刷新按航班渐进，期间投影处于过渡态，成功即与快照一致；是否提供原子切换视图取决于 `Q20`。失败后整包重处理，部分进度由重处理收敛到同一目标，收敛依赖逐航班写入幂等与版本只进不退（`INV-13`、`INV-20b`）；`G-FLOP-IDEMPOTENT` 闭合前收敛不可声明。 ### 4.3 投影、投递、历史与参考数据 @@ -177,7 +177,7 @@ | Q3 | 兼容入口的请求体上限、编码与 `Content-Type` 精确规则、HTTP 状态码、成功与失败响应结构 | 响应语义与解析限制已定（`C-28`）；旧系统线索为共用 `ResponseDto`、成功 `body` 是信箱编号（接口契约「HTTP」） | 兼容入口无法验收 | | Q4 | Kafka 载荷与去重标识 | 两个主题名、`msg` 单条变更、`schd` 定时批量已定（`US-08`；接口契约「Kafka」）；`msg` 的 `FLID` 保序见 `C-29`。`schd` 每条 record 装什么、批次边界未定 | key、分区规则、`schd` 粒度及去重标识仍须确定 | | Q5 | 请求与应答的对应字段、超时判定 | 见 `C-23` | 请求跟踪无法闭环 | -| Q7 | 处理标记的允许值、原文保留期、处理时间列、信箱时钟基准与时区 | 只填空值，不回撤不覆盖（`C-15`）；回填重试期间原文须在（`C-7`） | 允许值、保留期取值与时钟基准未定 | +| Q7 | 处理标记的允许值、原文保留期、处理时间列、信箱时钟基准与时区 | 只填空值，不回撤不覆盖（`C-15`）；回填重试期间信箱行须在，未完成消息原文须在（`C-7`） | 允许值、保留期取值与时钟基准未定 | | Q8 | 现场会发但 SIS 未定义的子类型（靠桥、延误等）的报文形态与逐类终态 | 按现有处理逻辑延续（`US-05` AC1） | 逐类终态与幂等规则未定（`G-FLOP-SEMANTICS`） | | Q9 | 清除方案与保留期 | 清除由库方执行（`C-8`）；旧系统按接收超过 1 天归档并删除入站行，是否沿用待确认。见 `C-6`～`C-9` | 清除边界与保留期未定 | | Q10 | 出站 ACK 与错误列语义、出站行清理与重复落信识别、作废请求的结案与应答处置、写入结果不明时名额的释放 | 交付承诺止于落信（`C-24`） | 出站行清理、去重责任与作废语义未定 | @@ -208,7 +208,7 @@ | Q18 | 人工发起 `RQRD` 的方式 | `US-09` 要求人工发起，HTTP 接口清单没有对应入口 | 参考数据请求无法人工触发 | | Q19 | `msg` 的版本与去重标识是否直接采用航班当前态的版本号 | 可用依据是 `FLIGHT_SCHD` 的版本规则（`INV-13`） | 消费方去重规则未定（与 `Q4` 衔接） | | Q21 | 回退时在途消息（已提交业务变更、未到处理完成）的处置 | 回填了结后切换（`C-34`）；在途消息无跨系统幂等保障 | 回退演练的验收口径（`OPS-4`） | -| Q22 | 是否在自有 PG 留存入站原文副本 | 不留存，原文只从信箱读取；提前清除按 `C-12` 处置 | 提前清除的消息不可恢复 | +| Q22 | 是否在自有 PG 留存入站原文副本，及原文提前清除时已登记消息的处置（含队头是否放行） | 不留存，原文只从信箱读取；提前清除的消息按处理失败保持未完成并告警（`C-12`） | 提前清除的消息不可恢复，处置未定 | | Q23 | 日计划中运营日冲突的处置 | 整包校验失败不落地（`INV-19`）；冲突是否属于整包校验未定 | 冲突场景无法验收（`INV-12`） | | Q26 | `REF_MASTER` 的物理列、唯一键、空值存储与写入后可见时点 | 记录用类别码加识别标签识别（接口契约「静态参考数据类别与编号来源」） | admin-api 读取契约无法定稿（`C-31`） | | Q27 | Elasticsearch 历史索引、文档 ID、字段映射、成功判据、写入结果不明的对账与幂等策略 | 历史写入确认成功才删实时数据（`D1`、`INV-28`） | 历史链路无法验收（`US-14`；`G-FLIGHT-HIST-RETENTION`） | @@ -249,15 +249,15 @@ | INV-10、C-29 | `US-08` AC1/AC2/AC3 | `msg` 单条变更、`schd` 批量；失败重试后仍能投出且同一 `FLID` 顺序不颠倒（端到端保序待 `Q4`，见 `CLM-7`）；一直失败的记录保留可查并告警 | | INV-11b | 架构「系统定位与范围」 | 航班当前态的权威写入只在自有 PG | | INV-12、INV-13 | 架构「必须保持的约束」、`US-04` AC1 | 运营日写入后不变，没带计划时间的航班留空；重复消息不推进版本 | -| INV-14b | `US-04` AC2、`US-05` AC2 | 未携带的字段保持原值 | +| INV-14b | `US-04` AC2 | 未携带的字段保持原值 | | INV-29 | `US-04` AC3 | 已删除航班收到 `ADFT` 后恢复有效并推进版本 | | INV-15b | `US-07` AC2/AC3 | 缺席的航班在 PG 标为已删除并从 Redis 投影移除；未携带的字段被清空 | | INV-17b | `US-03` AC4、`US-05` AC4、`US-06` AC1 | 投影写失败时，没有终态与回填意图落库；处理完成前事件不可投递 | | INV-18 | `US-14` AC4 | 历史清理跳过正在被消息处理的航班 | | INV-19 | `US-07` AC1 | 校验失败后本地数据与版本不变 | -| INV-31 | `US-07` AC4/AC5 | 分批失败后整包重处理收敛到同一目标；Redis 在整包完成后按快照刷新 | +| INV-31 | `US-07` AC4/AC5 | 分批失败后整包重处理收敛到同一目标（`G-FLOP-IDEMPOTENT` 闭合前无法验证）；Redis 在整包写入完成后按快照刷新，成功即与快照一致 | | INV-20b、CLM-3 | `US-01` AC2、`US-03` AC3、`US-05` AC1/AC2 | 重复执行不增加业务效果；逐子类型规则与幂等矩阵在 `Q8`、`G-FLOP-IDEMPOTENT`、`G-FLOP-SEMANTICS` 闭合前无法验证 | -| INV-21、INV-22、INV-28 | `US-06` AC1/AC2、`US-14` AC3 | 主/共享删除联动后没有半删状态；删除事件在实时数据删除前登记并投递（`D1`）；移除与刷新任一失败时下轮重做 | +| INV-21、INV-22、INV-28 | `US-06` AC1/AC2、`US-14` AC3 | 主/共享删除联动后没有半删状态；删除事件在实时数据删除前登记（`D1`），投递按至少一次随后完成；移除与刷新任一失败时下轮重做 | | INV-23 | `US-05` AC4、`US-06` AC1 | 投影写失败的消息下轮仍被处理 | | INV-24 | `US-12` AC1/AC2 | 返回全部非共享航班，且与 Redis 一致；Redis 故障时返回错误 | | INV-25 | `US-11` AC1/AC2 | 未完成的记录不被删除 | @@ -268,7 +268,8 @@ | CLM-9（不承诺完成时限） | `OPS-2` | 积压、处理失败、投递失败、回填失败各有指标与告警（架构「总体架构」） | | CLM-10（容量假设） | `OPS-2` | 上线前用现场量级重估 | | C-34 | `OPS-4` | 回退演练：回填了结后切回，旧系统不重处理已产生业务效果的消息；在途窗口处置见 `Q21` | -| PRE-5（部署约束） | `OPS-1`、`OPS-3` | 配置不完整拒绝启动，双实例同时启动只允许一个实例处理；测试环境用独立数据库、Redis 与主题，不连接生产信箱 | +| PRE-5（部署约束） | `OPS-1` | 双实例同时启动只允许一个实例处理消息；配置不完整拒绝启动属 `OPS-1` 自身验收，无不变量承载 | +| C-35（测试隔离承诺） | `OPS-3` | 测试环境配置核对：独立数据库、Redis 与 Kafka 主题，不连接生产信箱 | ## 9. 契约数值