fix: harden dependencies and downstream delivery

docs/first-version-development-requirements.md

@@ -279,7 +279,10 @@
 - 已实现下游投递失败审计与人工重投第一版：运营端后端与页面可分页查看 `CmppDownstreamDelivery` 的 pending/awaiting_ack/failed/unconfirmed/rejected/delivered 记录，支持按状态、类型、应用和关键字筛选，并可对非 `awaiting_ack` 记录执行人工重投，真实调用 Gateway `/downstream/receipt` 或 `/downstream/uplink`。主记录必须分开保存自动重试次数 `retryCount`、人工重投次数 `manualRetryCount` 和最近人工重投时间 `lastRetriedAt`，操作日志保留重投前状态与自动重试次数。
 - 已实现下游投递批量重投第一版：运营端可在当前页勾选多条 `pending/failed` 下游投递记录，调用真实批量接口逐条重投并返回成功/失败汇总，不允许用前端循环假装成功。
 - 下游投递的 `pending` 展示必须结合真实尝试字段：自动与人工次数均为 0 时显示“待首次投递”，`retryCount > 0` 时显示“等待自动重试”，`manualRetryCount > 0` 时显示“人工重投排队中”。人工重投可重置新一轮自动重试预算，但不得把记录伪装成从未投递。
-- 已实现下游投递告警统一口径：运营看板、侧栏通知、下游投递 Dashboard 和应用告警排行必须基于同一组真实 `CmppDownstreamDelivery` 条件统计：`pending` 超过积压阈值、`awaiting_ack` 超过 `ackDeadlineAt`，以及最近失败窗口内的 `failed/unconfirmed/rejected`。默认积压阈值为 10 分钟，最近失败窗口为 1 小时，可分别通过 `CMPP_DOWNSTREAM_ALERT_PENDING_MINUTES` 和 `CMPP_DOWNSTREAM_ALERT_RECENT_FAILED_HOURS` 覆盖。
+- 下游投递不得无限停留在 `pending`：Gateway 对未写出的结果必须返回明确的 `retryable/reasonCode/errorMessage`。状态回执在原消息映射已经丢失且缺少 `submitSequenceId` 时属于不可恢复错误，立即转为 `failed` 并保留失败原因和操作日志；客户端暂时离线属于可恢复错误，按既有重试次数与指数退避处理。所有 pending 从创建时间或最近人工重投时间起最多保留 72 小时，可通过 `CMPP_DOWNSTREAM_PENDING_TIMEOUT_HOURS` 调整，超时后自动终结为 `failed`。
+- 新产生的客户侧状态回执投递 payload 必须保存短信原始 `cmppSubmitSequenceId`，使 Gateway 重启后仍能结合账号和平台消息 ID 重建与原 `CMPP_SUBMIT_RESP` 一致的非 0 `Msg_Id`；不得用伪造或为 0 的 `Msg_Id` 冒充成功投递。
+- 已实现下游投递告警统一口径：运营看板、下游投递 Dashboard 和应用告警排行必须基于同一组真实 `CmppDownstreamDelivery` 条件统计：`pending` 超过积压阈值、`awaiting_ack` 超过 `ackDeadlineAt`，以及最近失败窗口内的 `failed/unconfirmed/rejected`。默认积压阈值为 10 分钟，最近失败窗口为 1 小时，可分别通过 `CMPP_DOWNSTREAM_ALERT_PENDING_MINUTES` 和 `CMPP_DOWNSTREAM_ALERT_RECENT_FAILED_HOURS` 覆盖。右上角“待审核任务”仅汇总审核业务，不显示下游投递告警菜单或数字。
+- pending 积压告警必须从本轮排队开始时间计算：从未人工重投的记录使用 `createdAt`，人工重投记录使用 `lastRetriedAt`；刚执行人工重投的记录不得因旧 `createdAt` 立即重新计入积压告警。
 - 已实现下游投递 Dashboard 第一版：运营端“下游投递记录”页面顶部新增真实聚合总览，直接按 `tenantId/applicationId/deliveryType` 统计投递总量、pending/awaiting_ack/delivered/failed/unconfirmed/rejected、积压告警、ACK 超时告警、按类型分布、重试压力分布和应用告警排行，数据源必须来自 `CmppDownstreamDelivery`，不能靠前端本地汇总。应用告警排行只统计满足统一告警时间窗的记录，不得将新创建的 `pending` 或超出最近窗口的历史失败永久累加为告警。
 - 已实现下游连接映射持久化第一步：Gateway 在客户 CMPP 账号 bind 成功、下游 submit 建链和回执/上行下发时，会把账号在线状态、实例标识、最近活跃时间写入 Redis presence；该状态不再只保留在 Gateway 进程内存中，为后续“Gateway 重启后的 pending 恢复”提供外部状态基础。
 - 已实现下游连接映射持久化第二步：Gateway 启动时会读取 Redis presence 与当前内存在线账号，形成“恢复候选视图”，并通过控制面 `GET /downstream/recovery-candidates` 暴露候选账号列表，供后续恢复逻辑与运维排查使用；本阶段仍不等同于自动恢复 pending 投递。
@@ -521,6 +524,7 @@
 - 计费规则：支持按短信计费条数和企业应用单价计算费用；发送准入额度为现金余额加授信额度。
 - 账务流水必须与短信记录形成可追溯关系，支持对账导出。
 - 最终失败、超时失败需要退费。
+- “今日返还金额”按当天实际恢复到企业可用余额的消息级流水汇总：包含已扣费后的 `refunded`，以及提交前失败后按 `sms_message_record` 释放的 `released`；任务冻结转扣费过程中按 `sms_batch_task` 产生的内部释放不得计入返还。
 - 计费口径可配置为按提交成功计费或按回执成功计费。
 
 ### 5.20 数据保存与清理
@@ -1346,6 +1350,7 @@
    - 原“剩余条数”改为“剩余余额”。
    - 原“近24小时成功率”改为“今日发送条数和今日成功率”。
    - 新增“今日消费金额”和“今日返还金额”展示。
+   - “今日返还金额”展示当天真实返还到可用余额的金额，包含消息级冻结释放和扣费后退款，排除任务冻结转扣费产生的内部释放流水，金额统一保留三位小数。
 3. 运营端增加系统日志。
    - 运营端可查询全平台系统日志。
    - 日志需支持按企业、模块、级别、操作人、资源 ID 或详情定位。