# 批量发送任务人工审核状态优化方案

## 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. 单独设计并实施事务或失败补偿机制。

第一阶段应作为独立提交，避免将低风险展示修复与高影响流程事务改造混在同一个提交中。