hectorzhao/lislgosms
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

feat: wire admin workflows to real APIs

Browse Source
This commit is contained in:
hectorzhao
2026-07-02 13:50:09 +08:00
parent f8c9b78c21
commit ab421cf8a7
42 changed files with 2596 additions and 250 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/first-version-development-requirements.md
+71 -8
View File
@@ -55,9 +55,10 @@
- 账单流水
- 企业认证
- 用户管理
- 账号设置
- 系统日志
第一版不展示独立“账号设置”菜单，退出登录、修改密码统一放在右上角用户头像下拉菜单。
暂不开发：
- 彩信服务分组下全部菜单
@@ -241,26 +242,41 @@
- 展示总发送量、成功率、通道健康度、待处理审核数。
- 发送监控展示通道状态、发送趋势、失败率、积压队列。
- 数据统计支持按企业、应用、通道、日期统计。
- 运营概览一级菜单下只保留运营看板、发送监控、数据统计；客户管理独立作为一级业务域展示，避免重复菜单。
- 右上角消息铃铛展示所有待审核任务总数，并按企业认证、短信审核、短信模板审核、签名审核等分类展示；点击分类跳转到对应审核页面。
- 新审核任务进入时，运营端应触发浏览器通知或站内提醒；提醒数据必须来自真实待审核数量接口，不得只写死前端数字。
### 5.11 运营端客户与企业
- 支持企业列表、企业详情、新增、编辑、启用、停用。
- 支持企业认证资料审核。
- 支持查看企业下应用、签名、模板、发送记录、报备记录。
- 企业管理列表不提供无业务意义的“详情”按钮；需要查看明细时从企业应用、签名、模板、发送记录等业务入口进入。
- 企业应用管理编辑保存后返回企业应用管理列表。
- 企业应用列表展示 CMPP 连接数；点击连接数打开连接详情弹窗，内容包含连接 id、状态、连接建立时间、最近心跳时间、上次提交时间、窗口占用等。
- 企业应用连接详情支持删除连接；删除连接必须调用真实后端接口或 Gateway 回写接口，并写入系统日志。
- 企业应用列表提供 CMPP 连接参数查看与一键复制能力，参数来源于真实应用/通道配置，不允许只在前端拼接假数据。
### 5.12 运营端审核
- 企业认证审核：通过、驳回、查看材料。
- 企业认证详情必须展示客户提交的主体资料、统一社会信用代码、法定代表人、注册地址、营业执照附件、对公账户验证资料、联系人信息、提交时间、审核备注、驳回原因等；通过/驳回必须更新认证记录和租户认证状态，并写操作日志。
- 短信模板审核：通过、驳回、敏感词提示、变量检查。
- 短信模板审核必须支持按客户、应用、模板内容、审核编号和审核状态搜索；搜索应由真实后端 API 支持，前端只做展示和交互。
- 短信审核：查看短信内容、号码量、计费条数、进入审核原因、命中规则、风险原因；支持通过、驳回。
- 审核动作集中在审核中心；企业应用/签名/模板管理页面只做查询、维护、停用、备注和查看审核记录。
### 5.13 运营端通道管理
- 支持新增、编辑、删除、启用、停用短信通道。
- 删除通道采用软删除或停用归档，不能破坏历史发送、报备、日志外键；删除、启用、停用、复制等高影响操作必须二次确认并写系统日志。
- 支持复制通道：复制后新建一个通道，除 id/code 自动生成外，通道配置、CMPP 参数、通道报备字段、签名/引流报备材料和个性化字段配置均需从源通道复制；名称默认追加“副本”。
- 支持发送测试短信。
- 支持查看通道成功率、未知率、失败率、累计发送量。
- 支持进入通道报备详情。
- 通道报备详情页中，签名下的引流信息默认收起，用户点击后展开；展开/收起只影响页面展示，不改变报备数据。
- 通道列表状态区域展示“链接日志”入口；点击后弹窗展示真实连接日志，包括新建连接、断开、心跳、重连、异常等事件，日志来源于 Gateway 回写或 OperationLog。
- 通道操作按钮应保持一致的两列布局，报备详情、编辑、复制、发送测试、启停、删除等操作文案清晰。
### 5.14 运营端通道组管理
@@ -288,6 +304,9 @@
- 敏感词管理：发送前和审核时命中提示或拦截。
- 手机号段库：用于运营商识别和路由。
- 引流信息字段库：用于签名/报备资料结构化采集。
- 企业黑名单、全局黑名单、敏感词管理必须提供搜索、添加、启停/删除功能；所有操作调用真实后端 API，写入系统日志。
- 企业黑名单支持按企业、应用、手机号、入库原因、状态搜索；全局黑名单支持按手机号、原因、状态搜索；敏感词支持按词、分类/级别、状态搜索。
- “引流信息字段库”菜单命名为“报备字段库”，编辑、删除按钮使用通用操作按钮样式。
### 5.18 风控规则闭环
@@ -318,8 +337,11 @@
### 5.21 系统管理与审计
- 用户管理支持角色、权限、启停、重置密码。
- 系统日志记录登录、配置变更、审核、发送、导入导出、密钥重置等操作。
- 用户管理支持角色、权限、启停、重置密码；客户端用户角色第一版限定一个企业管理员，避免多个企业管理员导致租户管理边界不清。
- 用户管理删除按钮使用统一危险操作样式；删除、启停、重置密码必须二次确认并写操作日志。
- 客户端和运营端右上角用户头像提供下拉菜单，支持退出登录、修改密码；账号设置独立菜单第一版不展示。
- 客户端和运营端系统日志均支持分页、搜索和详情展示；详情列内容较长时使用详情卡/弹窗展示，不能被表格窄列截断。
- 系统日志记录登录、退出、配置变更、审核、发送、导入导出、密钥重置、通道复制、通道启停、通道删除、连接状态变化、安全控制变更等操作。
## 6. 非功能需求
@@ -550,6 +572,12 @@
- `GET /api/client/billing/transactions`
- `POST /api/client/enterprise-certification`
- `GET /api/client/users`
- `POST /api/client/users`
- `PUT /api/client/users/{id}`
- `DELETE /api/client/users/{id}`
- `POST /api/client/users/{id}/status`
- `POST /api/client/users/{id}/password/reset`
- `POST /api/client/auth/password/change`
- `GET /api/client/system-logs`
### 10.2 运营端 API
@@ -561,15 +589,29 @@
- `POST /api/admin/enterprises`
- `PUT /api/admin/enterprises/{id}`
- `GET /api/admin/enterprise-applications`
- `PUT /api/admin/enterprise-applications/{id}`
- `GET /api/admin/enterprise-applications/{id}/connections`
- `DELETE /api/admin/enterprise-applications/{id}/connections/{connectionId}`
- `GET /api/admin/enterprise-applications/{id}/cmpp-params`
- `GET /api/admin/enterprise-signatures`
- `GET /api/admin/enterprise-templates`
- `GET /api/admin/enterprise-certifications`
- `GET /api/admin/enterprise-certifications/{id}`
- `POST /api/admin/enterprise-certifications/{id}/approve`
- `POST /api/admin/enterprise-certifications/{id}/reject`
- `GET /api/admin/audit-summary`
- `POST /api/admin/audits/{id}/approve`
- `POST /api/admin/audits/{id}/reject`
- `GET /api/admin/channels`
- `POST /api/admin/channels`
- `PUT /api/admin/channels/{id}`
- `POST /api/admin/channels/{id}/status`
- `DELETE /api/admin/channels/{id}`
- `POST /api/admin/channels/{id}/copy`
- `POST /api/admin/channels/{id}/test`
- `GET /api/admin/channels/{id}/reports`
- `GET /api/admin/channels/{id}/connections`
- `GET /api/admin/channels/{id}/link-logs`
- `POST /api/admin/channel-groups`
- `GET /api/admin/report-tasks`
- `POST /api/admin/report-tasks/generate`
@@ -579,9 +621,18 @@
- `GET /api/admin/sms/tasks`
- `GET /api/admin/sms/records`
- `GET /api/admin/sms/uplinks`
- `GET /api/admin/blacklists/enterprise`
- `GET /api/admin/blacklists/global`
- `GET /api/admin/sensitive-words`
- `GET /api/admin/dictionaries/blacklists/enterprise`
- `POST /api/admin/dictionaries/blacklists/enterprise`
- `POST /api/admin/dictionaries/blacklists/enterprise/{id}/status`
- `DELETE /api/admin/dictionaries/blacklists/enterprise/{id}`
- `GET /api/admin/dictionaries/blacklists/global`
- `POST /api/admin/dictionaries/blacklists/global`
- `POST /api/admin/dictionaries/blacklists/global/{id}/status`
- `DELETE /api/admin/dictionaries/blacklists/global/{id}`
- `GET /api/admin/dictionaries/sensitive-words`
- `POST /api/admin/dictionaries/sensitive-words`
- `POST /api/admin/dictionaries/sensitive-words/{id}/status`
- `DELETE /api/admin/dictionaries/sensitive-words/{id}`
- `GET /api/admin/risk-rules`
- `POST /api/admin/risk-rules`
- `PUT /api/admin/risk-rules/{id}`
@@ -593,7 +644,17 @@
- `POST /api/admin/billing/recharges`
- `GET /api/admin/phone-segments`
- `GET /api/admin/drainage-fields`
- `POST /api/admin/drainage-fields`
- `PUT /api/admin/drainage-fields/{id}`
- `DELETE /api/admin/drainage-fields/{id}`
- `GET /api/admin/users`
- `POST /api/admin/users`
- `PUT /api/admin/users/{id}`
- `DELETE /api/admin/users/{id}`
- `POST /api/admin/users/{id}/status`
- `POST /api/admin/users/{id}/password/reset`
- `POST /api/admin/auth/password/change`
- `GET /api/admin/system-logs`
### 10.3 通道回调 API
@@ -774,8 +835,9 @@
2. NestJS 后端实现 Prisma schema、migration、Service、Controller、DTO、单元测试。
3. Go Gateway 实现配置、连接管理、CMPP submit/deliver/active test、回执事件发布、单元测试。
4. 前端将对应 mock 数据替换为 API 调用，保留现有视觉样式。
5. 补充错误处理、权限校验、操作日志。
6. 运行构建和相关测试。
5. 原型阶段的 mock、localStorage 或静态数据只能作为开发临时兜底，不得作为真实开发完成标准；审核、通道、连接、日志、黑名单、敏感词、报备字段、用户、账务等闭环必须接入真实 API、数据库或 Gateway 回写。
6. 补充错误处理、权限校验、操作日志。
7. 运行构建和相关测试，并更新测试进度文档。
```
## 14. 已确认关键决策
@@ -1096,6 +1158,7 @@
- 不从零手写整个 CMPP 协议栈，也不直接照搬完整开源网关；协议层可复用，服务层按本项目自研。
- NestJS 负责业务审核、风控、计费、报备、路由和发送编排。
- Go Gateway 只负责 CMPP 连接、协议提交、submit resp、回执、上行事件回传。
- 当前项目已进入真实开发阶段；前端 mock、localStorage 或静态数据只能临时兜底，不能作为功能完成标准。涉及审核、通道、连接、日志、安全控制、用户、账务等闭环时，必须接入真实 API、数据库或 Gateway 回写，并补测试。
请从 docs/first-version-development-requirements.md 的“阶段 0：技术 Spike”开始执行。
docs/system-functional-test-cases.md
+286
View File
@@ -174,6 +174,36 @@
- 可展示匹配到的下发 messageId。
- 未匹配上行仍可查询，状态或关联为空。
### TC-CLIENT-010 用户管理与企业管理员唯一性
- 优先级：P1
- 前置条件：企业管理员已登录，租户下已有一个企业管理员和一个普通用户。
- 步骤：
1. 打开客户端用户管理页面。
2. 新增普通用户并保存。
3. 编辑普通用户，尝试将角色改为企业管理员。
4. 删除普通用户并确认。
- 预期结果：
- 新增、编辑、删除均调用真实客户端用户 API。
- 第一版同一租户只允许一个企业管理员；重复设置时返回明确错误或前端禁用该角色选项。
- 删除按钮使用统一危险操作样式，删除前二次确认。
- 用户创建、编辑、删除均写入系统日志。
### TC-CLIENT-011 头像菜单、密码修改与系统日志分页
- 优先级：P1
- 前置条件：客户端用户已登录，系统日志超过一页。
- 步骤：
1. 点击右上角用户头像。
2. 执行修改密码并重新登录。
3. 再次点击头像执行退出登录。
4. 打开客户端系统日志，切换分页并查看长详情。
- 预期结果：
- 头像下拉展示退出登录、修改密码，不展示独立账号设置菜单。
- 修改密码调用真实 API，旧密码失效，新密码可登录。
- 退出登录清理会话并写日志。
- 系统日志分页来自真实 API，长详情使用详情卡或弹窗展示，不被表格窄列截断。
## 5. 运营端功能用例
### TC-ADMIN-001 签名审核通过
@@ -348,6 +378,141 @@
- 若人为构造缺失流水，diff 展示差额。
- 查询结果支持定位 taskId/messageId。
### TC-ADMIN-014 短信模板审核搜索与审核
- 优先级：P1
- 前置条件：存在不同客户、应用、内容、状态的短信模板审核记录。
- 步骤：
1. 打开运营端短信模板审核页面。
2. 分别按客户、应用、模板内容、审核编号、审核状态搜索。
3. 对一条待审核模板执行通过。
4. 对另一条待审核模板执行驳回并填写原因。
- 预期结果：
- 搜索条件由真实后端 API 处理，结果只包含匹配记录。
- 通过后模板状态变为 approved，驳回后模板状态变为 rejected。
- 审核记录、操作者、审核时间和驳回原因可追溯。
- 客户端模板列表同步展示最新状态。
### TC-ADMIN-015 企业认证详情与审核闭环
- 优先级：P1
- 前置条件：客户已提交企业认证资料，包含主体信息、营业执照、对公账户验证和联系人信息。
- 步骤：
1. 打开运营端企业认证审核列表并按客户名称搜索。
2. 进入认证详情，核对统一社会信用代码、法定代表人、注册地址、营业执照附件、银行验证资料、联系人、提交时间。
3. 审核通过一条认证。
4. 驳回另一条认证并填写原因，客户修改资料后重新提交。
- 预期结果：
- 详情页展示客户真实提交资料，不使用前端静态内容。
- 通过后认证记录和租户认证状态同步为 approved。
- 驳回后客户可见驳回原因，可重新提交。
- 审核动作写入系统日志，并影响立即发送和定时到点发送准入。
### TC-ADMIN-016 通道复制真实闭环
- 优先级：P1
- 前置条件：存在一个 active CMPP 通道，已配置 CMPP 参数、通道报备字段、签名/引流报备材料和个性化字段。
- 步骤：
1. 在通道列表点击复制通道并确认。
2. 查询新通道详情。
3. 打开新通道报备详情。
4. 查询操作日志。
- 预期结果：
- 后端创建新通道，新通道 id/code 与源通道不同，名称默认追加“副本”。
- 通道配置、CMPP 参数、报备字段、签名/引流报备材料和个性化字段与源通道一致。
- 复制动作写入系统日志。
- 复制后新通道可继续编辑、启停、删除，不影响源通道。
### TC-ADMIN-017 通道启停、删除确认与软删除
- 优先级：P1
- 前置条件：存在 active 通道，且通道关联历史发送、报备和日志记录。
- 步骤：
1. 点击停用通道，取消确认。
2. 再次点击停用并确认。
3. 点击启用并确认。
4. 点击删除并确认。
5. 查询历史发送、报备和日志。
- 预期结果：
- 取消确认不改变数据库状态。
- 启用、停用、删除均调用真实后端 API 并写系统日志。
- 删除采用软删除或停用归档，不破坏历史发送、报备、日志外键。
- 软删除后的通道不再参与路由和新任务发送。
### TC-ADMIN-018 企业应用 CMPP 连接数、连接详情与参数复制
- 优先级：P1
- 前置条件：Gateway 或测试替身已向 NestJS 回写企业应用连接状态，应用已配置 CMPP 接入参数。
- 步骤：
1. 打开企业应用管理列表。
2. 查看 CMPP 状态列连接数。
3. 点击连接数打开连接详情。
4. 删除一个连接并确认。
5. 点击 CMPP 连接参数按钮并一键复制。
- 预期结果：
- 连接数来自真实连接状态 API。
- 连接详情展示连接 id、状态、建立时间、最近心跳时间、上次提交时间、窗口占用等要素。
- 删除连接调用真实后端或 Gateway 接口，连接状态刷新并写系统日志。
- CMPP 参数来源于真实应用/通道配置，一键复制内容与 API 返回一致。
### TC-ADMIN-019 通道链接日志展示
- 优先级：P1
- 前置条件：Gateway 或测试替身已产生新建连接、心跳、断开、重连、异常事件。
- 步骤：
1. 打开短信通道管理页面。
2. 在状态区域点击链接日志。
3. 查看日志时间、事件类型、连接 id、详情。
- 预期结果：
- 链接日志由真实后端 API 返回，不使用前端硬编码数据。
- 日志包含新建连接、断开、心跳、重连、异常等事件。
- 日志按时间倒序展示，并可定位到对应通道或连接。
### TC-ADMIN-020 安全控制搜索、添加、启停与删除
- 优先级：P1
- 前置条件：运营管理员已登录，存在企业、应用和若干黑名单/敏感词数据。
- 步骤：
1. 在企业黑名单中按企业、应用、手机号、原因、状态搜索。
2. 新增企业黑名单，停用后再删除。
3. 在全局黑名单中按手机号、原因、状态搜索，并新增、停用、删除。
4. 在敏感词管理中按词、分类/级别、状态搜索，并新增、停用、删除。
- 预期结果：
- 搜索、添加、启停、删除均调用真实字典 API。
- 启停/删除后发送前风控只使用 active 数据。
- 所有安全控制变更写入系统日志。
- 操作按钮使用统一编辑、删除、启停样式。
### TC-ADMIN-021 运营端消息铃铛审核提醒
- 优先级：P1
- 前置条件：浏览器允许通知，存在企业认证、短信审核、模板审核、签名审核待处理任务。
- 步骤：
1. 打开运营端任意页面，查看右上角消息铃铛数字。
2. 点击铃铛查看分类数量。
3. 点击某个分类。
4. 新增一条待审核任务。
- 预期结果：
- 铃铛数字等于所有待审核任务总数，分类数量来自真实待审核统计 API。
- 点击分类跳转到对应审核页面并带入筛选状态。
- 新审核任务进入时触发浏览器通知或站内提醒。
- 审核完成后总数和分类数量刷新。
### TC-ADMIN-022 运营端系统日志分页与详情展示
- 优先级：P1
- 前置条件：存在超过一页的运营端系统日志，且部分日志详情较长。
- 步骤：
1. 打开运营端系统日志页面。
2. 按操作者、操作类型、资源、时间搜索。
3. 切换分页。
4. 查看长详情日志。
- 预期结果：
- 分页、搜索由真实后端 API 处理。
- 页面只保留一个标题和一个图标。
- 长详情使用详情卡或弹窗展示，不被表格窄列截断。
- 能查询到登录、退出、审核、通道复制、通道启停、通道删除、连接状态变化、安全控制变更等日志。
## 6. 风控规则专项用例
### TC-RISK-001 单任务最大号码数直接拒绝
@@ -2196,3 +2361,124 @@ npm run verify:phase8
```
若测试环境具备 PostgreSQL、Redis、MinIO，再补充执行 E2E smoke 和真实 API HTTP 测试。
## 17. 新增和更新用例细化执行清单
本节用于细化 2026-07-02 新增的页面真实后端、Dashboard、人工充值、系统日志、客户管理和 CMPP 连接状态用例。执行时应优先使用真实 NestJS API、Prisma/PostgreSQL、Redis/BullMQ 和 Gateway 测试替身；mock、localStorage 或前端静态数组只能作为单元测试替身，不能作为业务验收通过依据。
### 17.1 通用断言规则
| 断言类型 | 检查点 |
| --- | --- |
| 数据来源 | 页面列表、详情、统计卡片、弹窗和下拉选项均必须来自真实 API 响应；网络失败时可有兜底展示，但兜底不能计入通过。 |
| 租户隔离 | 客户端接口必须以当前租户为边界；通过 URL、查询参数或资源 id 访问其他租户数据时，应返回无权限、无数据或明确错误。 |
| 状态联动 | 客户、应用、签名、模板、引流信息、通道、连接状态变化后，立即发送、定时到点、导入确认发送都必须重新校验。 |
| 日志证据 | 创建、编辑、删除、启停、复制、审核、导入、导出、充值、冲正、发送阻断、连接状态变化、失败动作都必须写系统日志。 |
| 历史数据 | 软删除、停用、归档不得破坏历史发送、报备、计费、trace 和对账记录。 |
| 计费口径 | Dashboard、账单流水、短信计费记录、账户交易和 reconciliation 的金额、条数、状态口径必须一致。 |
| Gateway 边界 | 不依赖真实运营商 SMSC；CMPP 登录、心跳、断线、重连、慢响应使用 Go Gateway 本地模拟器或连接状态回写 API。 |
### 17.2 客户端用户和系统日志细化
| 用例 | 细化执行点 | 必查断言 |
| --- | --- | --- |
| TC-CLIENT-010 | 新增普通用户，检查请求体包含 tenantId、手机号、角色、状态；编辑用户基础信息；尝试把第二个用户设为企业管理员；删除普通用户。 | 新增后用户列表刷新；同租户第二个企业管理员被阻止；删除为软删除或状态不可用；每步写 `operation_logs`，resource 指向 user id。 |
| TC-CLIENT-010 | 使用普通用户登录后访问用户管理页面和 API。 | 普通用户无权限或只读；无权限访问也写失败日志。 |
| TC-CLIENT-011 | 点击头像下拉，执行修改密码，使用旧密码登录，再使用新密码登录。 | 旧密码失效，新密码有效；修改密码日志不泄露明文密码；退出登录清理 token/session。 |
| TC-CLIENT-011 | 客户端系统日志准备至少 2 页数据，按动作、操作者、时间查询，查看长详情。 | 分页参数传给后端；总数、页码、页大小准确；长详情不在表格中截断，详情弹窗/卡片展示完整 JSON 摘要。 |
### 17.3 运营端真实后端页面细化
| 用例 | 细化执行点 | 必查断言 |
| --- | --- | --- |
| TC-ADMIN-014 | 按客户名称、应用名称、模板内容、审核编号、审核状态分别搜索模板审核列表。 | 每次搜索均发起 API 请求；结果只包含匹配数据；清空条件后恢复默认列表；跨租户/不存在关键字无误展示。 |
| TC-ADMIN-014 | 对待审核模板分别执行通过、驳回。 | 审核状态更新；审核记录包含审核人、时间、原因；客户端模板列表同步；驳回模板不能发送。 |
| TC-ADMIN-015 | 运营端查看企业认证详情，核对主体信息、执照附件、对公账户验证、联系人。 | 详情字段来自 certification API；附件 id/URL 可追溯；通过/驳回同步 Tenant.certificationStatus；驳回后客户可重提。 |
| 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-020 | 企业黑名单、全局黑名单、敏感词分别执行搜索、新增、停用、删除。 | 搜索由 API 处理；停用/删除后发送前风控只使用 active 数据；删除不影响历史命中记录；所有动作写日志。 |
| TC-ADMIN-021 | 创建待审核企业认证、签名、模板、短信审核任务，检查铃铛总数和分类数。 | 总数等于分类汇总；点击分类跳转并带入筛选；审核完成后数量刷新；新增待办触发站内提醒或浏览器通知。 |
| TC-ADMIN-022 | 运营日志按客户、操作者、动作、资源、时间搜索，查看长详情。 | 后端分页和搜索准确；详情不截断；可查到通道复制、启停、删除、连接状态变化、安全控制变更、充值等日志。 |
### 17.4 Dashboard 指标细化
| 用例 | 数据准备 | 指标断言 |
| --- | --- | --- |
| TC-DASHBOARD-001 | 客户 A 当天 delivered=10、failed=3、unknown=2、timeout=1；客户 B 有干扰数据。 | 客户端总量=16；成功=10；失败按 failed+timeout 为 4；unknown=2；成功率若按 delivered/total 为 62.5%；点击卡片后的明细筛选一致。 |
| TC-DASHBOARD-002 | 账户余额 10000 分、套餐 200 条、授信 5000 分，另有冻结、扣费、释放、退款流水。 | 可用余额不重复计算冻结；金额余额和套餐余量分开展示；账单流水余额 after 与 Dashboard 一致。 |
| TC-DASHBOARD-003 | 待审核签名 2、模板 3、待报备 1、pending_review 发送任务 4。 | 待处理总数和分类数准确；点击跳转后列表筛选数量一致；只包含当前租户。 |
| TC-DASHBOARD-004 | 多客户、多通道、多状态发送和账务流水。 | 运营端统计全平台；活跃客户、今日发送、成功率、待审核、收入均可在明细页复核。 |
| TC-DASHBOARD-005 | 客户 A/B 均有发送、账务、审核数据。 | 切换客户后所有卡片、趋势、状态分布、账务汇总同步刷新；跳转明细继承客户筛选。 |
| TC-DASHBOARD-006 | 通道 A online 2/2，B disconnected 0/2，C auth_failed。 | 在线连接总数等于各通道 currentConnections 之和；异常通道数分类准确；点击异常通道展示错误原因。 |
| TC-DASHBOARD-007 | 准备跨日、跨小时和时区边界数据。 | 今日、近 7 天、近 30 天边界明确；趋势图每个点位与明细聚合一致；使用平台时区。 |
### 17.5 人工充值和账务细化
| 用例 | 细化执行点 | 必查断言 |
| --- | --- | --- |
| TC-BILLING-006 | 运营端人工充值金额和短信条数，客户端查看 Dashboard 和账单流水。 | RechargeOrder 状态为 paid/manual_topup；TenantAccount 同步增加；AccountTransaction 类型 recharge；运营日志和客户端流水均可追溯。 |
| TC-BILLING-007 | 分别只填金额、只填短信条数。 | 未填项按 0；金额和条数字段方向正确；不会产生 null、NaN 或负数脏数据。 |
| TC-BILLING-008 | 对已充值记录执行撤销/冲正，分别覆盖未消费和已部分消费。 | 未消费可全额回退；已消费按规则拒绝或生成人工调整；原订单状态和反向流水清晰；日志记录原因。 |
| TC-BILLING-009 | 无权限用户、审核员、管理员、大额审批分别执行充值。 | 权限不足被拒绝并写失败日志；大额充值 pending 时不更新余额；审批通过才入账，驳回不入账。 |
| TC-BILLING-010 | 余额不足发送失败，人工充值后重试发送并模拟 delivered。 | 充值前不扣费；充值后发送成功；冻结、扣费、短信计费记录完整；reconciliation diff 为 0。 |
### 17.6 系统日志细化
| 用例 | 细化执行点 | 必查断言 |
| --- | --- | --- |
| TC-LOG-005 | 客户 A 查看日志并尝试查询客户 B 日志。 | 客户端只返回本租户日志；越权查询失败；日志包含 IP、User-Agent、result、resourceId。 |
| TC-LOG-006 | 客户端导入号码、立即发送、创建并取消定时任务。 | 导入日志含文件名、行数、成功/失败数；发送日志含任务编号、号码数、发送类型；取消日志含取消人。 |
| TC-LOG-007 | 运营端按客户、动作、资源、结果、时间查询并导出。 | 查询准确；导出内容与筛选一致；导出动作本身写日志。 |
| TC-LOG-008 | 人工充值、冲正、账户调整。 | 日志含客户、金额、短信条数、订单号、流水号、操作者；敏感字段脱敏。 |
| TC-LOG-009 | 触发无权限充值、余额不足发送、无在线通道发送。 | 失败动作也写日志；result/status 标记失败；失败原因与前端提示一致。 |
### 17.7 客户管理细化
| 用例 | 细化执行点 | 必查断言 |
| --- | --- | --- |
| TC-CUSTOMER-001 | 运营端创建客户并初始化管理员账号、租户、账户。 | Tenant、管理员用户、TenantAccount 创建成功；客户详情业务入口可用；新管理员只能访问本租户。 |
| TC-CUSTOMER-002 | 修改客户名称、联系人、备注，查看客户端和历史数据。 | 展示同步更新；历史任务和账务不丢失；日志记录修改前后摘要。 |
| TC-CUSTOMER-003 | 停用客户后分别通过客户端、API、CMPP 接入尝试发送。 | 全部阻断；不入队、不扣费；失败原因是客户停用；历史任务可查。 |
| TC-CUSTOMER-004 | 客户 active 时创建 scheduled，到点前停用。 | 到点重校验失败；任务 rejected/canceled/failed；冻结费用释放；日志指向客户停用。 |
| TC-CUSTOMER-005 | 重新启用客户后发送。 | 客户状态 active；新发送成功进入链路；账务和日志完整。 |
| TC-CUSTOMER-006 | 余额不足、套餐不足、授信不足、欠费标记。 | 发送前账户校验失败；不投递 Gateway；客户详情展示欠费或不足状态。 |
| TC-CUSTOMER-007 | 客户 A 使用 URL/API 参数访问客户 B 资源。 | 不泄露 B 数据；返回无权限或空结果；失败访问写安全日志。 |
| 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-012 | 调整客户通道连接数并触发 Gateway 重载。 | desired/current 连接数最终一致；发送能力或窗口容量随配置变化；日志记录变更。 |
| TC-CUSTOMER-013 | 超过通道最大连接数分配。 | 保存失败；提示最大连接数、已分配数和可用数；不影响已有连接；失败日志存在。 |
### 17.8 CMPP 连接状态细化
| 用例 | 模拟方式 | 必查断言 |
| --- | --- | --- |
| TC-CMPP-STATUS-001 | Gateway 未启动或未回写。 | 通道业务 active 与连接 disconnected/unknown 分开展示；不可误判为可提交。 |
| TC-CMPP-STATUS-002 | 模拟 SMSC 登录成功。 | 状态 online；连接建立时间、最近心跳、窗口可用；发送可路由到该通道。 |
| 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-006 | 主通道离线、备用在线且报备通过。 | 路由跳过主通道并选择备用；trace 展示备用 channelId。 |
| TC-CMPP-STATUS-007 | 所有通道离线或认证失败。 | 不提交到离线连接；任务 delayed/retry/failed/pending_channel；不错误扣费。 |
| TC-CMPP-STATUS-008 | 通道业务 disabled 但连接 online。 | 不参与路由；连接状态仍可运维观察；启用后按连接状态恢复可用性。 |
| TC-CMPP-STATUS-009 | 模拟 submit resp 慢响应。 | 窗口占用、慢响应、队列积压可见；恢复后积压下降；超时可追踪。 |
| TC-CMPP-STATUS-010 | 触发 online/disconnected/reconnecting/online。 | 每次变化有状态历史、健康指标和系统日志。 |
| 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-015 | desired=0 或 current=0。 | 路由不选择该通道；无备用时任务失败或等待；原因包含无在线连接。 |
| TC-CMPP-STATUS-016 | 单连接限速 100，连接数 1 和 2 分别压测。 | 理论能力随在线连接数变化；实际 TPS 不超过限速；不重复发送。 |
### 17.9 自动化落地建议
| 层级 | 建议覆盖 |
| --- | --- |
| API Jest | 认证、字典、安全控制、通道复制/软删除、连接状态、人工充值、系统日志查询、Dashboard 聚合口径。 |
| HTTP Smoke | 客户创建、认证审核、通道复制、连接状态回写、人工充值、立即发送、定时到点、trace、reconciliation。 |
| Go Gateway | 连接状态回写契约、登录成功/失败、心跳超时、断线重连、窗口占满、连接数调整。 |
| 前端 Smoke | 客户端头像菜单、系统日志分页、运营模板审核搜索、企业认证详情、通道复制/链接日志、安全控制 CRUD、Dashboard 指标跳转。 |
| 性能 Smoke | BullMQ 500 TPS、CMPP 连接数变化后的提交能力、慢响应积压恢复。 |
docs/testing-plan.md
+4 -3
View File
@@ -79,7 +79,8 @@ Windows 本项目推荐使用根脚本 `npm run test:gateway`，脚本会临时
## 4. 已知边界
- 本轮 API 测试不连接真实 PostgreSQL、Redis、MinIO。
- 发送 Worker 的 Redis 限速和 BullMQ 投递在 unit/light integration 中使用 mock；真实 Redis 链路由 `spike:bullmq` 覆盖。
- 前端暂未新增测试框架；当前保留 `npm run build` 作为 smoke。若后续引入 Vitest/Playwright，应先覆盖登录页、客户端发送页、运营端监控页的加载 smoke。
- 单元测试和轻集成测试可以使用 mock Prisma/BullMQ/Redis 作为测试替身，但这只适用于测试隔离，不代表业务功能可以停留在 mock。
- 真实开发完成标准必须包含：Prisma/PostgreSQL 模型或查询、NestJS Service/Controller、必要的操作日志、前端调用真实 API，以及在真实 PostgreSQL/Redis/MinIO 可用时完成 smoke。
- 发送 Worker 的 Redis 限速和 BullMQ 投递可在 unit/light integration 中使用 mock；真实 Redis 链路仍需由 `spike:bullmq`、API smoke 或端到端验证覆盖。
- 前端暂未新增测试框架；当前保留 `npm run build` 作为 smoke。新增页面能力不能只依赖前端本地状态或 localStorage，除非需求明确声明为临时演示。
- Gateway 不连接真实运营商 SMSC；使用 gocmpp 适配测试和内部模拟器测试。
docs/testing-progress.md
+46
View File
@@ -173,3 +173,49 @@ npm run test:gateway
- 客户侧导入当前提供 API 级文本预览/确认闭环；浏览器端真实文件选择、GBK 二进制转码和错误文件下载仍需前端/E2E 后续覆盖。
- Gateway 连接状态通过 NestJS API 支持 mock/Gateway 回写；真实运营商 SMSC 联调仍需运营商测试环境。
## 2026-07-02 运营端优化转真实后端补齐
### 本轮修复范围
- 修正测试策略说明：mock 仅作为单元/轻集成测试替身，不能作为业务完成标准；新增页面能力必须接 NestJS API、Prisma/PostgreSQL 和必要操作日志。
- 通道管理补齐真实 API：
- `POST /api/admin/channels/:id/copy`：复制通道配置、通道报备字段和该通道签名报备材料，写入操作日志。
- `DELETE /api/admin/channels/:id`：软删除通道，避免破坏历史发送/报备外键。
- `GET /api/admin/channels/:id/link-logs`：基于 `OperationLog` 和 `CmppConnectionState` 查询链接日志。
- 安全控制补齐真实 API：敏感词、全局黑名单、企业黑名单支持 keyword/status 查询、创建、启停/软删除，并写操作日志。
- 模板审核补齐真实查询：运营端模板列表支持 keyword/status，并返回企业、应用、签名信息；前端模板审核页已改为调用真实 API。
- 企业认证审核补齐真实查询：列表支持 keyword/status，详情返回企业信息和认证 materials；前端企业认证审核页已改为调用真实 API。
- 前端新增 `/api` Vite 代理和 `src/api/adminApi.ts`，通道管理、模板审核、企业认证审核优先调用真实 API，API 不可用时仅保留静态兜底避免开发预览空白。
### 新增/更新测试
| 测试文件 | 新增覆盖 |
| --- | --- |
| `api/src/channels/channels.service.spec.ts` | 通道复制、软删除、连接状态日志写入、链接日志查询。 |
| `api/src/dictionaries/dictionaries.service.spec.ts` | 敏感词、全局黑名单、企业黑名单查询、创建、软删除和操作日志。 |
### 已执行命令
```bash
npm --prefix api run build
npm --prefix api test
npm run build
```
### 当前结果
- API build 通过。
- API Jest：8 个 test suite 通过，38 个测试通过。
- 前端 build 通过，仍存在既有 Vite chunk size warning。
### 文档同步
- 已将今天的客户端和运营端优化要求补入 `docs/first-version-development-requirements.md`：
- 去除客户端独立账号设置菜单，改为头像下拉承载退出登录和修改密码。
- 明确模板审核搜索、企业认证详情审核、企业应用 CMPP 连接数/连接详情/参数复制、通道复制、通道软删除、通道链接日志、安全控制 CRUD、系统日志分页等均需要真实后端 API 支撑。
- 补充客户端用户、运营端企业认证、通道、连接、字典、安全控制、系统日志等接口范围。
- 修正 Codex 执行模板，明确 mock、localStorage 或静态数据不得作为真实开发完成标准。
- 已将今天的验收点补入 `docs/system-functional-test-cases.md`：
- 新增 TC-CLIENT-010 到 TC-CLIENT-011。
- 新增 TC-ADMIN-014 到 TC-ADMIN-022。