# 2026-06-30 单提交生产发布功能清单

## 1. 发布范围

本清单说明本地分支 `dev-ui` 相对远程 `origin/dev-ui` 的单提交发布内容。

本次生产发布建议以当前本地 `HEAD` 单提交 `完善外部人员预警与项目分析上线内容` 为准，准确提交号以 `git log -1 --oneline` 输出为准。

对比基线：

- 远程基线：`origin/dev-ui`，当前提交为 `4e90e22e 优化项目详情资金流向图谱展示`。
- 本地提交：当前本地 `HEAD`，提交说明为 `完善外部人员预警与项目分析上线内容`。
- 提交数量：1 个。
- 文件范围：76 个文件，覆盖后端、前端、SQL、测试与实施文档。

## 2. 本次提交改了哪些内容

### 2.1 后端接口与领域对象

改动范围：

- 修改 `CcdiProjectOverviewController`，新增外部人员预警、外部风险模型卡片、外部模型命中人员和导出入口。
- 新增外部人员查询 DTO、外部风险模型命中人员 DTO。
- 新增外部人员预警列表 VO、汇总 VO、外部风险汇总 VO。
- 新增外部人员预警导出对象、风险模型命中人员导出对象。
- 调整涉疑交易明细导出对象，补齐流水基础字段和关联员工字段。

实现结果：

- 结果总览具备外部人员预警接口能力。
- 外部人员模型命中人员可以分页查询和导出。
- 风险明细导出的“涉疑交易明细”更接近流水明细查询导出格式。

### 2.2 后端 SQL 与服务逻辑

改动范围：

- 修改 `CcdiProjectOverviewMapper.xml`，新增外部人员识别、汇总、列表、外部模型、外部模型命中人员 SQL。
- 修改 `CcdiBankTagAnalysisMapper.xml`，新增外部人员规则打标 SQL。
- 修改 `CcdiBankStatementMapper.xml`，支持按本方证件号查询流水。
- 修改 `CcdiProjectSpecialCheckMapper.xml`，调整专项分析员工范围。
- 修改 `BankTagRuleConfigResolver`、`CcdiBankTagServiceImpl`，接入外部人员规则参数和执行分发。
- 修改 `CcdiProjectOverviewServiceImpl`，组装外部人员预警、风险模型、详情导出、PDF 数据。
- 修改 `CcdiProjectRiskDetailWorkbookExporter` 和 `CcdiProjectOverviewReportPdfExporter`。

实现结果：

- 外部人员以流水本方证件号 `bs.cret_no` 识别。
- 外部主体必须证件号非空，且不是员工、不是员工亲属。
- 外部主体再匹配中介库、信贷客户库，区分“中介 / 客户 / 外部人员”。
- 外部人员对象级命中和流水级命中都能进入结果总览。
- 专项分析员工范围改为项目流水覆盖员工，而不是只看打标命中员工。

### 2.3 前端页面与交互

改动范围：

- 新增 `ExternalPersonDetailDialog.vue`。
- 修改结果总览入口 `PreliminaryCheck.vue`。
- 修改风险人员区 `RiskPeopleSection.vue`。
- 修改风险模型区 `RiskModelSection.vue`。
- 修改项目分析弹窗、侧栏、资金流向 Tab、流水明细查询标题等组件。
- 修改 `projectOverview.js`，补充外部人员相关 API。

实现结果：

- 结果总览风险人员区域新增“外部人员预警”页签。
- 外部人员详情在当前页面弹窗打开，不再跳转流水明细查询。
- 外部人员详情只保留“异常明细”和“资金流向”两个页签。
- 外部人员没有员工专属的资产、征信等模块。
- 风险模型区域同时支持员工模型和外部人员模型。
- 修复外部模型重复渲染导致的 Vue duplicate key 问题。

### 2.4 测试、文档和 SQL

改动范围：

- 新增或调整后端单测，覆盖外部人员 SQL、规则参数、服务分发、PDF、Excel 导出。
- 新增后端和前端实施计划、实施记录、验收记录。
- 新增外部风险总览原型文档。
- 新增外部人员规则生产 SQL。
- 新增外部人员预警测试数据 SQL。

实现结果：

- 提交内包含可追溯的实施文档和验收记录。
- 生产 SQL 和测试 SQL 已拆开说明，避免生产误执行测试数据。

## 3. 做了什么

### 3.1 专项分析员工范围调整

做了：

- 将专项分析的员工范围从“项目打标命中员工”调整为“项目流水对应员工”。
- 通过 `ccdi_bank_statement.project_id` 和流水本方证件号 `cret_no` 关联 `ccdi_base_staff.id_card`。

实现了：

- 项目流水中存在的员工，即使没有命中风险模型，也能进入专项分析范围。
- 员工家庭资产负债、采购拓展、招聘拓展、调动拓展使用同一项目员工范围。
- 不改变结果总览风险人员统计口径，不改变打标结果表。

### 3.2 外部人员识别与预警

做了：

- 新增外部人员识别逻辑。
- 外部人员主体口径为：流水 `bs.cret_no` 非空，且该证件号不是员工、不是员工亲属。
- 新增外部人员预警汇总、列表、模型卡片、模型命中人员等后端查询能力。

实现了：

- 结果总览可以分析员工以外的中介、信贷客户、其他外部主体。
- 外部人员可以按“中介 / 客户 / 外部人员”等主体类型展示。
- 仅有无风险外部主体时，不展示外部人员预警空 Tab，不在 PDF 里输出外部人员空段落。
- 对象级外部人员命中也能进入结果总览统计。

### 3.3 外部人员 7 条流水规则

做了：

- 新增 SQL 迁移脚本：`sql/migration/2026-06-29-add-external-person-bank-tag-rules.sql`。
- 新增 7 条外部人员流水打标规则，并接入后端打标服务分发。

实现了以下规则：

1. 外部人员单笔大额交易：外部主体单笔交易金额超过大额阈值。
2. 外部人员累计交易超限：外部主体累计交易金额超过累计阈值。
3. 外部人员年流水交易额超限：外部主体近一年流水交易额超过年累计阈值。
4. 外部人员夜间集中交易：外部主体在 22:00 至次日 06:00 发生交易。
5. 外部人员疑似赌博摘要：摘要、交易类型或对手方名称命中赌博敏感词。
6. 外部人员同日多对手方疑似赌博交易：同日多笔、多对手方、金额位于疑似赌博区间。
7. 外部人员与员工或员工亲属交易：外部主体与员工或员工亲属发生资金往来。

规则口径：

- 外部人员大额类规则复用已有 `LARGE_TRANSACTION` 参数。
- 外部人员疑似赌博对象规则复用已有 `SUSPICIOUS_GAMBLING` 参数。
- 外部人员单笔大额、累计交易超限、年流水交易额超限为中风险；外部人员与员工/亲属交易、同日多对手方疑似赌博交易为高风险。
- 不使用对手方证件号判断，因为流水没有可靠的对方证件号。
- 外部人员与信贷客户/中介交易时，优先按对手方账号识别。
- 外部人员与员工/亲属交易时，优先按对手方账号识别；账号没有命中已维护账号时，才按对手方名称匹配员工或亲属。
- 如果对手方账号命中信贷客户，即使名称与员工相同，也按信贷客户展示。

### 3.4 结果总览页面

做了：

- 结果总览增加外部人员统计。
- 风险人员区域增加“外部人员预警”页签。
- 风险模型区域同时展示员工模型和外部人员模型。
- 修复外部模型重复渲染导致的 Vue duplicate key 问题。

实现了：

- 顶部统计卡保持 dev-ui 原结构，展示总人数、高风险、中风险、低风险、无风险。
- 顶部统计卡数值按员工与外部主体合并计算：总人数等于员工总人数加外部总人数，高中低和无风险分别加上外部对应人数。
- 当外部总人数大于 0 时，统计卡显示“员工 X / 外部 Y”拆分小字；外部总人数为 0 时不显示拆分小字。
- 外部人员预警列表展示：姓名、证件号、主体类型、风险等级、核心异常点、涉及对象、最近交易时间。
- 涉及对象显示业务词，如员工、员工亲属、中介库人员、信贷客户、资金。
- 不再展示不清晰的“关联对象”文案。
- 风险模型区可以筛选员工模型和外部模型，并查看命中人员。

### 3.5 外部人员详情

做了：

- 新增外部人员详情弹窗。
- 外部人员详情只保留“异常明细”和“资金流向”两个页签。
- 右上角提供关闭按钮。
- 移除右上角重复的“分析主体：xxx”。
- 移除“跳转流水明细查询”的交互。

实现了：

- 点击外部人员“查看详情”后，在当前结果总览内打开详情弹窗。
- 异常明细按员工详情的异常明细方式展示。
- 流水型异常展示流水明细。
- 对象型异常展示对象命中原因，例如年流水超限。
- 资金流向页签使用与员工资金流向一致的资金图谱能力。

### 3.6 涉疑交易明细与导出

做了：

- 调整风险明细工作簿中“涉疑交易明细”sheet 的字段。
- 保留“员工负面征信信息”和“异常账户人员信息”sheet。

实现了：

- 风险明细导出包含 3 个 sheet：
  - 涉疑交易明细。
  - 员工负面征信信息。
  - 异常账户人员信息。
- “涉疑交易明细”字段为：
  - 交易时间。
  - 本方账户。
  - 本方主体。
  - 对方名称。
  - 对方账户。
  - 关联员工。
  - 摘要。
  - 交易类型。
  - 异常标签。
  - 交易金额。

### 3.7 PDF 报告

做了：

- 调整结果总览 PDF 的风险汇总展示。
- 增加外部人员相关汇总输出。
- 避免无外部风险时输出空的外部人员段落。

实现了：

- PDF 顶部风险指标按总人数、高风险、中风险、低风险、无风险汇总，并合并外部人员对应风险等级。
- PDF 第三章标题为“风险总览”。
- 存在外部人员风险时，输出外部人员风险汇总、外部模型汇总、外部人员预警明细。
- 不存在外部风险命中时，不输出外部人员预警空段落。

### 3.8 页面交互细节

做了：

- 移除流水明细查询页头部多余副标题。
- 移除风险人员区域 Tab 右侧的小型导出入口。
- 保留结果总览顶部“导出报告”入口。
- 修复项目分析弹窗和外部人员详情交互中的细节问题。

实现了：

- 页面更贴合实际业务操作路径。
- 外部人员详情不会引导用户跳到流水明细查询。
- 外部人员没有员工专属的资产、征信等模块。

## 4. 包含的接口能力

本次代码中涉及或完善的接口能力包括：

- 外部人员预警列表：`/ccdi/project/overview/external-persons`
- 外部人员预警汇总：`/ccdi/project/overview/external-persons/summary`
- 外部风险模型卡片：`/ccdi/project/overview/external-risk-models/cards`
- 外部风险模型命中人员：`/ccdi/project/overview/external-risk-models/people`
- 外部风险模型命中人员导出：`/ccdi/project/overview/external-risk-models/people/export`
- 风险明细导出：`/ccdi/project/overview/risk-details/export`
- 涉疑交易明细查询和导出仍保留现有入口，并补齐导出字段。

## 5. 包含的数据库脚本

生产需要执行：

- `sql/migration/2026-06-29-add-external-person-bank-tag-rules.sql`

该脚本用于写入外部人员 7 条流水打标规则，支持重复执行更新规则口径。

提交内还包含测试数据脚本：

- `sql/migration/2026-06-24-add-external-person-warning-test-data.sql`

该脚本只用于本地或测试环境造数验证，生产不要执行。

本次提交不包含表结构变更，不需要新增业务表、系统表、菜单表或字典表。

## 6. 不包含的内容

本次提交不包含以下内容：

- 不提交 `tongweb_62318.properties`，该文件包含本机路径。
- 不提交 `ruoyi-admin/src/main/resources/application-dev.yml` 中未确认的 `allow-circular-references: true`。
- 不提交随机 `.docx` 文件。
- 不提交 `ruoyi-ui/public/*.docx`，这些文件会污染前端生产 `dist`。
- 不提交历史 5 月文档、SQL 和原型图片。
- 不改变员工风险人员结果总览的打标统计口径。
- 不改变负面征信和异常账户的业务规则。

## 7. 验证结论

已完成以下验证：

- 后端外部人员规则、SQL、服务分发、导出、PDF 相关单元测试通过。
- 后端针对性单测共 13 个测试类、82 个用例，0 失败、0 错误。
- `mvn -pl ccdi-project -am compile -DskipTests` 通过。
- `mvn -pl ruoyi-admin -am package -DskipTests` 通过。
- 前端使用 Node `22.22.3` 执行 `npm run build:prod` 通过。
- 真实页面登录并进入项目 `90629002` 验证通过：
  - 结果总览可打开。
  - 外部人员预警 Tab 可展示。
  - 外部人员详情弹窗可打开。
  - 异常明细在详情弹窗内展示。
  - 风险模型区域无 duplicate key 控制台错误。
- 风险明细导出实测通过，导出的 xlsx 包含 3 个 sheet，涉疑交易明细字段符合本清单。

结论：本地已提交的业务功能可以作为生产发布候选；发布时必须使用干净提交产物，不要使用当前脏工作区直接打包。
