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:

```bash
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:

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

Expected:

- `PASS`

- [ ] **Step 5: Commit**

```bash
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:

```bash
mvn test -pl ccdi-project -Dtest=CcdiProjectOverviewServiceImplTest
```

Expected:

- `PASS`

- [ ] **Step 4: Review for boundary compliance**

人工检查以下边界：

- 未新增新接口
- 未删除 `getTopRiskPeople`
- 未修改风险等级分级口径
- 未修改 `CcdiProjectOverviewMapper.xml` 排序和聚合 SQL

- [ ] **Step 5: Commit**

```bash
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:

```bash
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**

```bash
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**

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

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

- [ ] **Step 3: Commit**

```bash
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 "补充风险人员总览收口后端实施记录"
```