fix: harden real backend workflows and channel connections

2026-07-06 17:54:53 +08:00
parent 8cca361441
commit b5132d7f4e
47 changed files with 2530 additions and 314 deletions
@@ -217,7 +217,7 @@

 问题：

- 创建、复制、启停、删除、链接日志已经接真实 API。
+- 创建、复制、启停、删除、连接日志已经接真实 API。
 - 旧实现编辑通道时直接提示“短信通道编辑接口待补，当前不做本地模拟保存”。

 影响：
@@ -149,12 +149,13 @@
 14. 通道组明细 `carrier` 必须保留并参与发送逻辑，且必须等于通道组运营商。三网只允许作为通道本体能力 `SmsChannel.carrier=all`，表示该通道可被运营分配到移动、联通或电信通道组；一旦放入某个通道组，只能服务该通道组所属运营商。
 15. 通道组明细引用通道时必须校验通道能力：移动组只能引用移动通道或三网通道，联通组只能引用联通通道或三网通道，电信组只能引用电信通道或三网通道。
 16. 未命中企业应用通道组或无可用通道时不得 fallback 到全局第一个 active 通道，应将该短信标记为 failed，并记录可读失败原因、trace 和系统日志；客户端本期不展示通道细节。
-17. 可发送通道必须同时满足：通道业务状态 active、CMPP 连接状态 online、当前连接数大于 0、心跳未失败；auth_failed、heartbeat_timeout、reconnecting、disconnected 或当前连接数为 0 的通道均不可被选中。
-18. 多连接通道只要至少 1 条连接 online 且可用即可参与路由；心跳失败应及时更新连接状态，连续 3 次心跳失败后进入重连，重连成功前不可发送。
-19. 通道异常时应支持熔断、降级、切换备用通道和失败重试；失败补发必须在同一企业应用授权的通道组范围内执行，并使用触发补发时的当前通道组配置，保证计费、退款、幂等和 trace 可追踪。
-20. 失败补发除以下情况外均应触发：短信状态为 unknown；距离客户提交时间超过 72 小时；距离客户提交时间超过通道组配置的补发时间上限；通道组关闭失败补发。
-21. 通道组补发时间上限由运营端配置，最大不得超过 72 小时；本期不配置最大补发次数、补发间隔、失败类型白名单或人工重发能力，进入最终 failed/timeout 后不再人工重发。
-22. 提交 accepted 后立即按企业应用配置的客户费率扣费；补发过程中最终成功只扣一次，submit failed 未真正发出时释放冻结且不扣费；failed receipt 导致最终全失败时退款；本期客户计费不使用通道成本价。
+17. 可发送通道必须同时满足：通道业务状态 active、CMPP 连接状态 connected、期望连接数大于 0、当前连接数大于 0、心跳未失败；auth_failed、heartbeat_timeout、reconnecting、disconnected、failed 或当前连接数为 0 的通道均不可被选中。Gateway 旧回写词 online/open 仅允许在 API 入库时兼容归一化为 connected，不作为发送判断状态。
+18. 多连接通道只要至少 1 条连接 connected 且可用即可参与路由；心跳失败应及时更新连接状态，连续 3 次心跳失败后进入重连，重连成功前不可发送。
+19. 新建或启用通道后，系统应立即创建/更新默认 CMPP 连接状态为 connecting 并通知 Go Gateway 发起连接；如果 connecting 超过 30 秒仍未收到 Gateway 回写 connected 或 failed，API 后台兜底任务必须将该连接标记为 failed，写入 `lastError=Gateway connection request timed out after 30 seconds` 和连接日志。默认扫描间隔 5 秒，可通过环境变量调整。
+20. 通道异常时应支持熔断、降级、切换备用通道和失败重试；失败补发必须在同一企业应用授权的通道组范围内执行，并使用触发补发时的当前通道组配置，保证计费、退款、幂等和 trace 可追踪。
+21. 失败补发除以下情况外均应触发：短信状态为 unknown；距离客户提交时间超过 72 小时；距离客户提交时间超过通道组配置的补发时间上限；通道组关闭失败补发。
+22. 通道组补发时间上限由运营端配置，最大不得超过 72 小时；本期不配置最大补发次数、补发间隔、失败类型白名单或人工重发能力，进入最终 failed/timeout 后不再人工重发。
+23. 提交 accepted 后立即按企业应用配置的客户费率扣费；补发过程中最终成功只扣一次，submit failed 未真正发出时释放冻结且不扣费；failed receipt 导致最终全失败时退款；本期客户计费不使用通道成本价。

 ### 4.7 通道签名报备

@@ -297,7 +298,7 @@
 - 支持查看通道成功率、未知率、失败率、累计发送量。
 - 支持进入通道报备详情。
 - 通道报备详情页中，签名下的引流信息默认收起，用户点击后展开；展开/收起只影响页面展示，不改变报备数据。
- 通道列表状态区域展示“链接日志”入口；点击后弹窗展示真实连接日志，包括新建连接、断开、心跳、重连、异常等事件，日志来源于 Gateway 回写或 OperationLog。
+- 通道列表状态区域展示“连接日志”入口；点击后弹窗展示真实连接日志，包括连接请求、连接成功、断开、心跳、重连、异常等事件，日志来源于 Gateway 回写或 OperationLog。
 - 通道操作按钮应保持一致的两列布局，报备详情、编辑、复制、发送测试、启停、删除等操作文案清晰。

 ### 5.14 运营端通道组管理
@@ -467,17 +467,17 @@
  - 删除连接调用真实后端或 Gateway 接口，连接状态刷新并写系统日志。
  - CMPP 参数来源于真实应用/通道配置，一键复制内容与 API 返回一致。

-### TC-ADMIN-019 通道链接日志展示
+### TC-ADMIN-019 通道连接日志展示

 - 优先级：P1
- 前置条件：Gateway 或测试替身已产生新建连接、心跳、断开、重连、异常事件。
+- 前置条件：Gateway 或测试替身已产生连接请求、连接成功、心跳、断开、重连、异常事件。
 - 步骤：
  1. 打开短信通道管理页面。
-  2. 在状态区域点击链接日志。
+  2. 在状态区域点击连接日志。
  3. 查看日志时间、事件类型、连接 id、详情。
 - 预期结果：
-  - 链接日志由真实后端 API 返回，不使用前端硬编码数据。
-  - 日志包含新建连接、断开、心跳、重连、异常等事件。
+  - 连接日志由真实后端 API 返回，不使用前端硬编码数据。
+  - 日志包含连接请求、连接成功、断开、心跳、重连、异常等事件。
  - 日志按时间倒序展示，并可定位到对应通道或连接。

 ### TC-ADMIN-020 安全控制搜索、添加、启停与删除
@@ -2585,7 +2585,7 @@ npm run verify:phase8
 | TC-ADMIN-016 | 复制通道，随后查询新通道详情、报备字段、签名报备材料。 | 新通道 code/id 唯一；CMPP 参数、限速、报备字段、材料被复制；源通道不受影响；复制日志包含 sourceChannelId 和 newChannelId。 |
 | TC-ADMIN-017 | 对有关联历史的通道执行停用、启用、删除。 | 取消确认无请求或无状态变化；停用后不参与路由；删除为软删除/归档；历史发送、报备、日志仍可查。 |
 | TC-ADMIN-018 | 企业应用列表展示 CMPP 连接数，打开连接详情，删除连接，复制 CMPP 参数。 | 连接数来自连接状态 API；详情含 connectionId/status/heartbeat/window/lastSubmitAt；删除连接调用真实接口；复制文本与 API 返回一致。 |
-| TC-ADMIN-019 | 打开通道链接日志，按事件类型和时间查看。 | 日志包含 connect、active_test、disconnect、reconnect、auth_failed、slow_response；按时间倒序；可定位 channelId/connectionId。 |
+| TC-ADMIN-019 | 打开通道连接日志，按事件类型和时间查看。 | 日志包含 connect、active_test、disconnect、reconnect、auth_failed、slow_response；按时间倒序；可定位 channelId/connectionId。 |
 | TC-ADMIN-020 | 企业黑名单、全局黑名单、敏感词分别执行搜索、新增、停用、删除。 | 搜索由 API 处理；停用/删除后发送前风控只使用 active 数据；删除不影响历史命中记录；所有动作写日志。 |
 | TC-ADMIN-021 | 创建待审核企业认证、签名、模板、短信审核任务，检查铃铛总数和分类数。 | 总数等于分类汇总；点击分类跳转并带入筛选；审核完成后数量刷新；新增待办触发站内提醒或浏览器通知。 |
 | TC-ADMIN-022 | 运营日志按客户、操作者、动作、资源、时间搜索，查看长详情。 | 后端分页和搜索准确；详情不截断；可查到通道复制、启停、删除、连接状态变化、安全控制变更、充值等日志。 |
@@ -2636,7 +2636,7 @@ npm run verify:phase8
 | TC-CUSTOMER-008 | 删除/归档有历史数据的客户。 | 不允许硬删除或执行归档；新发送和未执行 scheduled 阻断；历史 trace/对账可查。 |
 | TC-CUSTOMER-009 | 客户详情总览应用、签名、模板、今日发送、余额。 | 各指标与明细列表聚合一致；跳转带客户筛选；异常状态有标识。 |
 | TC-CUSTOMER-010 | 客户绑定通道组，主通道 online、备通道 disconnected。 | 客户详情展示通道组和连接状态；发送路由选择 online 且报备通过通道；trace channelId 一致。 |
-| TC-CUSTOMER-011 | 客户 A/B 不同连接配置和在线数。 | 客户列表摘要如 `2/2 online`、`1/3 degraded`；详情和通道监控一致。 |
+| TC-CUSTOMER-011 | 客户 A/B 不同连接配置和在线数。 | 客户列表摘要如 `2/2 connected`、`1/3 degraded`；详情和通道监控一致。 |
 | TC-CUSTOMER-012 | 调整客户通道连接数并触发 Gateway 重载。 | desired/current 连接数最终一致；发送能力或窗口容量随配置变化；日志记录变更。 |
 | TC-CUSTOMER-013 | 超过通道最大连接数分配。 | 保存失败；提示最大连接数、已分配数和可用数；不影响已有连接；失败日志存在。 |

@@ -2645,21 +2645,22 @@ npm run verify:phase8
 | 用例 | 模拟方式 | 必查断言 |
 | --- | --- | --- |
 | TC-CMPP-STATUS-001 | Gateway 未启动或未回写。 | 通道业务 active 与连接 disconnected/unknown 分开展示；不可误判为可提交。 |
-| TC-CMPP-STATUS-002 | 模拟 SMSC 登录成功。 | 状态 online；连接建立时间、最近心跳、窗口可用；发送可路由到该通道。 |
+| TC-CMPP-STATUS-002 | 模拟 SMSC 登录成功。 | 状态 connected；连接建立时间、最近心跳、窗口可用；发送可路由到该通道。 |
 | TC-CMPP-STATUS-003 | 模拟登录认证失败。 | 状态 auth_failed；错误码/原因展示；路由跳过；日志/告警记录。 |
 | TC-CMPP-STATUS-004 | 模拟 active test 超时。 | 状态 heartbeat_timeout/disconnected；进入重连；新发送走备用或等待失败。 |
-| TC-CMPP-STATUS-005 | 模拟 TCP 断开再恢复。 | 状态 disconnected -> reconnecting -> online；重连次数增加；未确认消息状态明确。 |
+| TC-CMPP-STATUS-005 | 模拟 TCP 断开再恢复。 | 状态 disconnected -> reconnecting -> connected；重连次数增加；未确认消息状态明确。 |
 | TC-CMPP-STATUS-006 | 主通道离线、备用在线且报备通过。 | 路由跳过主通道并选择备用；trace 展示备用 channelId。 |
 | TC-CMPP-STATUS-007 | 所有通道离线或认证失败。 | 不提交到离线连接；任务 delayed/retry/failed/pending_channel；不错误扣费。 |
-| TC-CMPP-STATUS-008 | 通道业务 disabled 但连接 online。 | 不参与路由；连接状态仍可运维观察；启用后按连接状态恢复可用性。 |
+| TC-CMPP-STATUS-008 | 通道业务 disabled 但连接 connected。 | 不参与路由；连接状态仍可运维观察；启用后按连接状态恢复可用性。 |
 | TC-CMPP-STATUS-009 | 模拟 submit resp 慢响应。 | 窗口占用、慢响应、队列积压可见；恢复后积压下降；超时可追踪。 |
-| TC-CMPP-STATUS-010 | 触发 online/disconnected/reconnecting/online。 | 每次变化有状态历史、健康指标和系统日志。 |
+| TC-CMPP-STATUS-010 | 触发 connected/disconnected/reconnecting/connected。 | 每次变化有状态历史、健康指标和系统日志。 |
 | TC-CMPP-STATUS-011 | 通道 maxConnections=4、desired=2、current=2。 | 通道详情、监控、Dashboard 连接数一致；连接列表展示 connectionId、心跳、窗口、sequence。 |
 | TC-CMPP-STATUS-012 | desired 1 调整为 3。 | Gateway 建立新连接至 3/3；任务可按连接/窗口分摊；日志记录调整。 |
 | TC-CMPP-STATUS-013 | desired 3 调整为 1。 | 多余连接优雅关闭；未确认 submit 不丢失不重复；终态 1/1。 |
-| TC-CMPP-STATUS-014 | 3 条连接中断 1 条。 | 展示 degraded 或 2/3 online；异常连接数增加；重连恢复后 3/3。 |
+| TC-CMPP-STATUS-014 | 3 条连接中断 1 条。 | 展示 degraded 或 2/3 connected；异常连接数增加；重连恢复后 3/3。 |
 | TC-CMPP-STATUS-015 | desired=0 或 current=0。 | 路由不选择该通道；无备用时任务失败或等待；原因包含无在线连接。 |
 | TC-CMPP-STATUS-016 | 单连接限速 100，连接数 1 和 2 分别压测。 | 理论能力随在线连接数变化；实际 TPS 不超过限速；不重复发送。 |
+| TC-CMPP-STATUS-017 | 新建/启用通道后 Gateway 未回写，连接状态停留 connecting 超过 30 秒。 | API 兜底任务将连接标记为 failed，currentConnections=0，lastError 为 `Gateway connection request timed out after 30 seconds`；连接日志包含 connect_timeout；发送路由不可选择该通道。 |

 ### 17.9 自动化落地建议

@@ -2668,7 +2669,7 @@ npm run verify:phase8
 | API Jest | 认证、字典、安全控制、通道复制/软删除、连接状态、人工充值、系统日志查询、Dashboard 聚合口径。 |
 | HTTP Smoke | 客户创建、认证审核、通道复制、连接状态回写、人工充值、立即发送、定时到点、trace、reconciliation。 |
 | Go Gateway | 连接状态回写契约、登录成功/失败、心跳超时、断线重连、窗口占满、连接数调整。 |
-| 前端 Smoke | 客户端头像菜单、系统日志分页、运营模板审核搜索、企业认证详情、通道复制/链接日志、安全控制 CRUD、Dashboard 指标跳转。 |
+| 前端 Smoke | 客户端头像菜单、系统日志分页、运营模板审核搜索、企业认证详情、通道复制/连接日志、安全控制 CRUD、Dashboard 指标跳转。 |
 | 性能 Smoke | BullMQ 500 TPS、CMPP 连接数变化后的提交能力、慢响应积压恢复。 |

 ### 17.9 登录和用户管理闭环
@@ -1,5 +1,60 @@
 # 第一版系统化测试进度

+## 2026-07-06 企业管理列表字段回归
+
+- 按设计锚点 `131f344a^` 恢复运营端企业管理列表字段：企业 ID、企业名称、当前余额、透支限额、今日消费、企业状态、操作。
+- 新增真实后端接口 `GET /api/admin/tenants/management-list`，由 NestJS/Prisma 聚合租户、企业账户和当天短信消息金额；前端不再用静态字段或本地假数拼出今日消费。
+- 当前余额来自 `TenantAccount.balanceCents`，透支限额来自 `TenantAccount.creditCents`，今日消费来自当天 `SmsMessageRecord.amountCents` 汇总。
+- 已执行：
+  - `npm --prefix api test -- tenants.service.spec.ts --runInBand`
+  - `npm --prefix api run build`
+  - `npm run build`
+- 验证结果：API 单测、API build、前端 build 均通过；前端 build 仅保留既有 Vite chunk size warning。
+
+## 2026-07-06 企业编辑页和上传链路修复
+
+- 按设计锚点 `131f344a^` 恢复运营端企业新建/编辑页字段：企业照片、企业名称、统一社会信用代码、省/直辖市、市/区、通讯地址、联系人姓名、身份证号、手机号、电子邮箱。
+- 运营端企业新建/编辑页移除偏离锚点的企业编码、企业状态字段；后端 `POST /api/admin/tenants` 支持不传企业编码，并按信用代码/企业名生成真实唯一企业编码。
+- 修复营业执照/企业照片上传 500：
+  - 启动脚本在 MinIO 不可用时启用本地对象存储 `.local-data/object-storage`，文件仍通过真实 NestJS 上传接口写入对象存储目录并创建 `FileObject` 数据库记录。
+  - 文件上传接口缺少 multipart 文件时返回 400。
+  - `FileObject.sizeBytes` 返回前转换为字符串，避免 Prisma `BigInt` JSON 序列化 500。
+- 已执行：
+  - `npm --prefix api test -- tenants.service.spec.ts files.service.spec.ts --runInBand`
+  - `npm --prefix api run build`
+  - `npm run build`
+  - `POST http://localhost:3000/api/admin/files/upload` multipart smoke
+- 验证结果：API 单测、API build、前端 build 和真实上传 smoke 均通过；前端 build 仅保留既有 Vite chunk size warning。
+
+## 2026-07-06 本地 MinIO 启动脚本补充
+
+- `tools/start-local.ps1` 补充本地 MinIO 启动流程：Docker Compose 优先；无 Docker 时查找 `C:\cmpp-platform-local\minio.exe`、`C:\cmpp-platform-local\minio\minio.exe` 或 PATH 中的 `minio.exe`，使用 `C:\cmpp-platform-local\minio-data` 作为数据目录，监听 `9000/9001`。
+- `package.json` 新增 `npm run start:local:minio`，用于单独启动本地 MinIO。
+- MinIO 不可用时，脚本仍会明确启用 `.local-data/object-storage` fallback；启动完成提示会区分 MinIO 是否真实运行。
+- MinIO 模式下对象存储服务会在上传/预签名前自动确认并创建 `cmpp-platform` bucket。
+- 已执行：
+  - `npm --prefix api run build`
+  - `npm run start:local -- -SkipApi -SkipWeb -SkipMigrate`
+- 验证结果：API build 和启动脚本 smoke 通过；当前机器未发现 `minio.exe`，脚本按预期提示并启用本地对象存储 fallback。
+
+## 2026-07-06 应用级 CMPP 连接和签名/引流表单基线
+
+- CMPP 连接状态从企业/租户级聚合改为应用级独立连接：
+  - `CmppConnectionState` 新增 `applicationId` 并关联 `SmsApplication`。
+  - 企业应用列表和连接详情只读取当前应用的 `CmppConnectionState`。
+  - 运营端断开连接只操作当前应用下的连接。
+  - Gateway 连接上报 `POST /api/admin/gateway/connections` 支持 `applicationId`，新连接可按应用独立记录。
+- 运营端添加/编辑短信签名页面按设计锚点 `131f344a^` 补齐字段：签名依据、短信签名、资质凭证、公司名称、统一社会信用代码、法人姓名、法人身份证号、法人身份证照片、责任人姓名、责任人手机号、责任人身份证号、责任人身份证照片、三网报备状态。
+- 运营端添加/编辑引流信息页面按设计锚点 `131f344a^` 补齐字段：引流信息、字段名称 1-10、文件上传、三网报备状态、提交时间、备注。
+- 签名和引流表单仍使用真实 `enterprise-signatures` 后端接口保存；扩展字段写入 `SmsSignature.drainageInfo` JSON，文件上传走真实 `admin/files/upload` 并保存 `FileObject` 引用。
+- 已执行：
+  - `npm --prefix api run prisma:generate`
+  - `npm --prefix api test -- sms-config.service.spec.ts channels.service.spec.ts --runInBand`
+  - `npm run build`
+  - `npm --prefix api run build`
+  - `npm --prefix api run prisma:migrate:deploy`
+- 验证结果：Prisma Client 生成、API 针对测试、API build、前端 build 和本地 PostgreSQL migration deploy 均通过；前端 build 仅保留既有 Vite chunk size warning。
+
 ## 2026-07-01

 ### 新增测试基础
@@ -183,7 +238,7 @@ npm run test:gateway
 - 通道管理补齐真实 API：
  - `POST /api/admin/channels/:id/copy`：复制通道配置、通道报备字段和该通道签名报备材料，写入操作日志。
  - `DELETE /api/admin/channels/:id`：软删除通道，避免破坏历史发送/报备外键。
-  - `GET /api/admin/channels/:id/link-logs`：基于 `OperationLog` 和 `CmppConnectionState` 查询链接日志。
+  - `GET /api/admin/channels/:id/connection-logs`：基于 `OperationLog` 和 `CmppConnectionState` 查询连接日志；保留 `/link-logs` 兼容旧前端。
 - 安全控制补齐真实 API：敏感词、全局黑名单、企业黑名单支持 keyword/status 查询、创建、启停/软删除，并写操作日志。
 - 模板审核补齐真实查询：运营端模板列表支持 keyword/status，并返回企业、应用、签名信息；前端模板审核页已改为调用真实 API。
 - 企业认证审核补齐真实查询：列表支持 keyword/status，详情返回企业信息和认证 materials；前端企业认证审核页已改为调用真实 API。
@@ -193,7 +248,7 @@ npm run test:gateway

 | 测试文件 | 新增覆盖 |
 | --- | --- |
-| `api/src/channels/channels.service.spec.ts` | 通道复制、软删除、连接状态日志写入、链接日志查询。 |
+| `api/src/channels/channels.service.spec.ts` | 通道复制、软删除、连接状态日志写入、连接日志查询。 |
 | `api/src/dictionaries/dictionaries.service.spec.ts` | 敏感词、全局黑名单、企业黑名单查询、创建、软删除和操作日志。 |

 ### 已执行命令
@@ -214,7 +269,7 @@ npm run build

 - 已将今天的客户端和运营端优化要求补入 `docs/first-version-development-requirements.md`：
  - 去除客户端独立账号设置菜单，改为头像下拉承载退出登录和修改密码。
-  - 明确模板审核搜索、企业认证详情审核、企业应用 CMPP 连接数/连接详情/参数复制、通道复制、通道软删除、通道链接日志、安全控制 CRUD、系统日志分页等均需要真实后端 API 支撑。
+  - 明确模板审核搜索、企业认证详情审核、企业应用 CMPP 连接数/连接详情/参数复制、通道复制、通道软删除、通道连接日志、安全控制 CRUD、系统日志分页等均需要真实后端 API 支撑。
  - 补充客户端用户、运营端企业认证、通道、连接、字典、安全控制、系统日志等接口范围。
  - 修正 Codex 执行模板，明确 mock、localStorage 或静态数据不得作为真实开发完成标准。
 - 已将今天的验收点补入 `docs/system-functional-test-cases.md`：
@@ -253,7 +308,7 @@ node <browser-and-api-smoke>
 | TC-CMPP-STATUS-UI | UI-SMOKE PASS / BACKEND GAP | 企业应用管理可展示 CMPP 状态和连接数量并打开连接详情；页面当前仍有本地初始数据路径。 |
 | TC-FRONTEND-CONSOLE | PASS | 关键页面无相关 console error/pageerror；仅忽略 favicon 404。 |
 | TC-BILLING-MANUAL-API | PASS | 人工充值无需审批：确认后账户余额、短信条数、充值单、账户流水和 Dashboard transactions 聚合同步更新。 |
-| TC-CMPP-STATUS-API | PASS | 通道创建、Gateway 连接状态回写、按通道/客户查询、链接日志和 Dashboard gatewayConnections 聚合通过。 |
+| TC-CMPP-STATUS-API | PASS | 通道创建、Gateway 连接状态回写、按通道/客户查询、连接日志和 Dashboard gatewayConnections 聚合通过。 |

 ### 发现和说明

@@ -274,7 +329,7 @@ node <browser-and-api-smoke>
 | BUG-DEV-001 | P1 | `npm run dev` 在 5173 被占用后切到 5174，Vite 依赖 bundling 长时间未完成，浏览器看到白屏。 | 本轮浏览器测试中 5174 HTTP 后续可达，但首次打开截图为空白；生产 build/preview 正常。 | 检查 Vite dev 依赖预构建和端口占用问题，确保开发模式可稳定渲染。 |
 | BUG-SEND-001 | P0 | 发送路由规则允许直接绑定单个通道，违反“规则只能绑定通道组”的业务约束。 | `SendChainService.selectChannel()` 当前存在 `route?.channel ?? route?.group...` 路径；`ChannelRouteRule` 模型也保留 `channelId` 字段。 | 路由规则只能表达应用到通道组的绑定关系；发送链路必须从企业应用绑定的运营商通道组内选路，不允许规则直接指定单个通道。 |
 | BUG-SEND-002 | P0 | 未命中路由规则时会 fallback 到全局第一个 `active` 通道，可能把短信发到未配置给该企业/应用的通道。 | `SendChainService.selectChannel()` 未找到 route 后执行 `smsChannel.findFirst({ where: { status: 'active' } })`。 | 企业应用没有配置对应运营商通道组或无可用通道时，短信直接 failed；不得进入 pending/delayed，不得 fallback 到其他 active 通道，需记录 trace/日志。 |
-| BUG-SEND-003 | P0 | 发送选路只判断通道业务状态 `active`，不判断 CMPP 真实连接状态。 | `selectChannel()` 只检查 `SmsChannel.status`，未查询 `CmppConnectionState.status/currentConnections/lastHeartbeatAt/lastError`。 | 选路必须跳过离线、认证失败、心跳超时、重连中或 `currentConnections=0` 的通道；至少 1 条连接 online 且心跳正常才可发送，连续 3 次心跳失败进入重连且不可选。 |
+| BUG-SEND-003 | P0 | 发送选路只判断通道业务状态 `active`，不判断 CMPP 真实连接状态。 | `selectChannel()` 只检查 `SmsChannel.status`，未查询 `CmppConnectionState.status/currentConnections/lastHeartbeatAt/lastError`。 | 选路必须跳过离线、认证失败、心跳超时、重连中或 `currentConnections=0` 的通道；至少 1 条连接 connected 且心跳正常才可发送，连续 3 次心跳失败进入重连且不可选。 |
 | BUG-SEND-004 | P0 | 通道组主通道提交失败、超时或回执失败后不会切换到下一个通道补发。 | `handleSubmitResult()` 和 `handleReceipt()` 只更新状态、释放/退款和刷新进度，没有重新选路或创建补发记录；`retry.maxAttempts` 目前未形成业务补发闭环。 | 除 unknown、超过 72 小时、超过通道组补发时间上限或通道组关闭补发外，submit rejected/timeout、连接断开、未提交成功、receipt failed 均需补发；省网失败后立即走全国通道，全国通道按优先级继续补发，最终成功只按企业应用客户费率扣一次。 |
 | BUG-SEND-005 | P0 | 通道组省网/全国路由没有接入真实发送链路，手机号段库也未参与归属地识别。 | `SmsChannelGroupItem` 和 `ChannelRouteRule` 虽有 `carrier/province` 字段，`PhoneSegment` 有 `prefix/carrier/province/city`，但 `SendChainService.selectChannel()` 未读取 message.phoneNumber、未查询 `phoneSegment`，只按优先级取第一个 active 通道；前端 `AdminChannelGroupFormPage` 的省网/全国配置仍为本地 `useState`。 | 发送前按可配置号码前缀正则识别运营商，识别失败走移动通道组；按手机号段库识别省份和城市，省份识别失败走对应运营商全国通道；通道需支持移动/联通/电信/三网和全国/单省发送地区，三网作为通配。 |
 | BUG-SEND-006 | P0 | 企业应用缺少按运营商绑定多个通道组和保存校验的真实闭环。 | 当前发送链路只按 `tenantId/applicationId` 查询单一路由规则；未体现一个应用分别绑定移动、联通、电信通道组，也未强制至少绑定一个通道组后才能保存。 | 企业应用可分别绑定移动、联通、电信通道组；一个都不绑定时 UI 不允许保存，发送时直接 failed；移动、联通、电信短信按识别结果进入对应通道组。 |
@@ -285,7 +340,8 @@ node <browser-and-api-smoke>

 - BUG-SEND-001：后端 `createRouteRule` 禁止直接绑定单通道，路由规则只能绑定应用、运营商和通道组；发送链路不再读取 `route.channel`。
 - BUG-SEND-002：发送链路未找到企业应用对应运营商通道组或无可用在线通道时，短信直接标记 `failed`，不再 fallback 到全局第一个 active 通道。
- BUG-SEND-003：发送选路加入 CMPP 连接状态过滤，通道必须业务 `active`、连接 `online/connected`、`desiredConnections > 0` 且 `currentConnections > 0` 才可选。
+- BUG-SEND-003：发送选路加入 CMPP 连接状态过滤，通道必须业务 `active`、连接 `connected`、`desiredConnections > 0` 且 `currentConnections > 0` 才可选；`online/open` 仅作为旧 Gateway 回写兼容词入库归一化。
+- BUG-CMPP-STATUS-001：新建/启用通道后若 Gateway 连接请求长时间无回写，API 后台兜底任务会将超过 30 秒的 `connecting` 连接标记为 `failed`，写入超时原因和连接日志，避免页面长期停留“连接中”。
 - BUG-SEND-004：submit rejected、submit timeout、回执 failed 等失败场景会在补发开启且未超过时间限制时，排除已尝试通道并切换到同一通道组全国通道继续提交；unknown、超过 72 小时、超过通道组补发上限或关闭补发时不补发。
 - BUG-SEND-005：新增 `PhoneCarrierRule` 运营商前缀正则配置，发送前先识别运营商，识别失败默认移动；手机号段库用于识别省份，省份识别失败走对应运营商全国通道；通道新增 `sendRegion`，支持全国或单省。
 - BUG-SEND-006：企业应用创建页面可分别选择移动、联通、电信通道组，一个都不选时 UI 阻止保存；创建应用成功后写入真实通道组路由规则。
@@ -601,3 +657,50 @@ git diff --check
  - 企业模板管理表格最小宽度 1820px，模板内容列 420px，横向滚动生效。
  - 新建企业应用弹窗在 1280px 视口下未截断，未选择企业时“下一步”禁用。
  - 新建短信应用页显示三网通道组卡片、已配置数量和无可用通道组提示，初始状态“创建应用”禁用。
+
+## 2026-07-06 文件上传预览和下载回归
+
+### 本轮修复
+
+- 文件服务新增真实下载接口 `GET /api/admin/files/:id/download`，从 MinIO 或本地对象存储读取真实文件对象，支持 `inline` 预览和 `attachment` 下载。
+- 运营端企业照片、企业签名材料、引流材料、报备回执导入均在真实上传成功后显示下载入口；图片类型文件显示点击预览入口。
+- 客户端企业认证营业执照上传成功后显示下载入口，图片类型文件显示点击预览入口；提交认证时保存文件类型信息。
+- 客户端签名列表对已保存签名材料显示下载入口，图片材料按文件名或类型显示预览入口。
+- 客户端短信发送导入号码文件为前端解析文件，未生成后端文件对象；页面仅提供本地原始文件下载，不标记为真实后端归档。
+
+### 已执行命令
+
+```bash
+npm --prefix api test -- files.service.spec.ts
+npm --prefix api run build
+npm run build
+git diff --check
+```
+
+### 当前结果
+
+- 文件服务单测通过：1 个 test suite、2 个测试通过。
+- API build 通过。
+- 前端 build 通过，仍存在既有 Vite chunk size warning。
+- `git diff --check` 无空白错误，仅 Windows 工作区 LF/CRLF 提示。
+
+## 2026-07-06 企业列表人工充值入口
+
+### 本轮修复
+
+- 运营端企业管理列表新增“充值”按钮。
+- 点击“充值”打开企业人工充值弹窗，展示企业名称、当前余额，并支持录入充值金额、操作人和备注；企业列表入口不要求填写短信条数。
+- 提交后调用现有真实接口 `POST /api/admin/billing/manual-recharges`，成功后重新拉取企业管理列表，余额来自真实账户接口聚合结果。
+- 该入口不使用前端本地状态模拟充值入账；充值订单、账户余额、账户流水和操作日志仍由后端 `BillingService.createManualRecharge` 负责。
+
+### 已执行命令
+
+```bash
+npm run build
+git diff --check
+```
+
+### 当前结果
+
+- 前端 build 通过，仍存在既有 Vite chunk size warning。
+- `git diff --check` 无空白错误，仅 Windows 工作区 LF/CRLF 提示。