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

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

建议修复：

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

3.2 审核退回流程不完整

问题描述：

• 当前实现：仅记录 audit_opinion 文本字段
• 需求要求：结构化记录退回原因、驳回时间、驳回人

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

建议修复：

-- 增加字段
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 模板缺少"复制"功能

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

业务场景：

• 管理员需要基于现有模板创建新版模板
• 不同监区需要基于标准模板创建本地化版本

建议实现：

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

4.2 维度缺少"复制"功能

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

业务场景：

• 类似维度需要微调配置
• 跨模板复用维度配置

建议实现：

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

4.3 缺少批量生成报告功能

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

业务场景：

• 月末批量生成在押犯评估报告
• 入监队批量生成新入监罪犯评估报告

建议实现：

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

4.4 缺少归档管理功能

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

建议实现：

@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 缺少版本对比和回滚功能

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

建议实现：

// 版本对比
@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格式导出

建议实现：

@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小时过期）

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

建议实现：

@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服务

建议实现：

@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