msgexchange-v2/docs/user-stories.md

msgexchange-v2 用户故事草案

依据 architecture.md、design.md、Plane ACM2-3/5/6/7/12/15～22 与 legacy 基线整理。 本文描述目标能力和明确保留的兼容行为，不代表当前代码已完成。

1. 约定

• “信箱已落信”“PG 已入队”“业务处理成功”“共享信箱已回填”“下游已投递”是不同事实。
• KEEP 表示兼容现役；FIX 表示修复 legacy 缺陷；DEFERRED 表示不属于阶段 A。
• 依赖只表示前置能力，不形成循环；待决策内容不得伪装成验收标准。

2. 阶段 A 用户故事

US-01 可靠采集共享信箱报文

作为 平台运维人员，我希望 持续采集 CMINMSGS 未处理报文，以便 上游无需改变投递方式。

验收标准

1. 按配置周期、ID 升序和有限批次采集 DATE_PROCESSED IS NULL；这里只采集入队，不代表业务已处理。
2. 快路径使用持久化高水位增量扫描；另以受控周期补偿重扫“未处理且 PG 无状态”的记录。水位只在本批入队确认后推进。
3. 每个 ID 在 PG 至多一个 PROC_STATE(PENDING)；重复发现不重复入队。
4. PG 不可用时不改共享信箱标记；恢复后补偿重扫能补建遗漏状态。
5. 单条异常和数据库故障可观察，轮询线程不得静默退出。

依赖：共享库读权限、字段与索引契约。
实现差距：当前 InboxPoller 固定 afterId=0 全量扫描，无持久化水位和独立补偿频控。

US-02 通过兼容接口注入报文

作为 联调人员，我希望 通过 POST /cminmsgs/send 注入 XML，以便 执行回放和对拍。

验收标准

1. 信箱落信后返回 CMINMSGS_ID，响应不得暗示 PG 已入队或业务已处理。
2. 落信成功但 PG 入队失败时，由 US-01 最终补建。
3. Content-Type 支持 text/xml、application/xml 与 text/plain（默认按 UTF-8 解码）；空报文、超大报文（> 10MB）及畸形 XML 返回规范错误。
4. 响应结构逐字兼容 legacy ResponseDto：成功返回 {"is_success": true, "body": <CMINMSGS_ID>}，失败返回 {"is_success": false, "err_code": "<code>", "err_msg": "<detail>"}。
5. 生产默认沿用现役内网互信免密姿态（网关限定内部 IP 网段与审计）；外露或跨网络时启用 Header 认证。

依赖：US-01。

US-03 严格按序且幂等地执行处理管道

作为 航班数据消费者，我希望 报文严格按信箱顺序处理，以便 重试不会造成倒序状态。

验收标准

1. 选择最小未完成 ID；PENDING、FAILED 都占队头，退避期间后续消息不得越过。
2. identity 首绑为 SNDR|TYPE|STYP|SEQN；冲突转 SKIPPED 并记录原 ID。
3. MALFORMED 直接 DEAD；CODEC_ERROR/UNSUPPORTED/INFRA 退避；attempts 或 HOL deadline 耗尽后转 DEAD(EXHAUSTED)。
4. PUMP_JOB 不与消息形成统一全序，只在无队头或队头尚在退避窗口时执行；不得让已到期消息饥饿。
5. Redis 先应用；MSG_EVENT 与 PROC_STATE→SUCCEEDED 在同一 PG 事务提交。
6. Redis 已写、PG 未提交的窗口可幂等重放。

依赖：US-01。
既有基线定案：生产幂等键默认采用 SNDR|TYPE|STYP|SEQN，include-day-boundary=false 禁开，防止跨日重放漏判；HOL deadline 起算时间统一固化为 PROC_STATE.CREATED_AT（稳定入队时间戳），消除重试刷新 updatedAt 导致的超时不可达缺陷。

US-04 忽略非业务报文（KEEP）

作为 运维人员，我希望 已确认无需处理的报文被明确忽略，以便 不产生 DLQ 噪声。

验收标准

1. 解码 META 后、查 Handler 前，大小写不敏感匹配 TYPE-STYP 与 TYPE-*。
2. 基线为 LDM-*、REGN-*、RSTA-*、EROR-*；统一采用 EROR，消除 test 的 ERROR 漂移。
3. 命中后进入 SKIPPED，记录 ignored:<rule>，不创建业务事件。
4. 按 US-09 的规则回填共享信箱，并保留审计计数。

依赖：US-03、US-09。

US-05 应用 ADFT 与 29 类 FLOP 报文

作为 OMMS 业务，我希望 正确应用增量报文，以便 Redis 动态符合 wire 契约。

验收标准

1. SCHD-ADFT 和 29 个 FLOP 子类型均有纯函数 Handler；未知类型进入 FAILED(UNSUPPORTED)。
2. 每类覆盖输入、Redis 变化、msg、schd、处理终态五面断言。
3. 航班不存在按 legacy KEEP 语义结束且不重试：以 SUCCEEDED 终态结束，按 US-09 回填共享信箱 DATE_PROCESSED = now(), STATUS = 'SUCCESS'，防止死循环。
4. 共享航班默认不直接发通知，而是更新并通知主航班；FDEL 例外定案：删除共享航班时更新主航班 MAFL 列表并发出主航班通知；若删除主航班则删除其及所有子共享关联并发出删除通知；目标航班不存在时幂等成功退出。
5. ADFT/FDEL 使用值相等比较，主/共享关系作为一次原子 Redis 变更持久化（FIX）。
6. PSDT 依赖 US-14，Handler 不直接调用 admin-api。

依赖：US-03、US-14、SIS/XSD 与 KEEP/FIX 矩阵。

US-06 导入 RESP/DNLD 日计划快照

作为 航班计划使用方，我希望 RESP 与 DNLD 共用快照流程，以便 主动下载和请求应答获得相同终态。

报文	SnapshotFlow	REQ_TRACK	Kafka msg	迟到/无匹配处理
SCHD-DNLD	是	不更新	成功后通知	不适用（广播/全量）
SCHD-RESP	是	匹配开放 RQFD 后 DONE	成功后通知	严禁更快照，转 SKIPPED 并审计
SCHD-ADFT	否，走 US-05	不更新	按增量规则	增量应用

验收标准

1. RESP/DNLD 共用 staging 流式整包校验和 SnapshotFlow，不作为普通 FLOP 增量 Handler 重复实现。
2. 主泵执行先后严格服从 I2（happens-before）：主泵线程先执行 Redis Lua 完成写新代、旧代差集删除及 generation 版本 CAS（ADFT 航班存活，FIX）；Redis 执行成功后进入自有 PG 本地事务。
3. 自有 PG 本地事务原子性：同一 PG 事务内原子提交 PROC_STATE → SUCCEEDED、匹配开放请求的 REQ_TRACK → DONE（记录 completed_at 与 resp_cminmsgs_id）及 MSG_EVENT 出站通知。
4. 整包失败保留旧快照；相同报文重放（CAS 版本一致）幂等，不重复增代或差删。
5. 迟到（dttm < req.sentAt）或无匹配/过期（EXPIRED）RESP 严禁更新快照，转入 PROC_STATE → SKIPPED 并记录审计与告警，防止历史快照时光倒流覆盖新状态（对齐 G12）。
6. 覆盖首次/连续发布、DNLD→ADFT→DNLD′、RESP 匹配和崩溃窗口。

依赖：US-03、US-08、Redis gen 协议。

US-07 可靠、有序地投递 Kafka

作为 Kafka 消费者，我希望 状态可见后有序投递，以便 通知不指向旧状态。

验收标准

1. KAFKA:msg 按 EVENT_ID FIFO，确认后才标 SENT。
2. KAFKA:schd 按周期和上限领取；同一 FLID 仅发批内最新事件。
3. 失败保持队头并退避；耗尽后 DEAD，不静默丢弃。
4. 事件包含稳定去重标识，分区键和重复投递有契约测试：KAFKA:msg 以 SNDR 作为分区键；KAFKA:schd 严格以 FLID 为分区键，确保单航班有序。
5. 生产环境对接 Kafka 2.8+ / 3.x+，生产者强制 acks=all、enable.idempotence=true 与 max.in.flight.requests.per.connection=1，严禁非幂等降级；投递失败退避重试，达上限转 DEAD(DLQ) 告警，绝不静默丢弃。

依赖：US-03、现网 Kafka Broker API 版本确认（切流前 kafka-broker-api-versions.sh 探测 InitProducerId(22)；未确认前不得标 US-07 实施完成）。

US-08 发起并跟踪 15 类 AODB 请求

作为 业务或运维人员，我希望 发起请求并跟踪生命周期，以便 区分登记、落信、等待、完成和超时。

验收标准

1. 支持 14 类 RQRD 参考请求和 1 类 RQFD-NONE 日计划请求。
2. REQ_TRACK 先登记；COUTMSGS 落信后才关联 ID 并标 SENT，落信不等于对方已发送。
3. 逐类超时与并发规则定案：同类请求并发严格为 1（新请求注册时强制同类未决请求转 EXPIRED）；RQFD-NONE 超时为 60s，14 类 RQRD 超时默认为 30s。
4. 响应经 US-01/US-03 入站：优先以报文回显 SEQN（echoSeqn）精确匹配开放请求；无回显时降级为时序判定（仅接受 DTTM >= SENT_AT 的开放请求），并在完成时同 PG 事务标 DONE。
5. 超时或被替代的请求 EXPIRED；迟到响应（DTTM < SENT_AT）或无匹配响应严禁更新业务状态/快照，转 SKIPPED 并留审计。
6. 集成验收：SCHD-RESP 遵循 US-06；14 类响应刷新 REF_MASTER，不与 admin-api 21 类混同。

依赖：US-01、US-03、COUTMSGS 适配器及逐类超时参数。

US-09 补偿回填共享信箱

作为 上游和运维人员，我希望 PG 终态最终反映到共享信箱，以便 未处理积压语义准确。

验收标准

1. 解耦与异步执行：主泵 PG 事务（更新 PROC_STATE 终态 + 插入 MSG_EVENT）内写入持久化回填意图；PG 事务提交后异步触发共享信箱回填，严禁内联同步阻塞等待共享库；回填失败绝不回滚 PG 终态。
2. 持久化补偿：未完成或失败的回填由后台补偿任务按指数退避重试；暴露待回填积压量与最老年龄指标，持续失败触发告警。回填 SQL 具备幂等性（UPDATE CMINMSGS SET DATE_PROCESSED = :now, STATUS = :status ... WHERE CMINMSGS_ID = :id）。
3. 各终态回填规则矩阵（单值锁定；库方/legacy 实测前为占位，见 §7-9）：
   • SUCCEEDED：必须回填（DATE_PROCESSED = now(), STATUS = 'SUCCESS'，补齐 META 子系统列）。
   • ignore SKIPPED（规则忽略）：必须回填（DATE_PROCESSED = now(), STATUS = 'SKIPPED'），防止上游视作未处理积压持续重扫。
   • duplicate SKIPPED（身份键重复）：必须回填（DATE_PROCESSED = now(), STATUS = 'DUPLICATE'），确认去重终结。
   • DEAD（毒丸/耗尽/MALFORMED）：必须回填（DATE_PROCESSED = now(), STATUS = 'DEAD'），避免共享信箱长期未处理告警或双跑旧系统死循环。运维人工重放基于自有 PG 驱动，不依赖信箱重置。
   • 非终态（PENDING、FAILED）：绝对禁止回填，保持 DATE_PROCESSED IS NULL。
4. 影子与双跑隔离：影子实例绝对禁止回填共享信箱；与 legacy 双跑时严格保持单系统持有标记写权。
5. 查询和日志分别展示 PG 终态与信箱回填状态。

依赖：US-03、共享库更新权限、共享库 STATUS 值域确认（库方/legacy 对拍）。

US-10 运维重放与故障处置

作为 运维人员，我希望 查询并安全重放失败项，以便 修复故障而不破坏顺序。

验收标准

1. 可按记录、错误类和时间查询 attempts、错误及 traceId。
2. 仅 CODEC_ERROR/UNSUPPORTED/INFRA/EXHAUSTED 可重放；请求含 MALFORMED 时静默跳过该记录，并返回逐项结果。
3. 重放清零 attempts/nextAttemptAt，保留错误审计，仍服从 FIFO。
4. DEAD、持续回填失败、队列年龄越界产生告警；操作记录操作者、原因、范围和结果。

依赖：US-03、鉴权与审计。

US-11 归档终态入站报文

作为 平台运维人员，我希望 定期归档终态报文，以便 控制信箱规模且不丢未完成工作。

验收标准

1. 默认处理接收时间早于 1 天的 SUCCEEDED/SKIPPED/DEAD；保留期可配置为 1～7 天；不迁 PENDING/FAILED。
2. 共享库零建表与 DML 最小化定案：严禁向共享 MySQL 写入 CMINMSGS_HST，共享库严格限定为信箱两表（CMINMSGS 读/回填，COUTMSGS 写入）；共享 MySQL 自身历史清理交由库方自身 DBA 策略。
3. 归档迁入自有 PG：在自有 PostgreSQL 设计 PROC_STATE_HST（及 MSG_EVENT_HST）承载历史归档数据。
4. 重复执行幂等并记录计数；迁移失败时 fail-closed，不删除源记录。

阶段：A。

US-12 查询实时航班

作为 授权调用方，我希望 查询实时航班，以便 获得与 Redis 权威态一致的数据。

验收标准

1. KEEP GET /all/flights：返回 Redis 当前航班并过滤 MAID != NULL 的共享航班。
2. 固定响应、空结果、排序、分页/大小上限和一致性时点。
3. 影子只查询影子 key；接口具备认证、限流和审计。

US-13 刷新 21 类参考主数据

作为 业务组件，我希望 从 admin-api 刷新 21 类数据到 REF_MASTER，以便 使用可审计的本地主数据。

验收标准

1. 采用 ACM2-5 清单；admin-api 拉取与 US-08 的 AODB 请求是两个入口。
2. 以 (RTYPE,RKEY) 幂等 upsert，记录 SOURCE、刷新时间和批次审计。
3. 单类失败不发布半批，不破坏上个可用版本；影子默认不主动刷新生产数据。

US-14 提供机位与登机桥数据

作为 PSDT 处理逻辑，我希望 获得机位和登机桥映射，以便 正确计算 abdg。

验收标准

1. 保留 ORMS_STAND 与 ORMS_STAND_AIRBRIDGE，和新增 21 类分开统计。
2. 通过适配器拉取并缓存；Handler 不直接 HTTP。
3. 近机位生成登机桥，远机位或清空时 abdg 为空；多桥规则由 golden 固定。
4. admin-api 不可用时使用最后可用版本或明确失败，不写不完整缓存。

3. 延后故事

US-15 历史航班清场（DEFERRED）

作为 平台运维人员，我希望 历史写成功后移出实时态，以便 控制 Redis 规模且不丢历史。

1. 全系统统一固定基准时区为 Asia/Shanghai（CST, UTC+8）。
2. 阶段归属与 ES 边界定案：HISTORY_SWEEP 延后为阶段 B 能力（DEFERRED），阶段 A 永续以 Redis 作为航班动态权威，完全不接入 ES；不作为阶段 A 切流门禁。
3. 五条判史规则与 ES 写入留在阶段 B 启用前完成 100% golden 对拍；逐条隔离坏数据；仅历史写成功的 FLID 可由主泵删除。
4. 与快照保持单写者串行并记录计数。

4. 上线 Epic

EPIC-OPS 安全运行、影子验证与切流

该范围不能作为一个故事验收，拆为：

1. OPS-1 单写者与 fail-fast：第二写实例拒启；生产缺依赖或管道未启用时失败并说明原因。
2. OPS-2 可观测性：健康、队列、最老年龄、投递延迟、回填滞后、DEAD 和一致性均有指标/告警。
3. OPS-3 影子隔离：独立 PG、Redis 前缀、topic、服务名；禁用真实出站和回填。
4. OPS-4 切流回滚：影子连续稳定对拍不少于 7 天；未解释业务字段差异严格为 0；DLQ 积压为 0；MSG_EVENT 最老滞留 < 5s；切流后设立 48 小时观察期，24 小时内支持按 Runbook 平滑一键回滚。

依赖按实际进入上线范围的阶段 A 故事计算，不包含 US-15。

5. Legacy HTTP 工具面

端点	决定	目标口径
POST /cminmsgs/send	KEEP	US-02
POST /schd/sync	KEEP，修正	24 小时制、非空/区间校验；只承诺 RQFD 落 COUTMSGS
GET /all/flights	KEEP	US-12
POST /kafka/topics/{name}/msgs	不进生产	若开发仍需，另建工具并限制 topic allowlist
GET /flights/migrate	不做	legacy 一次性 ES 迁移工具

6. 详细文档 TODO

顺序	Plane	文档动作	完成条件
1	ACM2-16	固定 RESP/DNLD/ADFT 路由	US-06、design、ACM2-6 一致，迟到/无匹配禁更快照定案
2	ACM2-17	拆归档与清场并标阶段	US-11 属 A，US-15 DEFERRED；HST 禁写，自有 PG 归档定案
3	ACM2-19	增补信箱回填	提交后执行、持久化补偿、四终态回填、影子禁写定案
4	ACM2-21	消除循环依赖并补管道边界	US-03 仅依赖 US-01，业务例外归 US-05
5	ACM2-15	增补 ignoreMsg	规则、终态、回填和拼写确定
6	ACM2-18	补查询、机位、21 类数据	US-12～14 与 US-08 分界明确
7	ACM2-20	声明 HTTP 工具去留	五端点均有决定
8	ACM2-22	吸收评审剩余项	水位、依赖、Broker、deadline 一致
9	—	同步 architecture/design/README	权威口径、索引与阶段表一致

7. 开放问题定案结论汇总

1. 【已定案·ACM2-17】归档存储目标：共享库 CMINMSGS_HST 严禁写入，共享库严格限定信箱两表；归档目标确认为自有 PG PROC_STATE_HST。
2. 【已定案·ACM2-21】SEQN 重置与时钟锚点：生产默认保持 include-day-boundary=false；HOL deadline 锚点固化为 PROC_STATE.CREATED_AT（稳定入队时间戳）。
3. 【已定案·ACM2-20/25】compat 接口契约：支持 text/xml、application/xml 与 text/plain；逐字兼容 legacy ResponseDto（成功 is_success+body；失败 is_success+err_code+err_msg，不用 msg）；生产保持内网信任姿态。
4. 【已定案·ACM2-21】航班不存在与 FDEL：航班不存在按 KEEP 正常结束且回填信箱；FDEL 共享航班更新主航班 MAFL 并通知，主航班删除清空关联。
5. 【已定案·ACM2-16/18】15 类请求生命周期：同类并发严格为 1；RQFD 超时 60s，RQRD 超时 30s；优先 SEQN 回显，无回显退化 DTTM 时序判定；迟到/无匹配禁更快照。
6. 【已定案·ACM2-22/23】Kafka 生产契约：强制 acks=all 与 idempotence=true，分区键按 FLID（schd）/SNDR（msg）固化；严禁非幂等降级；现网 Broker API 版本未确认前 US-07 不得标实施完成；README 不提供生产降级 env。
7. 【已定案·ACM2-17】时区与判史边界：统一 Asia/Shanghai 时区；HISTORY_SWEEP 延后至阶段 B，阶段 A 不依赖 ES，Redis 永续动态权威。
8. 【已定案·ACM2-22】对拍与回滚阈值：影子对拍至少 7 天；业务差异 0 容忍；DLQ 积压为 0；切流后 48 小时保驾、24 小时可平滑回滚。
9. 【已定案·ACM2-26】信箱回填 STATUS 值域：SUCCEEDED→SUCCESS；ignore SKIPPED→SKIPPED；duplicate SKIPPED→DUPLICATE；DEAD→DEAD（库方/legacy 实测前为占位；若库方禁新值则仅用 legacy 已用集合）。