feat: refine client status and review views
This commit is contained in:
hectorzhao
@@ -0,0 +1,216 @@
|
||||
# 批量发送任务人工审核状态优化方案
|
||||
|
||||
## 1. 文档目的
|
||||
|
||||
本文档记录客户端创建批量发送任务并进入运营人工审核期间的当前代码行为、已确认问题、建议修复范围和验收标准，供主任务实施与测试使用。
|
||||
|
||||
本文结论来自 2026-08-27 对当前工作区代码的静态核对，不代表测试环境或预生产环境的实时运行结果。实施完成后仍需通过接口、数据库和页面进行完整验证。
|
||||
|
||||
## 2. 当前代码行为
|
||||
|
||||
客户端创建批量发送任务并命中人工审核规则时，系统会创建两类关联记录：
|
||||
|
||||
1. `SmsSendTask`：运营审核任务。
|
||||
- 风控判定结果为 `pending_review`。
|
||||
- 任务状态为 `pending_review`。
|
||||
- 运营端“短信审核”页面默认查询该状态，可执行通过或驳回。
|
||||
|
||||
2. `SmsBatchTask`：实际批量发送任务。
|
||||
- 状态同样为 `pending_review`。
|
||||
- `riskTaskId` 指向对应的 `SmsSendTask`。
|
||||
- 客户端批量任务页面和运营端短信任务进度页面均可查询到该记录。
|
||||
|
||||
短信明细也会创建，并通过 `reviewTaskId` 或批量任务的 `riskTaskId` 与审核任务关联。在审核通过前，短信不应进入实际发送流程。
|
||||
|
||||
主要代码位置：
|
||||
|
||||
- `api/src/risk-review/risk-review.service.ts`：风控判定及 `SmsSendTask` 创建。
|
||||
- `api/src/send-chain/send-batch-entry.service.ts`：`SmsBatchTask`、短信明细创建及审核任务关联。
|
||||
- `api/src/risk-review/admin-risk-review.controller.ts`：运营审核任务查询与审核入口。
|
||||
- `api/src/send-chain/send-review-continuation.service.ts`：审核决定后的发送流程续接。
|
||||
- `src/apps/admin/AdminSmsAuditPage.tsx`：运营端短信审核页面。
|
||||
- `src/apps/admin/AdminSmsTaskProgressPage.tsx`：运营端短信任务进度页面。
|
||||
- `src/apps/client/ClientBatchTasksPage.tsx`：客户端批量任务页面。
|
||||
|
||||
## 3. 已确认问题
|
||||
|
||||
### 3.1 客户端审核状态显示错误
|
||||
|
||||
`ClientBatchTasksPage.tsx` 的状态归一化逻辑没有识别 `pending_review`，所有未单独处理的状态都会落入 `sending`，因此待人工审核任务被错误显示为“发送中”。
|
||||
|
||||
### 3.2 运营端任务进度状态显示错误
|
||||
|
||||
`src/apps/admin/sms-task-progress/taskModel.ts` 同样没有将 `pending_review` 作为独立任务状态，导致运营端短信任务进度页面也将待审核任务显示为“发送中”。
|
||||
|
||||
### 3.3 审核字段在客户端映射时丢失
|
||||
|
||||
后端任务类型和接口结果已包含以下字段：
|
||||
|
||||
- `auditStatus`
|
||||
- `reviewReason`
|
||||
- `rejectReason`
|
||||
- `riskTaskId`
|
||||
|
||||
但客户端页面的 `mapTask()` 没有保留这些字段，因此客户无法看到任务正在审核、触发原因或驳回原因。
|
||||
|
||||
### 3.4 客户端展示了不可用的“终止”操作
|
||||
|
||||
客户端将 `pending_review` 映射为 `sending` 后，会启用“终止”按钮；但客户端取消接口只允许取消后端状态为 `scheduled` 的任务。对待审核任务点击该按钮必然返回失败。
|
||||
|
||||
### 3.5 存在孤立审核任务风险
|
||||
|
||||
当前流程先调用风控服务创建 `SmsSendTask`，之后才继续余额校验、余额冻结和 `SmsBatchTask` 创建。如果后续步骤失败，可能留下没有实际批量任务与短信明细的审核记录。
|
||||
|
||||
该问题属于流程可靠性风险，建议与前端状态修复分开实施和提交。
|
||||
|
||||
## 4. 优化目标
|
||||
|
||||
1. 客户端和运营端都能准确识别并显示“待人工审核”。
|
||||
2. 审核期间不得误导用户认为短信正在发送。
|
||||
3. 页面操作权限必须与后端状态机一致。
|
||||
4. 审核原因、驳回原因及关联审核任务应可追踪。
|
||||
5. 审核通过或驳回后，审核任务、批量任务、短信明细和余额状态保持一致。
|
||||
6. 后续消除审核任务先创建导致的孤立记录风险。
|
||||
|
||||
## 5. 建议实施方案
|
||||
|
||||
### 5.1 第一阶段：最小充分修复
|
||||
|
||||
#### 5.1.1 客户端批量任务页面
|
||||
|
||||
- 将 `pending_review` 增加为独立展示状态。
|
||||
- 标签显示“待人工审核”，使用警告色。
|
||||
- 审核期间发送进度保持为零，不显示为正在发送。
|
||||
- 在详情中展示 `reviewReason`。
|
||||
- 审核驳回后展示 `rejectReason`。
|
||||
- `pending_review` 状态隐藏或禁用“终止”按钮。
|
||||
- 只有后端状态为 `scheduled` 时才允许调用客户端取消接口。
|
||||
|
||||
#### 5.1.2 运营端短信任务进度页面
|
||||
|
||||
- 将 `pending_review` 增加为独立展示状态。
|
||||
- 标签显示“待人工审核”，使用警告色。
|
||||
- 审核期间不展示发送中进度语义。
|
||||
- 保留 `rawStatus`、`auditStatus`、`reviewReason`、`rejectReason` 和 `riskTaskId`。
|
||||
- 待审核任务不提供普通“终止发送”操作。
|
||||
- 条件允许时增加“前往审核”入口，定位到对应的 `SmsSendTask`。
|
||||
|
||||
#### 5.1.3 运营端短信审核页面
|
||||
|
||||
- 同时展示审核任务号和关联批量任务号。
|
||||
- 展示企业、应用、号码数量、短信内容、触发规则和审核原因。
|
||||
- 审核完成后允许跳转到批量任务进度详情。
|
||||
- 若暂不实现跨页面跳转，至少保证审核任务号、批量任务号及关联关系可见。
|
||||
|
||||
#### 5.1.4 统一前端状态模型
|
||||
|
||||
建议将客户端和运营端重复的状态归一化逻辑提取到共享模块，统一维护：
|
||||
|
||||
- 状态显示名称。
|
||||
- 标签颜色。
|
||||
- 进度语义。
|
||||
- 允许执行的操作。
|
||||
- 是否显示审核原因或失败原因。
|
||||
|
||||
禁止继续使用“未识别状态默认等于发送中”的策略。未识别状态应显示“未知状态”，并保留后端原始状态值，便于发现状态协议漂移。
|
||||
|
||||
### 5.2 建议统一状态映射
|
||||
|
||||
| 后端状态 | 页面显示 | 主要允许操作 |
|
||||
| --- | --- | --- |
|
||||
| `pending_review` | 待人工审核 | 查看 |
|
||||
| `scheduled` | 等待定时发送 | 客户端可取消 |
|
||||
| `ready`、`queued` | 等待发送 | 查看 |
|
||||
| `sending`、`submitted` | 发送中 | 按权限终止 |
|
||||
| `completed`、`finished`、`done` | 已完成 | 查看 |
|
||||
| `rejected` | 审核驳回 | 查看审核原因 |
|
||||
| `canceled`、`cancelled`、`terminated` | 已取消或已终止 | 查看 |
|
||||
| `failed` | 发送失败 | 查看失败原因 |
|
||||
| 未识别状态 | 未知状态（附原始值） | 查看 |
|
||||
|
||||
### 5.3 第二阶段：流程可靠性优化
|
||||
|
||||
前端状态修复完成后，再处理孤立审核任务风险。建议选择以下一种方案：
|
||||
|
||||
1. 将审核任务、批量任务、短信明细及可纳入数据库的余额操作放入一致事务边界。
|
||||
2. 如果余额服务或队列操作无法进入同一事务，则增加失败补偿：
|
||||
- 将已创建的审核任务标记为 `canceled` 或专用失败状态。
|
||||
- 写入失败原因。
|
||||
- 释放已冻结资源。
|
||||
- 确保运营端默认待审核列表不再展示该任务。
|
||||
|
||||
同时应保证状态联动：
|
||||
|
||||
- 审核通过：`SmsSendTask` 完成审核，`SmsBatchTask` 转为 `ready` 或 `scheduled`，符合条件的短信进入发送流程。
|
||||
- 审核驳回：审核任务、批量任务和短信明细同步转为拒绝终态，并释放冻结余额。
|
||||
- 审核取消或创建失败：关联记录全部进入不可继续审核、不可继续发送的明确终态。
|
||||
- 已完成、已驳回、已取消的审核任务不得再次执行审核决定。
|
||||
|
||||
## 6. 建议测试用例
|
||||
|
||||
### 6.1 创建与可见性
|
||||
|
||||
1. 创建命中人工审核规则的立即发送批量任务。
|
||||
2. 创建命中人工审核规则的定时发送批量任务。
|
||||
3. 验证数据库同时存在关联的 `SmsSendTask` 和 `SmsBatchTask`。
|
||||
4. 验证客户端批量任务页面能够看到任务并显示“待人工审核”。
|
||||
5. 验证运营端短信审核页面能够看到对应审核任务。
|
||||
6. 验证运营端短信任务进度页面能够看到批量任务并显示“待人工审核”。
|
||||
|
||||
### 6.2 审核期间行为
|
||||
|
||||
1. 验证任务没有进入短信发送队列。
|
||||
2. 验证发送数量和发送进度保持为零。
|
||||
3. 验证客户端不能对 `pending_review` 调用定时任务取消接口。
|
||||
4. 验证客户端和运营端均能查看审核原因。
|
||||
5. 验证页面不再显示“发送中”。
|
||||
|
||||
### 6.3 审核通过
|
||||
|
||||
1. 立即发送任务审核通过后进入 `ready` 或后续合法发送状态。
|
||||
2. 定时任务审核通过后进入 `scheduled`。
|
||||
3. 验证短信只入队一次，不发生重复发送。
|
||||
4. 验证审核任务、批量任务、短信明细状态一致。
|
||||
5. 验证余额冻结及最终扣费状态正确。
|
||||
|
||||
### 6.4 审核驳回
|
||||
|
||||
1. 审核任务转为 `rejected`。
|
||||
2. 批量任务和短信明细同步进入拒绝终态。
|
||||
3. 客户端和运营端均显示“审核驳回”及原因。
|
||||
4. 验证冻结余额正确释放。
|
||||
5. 验证任务不会进入发送队列。
|
||||
|
||||
### 6.5 异常与补偿
|
||||
|
||||
1. 模拟余额不足。
|
||||
2. 模拟余额冻结失败。
|
||||
3. 模拟批量任务创建失败。
|
||||
4. 模拟短信明细创建失败。
|
||||
5. 验证失败后不存在仍可由运营人员通过的孤立审核任务。
|
||||
6. 验证重复提交审核决定具有幂等保护。
|
||||
|
||||
## 7. 验收标准
|
||||
|
||||
本次最小修复满足以下条件即可验收：
|
||||
|
||||
1. 客户端和运营端任务进度页面都将 `pending_review` 显示为“待人工审核”。
|
||||
2. 审核期间不显示为“发送中”，发送进度不增长。
|
||||
3. 客户端待审核任务不再出现不可用的“终止”操作。
|
||||
4. 客户端详情能够显示审核原因和驳回原因。
|
||||
5. 运营审核页面能够找到并处理对应审核任务。
|
||||
6. 审核通过和驳回后，两端状态能够正确刷新。
|
||||
7. 新增或更新前后端自动化测试，覆盖状态映射、操作权限和审核状态联动。
|
||||
8. 相关测试用例及 `docs/testing-progress.md` 在主任务实施时同步更新。
|
||||
|
||||
## 8. 推荐实施顺序
|
||||
|
||||
1. 增加共享状态类型和状态映射。
|
||||
2. 修复客户端批量任务页面。
|
||||
3. 修复运营端任务进度页面。
|
||||
4. 补充审核原因和关联任务展示。
|
||||
5. 增加前端单元测试和后端状态联动测试。
|
||||
6. 执行真实接口、数据库、页面和队列验证。
|
||||
7. 单独设计并实施事务或失败补偿机制。
|
||||
|
||||
第一阶段应作为独立提交，避免将低风险展示修复与高影响流程事务改造混在同一个提交中。
|
||||
@@ -2169,3 +2169,12 @@
|
||||
- 验收必须保持正价，分别执行单企业100/150 TPS和至少两个独立企业合计200 TPS，按非补发首次供应商Submit、回执、上行、计费、主备补发、业务拦截及全队列排空对账；触发拒绝、连接错误、持续积压、数据库异常或账务不一致立即停止。多Gateway P2不在本阶段范围。
|
||||
- Gateway到主API的回环HTTP连接池空闲时长不得超过API服务端keep-alive生命周期；API默认keep-alive 120秒、headers timeout 125秒，并由发布环境显式设置和校验，防止负载期复用已被Node关闭的连接而把本可受理的Submit误回Result 9。
|
||||
- 同一Gateway下游会话的connected、heartbeat、submit和deliver状态回调允许并发到达；连接上限按不同`connectionId`计数，同一`connectionId`的首次状态必须幂等upsert，不得因查询/创建竞态误报超过连接数并主动断开客户连接。不同连接超过应用上限时仍返回403并由Gateway断开。
|
||||
|
||||
## 2026-08-27 客户端展示、三网报备与人工审核状态优化
|
||||
|
||||
- 客户端首页和账户余额页的金额使用继承系统字体的普通大号黑色字；客户端登录页提供“返回官网”。
|
||||
- 批量任务、发送详情、上行短信默认查询北京时间近 7 天；客户端右上角不展示运营审核任务入口。
|
||||
- 发送详情的发送状态和回执状态统一显示中文，未识别值显示“状态未知”；应用 CMPP 状态与运营端统一为已连接、已断开、未开通。
|
||||
- 客户端签名与引流列表不展示使用场景、已提交资料或审核状态，只展示移动、联通、电信三网可用性；全部通过和部分通过均显示“报备通过”，数据来自当前应用路由和真实通道报备任务汇总。
|
||||
- 人工审核批量任务把`pending_review`独立显示为“待人工审核”，审核期间进度为0；客户端仅允许取消`scheduled`任务，并展示审核原因和驳回原因。运营审核页展示审核任务号与关联批量任务号。
|
||||
- 运营端签名质量的通道活跃度热力图支持通道名搜索；短信任务进度支持后端任务状态查询。
|
||||
|
||||
@@ -4923,3 +4923,18 @@ npm run verify:phase8
|
||||
| TC-LG-STEP46-47-007 | 客户端批量任务显示 UTC ISO 时间 | 提交时间和定时时间统一转为 Asia/Shanghai `YYYY-MM-DD HH:mm:ss`，不显示原始 `T...Z` 字符串 |
|
||||
|
||||
执行记录：Gateway `resultoutbox` 定向测试及全包测试通过；API 45套528项通过；API构建、前端TypeScript与Vite生产构建通过。390×844 Chromium 渲染回归中，无模板直发按钮可用，日期弹层为366×476且操作区Y=431～471，XLSX明确拒绝，批次时间显示为北京时间，控制台无错误。
|
||||
|
||||
## TC-UI-REVIEW-20260827 客户端展示、三网报备与人工审核状态
|
||||
|
||||
| 用例ID | 场景 | 预期 |
|
||||
| --- | --- | --- |
|
||||
| TC-UI-REVIEW-001 | 查看客户端登录、首页和账户余额 | 登录页存在“返回官网”；金额为普通大号黑字；客户端右上角无待审核任务按钮 |
|
||||
| TC-UI-REVIEW-002 | 首次打开批量任务、发送详情和上行短信 | 三个日期区间均为北京时间近7天（含当天） |
|
||||
| TC-UI-REVIEW-003 | 查看不同状态的短信发送记录和回执 | 用户态状态为中文；未知协议值显示“状态未知” |
|
||||
| TC-UI-REVIEW-004 | 对比两端同一应用的CMPP状态 | 两端均按已连接、已断开、未开通显示 |
|
||||
| TC-UI-REVIEW-005 | 查看签名及引流三网状态 | 不显示使用场景、已提交资料、审核状态；三网状态来自真实路由和报备任务，部分通过与全部通过均映射为“报备通过” |
|
||||
| TC-UI-REVIEW-006 | 在通道签名活跃度热力图输入通道名 | 仅保留匹配通道的维度行；企业、应用、签名搜索仍有效 |
|
||||
| TC-UI-REVIEW-007 | 在运营端短信任务进度选择任务状态 | 请求携带精确状态且结果仅含该状态；重置恢复全部状态 |
|
||||
| TC-UI-REVIEW-008 | 创建命中人工审核规则的批量任务 | 两端显示“待人工审核”、进度为0；客户端无终止按钮，详情显示审核原因，运营审核页可见关联批量任务号 |
|
||||
| TC-UI-REVIEW-009 | 审核通过或驳回批量任务 | 状态按真实后端刷新；驳回时展示原因，不重复入队或发送 |
|
||||
| TC-UI-REVIEW-010 | 接口对接某个日志子接口失败 | 接口概览仍可用且提示中文，不直接显示`Internal server error` |
|
||||
|
||||
@@ -4046,3 +4046,11 @@ git diff --check
|
||||
- 移动端日期选择器使用视口内固定弹层和内部滚动，操作区置底；批量任务提交/定时时间统一为Asia/Shanghai格式。
|
||||
- 门禁通过：API 45套528项，Gateway全包（含新增Outbox重试与无messageId上行用例），API正式构建，前端TypeScript检查和Vite生产构建。390×844 Chromium回归的直发、XLSX拦截、定时弹层和批次时间均通过，控制台错误/警告0。
|
||||
- 本轮没有部署、重启服务、发送短信或处理测试机1974条积压；没有访问或修改预生产/生产。因此当前是本地代码与自动化/渲染回归通过，测试机真实CMPP闭环需在后续部署授权后再验收。
|
||||
|
||||
## 2026-08-27 客户端展示、三网报备与人工审核状态优化（本地门禁）
|
||||
|
||||
- 完成用户明确的10项页面优化，并按`batch-task-manual-review-status-optimization-20260827.md`第一阶段实现人工审核状态修复；第二阶段孤立审核任务事务/补偿不在本提交范围。
|
||||
- 客户端签名接口按运营端同一应用路由、通道运营商范围和报备任务计算三网汇总，只输出汇总，不暴露通道或报备任务明细。
|
||||
- 人工审核状态改用共享前端映射；未知状态不再默认“发送中”。客户端仅`scheduled`可取消，运营审核列表返回并展示关联批量任务号。
|
||||
- 本地前端TypeScript、API TypeScript正式构建和Vite生产构建通过；短信配置、风控审核、发送链3套214项API测试通过。客户端登录页真实渲染确认“返回官网”存在。
|
||||
- 测试环境发布、数据库/API/页面/队列验收尚待本轮后续完成；预生产未访问。
|
||||
|
||||
Reference in New Issue
Block a user