# 项目人数按流水 cret_no 统计实施记录

## 背景

- 生产反馈：同一项目上传一个人的流水后，结果总览卡片仍显示两个人。
- 业务确认：项目里的人数只按照流水中的 `cret_no` 计算。
- 本次只调整 `ccdi_project.target_count` 的统计口径，不调整风险人员、风险模型命中人员的归属与展示逻辑。

## 修改内容

1. 调整运行时统计 SQL：
   - 文件：`ccdi-project/src/main/resources/mapper/ccdi/project/CcdiBankStatementMapper.xml`
   - 方法：`countMatchedStaffCountByProjectId`
   - 新口径：仅统计 `ccdi_bank_statement.cret_no` 直接匹配 `ccdi_base_staff.id_card` 后的去重人数。
   - 移除口径：不再纳入家属关系归属员工，不再纳入本方账号账户库归属员工。

2. 新增生产回填脚本：
   - 文件：`sql/migration/2026-06-02-fix-project-target-count-cret-no-only.sql`
   - 作用：按新口径回写既有项目的 `ccdi_project.target_count`。

3. 补充测试约束：
   - `CcdiBankStatementMapperXmlTest.targetCount_shouldOnlyUseStatementCretNoMatchedStaff`

## 影响范围

- 结果总览顶部“总人数”卡片。
- 项目列表中的目标人数。
- 上传成功、删除上传记录、历史导入、标签重算后写回的 `target_count`。
- 生产既有项目需要执行新增迁移脚本，否则已存在的 `target_count` 不会自动立即回写。

## 不变范围

- 风险人员列表仍按打标结果归属员工展示。
- 风险模型卡片 `peopleCount` 仍来自 `ccdi_project_overview_employee_result`。
- 涉疑交易、负面征信、异常账户等结果总览子模块不在本次修改范围。

## 验证情况

- 已尝试运行：
  - `mvn -pl ccdi-project -Dtest=CcdiBankStatementMapperXmlTest#targetCount_shouldOnlyUseStatementCretNoMatchedStaff test`
- 结果：测试编译阶段被既有无关错误阻断，目标测试未执行到断言。
- 阻断点包括：
  - `CcdiBankStatementTest` 引用的 `BankStatementItem#setCustomerCertNo`、`setCustomerSocialCreditCode` 不存在。
  - `CcdiFileUploadServiceImplTest` 中多处仍按旧的 `LsfxAnalysisClient.uploadFile(Integer, Object, String)` 签名编写。
- 已通过静态校验确认：
  - 运行时 `countMatchedStaffCountByProjectId` 只统计 `ccdi_bank_statement.cret_no`。
  - 新增生产回填脚本不包含 `ccdi_staff_fmy_relation`、`ccdi_account_info`、`LE_ACCOUNT_NO`。
- 已通过源码编译：
  - `mvn -pl ccdi-project -DskipTests compile`

## 生产执行提醒

- 执行包含中文注释的 SQL 脚本时，按项目规则使用：

```bash
bin/mysql_utf8_exec.sh sql/migration/2026-06-02-fix-project-target-count-cret-no-only.sql
```

- 执行后可用以下 SQL 核对单个项目：

```sql
SELECT
  project.project_id,
  project.target_count,
  stats.target_count AS expected_target_count
FROM ccdi_project project
LEFT JOIN (
  SELECT
    bs.project_id,
    COUNT(DISTINCT TRIM(bs.cret_no)) AS target_count
  FROM ccdi_bank_statement bs
  INNER JOIN ccdi_base_staff staff
    ON staff.id_card = TRIM(bs.cret_no)
  WHERE bs.cret_no IS NOT NULL
    AND TRIM(bs.cret_no) != ''
  GROUP BY bs.project_id
) stats ON stats.project_id = project.project_id
WHERE project.project_id = {projectId};
```