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
@@ -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 提示。