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) 补充兼容性断言。
- 根据 2026-03-20 线上 `matchMode=ALL` 的 `UnsupportedOperationException`，在 [`CcdiProjectRiskModelPeopleQueryDTO.java`](/Users/wkc/Desktop/ccdi/ccdi/ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/dto/CcdiProjectRiskModelPeopleQueryDTO.java) 新增显式只读字段 `modelCodesCount`，并将 [`CcdiProjectOverviewMapper.xml`](/Users/wkc/Desktop/ccdi/ccdi/ccdi-project/src/main/resources/mapper/ccdi/project/CcdiProjectOverviewMapper.xml) 中 `having count(distinct base.model_code) = #{query.modelCodes.size}` 改为 `#{query.modelCodesCount}`，同时更新 [`CcdiProjectOverviewMapperRiskModelPeopleTest.java`](/Users/wkc/Desktop/ccdi/ccdi/ccdi-project/src/test/java/com/ruoyi/ccdi/project/mapper/CcdiProjectOverviewMapperRiskModelPeopleTest.java) 回归断言。
- 根据“模型触发次数为 0 也要展示卡片”的新要求，将 [`CcdiProjectOverviewMapper.xml`](/Users/wkc/Desktop/ccdi/ccdi/ccdi-project/src/main/resources/mapper/ccdi/project/CcdiProjectOverviewMapper.xml) 中 `selectRiskModelCardsByProjectId` 从命中结果直聚合改为以 `ccdi_bank_tag_rule` 启用模型为主表、左连项目命中聚合，并更新 [`CcdiProjectOverviewMapperRiskModelCardsTest.java`](/Users/wkc/Desktop/ccdi/ccdi/ccdi-project/src/test/java/com/ruoyi/ccdi/project/mapper/CcdiProjectOverviewMapperRiskModelCardsTest.java) 回归断言。

## 处理说明

- 继续复用现有 `CcdiProjectOverviewController + Service + Mapper` 结果总览链路，没有新增平行模块或补丁式接口。
- 模型卡片展示口径以 `ccdi_bank_tag_rule` 中启用的全量模型定义为准，不再只返回已命中的模型；卡片命中统计与人员分页仍统一建立在“员工本人 + 亲属归并到员工名下”的基础归并 SQL 上，确保与既有风险人员口径一致。
- 人员分页中的员工工号使用 `ccdi_base_staff.staff_id` 作为真实字段来源，并在 SQL 中转换为字符后映射到 `staffCode`。
- `ANY` 模式通过模型范围过滤直接返回并集结果；`ALL` 模式通过 `having count(distinct base.model_code) = #{query.modelCodesCount}` 约束交集结果，避免在 MyBatis 参数绑定阶段直接读取集合包装器属性。
- `modelNames` 与 `hitTagList` 使用同上下文子查询回填，只返回当前筛选模型范围内的数据。
- 风险模型人员分页复用公共归并 SQL 时，必须先把 `query.projectId` 绑定到顶层 `projectId`，否则 `resolvedEmployeeRiskBaseSql` 中的 `#{projectId}` 会在 MyBatis 分页查询阶段直接报绑定异常。
- 风险模型名称子查询需要按 `model_code` 保序返回，但不能使用 `distinct + order by 非 select 列` 组合；这里改为 `group by scoped.model_code, scoped.model_name` 后再排序，以兼容当前 MySQL 配置。
- 风险模型卡片查询改为从 `ccdi_bank_tag_rule` 先聚合出启用模型，再左连项目命中统计，`warningCount/peopleCount` 统一通过 `coalesce(..., 0)` 回填，确保 0 次模型卡片也能展示。
- 服务层对 `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*'
```

- 已执行重新打包与真实接口回归：

```bash
mvn -pl ruoyi-admin -am package -DskipTests
java -jar ruoyi-admin/target/ruoyi-admin.jar --server.port=62319
```

- 真实接口回归覆盖 `/risk-models/cards`、人员默认分页、单模型 `ANY`、单模型 `ALL`，项目 `42` 的实际返回均为 `code=200`，其中卡片接口返回 `10` 张模型卡片，仅 `1` 张存在真实命中，其余 `9` 张为 `warningCount=0`、`peopleCount=0`。
- 总体验证结果：22 个测试全部通过，0 failure，0 error；临时启动的 `62319` 实例已在验证完成后关闭。