mi-assessment/docs/报告状态拆分需求文档.md

报告状态拆分需求文档

一、背景

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

状态值	含义
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, "数据已就绪" } 2. RegenerateReportAsync：状态检查增加 6（允许 3、4、5、6 重新生成） 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" /> 2. "报告"按钮：v-if 从 row.status === 4 改为 row.status === 6 || row.status === 4 3. "网页报告"按钮：v-if 从 row.status === 4 改为 row.status === 6 || row.status === 4 4. "查看PDF"按钮：保持 v-if="row.reportUrl" 不变（状态 6 时 reportUrl 为空，自然不显示） 5. "下载PDF"按钮：保持 v-if="row.reportUrl" 不变 6. "重新生成"按钮：v-if 增加 row.status === 6 7. getStatusTagType 函数：新增 case 6: return 'primary' 8. 批量重新生成 eligibleRows 过滤：增加状态 6

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

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

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

四、详细修改说明

4.1 ReportGenerationService.PersistResultsAsync

当前代码（状态保持 3）：

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

修改为（状态改为 6）：

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

4.2 ReportDataService.GetReportDataAsync

当前代码：

if (record.Status != 3 && record.Status != 4)

修改为：

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 失败后还应该能看网页报告，我可以调整方案。