cdia/msgexchange-v2
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs(acm2-98): 告警口径收敛到可告警信号，外部告警归部署方

Browse Source 
OPS-2 验收改为故障注入验证指标变化；应用侧只保 /metrics
可观察与死信/放弃清单可查，不内置告警通道。
This commit is contained in:
windyboy
2026-09-23 17:16:48 +08:00
parent 71698b240b
commit ef99d3038e
12 changed files with 28 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture.md
+3 -3
View File
@@ -52,8 +52,8 @@ delivery 投递 jobs 作业：回填 / 出站重试 / 历史清理 /
3. **事务一**：持 `PIPELINE_LOCK`，领域变更、未映射字段记录与待发事件一起提交。
4. **投影**：写 Redis，写成功才算处理完成（`INV-10`）；失败保持未完成、下轮重写投影，业务效果幂等（`US-03` AC3）。
5. **事务二**：处理终态与回填意图一起提交。
6. **回填**：作业把处理标记写回共享信箱（`US-10`）；写不上的记录在案并告警。
7. **投递**：读待发事件发 `KAFKA:msg` / `KAFKA:schd`，至少一次（`C-9`）；一直失败的记录保留可查并告警（`US-08`）。
6. **回填**：作业把处理标记写回共享信箱（`US-10`）；写不上的记录在案可查。
7. **投递**：读待发事件发 `KAFKA:msg` / `KAFKA:schd`，至少一次（`C-9`）；一直失败的记录保留可查（`US-08`）。
其余类别与这条主干的差异：
@@ -61,7 +61,7 @@ delivery 投递 jobs 作业：回填 / 出站重试 / 历史清理 /
|---|---|---|---|
| 日计划（`DNLD`/`RESP`） | 第 3 步改为每批一个事务，第 5 步在整包完成后 | 整包成功，含 Redis 刷新（`US-07` AC4/AC5） | 不标记已处理，下轮整包重处理（`US-07` AC4） |
| 静态参考数据 | 无第 4 步；一个事务完成落库、终态与回填意图 | 该类落库成功（`US-13` AC1） | 校验不过整类不动，其他类照常（`US-13` AC2） |
| 出站请求 | 不走收报队列：登记新请求并作废同子类型旧请求；`RQRD` 与 `RQFD` 各自最多一条在途，后续请求待前一条结案再写入 `COUTMSGS` | 请求已写入信箱（`US-09` AC1） | `jobs` 按 `REQ_TRACK` 重试仍有效且确认未落信的请求；写入结果不明时记录并告警，不直接重发；交付承诺只到落信（`C-4`） |
| 出站请求 | 不走收报队列：登记新请求并作废同子类型旧请求；`RQRD` 与 `RQFD` 各自最多一条在途，后续请求待前一条结案再写入 `COUTMSGS` | 请求已写入信箱（`US-09` AC1） | `jobs` 按 `REQ_TRACK` 重试仍有效且确认未落信的请求；写入结果不明时记录在案，不直接重发；交付承诺只到落信（`C-4`） |
| 航班历史清理（作业） | 不走消息队列：历史写入成功后物理删除 | 实时数据已删（`US-14` AC3） | 历史写不成功不删，下轮重来（`US-14` AC3） |
## 5. 数据归属与一致性
docs/contracts/interface-contract.md
+4 -4
View File
@@ -35,13 +35,13 @@ AODB 经 CIIMS adapter 把 XML 报文写入 `CMINMSGS`，格式以架构指定
| 出站请求 | 本系统只发 `RQRD` 参考数据请求与 `RQFD` 日计划请求，经 `COUTMSGS` 落信，交付承诺止于落信（`US-09`、`C-4`）。 | 超时的时限取值。 |
| 在途与作废 | `RQRD` 与 `RQFD` 各自同时最多一条已落信、未结案的请求；同一子类型发新请求时旧请求作废，新请求登记为待发送，等该报文类型的在途请求收到应答、失败或超时后再落信；请求超过时限未等到应答标记超时（`US-09`）。 | 超时的时限取值。 |
| 应答匹配 | 应答按报文类型对应到等待中的请求；AODB 发错或迟到的应答不更新数据，记录后跳过（`US-09`）；`SCHD-RESP` 只在请求未过期时生效，迟到的应答不更新数据（`US-07`）。 | 请求与应答的对应字段、过期判定的依据字段。 |
| 错误回报 | 收到 `EROR` 时定位到本系统发出的请求，标记失败并告警（`US-09`）。 | `EROR` 与请求的对应字段。 |
| 错误回报 | 收到 `EROR` 时定位到本系统发出的请求，标记失败（`US-09`）。 | `EROR` 与请求的对应字段。 |
## Kafka
| 主题 | 已确定的消息语义 | 尚需确定 |
|---|---|---|
| `msg` | 单条航班变更通知；Kafka value 是整条 `MSG` 的 JSON（`META` 加对应业务体，空字段不输出），变更与删除由 `META` 的类型与子类型区分（`Q5`）；航班动态与删除处理完成后投递；发送失败自动重试，一直失败的记录保留可查并告警（`US-08`）；同一 `FLID` 的变更保序，对外按至少一次投递（`CLM-3`，单分区）。删除通知的来源有三处：`FDEL` 删除（`US-06`）、日计划完整名单覆盖范围内缺席删除（`US-07`）、历史清理在物理删除前必要时登记（架构 `D1`）。 | 编码方式（JSON 之外的压缩或封装是否引入）。 |
| `msg` | 单条航班变更通知；Kafka value 是整条 `MSG` 的 JSON（`META` 加对应业务体，空字段不输出），变更与删除由 `META` 的类型与子类型区分（`Q5`）；航班动态与删除处理完成后投递；发送失败自动重试，一直失败的记录保留可查（`US-08`）；同一 `FLID` 的变更保序，对外按至少一次投递（`CLM-3`，单分区）。删除通知的来源有三处：`FDEL` 删除（`US-06`）、日计划完整名单覆盖范围内缺席删除（`US-07`）、历史清理在物理删除前必要时登记（架构 `D1`）。 | 编码方式（JSON 之外的压缩或封装是否引入）。 |
| `schd` | 定时批量发送最新航班状态；待发航班按单批上限聚成 `SCHD.FLTR` 数组 JSON，每批作为单条 record 发出，超限部分后续轮次发出（`C-9`、`Q1`）；空字段不输出，字段与类型见 [XSD](../legacy/unisysaodbsis.xsd) 的 `FLTR`；没有变化不发；删除航班不进入本主题，由 `msg` 发一条删除通知；发送失败自动重试，对外按至少一次投递（`US-08`）。 | — |
旧系统线索（来源：旧项目用户故事「前端通知」「动态类（FLOP-*）处理」）：
@@ -60,8 +60,8 @@ AODB 经 CIIMS adapter 把 XML 报文写入 `CMINMSGS`，格式以架构指定
| 表 | 本系统的操作 | 需要对接方提供的物理契约 |
|---|---|---|
| `CMINMSGS` | 按信箱编号升序、分批读取未处理的报文，扫描与回写用同一处理时间列（`CMINMSGS_DATE_PROCESSED`，`Q8`）；兼容 HTTP 入口写入 XML 原文；处理完成后写入处理完成时刻，只填空值、不覆盖已有值；写回失败由后台任务重试，一直写不上的记录保留在案并告警（`US-01`、`US-02`、`US-10`）。信箱编号即入库行号，单调递增、不复用、不回退（`Q7`）。 | 表 DDL、信箱编号与报文原文字段、处理时间列的类型与可空性及写入样例（处理标记即该处理时间列，见 [specification.md](../specification.md)「术语」的处理标记；回填只填空值）、状态列 `CMINMSGS_STATUS` 的取值集与写权限（`Q8` 未确认）、写入必需列、原文保留期与清除协议（`C-1`）和索引。 |
| `COUTMSGS` | 写入 `RQRD` 参考数据请求与 `RQFD` 日计划请求；CIIMS adapter 消费。交付承诺止于请求落信；写入结果不明时记录并告警，不直接重发（架构「主流程」）。 | 表 DDL、请求原文字段、写入必需列、编号生成方式、重复落信的识别规则。 |
| `CMINMSGS` | 按信箱编号升序、分批读取未处理的报文，扫描与回写用同一处理时间列（`CMINMSGS_DATE_PROCESSED`，`Q8`）；兼容 HTTP 入口写入 XML 原文；处理完成后写入处理完成时刻，只填空值、不覆盖已有值；写回失败由后台任务重试，一直写不上的记录保留在案可查（`US-01`、`US-02`、`US-10`）。信箱编号即入库行号，单调递增、不复用、不回退（`Q7`）。 | 表 DDL、信箱编号与报文原文字段、处理时间列的类型与可空性及写入样例（处理标记即该处理时间列，见 [specification.md](../specification.md)「术语」的处理标记；回填只填空值）、状态列 `CMINMSGS_STATUS` 的取值集与写权限（`Q8` 未确认）、写入必需列、原文保留期与清除协议（`C-1`）和索引。 |
| `COUTMSGS` | 写入 `RQRD` 参考数据请求与 `RQFD` 日计划请求；CIIMS adapter 消费。交付承诺止于请求落信；写入结果不明时记录在案，不直接重发（架构「主流程」）。 | 表 DDL、请求原文字段、写入必需列、编号生成方式、重复落信的识别规则。 |
共享 MySQL 归 CIIMS adapter 方所有；本系统不建表、不改表结构，也不写共享历史表。入站行只写回处理标记，原文保留与清除由库方负责（`C-1`）。外部表的物理字段必须以对接方提供的现行 DDL 与读写样例核对，不能由本文件推造。
docs/implementation.md
+5 -5
View File
@@ -174,8 +174,8 @@ LIMIT PARAM:msgx.pipeline.backfill-batch
|---|---|---|
| 写入成功 | 标记为空、写入 1 行 | 记 `BACKFILL_AT`，不再重试 |
| 早已有标记 | 写入 0 行且信箱行存在 | **视为成功**，不覆盖已有值，记 `BACKFILL_AT` |
| 信箱行不存在 | 写入 0 行且行已删 | 立即放弃（`MISSING_ROW`）并告警 |
| 暂时性故障超 `R` | 超时/连接失败到 `R` 仍未写回 | 停自动重试（`TRANSIENT_DEADLINE`）并告警；`R` 前只退避 |
| 信箱行不存在 | 写入 0 行且行已删 | 立即放弃（`MISSING_ROW`），记入放弃清单与指标供外部告警 |
| 暂时性故障超 `R` | 超时/连接失败到 `R` 仍未写回 | 停自动重试（`TRANSIENT_DEADLINE`），记入放弃清单与指标供外部告警；`R` 前只退避 |
放弃 ≠ 已写回：不写 `BACKFILL_AT`，信箱行不删（`C-1`）。
@@ -184,7 +184,7 @@ LIMIT PARAM:msgx.pipeline.backfill-batch
`R` 见 [reference.md](reference.md) `PARAM:msgx.pipeline.overdue-backfill`：
- 超 `R` 未写回 → 每轮都试，不等退避。
- 暂时性故障到 `R` 仍失败 → 停自动重试；`backfill-max-attempts` 只告警。
- 暂时性故障到 `R` 仍失败 → 停自动重试；`backfill-max-attempts` 只记日志提醒（仍继续重试直到 `R`）。
- `MISSING_ROW` 立即放弃。`R ≤ R_keep`。写回已了结且超保留期（约 1 月，`C-1`）后删原文；放弃行不删。
## 7. 日计划快照与请求匹配
@@ -212,7 +212,7 @@ PENDING → SENT → DONE
- 开放槽：`RQRD`/`RQFD` 各一条（`US-09` AC1）；同类新请求前作旧请求过期。
- `COUTMSGS` 确认后才 `SENT`；本地未确认须补偿，不能盲重发。
- EROR → 标 `FAILED` 并告警（`US-09` AC3）。
- EROR → 标 `FAILED`（`US-09` AC3），错误定位可查。
- 应答按类型匹配开放请求（`US-09` AC2）；时间用本地时钟。
- 参考应答写 `REF_MASTER`；日计划走快照。结案后迟到应答不改状态。
- 出站只保证写入信箱（`C-4`、`CLM-4`）。
@@ -263,7 +263,7 @@ PENDING → SENT → DONE
| 领域事务已提交、Redis 写失败或终态未提交 | 该消息无终态（`PENDING`），仍占队头 | 整条消息重处理：Redis 航班快照按当前完整态重写；领域再跑是否只留一次效果见 `US-03`、`G-FLOP-IDEMPOTENT`；已提交结果不回滚（`US-03` AC3） |
| 事务已提交、标记未写 | 终态行仍持有回填意图 | 仅补写标记；业务处理结果保持不变 |
| 标记写入中途 | 标记仍为空 | 重新写入；重复写入同一值无副作用 |
| 回填时信箱行已不存在 | 写入 0 行且信箱行不存在 | 立即放弃自动重试（`MISSING_ROW`）并告警；放弃不等于标记已确认，仍需人工对账 |
| 回填时信箱行已不存在 | 写入 0 行且信箱行不存在 | 立即放弃自动重试（`MISSING_ROW`）并记入放弃清单；放弃不等于标记已确认，仍需人工对账 |
| `RECEIVED_AT` 为 NULL | 超期分支以本地 `ENQUEUED_AT` 判定，不受库方时钟与 NULL 影响 | 按 `R` 超期强补写；未超期则按退避重试 |
| 投递目标已接受、`SENT` 未置 | 事件仍 `PENDING` | 允许重发，消费方按事件身份去重 |
| PG 从备份恢复 | 终态与事件回退到备份点 | 按至少一次接受重复；不重放业务、不据此改写航班 |
docs/reference.md
+3 -3
View File
@@ -29,7 +29,7 @@
|---|---|---|---|
| `msgx.pipeline.overdue-backfill` | `30d` | 入队后超过期限 `R` 仍未写回处理时间，就立即再试；若仍失败，则停止自动重试。`R` 不得长于信箱行可保证的最短保留期 | 暂定 |
| `msgx.pipeline.backfill-batch` | `100` 条 | 一次最多检查多少条待写回信箱的记录 | 暂定 |
| `msgx.pipeline.backfill-max-attempts` | `100` 次 | 失败次数达到此值时告警，仍继续重试直到期限 `R` | 暂定 |
| `msgx.pipeline.backfill-max-attempts` | `100` 次 | 失败次数达到此值时记日志提醒，仍继续重试直到期限 `R` | 暂定 |
| `msgx.pipeline.backfill-backoff-ms` | `30000` ms | 首次写回失败后等多久再试 | 暂定 |
| `msgx.pipeline.backfill-backoff-cap-ms` | `900000` ms | 以后每次重试最长等多久 | 暂定 |
@@ -117,9 +117,9 @@
| `msgx.pipeline.codec.vipf_seen.total` | 收到含 `VIPF` 段的消息数 | 非零：核对 `G-SRVT-VIPF` |
| `msgx.pipeline.processing.ignored.total` | 被 `IgnoreRules` 跳过的消息数 | 现行清单仅 `LDM-*`；`REGN`/`RSTA`/`EROR` 已改走 US-13/US-09 |
| `msgx.pipeline.delivery.send_failures.total{target}` | 该投递目标累计发送失败次数（进程内，重启归零） | 持续增长且 `dead` 非零：投递链路故障（`OPS-2`） |
| `msgx.pipeline.delivery.dead{target}` | 该投递目标当前死信（`DEAD`）行数 | 非零即告警：死信需人工处置（`OPS-2`；状态语义见 [implementation.md](implementation.md)「状态与错误分类」） |
| `msgx.pipeline.delivery.dead{target}` | 该投递目标当前死信（`DEAD`）行数 | 非零供外部告警：死信需人工处置（`OPS-2`；状态语义见 [implementation.md](implementation.md)「状态与错误分类」） |
未处理消息的统计使用同一份缓存；统计不可用显示 `NaN`，没有记录可比时年龄与编号差显示 `-1`。作业计数在进程重启后归零；作业已启动却连续三个检查周期没有成功运行时，`/health` 报 `DOWN`。
未处理消息的统计使用同一份缓存；统计不可用显示 `NaN`，没有记录可比时年龄与编号差显示 `-1`。作业计数在进程重启后归零；作业已启动却连续三个检查周期没有成功运行时，`/health` 报 `DOWN`。上表关注信号即告警依据，由部署方配外部告警；应用侧只保证 `/metrics` 可观察与死信/放弃清单可查，不内置告警通道。
## 模块与代码入口
docs/requirements.md
+4 -4
View File
@@ -113,7 +113,7 @@
1. 两个 Kafka 主题：`msg` 发单条航班变更，`schd` 定时批量发最新状态。
2. 发送失败自动重试；同一航班的变更按顺序发送。
3. 发送一直失败的记录保留并可查，有告警。
3. 发送一直失败的记录保留并可查。
### US-09 向 AODB 请求数据
@@ -123,7 +123,7 @@
1. `RQRD` 与 `RQFD` 各自同时最多一条已落信、未结案的请求；同一子类型发新请求时旧请求作废，新请求待在途请求结案后再落信。请求超过时限未等到应答，标记超时。
2. 应答到达时按报文类型对应到等待中的请求；AODB 发错或迟到的应答不更新数据，记录后跳过。
3. 收到 EROR（AODB 错误回报）：定位到本系统发出的请求，标记失败并告警。
3. 收到 EROR（AODB 错误回报）：定位到本系统发出的请求，标记失败。
### US-10 回写信箱处理标记
@@ -132,7 +132,7 @@
**验收标准**
1. 处理完成时在本地记录「待标记」，后台任务把它写到 MySQL 信箱。
2. 写失败自动重试，重启后继续；一直写不上的记录在案并告警。
2. 写失败自动重试，重启后继续；一直写不上的记录在案可查。
### US-11 处理记录清理
@@ -185,6 +185,6 @@
| 编号 | 要求 | 验证方式 |
|---|---|---|
| `OPS-1` | 单实例运行：系统配置不完整时拒绝启动；同一时刻只允许一个实例处理消息。 | 配置错误启动失败测试；双实例同时启动测试。 |
| `OPS-2` | 可观测：消息积压、处理失败、发送失败、标记写回失败都有监控指标和告警。 | 故障注入触发告警；检查监控面板。 |
| `OPS-2` | 可观测：消息积压、处理失败、发送失败、标记写回失败都有监控指标与可告警信号。 | 故障注入验证指标变化；查 `/metrics` 与死信/放弃清单。 |
| `OPS-3` | 测试隔离：测试环境的实例使用独立的数据库、Redis、Kafka 主题，不连接生产信箱。 | 配置检查。 |
| `OPS-4` | 切换与回退：停旧系统、启新系统完成切换；出问题回退时停新、启旧，未处理的消息由旧系统继续，数据不丢。 | 切换与回退演练记录。 |
docs/specification.md
+1 -1
View File
@@ -169,7 +169,7 @@
| C-9、CLM-3 | `US-08` AC1～AC3 | `msg` 单条、`schd` 批量；失败可重试；`msg` 同 `FLID` 保序；同条可能发多次 |
| C-10 | `US-13` AC1～AC4 | 全量替换、增删改逐条；空值表示无值不是删除；单类校验失败只停该类 |
| INV-1（建立处理记录） | `US-01` AC1/AC2/AC4 | 重扫与重启后记录数不变、行不丢；同一编号重复出现时不新增记录 |
| INV-2 | `US-10` AC1/AC2 | 处理结束后才写回；重启后继续；一直失败有记录与告警 |
| INV-2 | `US-10` AC1/AC2 | 处理结束后才写回；重启后继续；一直失败有记录可查 |
| INV-3、INV-10 | `US-03` AC4、`US-05` AC4、`US-06` AC1 | Redis 失败时不记「处理结束」与「还要写回」；完成前不发 Kafka |
| INV-4 | `US-07` AC1 | 校验失败后 PG 航班数据不变 |
| INV-5 | 架构「数据归属与一致性」 | 航班数据只写入自有 PG |