ccdi/docs/plans/backend/2026-03-20-results-overview-risk-people-merge-backend-implementation.md

Results Overview Risk People Merge Backend Implementation Plan

For agentic workers: REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 扩展结果总览风险人员总览接口返回风险等级和命中模型数字段，为页面移除独立 TOP10 区块提供单一后端数据源。

Architecture: 复用 ccdi-project 现有员工风险聚合 SQL 与风险等级映射逻辑，不新增接口、不新增统计口径、不删除独立 TOP10 接口。仅扩展风险人员总览 VO、服务映射与相关测试，使 GET /ccdi/project/overview/risk-people 直接返回 riskLevel、riskLevelType、modelCount。

Tech Stack: Java 21, Spring Boot 3, MyBatis XML, Maven, JUnit 5, Mockito

---

Task 1: 锁定风险人员总览新增字段的测试预期

Files:

• Modify: ccdi-project/src/test/java/com/ruoyi/ccdi/project/service/impl/CcdiProjectOverviewServiceImplTest.java

• Modify: ccdi-project/src/test/java/com/ruoyi/ccdi/project/controller/CcdiProjectOverviewControllerTest.java

• Step 1: Write the failing test

调整 CcdiProjectOverviewServiceImplTest，在 shouldMapRiskPeopleOverviewRows 中增加对 riskLevel、riskLevelType、modelCount 的断言；必要时在 CcdiProjectOverviewControllerTest 中补充风险人员总览响应结构断言，锁定返回 JSON 中包含这三个字段。

• Step 2: Run test to verify it fails

Run:

mvn test -pl ccdi-project -Dtest=CcdiProjectOverviewServiceImplTest,CcdiProjectOverviewControllerTest

Expected:

• FAIL

• 原因是当前风险人员总览项尚未暴露 riskLevel、riskLevelType、modelCount

• Step 3: Write minimal implementation

保持现有测试数据构造方式不变，只补最小断言：HIGH -> 高风险 / danger，MEDIUM -> 中风险 / warning，LOW -> 低风险 / info，以及 modelCount 直接透传。

• Step 4: Run test to verify it passes after implementation

Run:

mvn test -pl ccdi-project -Dtest=CcdiProjectOverviewServiceImplTest,CcdiProjectOverviewControllerTest

Expected:

• PASS

• Step 5: Commit

git add ccdi-project/src/test/java/com/ruoyi/ccdi/project/service/impl/CcdiProjectOverviewServiceImplTest.java ccdi-project/src/test/java/com/ruoyi/ccdi/project/controller/CcdiProjectOverviewControllerTest.java
git commit -m "补充风险人员总览接口字段测试"

Task 2: 扩展风险人员总览 VO 与服务映射

Files:

• Modify: ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/vo/CcdiProjectRiskPeopleOverviewItemVO.java

• Modify: ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiProjectOverviewServiceImpl.java

• Verify: ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/vo/CcdiProjectEmployeeRiskAggregateVO.java

• Step 1: Implement the VO fields

在 CcdiProjectRiskPeopleOverviewItemVO 中新增：

• private String riskLevel;
• private String riskLevelType;
• private Integer modelCount;

保持原有字段和 Lombok @Data 不变，不新增多余兼容字段。

• Step 2: Implement service mapping

在 buildRiskPeopleItem 中补充：

• riskLevel 由 aggregate.getRiskLevelCode() 经现有映射逻辑转换
• riskLevelType 由现有 resolveRiskLevelType 生成
• modelCount 直接读取 aggregate.getModelCount()

不要更改：

• riskCount 继续读取 hitCount

• riskPoint 继续读取聚合结果

• 风险人员总览排序逻辑

• getTopRiskPeople 行为

• Step 3: Run focused backend tests

Run:

mvn test -pl ccdi-project -Dtest=CcdiProjectOverviewServiceImplTest

Expected:

• PASS

• Step 4: Review for boundary compliance

人工检查以下边界：

• 未新增新接口

• 未删除 getTopRiskPeople

• 未修改风险等级分级口径

• 未修改 CcdiProjectOverviewMapper.xml 排序和聚合 SQL

• Step 5: Commit

git add ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/vo/CcdiProjectRiskPeopleOverviewItemVO.java ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiProjectOverviewServiceImpl.java
git commit -m "扩展风险人员总览接口返回字段"

Task 3: 回归验证 SQL 和接口边界未被破坏

Files:

• Verify: ccdi-project/src/test/java/com/ruoyi/ccdi/project/mapper/CcdiProjectOverviewMapperSqlTest.java

• Verify: ccdi-project/src/test/java/com/ruoyi/ccdi/project/service/CcdiProjectOverviewServiceStructureTest.java

• Verify: ccdi-project/src/main/resources/mapper/ccdi/project/CcdiProjectOverviewMapper.xml

• Step 1: Run SQL and structure regression tests

Run:

mvn test -pl ccdi-project -Dtest=CcdiProjectOverviewMapperSqlTest,CcdiProjectOverviewServiceStructureTest

Expected:

• PASS

• 证明员工聚合 SQL、Mapper 结构与服务接口边界仍然稳定

• Step 2: Perform manual API contract review

检查风险人员总览接口对应的 Controller、Service、VO，确认本轮只增加返回字段，不引入新路径、不更改请求参数。

• Step 3: Commit

git add ccdi-project/src/test/java/com/ruoyi/ccdi/project/mapper/CcdiProjectOverviewMapperSqlTest.java ccdi-project/src/test/java/com/ruoyi/ccdi/project/service/CcdiProjectOverviewServiceStructureTest.java ccdi-project/src/main/resources/mapper/ccdi/project/CcdiProjectOverviewMapper.xml
git commit -m "回归校验结果总览后端接口边界"

Task 4: 补充后端实施与验证文档

Files:

• Create: docs/reports/implementation/2026-03-20-results-overview-risk-people-merge-backend-implementation.md

• Create: docs/tests/records/2026-03-20-results-overview-risk-people-merge-backend-verification.md

• Verify: docs/design/2026-03-20-results-overview-risk-people-merge-design.md

• Step 1: Write implementation record

记录本次后端改动内容：

• 扩展风险人员总览接口字段

• 复用现有风险等级映射

• 明确未删除后端 TOP10 接口

• Step 2: Write verification record

记录执行过的命令、日期、结果和验证结论，至少包含：

mvn test -pl ccdi-project -Dtest=CcdiProjectOverviewServiceImplTest,CcdiProjectOverviewControllerTest
mvn test -pl ccdi-project -Dtest=CcdiProjectOverviewMapperSqlTest,CcdiProjectOverviewServiceStructureTest

• Step 3: Commit

git add docs/reports/implementation/2026-03-20-results-overview-risk-people-merge-backend-implementation.md docs/tests/records/2026-03-20-results-overview-risk-people-merge-backend-verification.md
git commit -m "补充风险人员总览收口后端实施记录"