ccdi/docs/plans/backend/2026-03-20-results-overview-risk-model-linkage-backend-implementation.md

# Results Overview Risk Model Linkage 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:** 为结果总览模型区新增真实后端接口，支持模型卡片统计、人员分页查询，以及多卡片下“任意触发 / 同时触发”两种筛选方式。

**Architecture:** 继续沿用 `CcdiProjectOverviewController + Service + Mapper` 的结果总览链路，复用现有“员工本人 + 亲属归并到员工名下”的基础聚合 SQL，不新建平行模块或补丁式接口。模型卡片统计与人员列表查询都建立在同一套员工归并口径上，保证模型区与风险人员区统计一致。

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

---

### Task 1: 定义接口、DTO 与 VO 结构

**Files:**
- Modify: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/controller/CcdiProjectOverviewController.java`
- Modify: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/ICcdiProjectOverviewService.java`
- Create: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/dto/CcdiProjectRiskModelPeopleQueryDTO.java`
- Create: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/vo/CcdiProjectRiskModelCardVO.java`
- Create: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/vo/CcdiProjectRiskModelCardsVO.java`
- Create: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/vo/CcdiProjectRiskModelPeopleItemVO.java`
- Create: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/vo/CcdiProjectRiskModelPeopleVO.java`
- Create: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/vo/CcdiProjectRiskHitTagVO.java`
- Test: `ccdi-project/src/test/java/com/ruoyi/ccdi/project/controller/CcdiProjectOverviewControllerContractTest.java`

- [x] **Step 1: Write the failing test**

为控制器契约补静态/反射测试，锁定以下方法和路径：

- `GET /ccdi/project/overview/risk-models/cards`
- `GET /ccdi/project/overview/risk-models/people`

并锁定 DTO 字段：

- `projectId`
- `modelCodes`
- `matchMode`
- `keyword`
- `deptId`
- `pageNum`
- `pageSize`

- [x] **Step 2: Run test to verify it fails**

Run:

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

Expected:

- `FAIL`
- 原因是接口与类型尚未创建

- [x] **Step 3: Write minimal implementation**

补齐控制器、服务接口、DTO 与 VO。

DTO 关键约束：

- `modelCodes` 为多值条件
- `matchMode` 只允许 `ANY` 或 `ALL`
- `modelCodes` 为空时忽略 `matchMode`

VO 关键字段：

- 卡片：`modelCode`、`modelName`、`warningCount`、`peopleCount`
- 列表：`staffName`、`staffCode`、`idNo`、`department`、`modelNames`、`hitTagList`、`actionLabel`
- 标签：`ruleCode`、`ruleName`、`riskLevel`

- [x] **Step 4: Run test to verify it passes**

Run:

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

Expected:

- `PASS`

- [x] **Step 5: Commit**

```bash
git add ccdi-project/src/main/java/com/ruoyi/ccdi/project/controller/CcdiProjectOverviewController.java ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/ICcdiProjectOverviewService.java ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/dto/CcdiProjectRiskModelPeopleQueryDTO.java ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/vo/CcdiProjectRiskModelCardVO.java ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/vo/CcdiProjectRiskModelCardsVO.java ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/vo/CcdiProjectRiskModelPeopleItemVO.java ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/vo/CcdiProjectRiskModelPeopleVO.java ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/vo/CcdiProjectRiskHitTagVO.java ccdi-project/src/test/java/com/ruoyi/ccdi/project/controller/CcdiProjectOverviewControllerContractTest.java
git commit -m "定义结果总览模型区接口结构"
```

### Task 2: 扩展模型卡片统计 SQL

**Files:**
- Modify: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/mapper/CcdiProjectOverviewMapper.java`
- Modify: `ccdi-project/src/main/resources/mapper/ccdi/project/CcdiProjectOverviewMapper.xml`
- Test: `ccdi-project/src/test/java/com/ruoyi/ccdi/project/mapper/CcdiProjectOverviewMapperRiskModelCardsTest.java`

- [x] **Step 1: Write the failing test**

为模型卡片统计新增 mapper 测试，锁定以下口径：

- `warningCount` = 当前项目、当前模型的命中结果数
- `peopleCount` = 当前模型归并后的员工人数
- 排序按 `warningCount desc, model_code asc`

- [x] **Step 2: Run test to verify it fails**

Run:

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

Expected:

- `FAIL`

- [x] **Step 3: Write minimal implementation**

在 `CcdiProjectOverviewMapper.xml` 中：

- 复用 `resolvedEmployeeRiskBaseSql`
- 新增模型卡片查询
- 预警次数直接以标签命中记录计数
- 涉及人数按 `staff_id_card` 去重

不要新增新表、不要引入额外统计口径。

- [x] **Step 4: Run test to verify it passes**

Run:

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

Expected:

- `PASS`

- [x] **Step 5: Commit**

```bash
git add ccdi-project/src/main/java/com/ruoyi/ccdi/project/mapper/CcdiProjectOverviewMapper.java ccdi-project/src/main/resources/mapper/ccdi/project/CcdiProjectOverviewMapper.xml ccdi-project/src/test/java/com/ruoyi/ccdi/project/mapper/CcdiProjectOverviewMapperRiskModelCardsTest.java
git commit -m "补充结果总览模型卡片统计查询"
```

### Task 3: 实现人员分页查询与匹配模式

**Files:**
- Modify: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/mapper/CcdiProjectOverviewMapper.java`
- Modify: `ccdi-project/src/main/resources/mapper/ccdi/project/CcdiProjectOverviewMapper.xml`
- Test: `ccdi-project/src/test/java/com/ruoyi/ccdi/project/mapper/CcdiProjectOverviewMapperRiskModelPeopleTest.java`

- [x] **Step 1: Write the failing test**

新增列表查询测试，覆盖：

- 不选模型时返回全部模型命中人员
- 多模型 `ANY` 时按并集返回
- 多模型 `ALL` 时按交集返回
- `keyword` 同时匹配姓名与工号
- `deptId` 精确筛选
- `hitTagList` 和 `modelNames` 只返回当前筛选上下文内的数据

- [x] **Step 2: Run test to verify it fails**

Run:

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

Expected:

- `FAIL`

- [x] **Step 3: Write minimal implementation**

列表查询要求：

- 补齐员工工号字段映射；如果员工表实际字段不是 `staff_code`，按真实字段落地
- `ANY`：命中任一所选模型即可
- `ALL`：员工命中的所选模型去重数必须等于所选模型数
- `modelNames` 只拼接当前所选模型范围内的模型名称
- `hitTagList` 只返回当前所选模型范围内的标签
- 标签排序按风险等级、规则编码稳定输出

- [x] **Step 4: Run test to verify it passes**

Run:

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

Expected:

- `PASS`

- [x] **Step 5: Commit**

```bash
git add ccdi-project/src/main/java/com/ruoyi/ccdi/project/mapper/CcdiProjectOverviewMapper.java ccdi-project/src/main/resources/mapper/ccdi/project/CcdiProjectOverviewMapper.xml ccdi-project/src/test/java/com/ruoyi/ccdi/project/mapper/CcdiProjectOverviewMapperRiskModelPeopleTest.java
git commit -m "补充结果总览模型区人员分页查询"
```

### Task 4: 完成服务组装与控制器返回

**Files:**
- Modify: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiProjectOverviewServiceImpl.java`
- Test: `ccdi-project/src/test/java/com/ruoyi/ccdi/project/service/impl/CcdiProjectOverviewServiceImplTest.java`

- [x] **Step 1: Write the failing test**

在服务测试中补充：

- 项目不存在时抛出统一异常
- 卡片接口返回 `cardList`
- 人员接口返回 `rows + total`
- 空列表返回空数组，不返回 `null`
- `actionLabel` 固定为“查看详情”

- [x] **Step 2: Run test to verify it fails**

Run:

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

Expected:

- `FAIL`

- [x] **Step 3: Write minimal implementation**

在服务层：

- 统一做项目存在性校验
- 卡片接口直接封装 `cardList`
- 人员接口封装 `rows` 和 `total`
- `matchMode` 默认值为 `ANY`

- [x] **Step 4: Run test to verify it passes**

Run:

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

Expected:

- `PASS`

- [x] **Step 5: Commit**

```bash
git add ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiProjectOverviewServiceImpl.java ccdi-project/src/test/java/com/ruoyi/ccdi/project/service/impl/CcdiProjectOverviewServiceImplTest.java
git commit -m "完成结果总览模型区服务组装"
```

### Task 5: 后端回归验证与实施记录

**Files:**
- Modify: `docs/plans/backend/2026-03-20-results-overview-risk-model-linkage-backend-implementation.md`
- Create: `docs/tests/records/2026-03-20-results-overview-risk-model-linkage-backend-verification.md`
- Create: `docs/reports/implementation/2026-03-20-results-overview-risk-model-linkage-backend-implementation.md`

- [x] **Step 1: Run backend verification**

Run:

```bash
mvn test -pl ccdi-project -Dtest=CcdiProjectOverview*
```

Expected:

- `PASS`

- [x] **Step 2: Write verification and implementation records**

记录：

- 模型卡片接口
- 人员分页接口
- `ANY / ALL` 两种匹配方式
- 验证命令与结论

- [x] **Step 3: Commit**

```bash
git add docs/plans/backend/2026-03-20-results-overview-risk-model-linkage-backend-implementation.md docs/tests/records/2026-03-20-results-overview-risk-model-linkage-backend-verification.md docs/reports/implementation/2026-03-20-results-overview-risk-model-linkage-backend-implementation.md
git commit -m "补充结果总览模型区后端实施记录"
```