From 2a06c42993b606679cda6e080235d2da23556528 Mon Sep 17 00:00:00 2001 From: windyboy Date: Wed, 16 Sep 2026 17:56:19 +0800 Subject: [PATCH] =?UTF-8?q?docs(acm2-75):=20=E5=88=A0=E9=99=A4=E4=BD=9C?= =?UTF-8?q?=E5=BA=9F=E6=9D=A1=E6=AC=BE=E5=B9=B6=E6=94=B6=E7=B4=A7=20CLM=20?= =?UTF-8?q?=E4=B8=8E=20Q=20=E5=BA=8F=E5=8F=B7?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 删除 4.4 已作废条款（INV 旧编号已无外部引用） - CLM-3,6,7,8,9,10,11 收紧为 CLM-1 至 CLM-7，全文引用同步更新 - 6.2 已确认事项按 Q 编号排序 - C-1/C-4/C-7/C-11 合并已确认结论，6.1 清空 --- docs/contracts/interface-contract.md | 2 +- docs/specification.md | 34 ++++++++++++---------------- 2 files changed, 16 insertions(+), 20 deletions(-) diff --git a/docs/contracts/interface-contract.md b/docs/contracts/interface-contract.md index 04241c7..16b0ed9 100644 --- a/docs/contracts/interface-contract.md +++ b/docs/contracts/interface-contract.md @@ -12,7 +12,7 @@ |---|---|---|---|---| | `POST /cminmsgs/send` | 请求体是 XML 原文；接受 `text/xml`、`application/xml`、`text/plain`，默认 UTF-8；仅限内网，网络层限制来源。 | 报文写入 `CMINMSGS` 后返回信箱编号；写入的报文与上游投递走同一条处理路径、效果一致；该响应只证明已落信，不证明业务处理或下游投递（`US-02`）。 | 空报文、超大小上限、非法 XML 不落信并返回错误；写信失败不返回编号；XML 解析禁用外部实体和外部资源访问。 | 大小上限、请求编码与 `Content-Type` 的精确处理规则、HTTP 状态码、成功/失败响应体字段及样例。 | | `POST /schd/sync` | 触发一次 `RQFD` 日计划请求；请求字段尚未定义，登记与落信规则见「在途与作废」。 | 响应内容尚未定义；无论表示登记还是落信，都不代表 AODB 已收到。 | 错误响应尚未定义。 | 请求字段与时间格式、成功响应表示已登记还是已落信（`Q17`）、状态码、响应字段及样例。 | -| `GET /all/flights` | 无已定义的请求字段；从 Redis 投影读取当前全部动态航班，不含共享航班，与网页客户端同源（`US-12`）。 | 返回查询到的全部航班，不分页。 | Redis 异常时返回错误，不能返回空列表伪装成功。 | 航班字段与类型、集合外层结构、状态码和错误响应样例。 | +| `GET /all/flights` | 无已定义的请求字段；从 Redis 投影读取当前全部动态航班，不含共享航班，与网页客户端同源（`US-12`）。 | 返回查询到的全部航班，不分页；JSON 由消息文档中的 XML 结构转换而来（`Q24`）。 | Redis 异常时返回错误，不能返回空列表伪装成功。 | 状态码和错误响应样例；外层包装是否沿用旧 `ResponseDto`。 | 旧系统线索（来源：旧项目用户故事「HTTP 接口清单」「日计划请求」）： diff --git a/docs/specification.md b/docs/specification.md index b33ca99..7f5a76c 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -36,20 +36,19 @@ ### 2.1 共享信箱（库方） -- **C-1** 本系统清理已处理的信箱行：回填完成且超过保留期后才删，处理未完成或回填未完成的行不删。 +- **C-1** 本系统清理已处理的入站信箱行（MySQL `CMINMSGS`）：回填完成且超过保留期后才删；保留期可配置，按约 1 个月（`Q9`）。处理未完成或回填未完成的行不删。 - **C-2** 共享 MySQL 不做 Schema 变更，本系统只读写 `CMINMSGS` 与 `COUTMSGS` 两张表。 ### 2.2 上游（AODB / SIS） - **C-3** 业务身份由 `SNDR`、`TYPE`、`STYP`、`SEQN` 四字段组合；`SEQN` 自增，极少重置（消息服务器重启），重置后不会与旧消息冲突。 -- **C-4** 出站请求写入 `COUTMSGS`；交付承诺止于落信。 +- **C-4** 出站请求写入 `COUTMSGS`；交付承诺止于落信。编码：`SNDR=OMMS`；`SEQN` 本系统自建序列；`DTTM` 北京时间 `YYYYMMDDHHMMSS`；`RQRD` 子类型以 SIS 为准共 14 类；`RQFD` 为 `STYP=NONE`，全量同步不带 `STDB`/`STDE` 等筛选（`Q25`）。 - **C-5** 航班删除为标记删除，主航班与共享航班各自独立标记。 - **C-6** 日计划快照里没有携带的字段视为 AODB 已删除该值，本地同步清除（`US-07` AC3）。 ### 2.3 HTTP 入口 -- **C-7** `POST /cminmsgs/send`：把 XML 写进入站信箱，与 adapter 投递走同一套处理。成功返回消息编号（仅表示已入库，未处理）；失败无编号。支持 `text/xml`、`application/xml`、`text/plain`（UTF-8）；空、超长、格式错的不写；解析不拉外部资源。内网，访问由网络配置控制。 - 待确认：长度上限、失败响应（`Q3`）。 +- **C-7** `POST /cminmsgs/send`：把 XML 写进入站信箱，与 adapter 投递走同一套处理。成功返回消息编号（仅表示已入库、未处理）；失败不返回编号。支持 `text/xml`、`application/xml`、`text/plain`（UTF-8）；空、超长、格式错的不写；解析不拉外部资源。内网，访问由网络配置控制。仅内部联调；长度上限与失败响应实现时自定（`Q3`）。 - **C-8** `POST /schd/sync`：向出站表写入一条日计划请求。 待确认：请求参数、HTTP 响应（`Q17`）。 @@ -57,8 +56,7 @@ - **C-9** 航班变更发到 Kafka 主题 `msg`（单条）和 `schd`（批量）。同一条可能发多次。 - **C-10** 静态参考数据写入本系统数据库，供 admin-api 只读；本系统不调用 admin-api。 -- **C-11** 航班投影写入 Redis，供 `GET /all/flights` 与网页客户端查询。 - 待确认：key 与 value 结构（`Q20`）。 +- **C-11** 航班投影写入 Redis，供读取全体动态航班；`GET /all/flights` 与网页客户端读同一份；返回 JSON 由消息文档中的 XML 结构转换而来（`Q20`、`Q24`）。 ## 3. 前提 @@ -106,17 +104,7 @@ ### 6.1 待对方确认 -| 编号 | 事项 | 当前假定 | 影响 | -|---|---|---|---| -| Q2 | 信箱编号的分配顺序、单调与不复用 | 按编号升序处理，不声称是到达顺序 | 编号空间特性未确认，但不影响正确性 | -| Q3 | 兼容入口的请求体上限、编码与 `Content-Type` 精确规则、HTTP 状态码、成功与失败响应结构 | 响应语义与解析限制已定（`C-7`）；旧系统线索为共用 `ResponseDto`、成功 `body` 是信箱编号（接口契约「HTTP」） | 兼容入口无法验收 | -| Q4 | Kafka 载荷与去重标识 | 两个主题名、`msg` 单条变更、`schd` 定时批量已定（`US-08`；`C-9`）。`msg` 单分区，同一 `FLID` 按发送顺序保序可声明（`CLM-3`）。`schd` 每条 record 装什么、批次边界未定 | `schd` 粒度及去重标识仍须确定 | -| Q7 | 处理时间列的列名、类型与可空性；信箱时钟基准与时区 | 处理标记即处理时间列；回填未完成前行须在，未完成消息原文须在（`C-1`） | 列元数据与时钟基准未定 | -| Q8 | 现场会发但 SIS 未定义的子类型（靠桥、延误等）的报文形态与逐类终态 | 按现有处理逻辑延续（`US-05` AC1） | 逐类终态与幂等规则未定（`G-FLOP-SEMANTICS`） | -| Q9 | 清除方案与保留期 | 本系统自行清理（`C-1`）；旧系统按接收超过 1 天归档并删除入站行，是否沿用待确认 | 清除边界与保留期未定 | -| Q20 | Redis 投影的 key/value 结构、序列化方式与网页客户端读取约定 | 旧系统线索为 hash `flightInfo`、field 取 `FLID`（见接口契约「Redis：航班查询投影」） | 消费方读取契约无法定稿 | -| Q24 | `GET /all/flights` 的返回字段与类型、集合外层结构、状态码与错误响应 | 读 Redis 投影、返回当前全部动态航班、不分页（`C-11`）；旧系统线索为非共享航班 `SCHD.FLTR` 列表（接口契约「HTTP」） | 查询契约无法定稿 | -| Q25 | `RQRD`/`RQFD` 的子类型清单、发送方取值、时间与序号的构造规则 | 出站只有这两类报文（架构「系统定位与范围」）；旧系统线索为 `TYPE=RQFD`、`STYP=NONE`、`SNDR=OSH5`（接口契约「HTTP」） | 出站报文无法编码 | +（无） 答复就地更新结论，并按 [README.md](README.md)「维护清单」落到对应条款。 @@ -124,9 +112,17 @@ | 编号 | 事项 | 结论 | |---|---|---| +| Q2 | 信箱编号的单调、不复用、不回退 | 已定案：编号即入库行号，单调递增、不复用、不回退；按编号升序处理即按到达顺序（`US-01` AC3、`CLM-2`） | +| Q4 | `schd` 载荷 | 已定案：`schd` 每条为运营航班 JSON（`C-9`、`US-08`） | +| Q7 | 入站处理时间列 | 已定案：与旧系统相同，列名为 `CMINMSGS_DATE_PROCESSED`；空为未处理，回填写入完成时刻（`US-10`） | +| Q8 | 现场有、文档没有的报文 | 已定案：仍须想办法处理，不得因 SIS 未记载就丢掉（`US-05` AC1）；具体形态与落库规则随对拍补齐 | +| Q9 | 入站信箱行（MySQL `CMINMSGS`）清除 | 已定案：本系统回填后自清（`C-1`）；保留期可配置，按约 1 个月 | | Q11 | 上游 `SEQN` 的重置周期与身份是否加日期边界 | 已定案：`SEQN` 自增，极少重置，重置后不与旧消息冲突，不加日期边界（`C-3`） | | Q13 | 日计划未携带字段的删除语义 | 见 `C-6` | -| Q14 | 主/共享删除顺序 | 已定案：标记删除，各自独立（`C-5`） | 已闭环 | +| Q14 | 主/共享删除顺序 | 已定案：标记删除，各自独立（`C-5`） | +| Q20 | Redis 投影用途 | 已定案：供读取全体动态航班；与 `GET /all/flights`、网页客户端同一份（`C-11`、`US-12`） | +| Q24 | `GET /all/flights` 返回体结构 | 已定案：JSON 由消息文档中的 XML 结构转换而来；读 Redis、返回全体动态航班、不分页（`C-11`、`US-12`） | +| Q25 | `RQRD` / `RQFD` 编码字段 | 已定案：`SNDR=OMMS`；`SEQN` 本系统自建序列；`DTTM` 为北京时间 `YYYYMMDDHHMMSS`（SIS META）；`RQRD` 子类型以 SIS 为准共 14 类（含 `RSTA`，其可选 `RTYP`）；`RQFD` 的 `STYP=NONE`，`STDB`/`STDE` 等筛选可选，全量同步不带筛选（SIS：无参数则返回当天全部，对齐 `US-07`）（`C-4`） | ### 6.3 本系统与需求方待决 @@ -135,9 +131,9 @@ | 编号 | 事项 | 当前假定 | 影响 | |---|---|---|---| | Q1 | 生产库选型 | 自有 PG 是唯一权威；生产环境用 PostgreSQL 还是 Oracle 11g 不能从三份依据确定，Oracle 适配验证通过前不作支持承诺 | 生产部署验收 | +| Q3 | `POST /cminmsgs/send` 的长度上限与失败响应 | 仅内部联调、无外部引用；成功返回编号等行为见 `C-7`；上限与失败格式现阶段不定，实现时在代码里自定 | 不阻塞对外契约 | | Q17 | `POST /schd/sync` 的请求字段与时间格式、成功响应表示已登记还是已落信、状态码与错误响应 | 交付承诺止于落信（`C-4`）；旧系统线索为 `{startDate, endDate}` 与 12 小时制时间（接口契约「HTTP」） | 响应契约无法定稿（`C-8`） | | Q18 | 人工发起 `RQRD` 的方式 | `US-09` 要求人工发起，HTTP 接口清单没有对应入口 | 参考数据请求无法人工触发 | -| Q19 | `msg` 的版本与去重标识是否直接采用航班当前态的版本号 | 可用依据见 implementation「航班域」与投递中的 `STATE_VERSION` | 消费方去重规则未定（与 `Q4` 衔接） | | Q21 | 回退时在途消息（已提交业务变更、未到处理完成）的处置 | 回填了结后切换（`OPS-4`）；在途消息无跨系统幂等保障 | 回退演练的验收口径（`OPS-4`） | | Q22 | 是否在自有 PG 留存入站原文副本，及原文提前清除时已登记消息的处置 | 不留存，原文只从信箱读取 | 提前清除的消息不可恢复，处置未定 | | Q23 | 日计划中运营日冲突的处置 | 未定 | 冲突场景无法验收 |