# 报告状态拆分需求文档

## 一、背景

当前测评记录的状态定义如下：

| 状态值 | 含义 |
|--------|------|
| 1 | 待测评 |
| 2 | 测评中 |
| 3 | 生成中 |
| 4 | 已完成 |
| 5 | 生成失败 |

"生成中"（状态 3）实际包含了两个阶段：
1. **数据计算阶段**：根据答案计算得分、排名、星级、匹配结论，写入 `assessment_results` 和 `assessment_record_conclusions` 表
2. **PDF 生成阶段**：截图各报告网页 → 组装 PDF → 上传 COS

这两个阶段被合并在同一个状态 3 下，导致以下问题：

### 问题 1：截图服务截到空白页
PDF 生成阶段需要截图报告网页，但报告网页的数据接口（`ReportDataService`）检查状态必须为 4（已完成）才返回数据。此时状态还是 3，所以所有页面都返回"报告尚未生成完成"，截出来全是空白。

### 问题 2：网页报告不必等 PDF
数据计算完成后，网页报告所需的数据已经全部就绪，用户完全可以查看网页版报告。但因为状态还是 3，前端不显示"网页报告"按钮，用户必须等 PDF 生成完（状态变为 4）才能看到任何报告内容。

### 问题 3：职责不清晰
"数据是否就绪"和"PDF 是否生成"是两件独立的事，不应该用同一个状态来表示。

## 二、方案

新增状态值 6（数据已就绪），将原来的状态 3 拆分为两个阶段：

| 状态值 | 含义 | 说明 |
|--------|------|------|
| 1 | 待测评 | 不变 |
| 2 | 测评中 | 不变 |
| 3 | 生成中 | 数据计算阶段（得分、排名、星级、结论尚未完成） |
| **6** | **数据已就绪** | **数据计算完成，PDF 正在生成中** |
| 4 | 已完成 | PDF 生成完成，全部就绪 |
| 5 | 生成失败 | 不变（数据计算失败或 PDF 生成失败均为此状态） |

### 状态流转图

```
[1 待测评] → [2 测评中] → [3 生成中]
                                ↓
                          数据计算完成
                                ↓
                         [6 数据已就绪]
                                ↓
                          PDF 生成完成
                                ↓
                           [4 已完成]

失败路径：
  [3 生成中] → [5 生成失败]（数据计算失败，重试 3 次后）
  [6 数据已就绪] → [5 生成失败]（PDF 生成失败）
```

### 各状态下的功能可用性

| 功能 | 状态 3 | 状态 6 | 状态 4 | 状态 5 |
|------|--------|--------|--------|--------|
| 查看网页报告 | ❌ | ✅ | ✅ | ❌ |
| 查看 PDF | ❌ | ❌ | ✅（需有 reportUrl） | ❌ |
| 下载 PDF | ❌ | ❌ | ✅（需有 reportUrl） | ❌ |
| 重新生成 | ✅ | ✅ | ✅ | ✅ |
| 查看报告数据（后台） | ❌ | ✅ | ✅ | ❌ |

## 三、涉及修改的文件清单

### 3.1 后端 - 核心流程

| 文件 | 修改内容 |
|------|----------|
| `MiAssessment.Core/Services/ReportGenerationService.cs` | `PersistResultsAsync` 方法：数据写入完成后将状态从 3 改为 6 |
| `MiAssessment.Core/Services/ReportDataService.cs` | `GetReportDataAsync` 方法：状态检查从 `== 4` 改为 `== 6 \|\| == 4` |
| `MiAssessment.Core/Services/PdfGenerationService.cs` | `GeneratePdfAsync` 方法：PDF 生成失败时状态从 6 改为 5；已修复的静态图片路径问题保留 |
| `MiAssessment.Api/BackgroundServices/ReportQueueConsumer.cs` | `ProcessMessageAsync` 方法：PDF 生成失败时调用 `UpdateRecordStatusToFailedAsync` 不变，但此时记录状态是从 6 变为 5 |

### 3.2 后端 - 后台管理

| 文件 | 修改内容 |
|------|----------|
| `MiAssessment.Admin.Business/Services/AssessmentRecordService.cs` | 1. `StatusNames` 字典新增 `{ 6, "数据已就绪" }`<br>2. `RegenerateReportAsync`：状态检查增加 6（允许 3、4、5、6 重新生成）<br>3. `BatchRegenerateReportAsync`：同上 |
| `MiAssessment.Admin.Business/Services/AssessmentRecordService.cs` | `GetRecordReportAsync` 方法：状态检查从 `== 4` 改为 `== 6 \|\| == 4` |

### 3.3 前端 - 后台管理

| 文件 | 修改内容 |
|------|----------|
| `admin-web/src/views/business/assessment/record/index.vue` | 1. 搜索表单状态下拉：新增选项 `<el-option label="数据已就绪" :value="6" />`<br>2. "报告"按钮：`v-if` 从 `row.status === 4` 改为 `row.status === 6 \|\| row.status === 4`<br>3. "网页报告"按钮：`v-if` 从 `row.status === 4` 改为 `row.status === 6 \|\| row.status === 4`<br>4. "查看PDF"按钮：保持 `v-if="row.reportUrl"` 不变（状态 6 时 reportUrl 为空，自然不显示）<br>5. "下载PDF"按钮：保持 `v-if="row.reportUrl"` 不变<br>6. "重新生成"按钮：`v-if` 增加 `row.status === 6`<br>7. `getStatusTagType` 函数：新增 `case 6: return 'primary'`<br>8. 批量重新生成 `eligibleRows` 过滤：增加状态 6 |

### 3.4 前端 - 小程序（如已实现相关页面）

| 文件 | 修改内容 |
|------|----------|
| 测评结果状态轮询页 | 状态 6 时可跳转查看网页报告，不再需要等到状态 4 |
| 往期测评列表 | 状态 6 显示"报告已就绪"，允许查看网页报告 |

> 注：小程序前端如果尚未开发对应页面，此部分可后续处理。

## 四、详细修改说明

### 4.1 ReportGenerationService.PersistResultsAsync

当前代码（状态保持 3）：
```csharp
// 重新加载测评记录（带跟踪），保持 Status=3（生成中），等待 PDF 生成后再更新为4
var record = await _dbContext.AssessmentRecords
    .FirstAsync(r => r.Id == recordId);
record.UpdateTime = now;
```

修改为（状态改为 6）：
```csharp
// 数据计算完成，状态更新为 6（数据已就绪），等待 PDF 生成后再更新为 4
var record = await _dbContext.AssessmentRecords
    .FirstAsync(r => r.Id == recordId);
record.Status = 6;
record.UpdateTime = now;
```

### 4.2 ReportDataService.GetReportDataAsync

当前代码：
```csharp
if (record.Status != 3 && record.Status != 4)
```

修改为：
```csharp
if (record.Status != 6 && record.Status != 4)
```

说明：去掉状态 3 的放行（上一轮临时加的），改为只允许 6 和 4。状态 3 时数据还没算完，不应该渲染。

### 4.3 前端按钮逻辑汇总

```
报告按钮（后台抽屉）：  row.status === 6 || row.status === 4
网页报告按钮：          row.status === 6 || row.status === 4
查看 PDF 按钮：         row.reportUrl（不变，状态 6 时 reportUrl 为空）
下载 PDF 按钮：         row.reportUrl（不变）
重新生成按钮：          row.status === 3 || row.status === 4 || row.status === 5 || row.status === 6
```

## 五、数据库影响

### 5.1 无需修改表结构
`assessment_records.Status` 字段为 `int` 类型，直接使用新值 6 即可，无需 DDL 变更。

### 5.2 历史数据兼容
- 已有的状态 4 记录不受影响
- 已有的状态 3 记录（如果有卡在生成中的）不受影响，重新生成时会走新流程
- 已有的状态 5 记录不受影响

## 六、测试要点

| 场景 | 预期结果 |
|------|----------|
| 提交答案后触发报告生成 | 状态从 2 → 3 → 6 → 4 |
| 数据计算完成、PDF 未生成时 | 状态为 6，网页报告可查看，PDF 按钮不显示 |
| PDF 生成完成后 | 状态为 4，网页报告和 PDF 均可查看 |
| 数据计算失败（重试 3 次后） | 状态为 5 |
| PDF 生成失败 | 状态从 6 → 5，网页报告不可查看（因为状态变为 5） |
| 状态 6 时点击重新生成 | 状态从 6 → 3，重新走完整流程 |
| 状态 4 时点击重新生成 | 状态从 4 → 3，ReportUrl 清空，重新走完整流程 |
| 后台搜索状态筛选 | 下拉框包含"数据已就绪"选项，可正确筛选 |
| 批量重新生成 | 状态 3、4、5、6 的记录均可被选中 |

## 七、关于 PDF 生成失败的状态处理

当前方案：PDF 生成失败时状态从 6 改为 5（生成失败）。

这意味着用户在 PDF 生成失败后也无法查看网页报告了（因为状态 5 不允许）。

**备选方案**：PDF 生成失败时状态保持 6，只是 reportUrl 为空。这样用户至少还能看网页报告。但这样的话"生成失败"状态就只表示数据计算失败了。

**建议采用当前方案**（失败改为 5），理由：
- 状态 5 明确告诉管理员"这条记录有问题需要处理"
- 管理员可以点击"重新生成"重试
- 如果保持 6，管理员可能不知道 PDF 生成失败了

如果你觉得 PDF 失败后还应该能看网页报告，我可以调整方案。