调整项目人数按流水证件号统计

docs/reports/implementation/2026-06-02-project-target-count-cret-no-only.md

@@ -0,0 +1,79 @@
+# 项目人数按流水 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};
+```