# 中介库导入改造实施记录

## 基本信息

- 日期：2026-04-20
- 范围：中介库后端导入改造 + 前端导入入口与状态改造
- 关联设计：`docs/design/2026-04-20-intermediary-import-refactor-design.md`
- 关联计划：
  `docs/plans/backend/2026-04-20-intermediary-import-backend-implementation.md`
  `docs/plans/frontend/2026-04-20-intermediary-import-frontend-implementation.md`

## 实施内容

- 后端完成 `related_num_id` 语义切换，统一为“关联中介本人证件号码”，并补齐本人证件号变更同步、亲属唯一性收敛、统一列表联表条件切换。
- 后端完成“导入中介信息”链路重构，支持本人与亲属混合导入、同文件内引用先成功导入的本人、同亲属证件号挂到不同本人。
- 后端新增“导入中介实体关联关系”链路，按“本人证件号码 -> 本人 bizId -> 关系表”写入，并支持文件内去重、库内去重、失败记录回看。
- 前端完成中介导入入口改造，页面顶部改为“导入中介信息”“导入中介实体关联关系”两个按钮，导入弹窗改为 `scene` 驱动。
- 前端完成两类导入任务状态、本地缓存键、失败记录弹窗、历史任务恢复和完成态刷新逻辑，保留现有详情维护、亲属维护、关联机构维护的 `bizId` 契约。

## 验证结果

- 后端测试：
  `mvn -pl ccdi-info-collection -am -Dsurefire.failIfNoSpecifiedTests=false -Dtest=CcdiIntermediaryServiceImplTest,CcdiIntermediaryMapperTest,CcdiIntermediaryControllerTest,CcdiIntermediaryPersonImportServiceImplTest,CcdiIntermediaryEnterpriseRelationImportServiceImplTest test`
  结果：PASS
- 后端编译：
  `mvn -pl ccdi-info-collection -am clean compile`
  结果：PASS
- 前端静态测试：
  `source ~/.nvm/nvm.sh && cd ruoyi-ui && nvm use 14.21.3 >/dev/null && node tests/unit/intermediary-import-api.test.js && node tests/unit/intermediary-import-dialog.test.js && node tests/unit/intermediary-import-toolbar.test.js && node tests/unit/intermediary-import-state.test.js && node tests/unit/intermediary-person-edit-ui.test.js`
  结果：PASS
- 前端构建：
  `source ~/.nvm/nvm.sh && cd ruoyi-ui && nvm use 14.21.3 >/dev/null && npm run build:prod`
  结果：PASS（仅有原有 bundle size warning）

## SQL 执行结果

- 已执行：
  `bin/mysql_utf8_exec.sh sql/migration/2026-04-20-fix-ccdi-person-sub-type-dict.sql`
  `bin/mysql_utf8_exec.sh sql/migration/2026-04-20-migrate-intermediary-related-num-id-to-person-id.sql`
- 迁移后核查：
  `post_migration_missing_parent = 1025`
  `legacy_biz_id_reference = 0`
  `owner_person_id_empty_after_migration = 754`
- 结论：可迁移数据已经完成语义切换，旧 `biz_id` 语义残留已清零；历史中仍有缺失本人映射或 `related_num_id` 为空的脏数据，需要后续专项清洗。
