fix: correlate downstream receipts with submit responses

2026-07-14 16:22:41 +08:00
parent 135b4fd24e
commit 1ce02ef206
12 changed files with 487 additions and 91 deletions
@@ -280,6 +280,8 @@
 - 下游投递重试已改为指数退避第一版：首次失败后按基础间隔重试，随后按 2 倍递增，并受最大退避上限约束，避免客户长时间离线时平台每分钟机械重试。
 - 下游状态必须以客户确认作为终态：Gateway `SendPkt` 成功后只能写 `awaiting_ack`，仅收到匹配连接、`Sequence_Id`、`Msg_Id` 且 `CMPP_DELIVER_RESP.Result=0` 后才能写 `delivered`；超时、非零 Result 和历史未留存 ACK 的记录分别按未确认、拒绝或历史未确认展示，不能再把 TCP 写出冒充客户已收到。
 - 企业应用必须分别提供“回执自动重试投递”和“上行短信自动重试投递”开关，默认开启。开关按投递创建时快照保存；关闭只阻止已经写出但未获 ACK/被拒绝后的自动重发，不阻止离线队列在客户首次上线时完成首次投递。手工重投不受开关限制，但必须提示重复业务处理风险并二次确认。
+- 客户 Submit 的失败状态回执必须严格晚于对应 `CMPP_SUBMIT_RESP` 写出，且 Deliver 中的业务 `Msg_Id` 必须非 0、与该 SubmitResp 返回的 `Msg_Id` 完全一致；`Result=0` 但 `Msg_Id=0` 只能表示客户端协议栈收包，不能标记业务回执已确认。平台必须持久化原 Submit Sequence_Id，使 Gateway 重启或客户重连后的补投仍可重建相同业务 `Msg_Id`。
+- 运营端允许对 `delivered`（客户端已确认）记录再次手工重投，但单条和批量入口都必须明确提示可能造成下游重复处理；`awaiting_ack` 状态在确认窗口内不得并发重投。
 - 已实现客户侧最终 Deliver 推送的第一版能力：Gateway 在下游 Submit 被接受后记录 messageId 到客户连接的内存映射；NestJS 收到最终 receipt/uplink 并入库后调用 Gateway `/downstream/receipt`、`/downstream/uplink`，Gateway 向仍在线的客户 CMPP 连接下发 Deliver Receipt 或普通 Deliver。
 - 已实现客户侧 Deliver 持久化第一版能力：NestJS 收到最终 receipt/uplink 后写入 `CmppDownstreamDelivery` 待投递记录；在线推送成功标记 delivered，客户断线或 Gateway 不可达时保留 pending 并记录 retry 信息；客户重新 bind 后 Gateway 按账号拉取 pending 记录补发。
 - 已实现普通上行匹配与人工认领第一版：优先按 messageId 精确匹配；无 messageId 时按接入号匹配应用路由；仍无唯一应用时按手机号和最近下发时间窗口匹配；多候选标记 ambiguous 并写入 `SmsUplinkMatchCandidate` 候选，运营端可人工认领候选应用/下发记录；认领后更新上行记录、保留候选审计，并创建真实客户侧上行 Deliver 投递记录。