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

# 结果总览模型区联动筛选后端实施记录

## 本次改动

- 在 [`CcdiProjectOverviewController.java`](/Users/wkc/Desktop/ccdi/ccdi/ccdi-project/src/main/java/com/ruoyi/ccdi/project/controller/CcdiProjectOverviewController.java) 新增 `GET /ccdi/project/overview/risk-models/cards` 与 `GET /ccdi/project/overview/risk-models/people` 两个接口。
- 在 [`ICcdiProjectOverviewService.java`](/Users/wkc/Desktop/ccdi/ccdi/ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/ICcdiProjectOverviewService.java) 与 [`CcdiProjectOverviewServiceImpl.java`](/Users/wkc/Desktop/ccdi/ccdi/ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiProjectOverviewServiceImpl.java) 补齐模型卡片与模型人员分页服务。
- 新增 [`CcdiProjectRiskModelPeopleQueryDTO.java`](/Users/wkc/Desktop/ccdi/ccdi/ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/dto/CcdiProjectRiskModelPeopleQueryDTO.java) 及一组风险模型区 VO，用于承载卡片、分页行和命中标签结构。
- 在 [`CcdiProjectOverviewMapper.java`](/Users/wkc/Desktop/ccdi/ccdi/ccdi-project/src/main/java/com/ruoyi/ccdi/project/mapper/CcdiProjectOverviewMapper.java) 与 [`CcdiProjectOverviewMapper.xml`](/Users/wkc/Desktop/ccdi/ccdi/ccdi-project/src/main/resources/mapper/ccdi/project/CcdiProjectOverviewMapper.xml) 新增模型卡片统计与模型人员分页 SQL。
- 新增或扩展 [`CcdiProjectOverviewControllerContractTest.java`](/Users/wkc/Desktop/ccdi/ccdi/ccdi-project/src/test/java/com/ruoyi/ccdi/project/controller/CcdiProjectOverviewControllerContractTest.java)、[`CcdiProjectOverviewMapperRiskModelCardsTest.java`](/Users/wkc/Desktop/ccdi/ccdi/ccdi-project/src/test/java/com/ruoyi/ccdi/project/mapper/CcdiProjectOverviewMapperRiskModelCardsTest.java)、[`CcdiProjectOverviewMapperRiskModelPeopleTest.java`](/Users/wkc/Desktop/ccdi/ccdi/ccdi-project/src/test/java/com/ruoyi/ccdi/project/mapper/CcdiProjectOverviewMapperRiskModelPeopleTest.java)、[`CcdiProjectOverviewServiceImplTest.java`](/Users/wkc/Desktop/ccdi/ccdi/ccdi-project/src/test/java/com/ruoyi/ccdi/project/service/impl/CcdiProjectOverviewServiceImplTest.java) 以覆盖契约、SQL 和服务封装。
- 根据 2026-03-20 线上分页异常，在 [`CcdiProjectOverviewMapper.xml`](/Users/wkc/Desktop/ccdi/ccdi/ccdi-project/src/main/resources/mapper/ccdi/project/CcdiProjectOverviewMapper.xml) 的 `selectRiskModelPeoplePage` 增加 `<bind name="projectId" value="query.projectId"/>`，并在 [`CcdiProjectOverviewMapperRiskModelPeopleTest.java`](/Users/wkc/Desktop/ccdi/ccdi/ccdi-project/src/test/java/com/ruoyi/ccdi/project/mapper/CcdiProjectOverviewMapperRiskModelPeopleTest.java) 补充对应断言，防止再次出现参数绑定异常。
- 根据 2026-03-20 线上 MySQL 3065 异常，将 [`CcdiProjectOverviewMapper.xml`](/Users/wkc/Desktop/ccdi/ccdi/ccdi-project/src/main/resources/mapper/ccdi/project/CcdiProjectOverviewMapper.xml) 中 `selectRiskModelNamesByScope` 从 `select distinct` 调整为 `group by scoped.model_code, scoped.model_name`，并在 [`CcdiProjectOverviewMapperRiskModelPeopleTest.java`](/Users/wkc/Desktop/ccdi/ccdi/ccdi-project/src/test/java/com/ruoyi/ccdi/project/mapper/CcdiProjectOverviewMapperRiskModelPeopleTest.java) 补充兼容性断言。

## 处理说明

- 继续复用现有 `CcdiProjectOverviewController + Service + Mapper` 结果总览链路，没有新增平行模块或补丁式接口。
- 模型卡片统计与人员分页统一建立在“员工本人 + 亲属归并到员工名下”的基础归并 SQL 上，确保与既有风险人员口径一致。
- 人员分页中的员工工号使用 `ccdi_base_staff.staff_id` 作为真实字段来源，并在 SQL 中转换为字符后映射到 `staffCode`。
- `ANY` 模式通过模型范围过滤直接返回并集结果；`ALL` 模式通过 `having count(distinct base.model_code) = #{query.modelCodes.size}` 约束交集结果。
- `modelNames` 与 `hitTagList` 使用同上下文子查询回填，只返回当前筛选模型范围内的数据。
- 风险模型人员分页复用公共归并 SQL 时，必须先把 `query.projectId` 绑定到顶层 `projectId`，否则 `resolvedEmployeeRiskBaseSql` 中的 `#{projectId}` 会在 MyBatis 分页查询阶段直接报绑定异常。
- 风险模型名称子查询需要按 `model_code` 保序返回，但不能使用 `distinct + order by 非 select 列` 组合；这里改为 `group by scoped.model_code, scoped.model_name` 后再排序，以兼容当前 MySQL 配置。
- 服务层对 `matchMode` 缺省值统一收口为 `ANY`，并确保空列表返回空数组、分页行统一附加“查看详情”。

## 验证情况

- 已执行如下定向验证：

```bash
mvn test -pl ccdi-project -Dtest=CcdiProjectOverviewControllerContractTest
mvn test -pl ccdi-project -Dtest=CcdiProjectOverviewMapperRiskModelCardsTest
mvn test -pl ccdi-project -Dtest=CcdiProjectOverviewMapperRiskModelPeopleTest
mvn test -pl ccdi-project -Dtest=CcdiProjectOverviewServiceImplTest
```

- 已执行结果总览相关总体验证：

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

- 总体验证结果：22 个测试全部通过，0 failure，0 error。