xlcp/requirements/评估功能实现评估报告.md

# 评估功能前后端实现评估报告

> 评估日期：2026-01-18
> 评估范围：危险评估、计分考核、评估报告模块
> 评估目标：发现交互逻辑问题、功能设置问题，为产品专家评审提供依据

---

## 一、功能模块概览

### 1.1 已实现模块清单

| 模块名称 | 中文名称 | 后端路径 | 前端路径 | 完成度 |
|---------|---------|---------|---------|-------|
| RiskAssessment | 危险评估 | `controller/admin/riskassessment/` | `views/prison/riskassessment/` | 90% |
| Score | 计分考核 | `controller/admin/score/` | `views/prison/score/` | 85% |
| ScoreRule | 考核规则配置 | `controller/admin/score/rule/` | 未实现 | 70% |
| ScoreDetail | 考核明细记录 | `controller/admin/score/detail/` | 未实现 | 70% |
| EvaluationReport | 评估报告 | `controller/admin/evaluationreport/` | `api/prison/evaluation/` | 75% |

### 1.2 评估报告模块表结构

| 表名 | 说明 | 状态 |
|-----|------|------|
| `prison_evaluation_template` | 评估报告模板表 | ✅ 已创建 |
| `prison_evaluation_dimension` | 评估维度配置表 | ✅ 已创建 |
| `prison_evaluation_report` | 评估报告表 | ✅ 已创建 |
| `prison_evaluation_dimension_data` | 报告维度数据表 | ✅ 已创建 |
| `prison_report_comment` | 快捷评语库表 | ✅ 已创建 |
| `prison_evaluation_report_version` | 报告版本历史表 | ✅ 已创建 |
| `prison_evaluation_ai_log` | AI生成日志表 | ✅ 已创建 |

---

## 二、需求实现对比分析

### 2.1 模板管理功能对比

| 需求功能 | 实现状态 | 问题说明 |
|---------|---------|---------|
| 新增模板 | ✅ 已实现 | |
| 编辑模板 | ✅ 已实现 | |
| 复制模板 | ❌ **未实现** | 需求文档3.1.3明确要求 |
| 启用/停用模板 | ✅ 已实现 | |
| 设为默认 | ❌ **未实现** | 需求文档3.1.3明确要求 |
| 版本管理 | ⚠️ 部分实现 | 仅存储，未实现版本对比 |
| 模板分类 | ✅ 已实现 | 支持4种类型 |

### 2.2 维度管理功能对比

| 需求功能 | 实现状态 | 问题说明 |
|---------|---------|---------|
| 新增维度 | ✅ 已实现 | |
| 编辑维度 | ✅ 已实现 | |
| 删除维度 | ✅ 已实现 | |
| 复制维度 | ❌ **未实现** | 需求文档3.1.4.1明确要求 |
| 拖拽排序 | ❌ **未实现** | 仅后端存储sort字段，前端未实现拖拽 |
| 启用/停用 | ✅ 已实现 | |
| AI提示词配置 | ✅ 已实现 | |
| 数据源绑定 | ✅ 已实现 | |

### 2.3 报告生成功能对比

| 需求功能 | 实现状态 | 问题说明 |
|---------|---------|---------|
| 手动创建报告 | ✅ 已实现 | |
| 批量生成报告 | ❌ **未实现** | 需求文档3.5.2明确要求 |
| 数据自动填充 | ✅ 已实现 | |
| AI生成初稿 | ✅ 已实现 | |
| 人工修改 | ✅ 已实现 | |
| 逐维度重新生成 | ✅ 已实现 | |
| 快捷评语 | ✅ 已实现 | |

### 2.4 报告审核功能对比

| 需求功能 | 实现状态 | 问题说明 |
|---------|---------|---------|
| 提交审核 | ✅ 已实现 | |
| 审核通过 | ✅ 已实现 | |
| 审核退回 | ⚠️ **不完整** | 缺少结构化退回原因记录 |
| 撤回报告 | ❌ **未实现** | 需求文档3.13.3明确要求 |
| 退回后重新提交 | ✅ 已实现 | |

### 2.5 报告导出功能对比

| 需求功能 | 实现状态 | 问题说明 |
|---------|---------|---------|
| 导出Excel | ✅ 已实现 | |
| 导出PDF | ❌ **未实现** | 需求文档3.9明确要求 |
| 导出Word | ❌ **未实现** | 需求文档3.9明确要求 |
| 批量导出 | ❌ **未实现** | 需求文档3.11.5明确要求 |
| 批量打包下载 | ❌ **未实现** | 需求文档3.9.2明确要求 |

### 2.6 归档管理功能对比

| 需求功能 | 实现状态 | 问题说明 |
|---------|---------|---------|
| 报告归档 | ❌ **未实现** | 需求文档3.10明确要求 |
| 归档查询 | ❌ **未实现** | |
| 归档后不可修改 | ❌ **未实现** | |

### 2.7 版本管理功能对比

| 需求功能 | 实现状态 | 问题说明 |
|---------|---------|---------|
| 版本记录 | ✅ 已实现 | 表结构已创建 |
| 版本查看 | ⚠️ 部分实现 | 仅存储，未实现查看功能 |
| 版本对比 | ❌ **未实现** | 需求文档3.8.2明确要求 |
| 版本回滚 | ❌ **未实现** | 需求文档3.8.2明确要求 |

---

## 三、交互逻辑问题清单

### 3.1 报告编号生成规则不一致

**问题描述**：
- 需求规范：`RPT-{监区编码}-{年月}-{4位序号}` 示例：`RPT-JQ01-202601-0001`
- 代码实现：`PGEV + yyyyMMdd + 6位序号` 示例：`PGEV20260118000001`

**影响**：报告编号不符合需求规范，无法直观识别监区信息

**建议修复**：
```java
// 建议改为：
// 1. 获取罪犯所属监区编码
// 2. 获取当前年月
// 3. 查询当月该监区的最大序号
// 4. 格式：RPT-{监区编码}-{年月}-{序号(4位)}
```

### 3.2 审核退回流程不完整

**问题描述**：
- 当前实现：仅记录 `audit_opinion` 文本字段
- 需求要求：结构化记录退回原因、驳回时间、驳回人

**影响**：退回原因无法有效传达给起草人，缺少退回时间追溯

**建议修复**：
```sql
-- 增加字段
ALTER TABLE prison_evaluation_report
ADD COLUMN return_reason VARCHAR(500) COMMENT '退回原因',
ADD COLUMN return_time DATETIME COMMENT '退回时间',
ADD COLUMN return_by BIGINT COMMENT '退回人ID';
```

### 3.3 缺少报告撤回功能

**问题描述**：
- 需求文档3.13.3明确要求：待审核状态可撤回为草稿
- 当前代码：没有撤回(Withdraw/Recall)相关接口

**影响**：提交审核后发现问题无法及时撤回修改

**建议新增接口**：
```
POST /prison/evaluation-report/report/withdraw
参数：reportId
前置条件：status = PENDING_AUDIT(2)
后置条件：status = DRAFT(1)
```

### 3.4 状态枚举定义不一致

**问题描述**：
- 需求文档：草稿(1)、待审核(2)、已通过(3)、已退回(4)、已归档(5)
- 代码实现：缺少"已归档"状态枚举

**影响**：归档功能无法正确实现状态流转

**建议修复**：在 `EvaluationReportStatusEnum` 中添加 `ARCHIVED(5, "已归档")`

### 3.5 维度类型定义不一致

**问题描述**：
- 数据库表：1-基本信息, 2-犯罪情况, 3-服刑表现...
- DO类定义：1-心理测评, 2-危险性评估, 3-改造表现...

**影响**：前后端数据交换可能出现类型映射错误

**建议修复**：统一枚举定义，确保DO类与数据库枚举值一致

---

## 四、功能设置问题清单

### 4.1 模板缺少"复制"功能

**问题描述**：需求要求支持复制模板快速创建，当前未实现

**业务场景**：
- 管理员需要基于现有模板创建新版模板
- 不同监区需要基于标准模板创建本地化版本

**建议实现**：
```java
@PostMapping("/template/copy")
public CommonResult<Long> copyTemplate(@RequestParam("templateId") Long templateId) {
    // 1. 查询原模板
    // 2. 复制模板基础信息（名称加"副本"后缀）
    // 3. 复制所有维度配置
    // 4. 返回新模板ID
}
```

### 4.2 维度缺少"复制"功能

**问题描述**：需求要求支持复制维度快速创建，当前未实现

**业务场景**：
- 类似维度需要微调配置
- 跨模板复用维度配置

**建议实现**：
```java
@PostMapping("/dimension/copy")
public CommonResult<Long> copyDimension(@RequestParam("dimensionId") Long dimensionId) {
    // 1. 查询原维度
    // 2. 复制维度配置（名称加"副本"后缀）
    // 3. 返回新维度ID
}
```

### 4.3 缺少批量生成报告功能

**问题描述**：需求要求支持选择多个罪犯+模板批量生成报告

**业务场景**：
- 月末批量生成在押犯评估报告
- 入监队批量生成新入监罪犯评估报告

**建议实现**：
```java
@PostMapping("/report/batch-generate")
public CommonResult<List<Long>> batchGenerate(
        @RequestBody BatchGenerateReqVO vo) {
    // vo包含：prisonerIds, templateId, evaluationDate
    // 使用异步队列处理，返回任务ID
}
```

### 4.4 缺少归档管理功能

**问题描述**：需求要求已审核报告可归档，归档后不可修改

**建议实现**：
```java
@PostMapping("/report/archive")
public CommonResult<Boolean> archive(@RequestParam("reportId") Long reportId);

@PostMapping("/report/unarchive")
public CommonResult<Boolean> unarchive(@RequestParam("reportId") Long reportId);

@PostMapping("/report/archive-list")
public CommonResult<Boolean> batchArchive(@RequestParam("reportIds") List<Long> reportIds);
```

### 4.5 缺少版本对比和回滚功能

**问题描述**：需求要求支持版本对比和回滚

**建议实现**：
```java
// 版本对比
@GetMapping("/report/version/compare")
public CommonResult<VersionCompareRespVO> compareVersions(
        @RequestParam("reportId") Long reportId,
        @RequestParam("version1") Integer version1,
        @RequestParam("version2") Integer version2);

// 版本回滚
@PostMapping("/report/version/rollback")
public CommonResult<Boolean> rollback(
        @RequestParam("reportId") Long reportId,
        @RequestParam("targetVersion") Integer targetVersion);
```

### 4.6 缺少PDF/Word导出功能

**问题描述**：需求要求支持PDF和Word格式导出

**建议实现**：
```java
@PostMapping("/report/export-pdf")
public void exportPdf(@RequestParam("reportId") Long reportId, HttpServletResponse response);

@PostMapping("/report/export-word")
public void exportWord(@RequestParam("reportId") Long reportId, HttpServletResponse response);

@PostMapping("/report/batch-export-zip")
public void batchExportZip(@RequestBody List<Long> reportIds, HttpServletResponse response);
```

---

## 五、性能与安全缺失项

### 5.1 缓存机制未实现

**需求要求**：
- 罪犯基础信息缓存（5分钟过期）
- 考核数据缓存（10分钟过期）
- 模板配置缓存（1小时过期）

**当前状态**：未实现任何缓存

**建议实现**：
```java
@Cacheable(value = "prisoner", key = "#prisonerId", ttl = 5 * 60)
public PrisonerDTO getPrisoner(Long prisonerId) { ... }

@Cacheable(value = "scoreData", key = "#prisonerId + ':' + #year", ttl = 10 * 60)
public ScoreDTO getScoreData(Long prisonerId, Integer year) { ... }
```

### 5.2 异步生成队列未实现

**需求要求**：
- 批量生成使用异步队列
- 支持队列状态查询
- 失败重试（最多3次）
- 生成完成通知

**当前状态**：同步调用LLM服务

**建议实现**：
```java
@Async("reportGenerateExecutor")
public CompletableFuture<ReportGenerateResult> generateReportAsync(GenerateTask task) {
    // 调用LLM生成报告
    // 失败时重试3次
    // 完成后发送系统通知
}
```

### 5.3 AI服务降级未实现

**需求要求**：AI服务不可用时有降级策略

**当前状态**：仅检查LLM是否可用，无降级机制

**建议实现**：
- 使用默认模板填充
- 标记维度为"待人工填写"
- 记录服务降级日志

---

## 六、前端交互问题

### 6.1 评估报告前端页面未完整实现

| 组件 | 状态 | 说明 |
|-----|------|------|
| 报告模板管理页 | ❌ 未实现 | 仅有API，无页面 |
| 维度配置管理页 | ❌ 未实现 | 仅有API，无页面 |
| 报告编辑页面 | ❌ 未实现 | 仅有API，无页面 |
| 报告列表页 | ❌ 未实现 | 仅有API，无页面 |

### 6.2 前后端联调问题

**问题**：前端API已定义，但后端Controller路径不一致

**示例**：
- 前端定义：`/prison/evaluation-report/template/page`
- 后端实际：`/prison/evaluation-report/template/page` ✅ 一致

**但缺少以下前端页面**：
- 模板列表/编辑页面
- 维度配置页面
- 报告编辑页面（左右分栏布局）
- 报告预览/打印页面
- 快捷评语管理页面

---

## 七、功能实现完成度汇总

| 功能模块 | 已实现 | 需完善 | 未实现 | 完成度 |
|---------|-------|-------|-------|-------|
| 模板管理 | 8项 | 1项 | 2项 | **75%** |
| 维度管理 | 5项 | 0项 | 2项 | **71%** |
| 报告创建 | 5项 | 1项 | 1项 | **79%** |
| 报告审核 | 3项 | 1项 | 1项 | **60%** |
| 报告导出 | 1项 | 0项 | 3项 | **25%** |
| 归档管理 | 0项 | 0项 | 3项 | **0%** |
| 版本管理 | 1项 | 1项 | 2项 | **33%** |
| AI生成 | 3项 | 2项 | 2项 | **50%** |
| 前端页面 | 0项 | 0项 | 5项 | **0%** |

**总体评估**：核心数据模型和API已实现，但前端页面缺失较多，高级功能（批量生成、归档、版本对比）未实现。

---

## 八、改进优先级建议

### P0 - 必须修复（影响核心流程）

1. **报告编号规则修复** - 符合需求规范
2. **审核退回流程完善** - 结构化记录退回原因
3. **添加报告撤回功能** - 支持待审核撤回
4. **状态枚举补全** - 添加已归档状态

### P1 - 应该实现（影响用户体验）

5. **模板复制功能**
6. **维度复制功能**
7. **批量生成报告功能**
8. **PDF/Word导出功能**
9. **归档管理功能**
10. **版本对比功能**

### P2 - 建议实现（提升体验）

11. **数据缓存机制**
12. **异步生成队列**
13. **AI服务降级**
14. **前端页面完整实现**
15. **维度拖拽排序前端**

---

## 九、待产品专家评审事项

### 9.1 业务流程问题

1. **批量生成场景确认**
   - 一次性最多生成多少个报告？
   - 是否需要显示生成进度？
   - 生成失败如何处理？

2. **审核退回流程确认**
   - 是否必须填写退回原因？
   - 退回原因是否需要分类？
   - 退回后是否需要通知起草人？

3. **归档策略确认**
   - 自动归档还是手动归档？
   - 归档后是否可导出？
   - 归档文件保留多长时间？

### 9.2 交互设计问题

1. **报告编辑页面布局**
   - 需求文档设计了左右分栏布局，是否认可？
   - 罪犯列表每页显示多少条？
   - 是否需要支持快捷键操作？

2. **版本对比界面**
   - 左右分屏对比是否足够？
   - 是否需要高亮显示差异？
   - 是否需要一键还原？

### 9.3 功能优先级确认

1. **第一阶段MVP功能范围**
   - 模板管理、维度配置
   - 报告创建、AI生成
   - 报告审核、Excel导出

2. **第二阶段功能范围**
   - 批量生成、PDF导出
   - 归档管理、版本对比

---

## 附录：关键文件清单

### 后端关键文件

| 文件路径 | 说明 |
|---------|------|
| `controller/admin/evaluationreport/EvaluationReportController.java` | 主控制器 |
| `service/evaluationreport/EvaluationReportService.java` | 服务接口 |
| `service/evaluationreport/impl/EvaluationReportServiceImpl.java` | 服务实现 |
| `dal/dataobject/evaluationreport/EvaluationReportDO.java` | 报告实体 |
| `dal/dataobject/evaluationreport/EvaluationDimensionDO.java` | 维度实体 |
| `enums/EvaluationReportStatusEnum.java` | 状态枚举 |

### 前端关键文件

| 文件路径 | 说明 |
|---------|------|
| `api/prison/evaluation/index.ts` | API定义 |
| `views/prison/riskassessment/index.vue` | 危险评估列表 |
| `views/prison/score/index.vue` | 计分考核列表 |

### 数据库脚本

| 文件路径 | 说明 |
|---------|------|
| `sql/evaluation_report.sql` | 评估报告表结构 |
| `sql/evaluation_report_dict_data.sql` | 字典数据 |

---

**报告生成时间**：2026-01-18
**评估人**：Claude Code
**版本**：v1.0