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

docs: 修复跨文档冲突与外部规范口径

Browse Source 
不动代码、配置与迁移，只收敛文档口径。

- 登记两项外部冲突：Q13 日计划缺失可选字段（SIS §3.16 注释 4 要求删除本地值，
  与现行"未携带字段保留"相反）、Q14 主/共享删除顺序与 EROR 回报义务
  （SIS §1.6.1-1.d / §4.8）；航班级"缺席不删"补 SIS §3.16 注释 1 依据。
- flight-state §3.3 补主/共享关联按 FLID 值比较的规则。
- message-lifecycle：§11 水位不变量与 §5.1 空洞老化自洽；删除过期的 updatedAt
  判据，统一为 PROCESSING_STARTED_AT + 可注入 Clock；§5.1/§6 补 SIS 480 分钟
  Expiry 与 legacy 1 天保留窗，作为 Q2/Q6/Q7 的取值参照。
- architecture/design：明细表口径统一为 8 张资源明细表 + FLIGHT_ROUTE_POINT；
  Oracle 11g 断言收敛为待适配验证；配置键按 application.yml 实际名称加 msgx. 前缀。
- user-stories：Q2/Q6/Q11 补外部锚点并收窄 Q11 到重置周期 + SNDR 值域；
  新增 Q13/Q14 并挂入 US-05/06/08 前置；五个独立事实改为引用 message-lifecycle §1。
- README/legacy：文档基线改为代码基线 eea1120 + git log 指引；补"外部协议冲突以
  SIS 为准"的维护规则；修正 /all/flights 过滤措辞；术语统一为「回填意图」。

验证：文档间章节引用 0 缺失、markdown 0 断链、SIS 引用小节全部存在、
Q1–Q14 正文与 Q 表双向可解析、代码块配对正常。
This commit is contained in:
windyboy
2026-09-10 20:54:01 +08:00
parent eea11203a2
commit 50e0e7f389
7 changed files with 70 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/design.md
+17 -16
View File
@@ -21,7 +21,7 @@
| `MSG_EVENT` | 等待投递的事件（outbox） | `EVENT_ID` 决定投递顺序；`TARGET` 区分 `KAFKA:msg` / `KAFKA:schd`；`PARTITION_KEY` 恒为 `FLID`；`EVENT_TYPE` 区分 UPSERT 与 TOMBSTONE。 |
| `REQ_TRACK` | 上游请求及应答关联 | 保存请求类型、覆盖运营日、发送方、出站信箱 ID 与发送/完成时间；同类只允许一个开放请求。登记、超时与应答匹配尚未实现（§10）。 |
| `REF_MASTER` | 静态参考数据（目标表） | `(RTYPE, RKEY)` 唯一；尚未建表，客户端与刷新流程见 user-stories.md US-13/US-14（US-14 两类映射的存储落点未定）。 |
| `FLIGHT_SCHD` | 航班标量及单值异常字段 | `FLID` 主键；`OPERATION_DAY` 一经确定不可变；版本与最近消息 ID 用于追踪。变长资源集合存于 9 张明细表，规则见 [flight-state.md](flight-state.md) §2，不在此重复。 |
| `FLIGHT_SCHD` | 航班标量及单值异常字段 | `FLID` 主键；`OPERATION_DAY` 一经确定不可变；版本与最近消息 ID 用于追踪。变长资源集合存于 8 张资源明细表与 `FLIGHT_ROUTE_POINT`，规则见 [flight-state.md](flight-state.md) §2，不在此重复。 |
| `INBOX_CURSOR` | 共享信箱消费水位 `W` | 单行游标；只随新 ID 成功入队推进，遇空洞即停，空洞超期判定为永久（[message-lifecycle.md](message-lifecycle.md) §5.1）。 |
| `PROC_STATE_HST` | 终态处理记录的归档目标 | 尚未建表；不得改写为共享库历史表。 |
@@ -37,7 +37,7 @@
SNDR | TYPE | STYP | SEQN
```
接收时只按信箱 ID 去重；解码后才首次绑定业务身份。重试保留原有绑定，不能把自己判为重复消息。身份被另一条记录占用时，当前消息转为 `SKIPPED`，记录 `duplicate-of:<id>`。是否加入日期边界取决于上游序号重置规则，默认关闭；上线后不能随意更换身份算法。
接收时只按信箱 ID 去重；解码后才首次绑定业务身份。重试保留原有绑定，不能把自己判为重复消息。身份被另一条记录占用时，当前消息转为 `SKIPPED`，记录 `duplicate-of:<id>`。是否加入日期边界取决于上游序号重置周期，默认关闭（`SEQN` 的取值范围与回绕已由 `SIS_AODB_RMS-V0.1.md` §2.8.1 定义，重置周期见 Q11）；上线后不能随意更换身份算法。
分派与落库由 `MessageProcessor` 统一协调：按 `MsgKind` 把已绑定身份的队头消息交给对应事务协调器（DNLD/RESP → `ScheduleProcessor`，ADFT → `AdftProcessor`，FLOP → `FlopProcessor`，FDEL → `FdelProcessor`，其余 → `FAILED(UNSUPPORTED)`）。这些 Processor 在 `PIPELINE_LOCK` 事务内读取当前完整态，调用纯领域决策逻辑得到下一完整态与待发事件，再统一落库并登记回填意图；它们不直接触碰 Kafka。处理终态与业务变更在同一事务边界提交（见 flight-state.md §4）。
@@ -45,7 +45,7 @@ SNDR | TYPE | STYP | SEQN
```text
处理：PENDING / FAILED → SUCCEEDED（成功）
→ SKIPPED（业务重复；忽略/无匹配分支见 US-04/US-06，尚未实现）
→ SKIPPED（业务重复已实现；忽略/无匹配分支见 US-04/US-06，尚未实现）
→ FAILED（等待退避重试）
→ DEAD（MALFORMED / PROTOCOL / EXHAUSTED，均需人工处置）
@@ -71,7 +71,7 @@ SNDR | TYPE | STYP | SEQN
`InboxPoller` 默认每秒按 ID 升序、有限批次（`claim-batch`，默认 50）读取水位之后的信箱记录（`ID > W`，**不以处理标记为谓词**），在自有 PG 建立 `PENDING` 并把水位推进到连续上界；入队与水位推进在同一 PG 事务内提交，重复扫描幂等、中断后重扫补建。收报层不解析业务载荷，也不回填已处理标记。
水位 W 与扫描谓词的完整口径（连续上界、遇空洞即停、空洞老化）唯一见 [message-lifecycle.md](message-lifecycle.md) §5.1；水位不是已处理标记，其有效性以 Q2 的 ID 单调承诺为前提。空洞老化阈值取 `pipeline.max-commit-delay`。
水位 W 与扫描谓词的完整口径（连续上界、遇空洞即停、空洞老化）唯一见 [message-lifecycle.md](message-lifecycle.md) §5.1；水位不是已处理标记，其有效性以 Q2 的 ID 单调承诺为前提。空洞老化阈值取 `msgx.pipeline.max-commit-delay`。
兼容 HTTP 入口执行“写入共享信箱 → PG 入队”。两步不在同一事务中：信箱成功而 PG 失败时，原文不能丢失，由轮询补建；客户端失败重试可能再次写信箱，业务身份去重仍然必需。
@@ -94,7 +94,7 @@ SNDR | TYPE | STYP | SEQN
DNLD / RESP → ScheduleProcessor（快照事务）
ADFT / FLOP / FDEL → Adft / Flop / FdelProcessor（单航班事务）
Unsupported → FAILED(UNSUPPORTED)
PG 单事务：锁 + 航班变更 + 待发事件 + 终态 + 回填待办预登记
PG 单事务：锁 + 航班变更 + 待发事件 + 终态 + 回填意图预登记
→ 提交后回填信箱；失败由补偿待办重试
```
@@ -112,7 +112,7 @@ SNDR | TYPE | STYP | SEQN
1. **重放判定**：`PROC_STATE` 已存在成功终态 → 幂等成功，仅追加留痕，不重复写入。
2. **整包校验**：声明记录数、航班标识与运营日推导等校验失败 → 整包 `DEAD(PROTOCOL)`，不写半包，既有状态保持不变。
3. **事务写入**：锁内按 `FLID` 点查归属日，发现同一航班跨运营日即整包回滚并 `DEAD(PROTOCOL)`；通过后合并写主表与资源明细。报文未携带的航班不因本次日计划报文被删除。
4. **提交结果**：同一事务保存 `KAFKA:schd` / `KAFKA:msg` 事件、置消息 `SUCCEEDED` 并预登记回填待办；事务提交后执行信箱回填，留痕在事务外追加。
4. **提交结果**：同一事务保存 `KAFKA:schd` / `KAFKA:msg` 事件、置消息 `SUCCEEDED` 并预登记回填意图；事务提交后执行信箱回填，留痕在事务外追加。
单事务保证未提交变更整体回滚。消息重放由 `PROC_STATE` 的消息 ID 与业务身份控制；版本号不能单独证明消息身份。
@@ -133,7 +133,7 @@ REGISTERED → SENT → WAITING → DONE
- 应答优先按已确认的回显字段精确匹配；回显契约未确认时的降级匹配（同类开放请求且 `DTTM ≥ sentAt`）存在跨代误配风险，必须明确接受并审计，不能宣称精确关联。比较前统一时区和时间单位。
- 参考应答写入自有 `REF_MASTER`（尚未建表），日计划应答走快照流程；请求完成必须在相应数据处理成功之后，超时和迟到应答不能修改已关闭请求对应的状态。
请求与参考数据的交付范围见 user-stories.md US-08/US-13/US-14 与 §10。
请求与参考数据的交付范围见 user-stories.md US-08/US-13/US-14 与本文 §10。
## 5. 事件投递
@@ -167,7 +167,7 @@ REGISTERED → SENT → WAITING → DONE
### 6.2 历史清理与归档
**航班历史清理**（`HistorySweepJob`，每天 03:30 触发）：按 `HistoryProps` 的保留期与终态/静默判据选出候选（含 `DELETED`），先写历史存储，成功后物理删除主行与明细；历史存储未接通或 `history-store-enabled=false` 时删除 0 条。未经 FDEL、由生命周期直接清除的航班，清除前补发一次删除事件。语义与红线见 flight-state.md §6，不在此重复。
**航班历史清理**（`HistorySweepJob`，每天 03:30 触发）：按 `HistoryProps` 的保留期与终态/静默判据选出候选（含 `DELETED`），先写历史存储，成功后物理删除主行与明细；历史存储未接通或 `msgx.history.history-store-enabled=false` 时删除 0 条。未经 FDEL、由生命周期直接清除的航班，清除前补发一次删除事件。语义与红线见 flight-state.md §6，不在此重复。
**留痕清理**：`SCHD_SNAP_LOG` 保留 90 天，在历史清理窗口内按 `(SCOPE_END, RECV_AT)` 删除。
@@ -179,15 +179,16 @@ REGISTERED → SENT → WAITING → DONE
兼容入口为 `POST /cminmsgs/send`，请求体为原始 XML，当前成功响应为 HTTP 200、`text/plain` 格式的信箱记录 ID。这只表示接收结果，不表示业务处理成功。请求媒体类型、字符集和失败响应仍需与现役逐项对拍；查询与其他兼容端点不能因列入需求就视为已提供。
运行配置以 `application.yml`、`application-dev.yml` 和 `.env.example` 为准，设计上重点区分：
运行配置以 `application.yml`、`application-dev.yml` 和 `.env.example` 为准，设计上重点区分（下列 `msgx.*` 参数以 `msgx.` 为前缀，`mailbox.*` 不带前缀）：
- `pipeline.autostart` 与 `msgx.stubs`：分别控制管道启动与内存适配器；生产禁止 stub，默认不自动启动。
- `pipeline.poll-interval / claim-batch / max-attempts / backoff / head-deadline`：控制轮询节奏、批次、重试上限、退避与队头滞留；这些参数不能改变 FIFO。
- `pipeline.max-commit-delay / overdue-backfill / backfill-batch`：空洞老化阈值（Q2 最大提交时延）、超期补写期限 R（Q6）与回填扫描批量；R 与老化阈值都不能为提速而下调。
- `msgx.pipeline.autostart` 与 `msgx.stubs`：分别控制管道启动与内存适配器；生产禁止 stub，默认不自动启动。
- `msgx.pipeline.poll-interval / claim-batch / max-attempts / backoff-ms / backoff-cap-ms / head-deadline`：控制轮询节奏、批次、重试上限、退避与队头滞留；这些参数不能改变 FIFO。
- `msgx.pipeline.max-commit-delay / overdue-backfill / backfill-batch`：空洞老化阈值（Q2 最大提交时延）、超期补写期限 R（Q6）与回填扫描批量；R 与老化阈值都不能为提速而下调。
- `msgx.operation-day.zone / cutoff-hour`：运营日时区与切日边界，决定 `OPERATION_DAY` 推导（flight-state.md §2.1）。
- `mailbox.processed-value`：写回共享信箱的处理标记值，仅限库方认可的 legacy 值集（Q7）。
- `schd.flush-period / flush-limit`：控制状态通知的聚合延迟与批量大小。
- `identity.include-day-boundary`：影响去重语义，不能作为普通调优项切换。
- `mailbox.shared-mysql.enabled` 与 `history.history-store-enabled`：分别门控真实信箱与历史存储接线，默认关闭。
- `msgx.schd.flush-period / flush-limit`：控制状态通知的聚合延迟与批量大小。
- `msgx.identity.include-day-boundary`：影响去重语义，不能作为普通调优项切换；序号重置周期见 Q11。
- `mailbox.shared-mysql.enabled` 与 `msgx.history.history-store-enabled`：分别门控真实信箱与历史存储接线，默认关闭。
日志关联消息 ID、事件 ID 和批次；失败记录错误分类、次数、下次执行时间。健康检查反映依赖实际可用性；队头滞留、积压、死信和补偿失败需要指标及告警。日志出口故障不得阻塞业务线程。
@@ -227,7 +228,7 @@ REGISTERED → SENT → WAITING → DONE
以下缺口直接影响上述设计是否成立，不能以类或接口已存在作为完成依据：
- **事务与外部副作用**：状态、事件、处理终态与回填意图同 PG 事务提交；回填意图落在 `PROC_STATE`（`BACKFILL_AT/NEXT_AT/ATTEMPTS/ERROR`），`BACKFILL_TODO` 已随 V2 迁移下线，[message-lifecycle.md](message-lifecycle.md) §4 的两个崩溃窗口（提交后回填前崩溃、待办二次落账失败）不再存在。回填本身仍是跨库单写，失败按退避重试并由超期期限 R 兜底；R 的取值待 Q6 确认。
- **事务与外部副作用**：状态、事件、处理终态与回填意图同 PG 事务提交；回填意图落在 `PROC_STATE`（`BACKFILL_AT/NEXT_AT/ATTEMPTS/ERROR`），`BACKFILL_TODO` 已随 V2 迁移下线，[message-lifecycle.md](message-lifecycle.md) §4 的两个崩溃窗口（提交后回填前崩溃、回填意图二次落账失败）不再存在。回填本身仍是跨库单写，失败按退避重试并由超期期限 R 兜底；R 的取值待 Q6 确认。
- **收报与调度**：水位 W 落库并与入队同事务推进，遇空洞即停、空洞超过 `max-commit-delay` 判定为永久（Q2 未书面确认前该阈值是假定值）；旧空洞补齐后出现的新空洞会重置老化起点。较小 ID 迟提交与空洞场景的端到端顺序保证仍待与库方联合验证。HOL deadline 已改用 `PROCESSING_STARTED_AT` 和可注入 `Clock`；Q6 仍需确认长期积压与人工重放的期限口径。
- **快照与业务能力**：DNLD/RESP/ADFT 与 FLOP/FDEL 处理器、整包校验与跨运营日整包拒绝均已接入；但 RESP 应答守卫与出站请求未实现，忽略规则（US-04）未实现，29 类 FLOP 与参考应答的逐类矩阵未补全，ADFT 缺失字段与 `FLID` 重用语义待上游确认。
- **航班读写**：唯一写入口与权威读已落地；ROUT/ERUT 联合主键、空值/未知属性保真、事件在事务内只算一次、逐航班多次查询仍待修正（见 flight-state.md §6）。`/all/flights` 尚未实现。