diff --git a/docs/design/2026-04-20-intermediary-import-refactor-design.md b/docs/design/2026-04-20-intermediary-import-refactor-design.md index 41882916..e593d5b7 100644 --- a/docs/design/2026-04-20-intermediary-import-refactor-design.md +++ b/docs/design/2026-04-20-intermediary-import-refactor-design.md @@ -29,6 +29,8 @@ 5. 全部导入采用纯新增模式,不支持覆盖更新 6. 导入交互、异步任务状态、失败记录展示与“员工数据导入”保持一致 7. 对历史数据执行一次性迁移,不保留双语义兼容逻辑 +8. 中介模块现有外部接口继续保持 `bizId` 作为主资源标识,不改成证件号码路由 +9. `relationType` 在中介模块中废弃,不再参与导入模板、校验与维护流程 ## 三、范围 @@ -151,6 +153,7 @@ 3. 导入全部为纯新增,失败逐条返回 4. 文件内去重与库内去重同时存在 5. 不引入补丁兼容逻辑 +6. 现有外部接口对前端继续保持 `bizId` 契约,内部再转换为本人证件号码处理 ### 6.2 顶部入口设计 @@ -180,6 +183,12 @@ - `person_sub_type != 本人` - `related_num_id = 关联中介本人证件号码` +唯一性口径调整为: + +1. 中介本人 `person_id` 全表唯一 +2. 中介亲属允许相同 `person_id` 关联多个不同中介本人 +3. 同一中介本人名下的亲属以 `related_num_id + person_id` 唯一 + ### 7.2 `related_num_id` 语义切换 本次统一调整为: @@ -194,8 +203,24 @@ 3. 首页联合查询亲属记录时按本人证件号码关联 4. 删除本人时按本人证件号码删除其亲属 5. 导入亲属时按本人证件号码回填 `related_num_id` +6. 外部接口继续传本人 `bizId`,服务层内部先查本人证件号码后再执行业务逻辑 -### 7.3 `ccdi_intermediary_enterprise_relation` +### 7.3 外部接口契约 + +本次仅调整中介模块内部关联语义,不调整现有外部接口的路径参数契约: + +1. 查询中介详情继续使用 `bizId` +2. 查询亲属列表继续使用 `bizId` +3. 新增中介亲属继续使用 `bizId` +4. 查询中介关联机构列表继续使用 `bizId` + +服务层处理方式统一为: + +1. 先根据外部传入的 `bizId` 查询中介本人 +2. 再使用本人 `personId` 处理亲属链路 +3. 机构关系链路继续使用本人 `bizId` + +### 7.4 `ccdi_intermediary_enterprise_relation` 中介实体关联关系继续存于: @@ -243,16 +268,16 @@ 11. 企业统一信用码 12. 职位 13. 关联中介本人证件号码 -14. 关系类型 -15. 备注 +14. 备注 说明: 1. `personSubType` 在导入模板中必须使用下拉框,不允许自由文本输入 -2. 下拉选项固定为:`本人 / 配偶 / 子女 / 父母 / 兄弟姐妹 / 其他` +2. `personSubType` 下拉来源使用系统字典 `ccdi_person_sub_type` 3. 模板生成方式与系统现有 Excel 字典下拉保持一致 4. `personSubType = 本人` 时,`relatedNumId` 必须为空 5. `personSubType != 本人` 时,`relatedNumId` 必须填写“关联中介本人证件号码” +6. `relationType` 字段在本次导入中废弃,不出现在模板中,也不参与导入校验与落库 #### 8.1.4 导入处理规则 @@ -272,23 +297,26 @@ 3. 校验 `relatedNumId` 对应的中介本人是否存在于: - 数据库已存在记录 - 本次第一阶段已导入成功的本人记录 -4. 校验亲属个人档案与关系唯一性 -5. 落库时 `related_num_id = 本人证件号码` +4. 允许相同亲属证件号码关联多个不同中介本人 +5. 校验同一中介本人名下的亲属关系唯一性 +6. 落库时 `related_num_id = 本人证件号码` #### 8.1.5 去重逻辑 双层去重: -1. 文件内按 `personId` 去重 -2. 数据库内按 `personId` 去重 -3. 对亲属记录额外按 `relatedNumId + personId` 去重 +1. 对中介本人记录,文件内按 `personId` 去重 +2. 对中介本人记录,数据库内按 `personId` 去重 +3. 对中介亲属记录,文件内按 `relatedNumId + personId` 去重 +4. 对中介亲属记录,数据库内按 `relatedNumId + personId` 去重 失败判定口径: -1. 同一文件内证件号重复,记失败 -2. 数据库中证件号已存在,记失败 +1. 中介本人证件号在同一文件内重复,记失败 +2. 中介本人证件号在数据库中已存在,记失败 3. 同一文件内相同“本人证件号 + 亲属证件号”重复,记失败 4. 数据库中相同“本人证件号 + 亲属证件号”已存在,记失败 +5. 相同亲属证件号若关联的是不同中介本人,允许导入成功 ### 8.2 导入中介实体关联关系 @@ -402,7 +430,9 @@ 7. `CcdiIntermediaryRelativeVO` 8. `CcdiIntermediaryPersonAddDTO` 9. `CcdiIntermediaryPersonEditDTO` -10. `CcdiIntermediaryPersonExcel` +10. `CcdiIntermediaryRelativeAddDTO` +11. `CcdiIntermediaryRelativeEditDTO` +12. `CcdiIntermediaryPersonExcel` ### 10.2 前端受影响代码 @@ -411,6 +441,7 @@ 3. `ruoyi-ui/src/api/ccdiIntermediary.js` 4. 失败记录弹窗相关状态管理 5. 导入模板说明文案 +6. 现有依赖 `bizId` 的亲属维护入口保持不变 ### 10.3 基本不受影响代码 @@ -443,12 +474,15 @@ 1. `related_num_id` 有值,但找不到对应本人 `biz_id` 2. 找到本人后,本人 `person_id` 为空 3. 同一历史关系迁移后是否会与现有新语义数据冲突 +4. 现有亲属记录在迁移后是否出现同一中介本人名下 `related_num_id + person_id` 冲突 ### 11.3 迁移原则 -1. 先清洗异常数据,再执行正式迁移 -2. 迁移完成后,全部代码统一按新语义运行 -3. 不保留同时兼容 `biz_id` 与证件号码的查询逻辑 +1. 按用户要求,迁移先于功能改造执行 +2. 先清洗异常数据,再执行正式迁移 +3. 迁移完成后,全部代码统一按新语义运行 +4. 不保留同时兼容 `biz_id` 与证件号码的查询逻辑 +5. 为避免旧逻辑读取失败,迁移、代码发布、回归验证必须放在同一实施窗口内连续完成 ## 十二、异常处理口径 @@ -461,8 +495,8 @@ 3. `personSubType = 本人` 但 `relatedNumId` 非空 4. `personSubType != 本人` 但 `relatedNumId` 为空 5. 关联中介本人证件号码不存在 -6. 导入文件内证件号码重复 -7. 数据库中证件号码已存在 +6. 中介本人证件号在导入文件内重复 +7. 中介本人证件号在数据库中已存在 8. 导入文件内亲属关系重复 9. 数据库中亲属关系已存在 @@ -488,8 +522,9 @@ 3. 删除中介本人时级联删除其亲属和关联机构关系 4. 本人和亲属混合导入成功 5. 亲属引用“本次文件内先导入成功的本人”成功 -6. 文件内重复、库内重复、无效关联均能正确记失败 -7. 中介实体关联关系导入成功与失败路径正确 +6. 相同亲属证件号关联不同中介本人成功 +7. 文件内重复、库内重复、无效关联均能正确记失败 +8. 中介实体关联关系导入成功与失败路径正确 ### 13.2 前端测试 @@ -506,10 +541,11 @@ 建议实施顺序如下: -1. 先完成 `related_num_id` 语义切换设计落地与历史数据迁移脚本 -2. 再改造中介模块内既有亲属查询与级联删除逻辑 -3. 再接入两类导入后端接口与异步处理 -4. 最后改造前端入口、弹窗、失败记录与状态恢复 +1. 先完成 `related_num_id` 历史数据迁移脚本与迁移校验 SQL +2. 在同一实施窗口内先执行迁移 +3. 紧接着发布中介模块语义切换代码,完成亲属查询、手工维护、删除级联改造 +4. 再接入两类导入后端接口与异步处理 +5. 最后改造前端入口、弹窗、失败记录与状态恢复 ## 十五、设计结论 @@ -520,7 +556,10 @@ 3. 中介实体关联关系单独导入,落关系表 4. `related_num_id` 整个中介模块统一改为“关联中介本人证件号码” 5. 所有导入采用纯新增模式 -6. 去重采用“文件内去重 + 库内去重” -7. 通过一次性历史数据迁移完成语义统一 +6. 中介本人按证件号全局唯一,亲属允许关联多个不同中介本人 +7. 去重采用“文件内去重 + 库内去重” +8. 外部接口继续保持 `bizId` 契约 +9. `relationType` 废弃,`personSubType` 使用字典下拉 +10. 通过一次性历史数据迁移完成语义统一 该方案满足当前需求边界,且符合最短路径实现原则,不引入兼容性补丁方案。