feat: complete cmpp gateway delivery recovery workflows

docs/testing-progress.md

@@ -606,6 +606,500 @@ npm run verify:phase8
 - 下游 submit 当前通过 `sourceType=cmpp` 的系统批次兼容承载，尚未完全拆成独立单条发送模型。
 - 客户侧最终 Deliver Receipt 投递、客户侧上行 Deliver 推送、上游真实 SMSC submit worker、上游 receipt/uplink 生产解析仍未完成。
 
+## 2026-07-07 Gateway 上游提交与下游 Deliver 闭环补齐
+
+### 本轮修复
+
+- `SubmitCommand` 契约、示例和 Go 结构增加 `upstream.gatewayHost/gatewayPort/account/passwordCipher/cmppVersion`，API 发送链路在真实业务校验通过后保留 BullMQ 审计投递，同时写入 Redis Stream `gateway.submit.commands` 主命令流。
+- Go Gateway 新增上游提交管理器，按通道建立/复用 gocmpp 客户端连接，发送真实 CMPP Submit，接收 SubmitResp，并回调 NestJS `SubmitResult`。
+- Go Gateway 上游读循环开始处理 deliver receipt 和普通 deliver 上行：receipt 解析后回调 NestJS `/gateway/events/receipt`，普通上行解码后回调 `/gateway/events/uplink`。
+- Gateway 下游入站服务记录客户 Submit 对应的 messageId 到在线客户连接映射；NestJS 收到最终 receipt/uplink 并入库后调用 Gateway `/downstream/receipt`、`/downstream/uplink`，Gateway 向在线客户下发 CMPP Deliver Receipt 或普通 Deliver。
+- `api/src/send-chain/send-chain.service.spec.ts` 覆盖 SubmitCommand 上游配置和 Redis Stream 发布；`gateway/internal/inbound/server_test.go` 覆盖客户 submit 后平台下发 Deliver Receipt；Gateway 契约示例覆盖新 upstream 字段。
+
+### 验证状态
+
+- `npm --prefix api test -- send-chain.service.spec.ts`：通过。
+- `npm --prefix api test`：通过，12 个 suites、82 个 tests。
+- `npm --prefix api run build`：通过。
+- `go test ./...`（Gateway）：通过。
+- `npm run spike:contracts`：通过，4 个 Gateway 队列契约示例通过。
+
+### 剩余缺口
+
+- Gateway 控制面 `/upstream/submit` 仅保留为调试/补偿入口；生产主链路由 Go Gateway submit worker 消费 Redis Stream `gateway.submit.commands` 触发。worker 当前覆盖新消息 `>` 消费和 ack，pending 历史消息扫描与精细重试治理放入后续在途恢复阶段。
+- 客户侧 Deliver Receipt/上行 Deliver 当前依赖 Gateway 内存在线连接映射；客户断线、Gateway 重启或映射丢失时尚未实现持久化缓存、重试和投递失败审计。
+- 普通上行只有能关联 messageId 的事件可推送给客户；仅按接入号、手机号、应用和时间窗口匹配客户连接仍待产品化。
+- 长短信拆分/重组、多连接窗口、窗口满、在途消息恢复、断线重连后的状态补偿仍待后续实现和压测。
+
+## 2026-07-07 阶段 1：Gateway SubmitCommand 独立消费
+
+### 本轮修复
+
+- NestJS SendChain 取消主链路同步调用 Gateway `/upstream/submit`；真实业务校验通过后创建 SmsSubmitRecord、保留 BullMQ `gateway.submit.queue` 审计/兼容投递，并向 Redis Stream `gateway.submit.commands` 写入 `SubmitCommand`。
+- Go Gateway 新增 `submitworker`，启动时默认创建/复用 consumer group `cmpp-gateway`，独立消费 Redis Stream 中的 `SubmitCommand`，调用同一个上游提交管理器真实 submit 到上游 SMSC。
+- Gateway `/upstream/submit` 保留为调试/运维补偿接口，不作为 API 主发送路径。
+- Gateway worker 支持环境变量：`REDIS_URL`、`GATEWAY_SUBMIT_STREAM`、`GATEWAY_SUBMIT_GROUP`、`GATEWAY_SUBMIT_CONSUMER`、`GATEWAY_SUBMIT_WORKER_DISABLED=true`。
+
+### 验收口径
+
+- API 入队后不再因为 Gateway 控制面短暂不可达而自己生成 timeout；SubmitResult 必须由 Gateway worker 真实消费和提交后回调。
+- Gateway 停止时，SubmitCommand 留在 Redis Stream；Gateway 恢复后由 consumer group 继续消费新消息。
+- BullMQ `gateway.submit.queue` 仅作为审计/兼容，不再是唯一主提交通道。
+
+### 剩余边界
+
+- 当前 worker 先覆盖新消息 `>` 消费和 ack；pending 历史消息扫描、claim、重试退避和死信审计放到在途恢复阶段继续做。
+
+## 2026-07-07 阶段 2/3：客户侧 Deliver 持久化重投与普通上行匹配
+
+### 本轮修复
+
+- Prisma 新增 `CmppDownstreamDelivery`，用于保存客户侧待投递 Deliver Receipt 和普通 Deliver 上行；状态覆盖 pending/delivered，记录 retryCount、nextRetryAt、lastError、payload、message/application 关联。
+- `SmsUplinkMessage` 增加 `applicationId`、`messageRecordId`、`matchStatus`、`matchReason`，并建立应用和匹配下发记录关系。
+- NestJS 收到最终 receipt 后，先写平台回执和消息状态，再创建客户侧待投递记录，尝试调用 Gateway `/downstream/receipt`；成功标记 delivered，客户不在线或 Gateway 不可达时保留 pending 并记录失败原因。
+- NestJS 收到普通上行后执行匹配：messageId 精确匹配优先；无 messageId 时按接入号匹配应用路由；仍无唯一应用时按手机号和最近下发时间窗口匹配；多候选标记 ambiguous，未匹配标记 unmatched，但均真实入库。
+- Gateway 下游客户 bind/login 成功后保存账号级在线连接，并调用 NestJS `/gateway/events/downstream/pending` 拉取 pending 投递；补发成功后回调 `/gateway/events/downstream/delivered`，失败回调 `/gateway/events/downstream/failed`。
+- 运营/客户端上行查询 include 应用和匹配下发记录，便于页面展示 matchStatus/matchReason。
+
+### 验证状态
+
+- `npm --prefix api run prisma:generate`：通过。
+- `npm --prefix api test -- send-chain.service.spec.ts`：通过。
+- `npm --prefix api test`：通过，12 个 suites、82 个 tests。
+- `npm --prefix api run build`：通过。
+- `go test ./...`（Gateway）：通过。
+- `npm run spike:contracts`：通过。
+- `npm run build`：通过，仅既有 Vite chunk size warning。
+
+### 剩余边界
+
+- 待投递 pending 目前在客户 bind/login 时拉取补发；后台周期扫描、指数退避、过期策略、死信队列和运营端失败审计页面仍待后续实现。
+- 上行匹配已覆盖 messageId、接入号和手机号时间窗口；共享接入号、多应用多候选时不会误推，但人工认领/改派流程尚未实现。
+- 客户连接断开检测和应用级连接数状态回写仍需继续产品化。
+
+## 2026-07-08 阶段 4：Gateway 长短信拆分与长上行重组
+
+### 本轮修复
+
+- Go Gateway 上游 Submit 支持长短信第一版拆分：超过 140 字节的短信按 CMPP 标准 6 字节 UDH 生成分片，每片总长度不超过 140 字节，并设置 `PkTotal/PkNumber/TpUdhi` 后逐包发送到上游 SMSC。
+- 同一平台 `SubmitCommand` 的多个 accepted 分片 `MsgId` 均登记到 Gateway 映射表，后续任一分片 receipt 可回溯到原 `messageId/submitId/channelId`。
+- Go Gateway 上游普通 Deliver 支持长上行第一版重组：收到 `TpUdhi=1` 且携带标准 UDH 的分片时，按通道、主叫、被叫、引用号和总片数缓存；分片齐全后只回传一条完整 `UplinkEvent` 给 NestJS。
+- 新增 `gateway/internal/upstream/long_message_test.go`，覆盖 UCS2 长短信拆分、短短信不分片、长上行乱序重组。
+
+### 验证状态
+
+- `go test ./...`（Gateway）：通过。
+
+### 剩余边界
+
+- 阶段 4 后长短信仍按单条平台消息记录展示，尚未提供运营端分片级提交明细、分片级补发审计和部分分片失败后的精细补偿；该审计缺口已在阶段 23 补齐第一版。
+- 长上行分片缓存当前为 Gateway 进程内内存；Gateway 重启、跨连接分片漂移或超过缓存 TTL 的残片不会恢复，后续在“在途消息恢复/状态补偿”阶段继续做。
+
+## 2026-07-08 阶段 5：Gateway 多连接窗口与窗口满控制
+
+### 本轮修复
+
+- `SubmitCommand.upstream` 契约、示例、Go 结构和 NestJS 生产者增加 `desiredConnections/windowSize`，字段来自通道真实配置；未配置时默认 `desiredConnections=1`、`windowSize=16`。
+- Go Gateway 上游提交管理器从单连接升级为通道级连接池：同一通道按 `desiredConnections` 建立多条 CMPP 客户端连接，每条连接独立维护 submit pending、receipt/uplink 映射和长上行分片缓存。
+- 每条上游连接增加窗口令牌；提交前必须获得窗口，SubmitResp、reject 或 timeout 后释放窗口；所有连接窗口均满时等待可用窗口，超过提交超时时返回 `WINDOW_TIMEOUT`。
+- 长短信分片也复用连接池窗口调度，同一条平台消息的多个 accepted 分片仍映射回原 `messageId/submitId/channelId`。
+- 新增 `gateway/internal/upstream/pool_test.go`，覆盖连接池跨连接获取窗口、窗口满拒绝继续占用、释放后可重新获取。
+
+### 验证状态
+
+- `go test ./...`（Gateway）：通过。
+- `npm --prefix api test -- send-chain.service.spec.ts`：通过。
+
+### 剩余边界
+
+- 当前窗口状态为 Gateway 进程内控制，尚未把连接级窗口占用、等待队列长度、submit latency 等指标回写到 NestJS 或运营端页面。
+- 当前阶段只处理窗口容量和多连接发送；Gateway 重启、上游连接断开时的在途 submit 恢复、pending claim、状态补偿和死信审计仍在下一阶段处理。
+
+## 2026-07-08 阶段 6：CMPP 配置入口补齐
+
+### 本轮修复
+
+- 运营端通道创建/编辑表单新增上游 `desiredConnections` 和 `windowSize` 输入，真实提交到 NestJS 通道 API，并规范化写入 `SmsChannel.config`。
+- NestJS `ChannelsService` 对 `desiredConnections/windowSize` 增加正整数校验；通道激活后的 `ConnectChannel` 请求和发送链路 `SubmitCommand.upstream` 均复用该真实配置。
+- Prisma 为 `SmsApplication` 新增 `cmppMaxConnections`、`cmppWindowSize` 字段；运营端短信应用创建/编辑表单新增 `cmppAccount`、客户最大连接数、客户提交窗口输入。
+- 企业应用 `cmppAccount` 现在支持两种真实路径：显式填写 6 位数字账号，或留空由后端自动生成唯一账号；重复账号和非法格式会被后端拒绝。
+- 企业应用 CMPP 参数接口改为从应用真实字段返回 `account/maxConnections/windowSize`，不再借用任意通道默认值拼装客户参数。
+
+### 验证状态
+
+- `npm --prefix api run prisma:generate`：通过。
+- `npm --prefix api test -- sms-config.service.spec.ts channels.service.spec.ts`：通过，2 个 suites、34 个 tests。
+- `npm --prefix api run build`：通过。
+- `npm run build`：通过，仅既有 Vite chunk size warning。
+
+### 说明
+
+- `desiredConnections/windowSize` 不是 CMPP 协议标准字段，也不是 gocmpp 的原生配置项；它们是本平台对上游通道连接池和提交窗口的运行参数。
+- `cmppAccount` 是客户侧应用接入账号；当前已支持真实生成、真实保存和显式配置。
+
+## 2026-07-08 阶段 7：SubmitCommand 在途恢复第一步
+
+### 本轮修复
+
+- Go Gateway `submitworker` 在正常消费新消息前新增 pending 恢复流程：对 Redis Stream consumer group 中空闲超过阈值的消息执行 `XAUTOCLAIM`，将滞留在 PEL 的 `SubmitCommand` 认领到当前 consumer。
+- 被认领的 pending 命令复用现有 `handleMessage -> Upstream.Submit -> XAck` 成功路径处理；成功后 ack，失败时保留在 PEL，留给后续重试/死信治理。
+- `submitworker` 增加可注入 `Submit` 函数，便于单测覆盖消息处理路径；新增单测覆盖 injected submit 和默认 `minIdle` 阈值。
+
+### 验证状态
+
+- `go test ./...`（Gateway）：通过。
+
+### 剩余边界
+
+- 当前恢复能力只覆盖 Redis Stream PEL 中“已被读走但未 ack”的 pending 命令；尚未实现恢复次数上限、死信队列、失败审计页面和人工补偿入口。
+- Gateway 重启时上游连接内已经发出但尚未收到 submit resp 的 in-flight CMPP 请求，仍未完成状态补偿；这部分继续放在后续“断线重连后的消息状态处理”阶段。
+
+## 2026-07-08 阶段 8：上游连接断开时 pending submit 补偿
+
+### 本轮修复
+
+- Go Gateway 上游连接读循环开始区分“空读超时”和“真实连接断开”；空读超时继续等待，真实断开则进入连接丢失处理。
+- 某条上游连接断开时，Gateway 会把该连接上所有等待 submit resp 的 pending submit 立即唤醒，返回 `timeout` + `CONNECTION_LOST`，不再机械等待固定 `SUBMIT_TIMEOUT`。
+- 连接池在再次分配连接前会重新执行 `ensureConnected()`；旧连接断开后，后续新消息可重新建立物理连接继续提交。
+- 新增 `gateway/internal/upstream/connection_loss_test.go`，覆盖 pending submit 被唤醒和临时读超时识别。
+
+### 验证状态
+
+- `go test ./...`（Gateway）：通过。
+- `npm --prefix api test -- send-chain.service.spec.ts`：通过。
+
+### 剩余边界
+
+- 当前补偿只覆盖“连接断开且 submit resp 尚未返回”的场景；尚未覆盖“上游其实已受理，但 submit resp 在断线前后丢失”的二次确认和幂等回查。
+- submit 结果死信队列、失败审计、恢复次数上限和人工补偿入口仍在后续阶段。
+
+## 2026-07-08 阶段 9：receipt 驱动的保守二次归因
+
+### 本轮修复
+
+- Gateway 上游 receipt 事件补充 `phoneNumber`，即使无法从内存 tracker 中精确恢复平台 `messageId`，也会把运营商回执手机号带回 NestJS。
+- NestJS `handleReceipt` 新增保守归因：如果 receipt 无法按平台 `messageId/gatewayMessageId` 精确命中，只在“同通道、同手机号、72 小时窗口内、且仅存在 1 条 `timeout + gatewayMessageId=null` 的 submit 记录”时才接收该回执。
+- 归因成功后会先回填该次 `sms_submit_record.gatewayMessageId/sequenceId`，再写入真实 `sms_receipt_record` 并按既有逻辑更新 `sms_message_record`、下游客户回执推送和幂等保护。
+- 新增 SendChainService 单测，覆盖唯一候选归因成功和多候选拒绝归因两种场景。
+
+### 验证状态
+
+- `go test ./...`（Gateway）：待本轮统一回归。
+- `npm --prefix api test -- send-chain.service.spec.ts`：待本轮统一回归。
+
+### 剩余边界
+
+- 当前只做“唯一候选才归因”的保守版本，仍未实现面向运营商或供应商的 submit 结果主动回查。
+- 如果同通道同手机号在窗口内存在多条 timeout 候选，系统会拒绝归因，后续仍需人工补偿或更强的协议级关联键。
+
+## 2026-07-08 阶段 10：SubmitCommand 死信治理第一版
+
+### 本轮修复
+
+- Prisma 新增真实表 `GatewaySubmitDeadLetter`，保存 Gateway SubmitCommand 死信的消息 ID、租户/应用/通道、失败原因、尝试次数、原始命令载荷、人工重入队状态和解决状态。
+- Go Gateway `submitworker` 新增失败次数治理：同一条 Stream 消息处理失败达到阈值后，调用 NestJS `/gateway/events/dead-letter` 入库死信，并对原消息执行 ack，避免它无限滞留在 PEL。
+- Gateway 对非法 `SubmitCommand` 载荷也会直接转死信，防止 poison message 持续阻塞消费。
+- NestJS 新增真实死信接口：Gateway 可上报死信；运营端后端可分页查询 `/api/admin/operations/gateway-submit-dead-letters`；可通过 `/api/admin/operations/gateway-submit-dead-letters/:id/requeue` 将原始 `SubmitCommand` 重新写回 Redis Stream。
+- NestJS 在收到同一 `submitId/messageId` 的后续真实 `SubmitResult` 时，会把对应死信自动标记为 `resolved`。
+
+### 验证状态
+
+- `npm --prefix api run prisma:generate`：通过。
+- `npm --prefix api test -- send-chain.service.spec.ts operations.service.spec.ts`：通过，2 个 suites、26 个测试通过。
+- `npm --prefix api run build`：通过。
+- `go test ./...`（Gateway）：通过。
+
+### 剩余边界
+
+- 当前死信治理只提供“达到阈值后入库 + 人工重入队”的第一版，尚未实现后台自动重放、重放节流、过期清理和专门的前端运营页面。
+- 非法载荷死信如果缺少完整 `SubmitCommand`，当前不可人工重放，只能用于审计和人工排查。
+
+## 2026-07-08 阶段 11：下游客户在线时周期补投与失败封顶
+
+### 本轮修复
+
+- 明确责任边界：客户系统负责断线后的重新 bind；平台负责客户不在线或临时投递失败时的消息不丢、待投递保存和补投。
+- Go Gateway 下游入站服务新增在线账号周期补投：除客户 bind 成功后立即拉取 pending 外，Gateway 还会按周期为当前在线账号再次调用 `/gateway/events/downstream/pending`，继续补发未投递成功的 Deliver Receipt/上行 Deliver。
+- Gateway 向下游发送 Deliver 失败时会清理失效的内存会话映射，避免对已失效连接无休止重复尝试。
+- NestJS `markDownstreamDeliveryFailed` 新增失败上限：未超过阈值时继续 `pending` 并推进 `retryCount/nextRetryAt`；达到阈值后转为 `failed`，停止无限重试，并写 `gateway.downstream_delivery_failed` 系统日志。
+
+### 验证状态
+
+- `npm --prefix api test -- send-chain.service.spec.ts`：通过，1 个 suite、21 个测试通过。
+- `go test ./internal/inbound ./internal/control ./...`（Gateway）：通过。
+
+### 剩余边界
+
+- 当前周期补投只针对“Gateway 认为客户在线”的账号；尚未实现下游投递失败专门列表、人工重投页面和跨 Gateway 实例共享的客户在线状态。
+- `CmppDownstreamDelivery` 目前仍使用固定重试间隔，尚未实现指数退避、不同消息类型差异化策略和过期归档。
+
+## 2026-07-08 阶段 12：下游投递失败审计与人工重投
+
+### 本轮修复
+
+- 运营端新增真实下游投递查询接口 `/api/admin/operations/downstream-deliveries`，支持按 `tenantId/applicationId/deliveryType/status/keyword` 筛选并分页返回真实 `CmppDownstreamDelivery` 数据。
+- NestJS 新增 `/api/admin/operations/downstream-deliveries/:id/requeue`，可对单条下游投递记录执行人工重投，真实调用 Gateway `/downstream/receipt` 或 `/downstream/uplink`，并写 `gateway.downstream_delivery_requeue` 系统日志。
+- 运营端新增“下游投递记录”页面，列表、详情、筛选和重投均接真实后端，不使用 mock、本地状态或静态数组。
+
+### 验证状态
+
+- `npm --prefix api test -- send-chain.service.spec.ts operations.service.spec.ts`：通过，2 个 suites、29 个测试通过。
+- `npm --prefix api run build`：通过。
+- `npm run build`：通过，仅有既有 Vite chunk size warning。
+
+### 剩余边界
+
+- 当前人工重投仍是单条操作，尚未提供批量重投、失败聚合告警和专门的下游投递 Dashboard。
+- 页面侧暂未做自动轮询刷新，需要手动查询或重进页面观察状态变化。
+
+## 2026-07-08 阶段 13：下游投递自动退避第一版
+
+### 本轮修复
+
+- `CmppDownstreamDelivery` 的失败重试从固定 60 秒改为指数退避：基础间隔来自 `CMPP_DOWNSTREAM_RETRY_DELAY_MS`，每次失败按 2 倍递增，并受 `CMPP_DOWNSTREAM_RETRY_MAX_DELAY_MS` 上限约束。
+- 这样在客户长时间离线或网络持续抖动时，平台不会每分钟机械重试同一条下游投递，能更温和地消耗 API、Gateway 和连接资源。
+- 总重试次数上限逻辑保持不变，超过 `CMPP_DOWNSTREAM_MAX_RETRIES` 后仍转 `failed` 并写失败审计。
+
+### 验证状态
+
+- `npm --prefix api test -- send-chain.service.spec.ts`：通过，新增指数退避单测。
+
+### 剩余边界
+
+- 当前退避策略还没有加入随机抖动，多个记录在同一时间失败时，后续重试时刻仍可能比较集中。
+- 退避参数当前是全局环境变量，尚未细分到 receipt/uplink 或不同客户应用级别。
+
+## 2026-07-08 阶段 14：下游投递批量重投
+
+### 本轮修复
+
+- 运营端下游投递记录页新增勾选和“批量重投”操作，仅允许对当前页的 `pending/failed` 记录执行批量重投。
+- NestJS 新增真实批量接口 `/api/admin/operations/downstream-deliveries/requeue`，逐条调用既有单条重投逻辑，返回成功/失败汇总，不用前端自行拼结果。
+- SendChainService 新增批量重投结果汇总与空选择拦截单测。
+
+### 验证状态
+
+- `npm --prefix api test -- send-chain.service.spec.ts`：通过，新增批量重投单测。
+- `npm --prefix api run build`：通过。
+- `npm run build`：待本轮统一回归。
+
+### 剩余边界
+
+- 当前批量重投只支持“勾选当前页记录”，还不支持“按筛选条件全量重投”或后台异步大批量任务。
+- 批量结果当前以内联提示为主，尚未做专门的批量执行历史与导出。
+
+## 2026-07-08 阶段 15：下游投递告警第一版
+
+### 本轮修复
+
+- `OperationsService.dashboard()` 新增真实下游投递告警聚合 `downstreamDeliverySummary`，统计 `pending/failed/delivered` 总量，以及“积压过久的 pending”和“最近失败”两类告警计数。
+- 运营端右上角通知新增“下游投递告警”，数量直接来自真实 Dashboard 聚合。
+- 运营看板新增下游投递告警摘要卡片，帮助运营从总览页直接感知当前下游投递异常。
+
+### 验证状态
+
+- `npm --prefix api test -- operations.service.spec.ts`：随定向测试通过。
+- `npm --prefix api run build`：通过。
+- `npm run build`：通过，仅有既有 Vite chunk size warning。
+
+### 剩余边界
+
+- 当前告警仍是站内聚合提醒，尚未接短信、邮件、企业微信等外部告警通道。
+- 告警口径当前采用全局阈值环境变量，尚未按客户应用、消息类型或时间段细分。
+
+## 2026-07-08 阶段 16：下游投递 Dashboard 第一版
+
+### 本轮修复
+
+- 新增真实接口 `/api/admin/operations/downstream-deliveries/dashboard`，直接按 `CmppDownstreamDelivery` 聚合返回 `summary/typeBreakdown/retryBuckets/topApplications`。
+- 运营端“下游投递记录”页面顶部补上真实 Dashboard 区域，展示投递总量、待投递、已投递、告警、类型分布、重试压力和应用告警排行。
+- Dashboard 筛选范围与页面应用/类型筛选保持一致，不允许由前端只根据当前页列表数据临时拼装。
+
+### 验证状态
+
+- `npm --prefix api test -- operations.service.spec.ts`：通过。
+- `npm --prefix api run build`：通过。
+- `npm run build`：通过，仅有既有 Vite chunk size warning。
+- `git diff --check`：无空白错误，仅 Windows LF/CRLF 提示。
+
+### 剩余边界
+
+- 当前 Dashboard 仍偏运营处置视角，尚未补时间趋势、按客户/账号维度的更细颗粒聚合。
+- 应用告警排行当前以 `pending + failed` 为主排序，尚未加入更复杂的权重和 SLA 指标。
+
+## 2026-07-08 阶段 17：下游在线账号 Presence 持久化底座
+
+### 本轮修复
+
+- Gateway inbound 新增 Redis presence store，客户 `cmppAccount` 在 bind 成功、submit 建链和下游回执/上行投递时，会把在线账号状态写入 Redis。
+- presence 数据至少包含 `account/srcId/remoteIp/gatewayInstanceId/state/connectedAt/updatedAt`，并按 TTL 自动过期，避免该状态只存在单进程内存中。
+- Gateway 发送失败触发连接清理时，会同步移除该账号的 Redis presence 记录。
+- 该阶段先完成“在线状态外部化”，尚未宣称“Gateway 重启后 pending 投递自动恢复”已完成；恢复逻辑在后续阶段继续补。
+
+### 验证状态
+
+- `go test ./internal/inbound/...`：通过。
+- `go test ./cmd/gateway/...`：通过。
+
+### 剩余边界
+
+- 当前 presence 主要服务于后续恢复能力，Gateway 还未在启动时主动根据 Redis presence 扫描并恢复 pending 投递。
+- 连接断开当前主要依赖发送失败清理和 TTL 过期兜底，尚未建立更完整的显式断线回收机制。
+
+## 2026-07-08 阶段 18：Gateway 恢复候选视图
+
+### 本轮修复
+
+- Gateway 启动时会读取 Redis presence，并输出恢复候选账号加载日志。
+- 新增控制面接口 `GET /downstream/recovery-candidates`，返回 Redis presence 与当前内存在线账号合并后的恢复候选视图。
+- 候选视图当前用于后续恢复逻辑和运维排查，不直接触发 pending 下游投递补发。
+
+### 验证状态
+
+- `go test ./internal/inbound/...`：通过。
+- `go test ./internal/control/...`：通过。
+- `go test ./cmd/gateway/...`：通过。
+
+### 剩余边界
+
+- 当前只是“识别谁值得恢复”，还没有执行“把这些账号的 pending 回执/上行自动继续补投”。
+- 候选视图默认按 Redis TTL 和最近活跃时间保留，尚未叠加更复杂的健康判定和跨实例去重策略。
+
+## 2026-07-08 阶段 19：Gateway pending 恢复执行第一版
+
+### 本轮修复
+
+- Gateway 启动时会立即按恢复候选账号执行一次 pending 下游投递恢复扫描。
+- 后续每轮补投周期除扫描当前内存在线账号外，也会继续扫描恢复候选账号，尝试恢复 `CmppDownstreamDelivery.pending`。
+- 当前恢复策略是“能投就投，投不了继续 pending”：若账号尚无可用下游连接，Gateway 不会把记录误标成失败，而是等待客户重连后的后续恢复机会。
+
+### 验证状态
+
+- `go test ./internal/inbound/...`：通过。
+- `go test ./internal/control/...`：通过。
+- `go test ./cmd/gateway/...`：通过。
+
+### 剩余边界
+
+- 当前恢复仍按固定扫描周期触发，尚未做更细的按账号退避、恢复批次追踪和恢复告警。
+- 仍未覆盖更复杂的长短信分片恢复、跨实例抢占协调和恢复中的重复投递防抖。
+
+## 2026-07-08 阶段 20：Gateway 恢复退避、锁与状态审计
+
+### 本轮修复
+
+- Gateway 新增账号级恢复锁，避免同一 `cmppAccount` 被并发重复恢复。
+- 恢复失败、等待连接和部分成功场景会写入真实恢复状态，并按指数退避计算下一次可恢复时间，减少无意义高频重试。
+- 控制面新增 `GET /downstream/recovery-statuses`，可查看账号最近恢复状态、尝试次数、下一次重试时间和错误原因。
+
+### 验证状态
+
+- `go test ./internal/inbound/...`：通过。
+- `go test ./internal/control/...`：通过。
+- `go test ./cmd/gateway/...`：通过。
+
+### 剩余边界
+
+- 当前恢复状态审计仍停留在 Gateway 控制面和 Redis，尚未同步到运营端页面或 NestJS 持久化审计表。
+- 恢复退避当前按账号统一处理，尚未细分到回执/上行类型、失败类别或跨实例抢占优先级。
+
+## 2026-07-08 阶段 21：Gateway 恢复总览与链路缺口收口
+
+### 本轮修复
+
+- 控制面新增 `GET /downstream/recovery-overview`，一次性返回恢复候选账号和恢复状态，便于生产联调与排查。
+- 需求文档已按当前真实代码重新梳理 CMPP 端到端链路剩余缺口，明确区分“已能验收的真实链路能力”和“尚未产品化完成的恢复审计/指标/复杂补偿能力”。
+- 系统测试用例新增恢复总览接口口径，便于后续生产验证直接对照。
+
+### 验证状态
+
+- `go test ./internal/control/...`：通过。
+- `go test ./internal/inbound/...`：通过（延续前一阶段验证结果，本轮未改动 inbound 核心分支逻辑）。
+- `go test ./cmd/gateway/...`：通过。
+
+### 阶段 21 后剩余真实缺口
+
+- 恢复状态仍未写回 NestJS/Prisma/PostgreSQL，运营端暂无真实恢复状态页面。
+- 多 Gateway 实例下更强的恢复抢占协调、分片级补偿审计、共享接入号上行人工认领仍未完成。
+- 连接级窗口利用率、恢复吞吐、恢复失败分布等运营指标仍未进入真实后台页面。
+
+## 2026-07-08 阶段 22：恢复状态回流 NestJS 与运营端展示
+
+### 本轮修复
+
+- NestJS 新增真实恢复状态接收接口 `/api/gateway/events/downstream/recovery-status`。
+- Prisma/PostgreSQL 新增 `GatewayDownstreamRecoveryStatus` 表，按 `cmppAccount` 持久化恢复状态、尝试次数、下一次恢复时间、错误原因及应用/企业关联。
+- 运营端新增独立“恢复状态管理”页面，支持真实恢复状态列表、分页、详情接口和当前筛选结果 CSV 导出。
+- 原“下游投递记录”页面仅保留投递记录与重投能力，不再混放恢复状态列表。
+- 恢复状态新增 `failureCategory` 失败分类字段，Gateway 回传、NestJS 兜底归类并落库，运营端支持分类筛选、分布统计、详情展示和导出。
+- 多 Gateway 恢复抢占协调补强：恢复锁升级为 Redis token 租约，恢复完成时通过 Lua 原子校验 token 后才写状态和释放锁；迟到旧实例不能误删新实例锁。
+- `GatewayDownstreamRecoveryStatus` 新增 `lockOwner/lockExpiresAt`，Gateway 回传并由 NestJS 入库，运营端恢复状态列表和详情可查看锁持有实例。
+- 本地启动脚本补充 `.local-tools\minio.exe` 查找路径，并已验证本机 MinIO 可通过 `npm run start:local:minio` 启动。
+
+### 验证状态
+
+- `npm --prefix api run prisma:generate`：通过。
+- `npm --prefix api test -- operations.service.spec.ts send-chain.service.spec.ts`：通过。
+- `npm --prefix api run build`：通过。
+- `go test ./internal/inbound/... ./internal/control/... ./cmd/gateway/...`：通过。
+- `npm run build`：通过，仅有既有 Vite chunk size warning。
+- `npm --prefix api run prisma:migrate:deploy`：通过，已应用 `20260708213000_add_recovery_lock_observability`。
+- `npm run start:local:minio`：通过，MinIO API `http://localhost:9000`、Console `http://localhost:9001` 已监听。
+
+### 阶段 22 后剩余真实缺口
+
+- 恢复状态已回流 NestJS，并已具备独立运营页、详情、导出和第一版失败分类分布；后续仍缺少恢复吞吐、耗时趋势、连续失败账号等更细指标。
+- 多 Gateway 账号级恢复抢占协调已具备 token 租约和完成校验；分片级补偿审计、共享接入号上行人工认领仍未完成。
+- 连接级窗口利用率、连接级心跳、恢复吞吐和恢复耗时等运营指标仍未进入真实后台页面。
+
+## 2026-07-08 阶段 23：长短信分片级补偿审计
+
+### 本轮修复
+
+- Prisma/PostgreSQL 新增 `SmsMessageSegmentAudit`，按短信记录、submitId、分片序号保存真实分片提交、回执和补偿归因。
+- Go Gateway 上游提交结果 `SubmitResult` 增加 `segments[]`，逐片回传 `segmentTotal/segmentIndex/sequenceId/gatewayMessageId/submitStatus/submittedAt`，长短信不再只暴露首个分片结果。
+- NestJS `handleSubmitResult` 写入分片提交审计，`handleReceipt` 按上游 `gatewayMessageId` 回填分片回执状态；重投或补偿产生的新 submitId 与历史 submitId 可并存追踪。
+- 运营端短信记录详情新增“分片补偿审计”列表，从真实 API 查询 `SmsMessageSegmentAudit`，展示分片、submitId、通道、Sequence、MsgId、提交状态、回执状态、补偿类型和错误信息。
+- 契约文档和示例补充 `SubmitResult.segments[]`，系统测试用例新增 `TC-GW-026 长短信分片补偿审计`。
+
+### 验证状态
+
+- `npm --prefix api run prisma:generate`：通过。
+- `go test ./internal/upstream/... ./internal/queue/... ./internal/submitworker/...`：通过。
+- `npm --prefix api test -- send-chain.service.spec.ts operations.service.spec.ts`：通过。
+- `npm --prefix api run build`：通过。
+- `npm run build`：通过，仅有既有 Vite chunk size warning。
+
+### 阶段 23 后剩余真实缺口
+
+- 长短信分片级提交、回执和补偿归因已具备真实审计；后续仍需补按单个分片自动重投、分片级人工重投和更细的补偿指标。
+- 共享接入号、多候选普通上行的人工认领流程仍未完成。
+- 连接级窗口利用率、连接级心跳、恢复吞吐、恢复耗时趋势和连续失败账号等运营指标仍未进入真实后台页面。
+
+## 2026-07-08 阶段 24：共享接入号上行人工认领
+
+### 本轮修复
+
+- Prisma/PostgreSQL 新增 `SmsUplinkMatchCandidate`，用于保存普通上行 ambiguous 场景下的候选企业、应用、下发短信、候选来源、置信度、认领状态和认领时间。
+- NestJS 上行匹配逻辑增强：接入号匹配多个应用、或手机号时间窗口匹配多条下发时，不误推客户；上行记录标记 `ambiguous`，并真实写入候选表。
+- 运营端“短信上行记录”详情新增候选认领区，展示候选企业、候选应用、候选来源、置信度、候选下发短信和候选原因，支持“认领并推送”。
+- 新增 `POST /admin/operations/uplink-messages/:id/claim`：认领后更新 `SmsUplinkMessage` 为 `matched`，选中候选置为 `claimed`，其他候选置为 `rejected`，写入操作日志，并创建真实 `CmppDownstreamDelivery(deliveryType=uplink)` 走客户侧下游投递链路。
+- 系统测试用例新增 `TC-GW-027 共享接入号上行人工认领`。
+
+### 验证状态
+
+- `npm --prefix api run prisma:generate`：通过。
+- `npm --prefix api run prisma:migrate:deploy`：通过，已应用 `20260708233000_add_uplink_match_candidates`。
+- `npm --prefix api test -- send-chain.service.spec.ts operations.service.spec.ts`：通过，40 个测试。
+- `npm --prefix api run build`：通过。
+- `npm run build`：通过，仅有既有 Vite chunk size warning。
+
+### 当前剩余真实缺口
+
+- 共享接入号上行已具备候选记录、人工认领和认领后下游投递第一版；后续仍需补批量认领、认领复核和认领准确率/积压指标。
+- 长短信分片级提交、回执和补偿归因已具备真实审计；后续仍需补按单个分片自动重投、分片级人工重投和更细的补偿指标。
+- 连接级窗口利用率、连接级心跳、恢复吞吐、恢复耗时趋势和连续失败账号等运营指标仍未进入真实后台页面。
+
 ## 2026-07-03 阶段 9：运营端报备回执导入真实上传/解析
 
 ### 本轮修复