ccdi/docs/reports/implementation/2026-04-20-intermediary-import-refactor-implementation.md

中介库导入改造实施记录

基本信息

• 日期：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 为空的脏数据，需要后续专项清洗。