ccdi/docs/design/2026-04-17-intermediary-library-refactor-design.md

中介库主从结构改造设计文档

模块: 中介库管理
日期: 2026-04-17
作者: Codex
状态: 已确认

一、背景

当前中介库模块采用“个人中介 / 机构中介”并列维护方式：

1. 个人中介数据存放于 ccdi_biz_intermediary
2. 机构中介数据直接复用 ccdi_enterprise_base_info
3. 前端新增弹窗在“个人 / 机构”之间二选一录入
4. 首页列表通过联合查询同时展示个人中介与机构中介

现业务需求已变更为新的主从维护模式：

1. 用户先录入中介个人信息
2. 再在该中介名下录入亲属个人信息
3. 再在该中介名下录入关联机构关系信息
4. 关联机构信息只维护“中介与机构的关系”，实体主档仍由实体信息维护功能负责
5. 首页列表需要统一查询“中介本人 / 中介亲属 / 中介关联机构”三类记录

本次设计目标是在尽量复用现有中介库模块基础上，将原并列建模改造为“中介本人主记录 + 亲属子记录 + 机构关系子记录”的结构。

二、目标

本次设计目标如下：

1. 中介库主记录统一为“中介本人”
2. ccdi_biz_intermediary 同时承载中介本人和中介亲属
3. 新增 ccdi_intermediary_enterprise_relation 维护中介与机构的关系
4. 首页统一展示三类记录，并支持统一查询
5. 新增流程改为“先新增中介本人，再在详情中维护亲属和关联机构”
6. 保持最短路径实现，不引入额外通用关系模型或平行模块

三、范围

3.1 本次范围

• 调整中介库数据模型
• 新增中介关联机构关系表
• 改造中介库首页联合查询
• 改造中介新增、详情、亲属维护、关联机构维护交互
• 调整后端中介、亲属、关联机构关系接口
• 补充设计文档与实施计划

3.2 不在本次范围

• 不负责录入或修改实体机构主档
• 不新增机构主档补录兜底逻辑
• 不做通用人员关系平台化抽象
• 不新增独立一级菜单拆分为三个平行模块
• 不扩展导入、导出、异步任务链路
• 不新增兼容性补丁、降级方案或过度设计

四、现状分析

4.1 前端现状

当前中介库页面位于：

• ruoyi-ui/src/views/ccdiIntermediary/index.vue
• ruoyi-ui/src/views/ccdiIntermediary/components/EditDialog.vue

现有特点：

1. 首页列表面向“个人中介 / 机构中介”两类并列记录
2. 新增弹窗先选择类型，再进入不同表单
3. 个人中介与机构中介使用不同详情接口
4. 机构中介可直接在中介库模块中新增与修改

这与当前需求存在三个核心偏差：

1. 主记录不是“中介本人”，而是“个人 / 机构”并列
2. 没有中介详情下的亲属子列表与机构关系子列表
3. 首页列表未按“本人 / 亲属 / 机构关系”统一口径展示

4.2 后端现状

当前中介控制器位于：

• ccdi-info-collection/src/main/java/com/ruoyi/info/collection/controller/CcdiIntermediaryController.java

现有后端特点：

1. POST /ccdi/intermediary/person 新增个人中介
2. POST /ccdi/intermediary/entity 新增机构中介
3. GET /ccdi/intermediary/list 联合查询个人中介与机构中介
4. 机构中介直接写入 ccdi_enterprise_base_info

这与新需求的偏差在于：

1. 机构不应再作为中介库主记录新增
2. 亲属未形成独立子资源模型
3. 中介与机构之间缺少独立关系表

4.3 现有可复用基础

仓库中已存在以下可参考实现：

1. ccdi_staff_fmy_relation 员工亲属关系维护
2. ccdi_staff_enterprise_relation 员工关联企业维护
3. ccdi_cust_enterprise_relation 客户关联企业维护

可复用的思路主要是：

1. 子资源独立 CRUD
2. 统一列表查询 + 独立编辑弹窗
3. 关系表联查企业主档展示企业名称

但本次不直接照搬上述模块，而是在中介库现有主页面中完成收口。

五、方案对比

5.1 方案 A：中介本人为主记录，亲属与机构关系作为子记录

做法：

1. ccdi_biz_intermediary 统一存中介本人和中介亲属
2. 新增 ccdi_intermediary_enterprise_relation
3. 首页列表联合查询三类记录
4. 首页新增只允许新增中介本人
5. 详情页维护亲属与关联机构

优点：

1. 最贴合当前业务口径
2. 最大程度复用现有中介库菜单、权限与主页面
3. 后端改造边界清晰
4. 前端操作路径与“先建中介，再维护子信息”一致

缺点：

1. 需要重写现有“个人 / 机构并列”的列表语义
2. 需要补一张新的机构关系表

5.2 方案 B：拆成中介本人、亲属、机构关系三个平行页面

做法：

1. 中介本人独立页面
2. 中介亲属独立页面
3. 中介关联机构独立页面

问题：

1. 与“先建中介，再在下面维护”不一致
2. 页面、菜单、权限改动面更大
3. 首页聚合查询与跳转链路更复杂

5.3 方案 C：抽象统一关系模型

做法：

1. 抽象统一的人员关系与机构关系模型
2. 中介、员工、客户共用一套关系平台

问题：

1. 抽象过重
2. 明显超出当前需求
3. 会引入额外改造面，不符合最短路径原则

5.4 结论

采用 方案 A：中介本人为主记录，亲属与机构关系作为子记录。

六、总体设计

6.1 设计原则

本次设计遵循以下原则：

1. 中介库只维护中介本人、亲属和中介机构关系
2. 机构主档继续归实体信息维护功能负责
3. 不新增无必要的身份字段，优先复用现有字段表达业务含义
4. 首页统一查询，编辑入口按记录类型分流
5. 删除中介本人时同时清理亲属与机构关系

6.2 数据流

新增中介链路：

1. 首页点击新增
2. 打开中介本人新增弹窗
3. 保存中介本人到 ccdi_biz_intermediary
4. 自动进入中介详情
5. 在详情中新增亲属与关联机构关系

首页查询链路：

1. 前端调用 GET /ccdi/intermediary/list
2. 后端联合查询：
   • ccdi_biz_intermediary 中 person_sub_type = 本人
   • ccdi_biz_intermediary 中 person_sub_type != 本人
   • ccdi_intermediary_enterprise_relation 联查 ccdi_enterprise_base_info
3. 统一返回前端展示字段与 recordType

删除中介链路：

1. 删除中介本人
2. 删除本人记录
3. 删除名下亲属记录
4. 删除名下关联机构关系记录
5. 不删除企业主档

七、数据模型设计

7.1 ccdi_biz_intermediary 使用方式调整

ccdi_biz_intermediary 继续作为人员表，不新增新的身份字段，直接复用：

• person_sub_type
• related_num_id

字段口径调整如下：

1. 中介本人

   • person_sub_type = 本人
   • related_num_id 为空

2. 中介亲属

   • person_sub_type = 配偶 / 子女 / 父母 / 兄弟姐妹 / 其他
   • related_num_id = 所属中介本人的 biz_id

因此：

• person_sub_type 负责表达“本人 / 亲属关系”
• related_num_id 负责表达“归属到哪个中介本人”

7.2 新增 ccdi_intermediary_enterprise_relation

新增表：ccdi_intermediary_enterprise_relation

建议字段：

1. id BIGINT 主键
2. intermediary_biz_id VARCHAR(64)
   关联中介本人 biz_id
3. social_credit_code VARCHAR(18)
   关联机构统一社会信用代码
4. relation_person_post VARCHAR(100)
   中介在该机构的关联角色/职务
5. remark VARCHAR(500)
6. created_by
7. create_time
8. updated_by
9. update_time

唯一性约束建议：

• uk_intermediary_enterprise (intermediary_biz_id, social_credit_code)

说明：

1. 只维护关系，不维护企业主档
2. 企业名称通过联查 ccdi_enterprise_base_info.enterprise_name 获取
3. 删除关系时只删该表记录

7.3 删除规则

删除中介本人时：

1. 删除 ccdi_biz_intermediary 中本人记录
2. 删除 ccdi_biz_intermediary 中 related_num_id = 本人 biz_id 的亲属记录
3. 删除 ccdi_intermediary_enterprise_relation 中 intermediary_biz_id = 本人 biz_id 的全部关系记录
4. 不删除 ccdi_enterprise_base_info

八、首页列表与查询口径

8.1 列表展示字段

首页列表统一展示以下字段：

1. 名称
2. 证件号
3. 关联中介姓名
4. 关联关系
5. 创建时间

8.2 三类记录展示映射

1. 中介本人

   • 名称：name
   • 证件号：person_id
   • 关联中介姓名：本人姓名
   • 关联关系：本人

2. 中介亲属

   • 名称：name
   • 证件号：person_id
   • 关联中介姓名：所属中介本人姓名
   • 关联关系：person_sub_type

3. 关联机构

   • 名称：机构名称
   • 证件号：统一社会信用代码
   • 关联中介姓名：所属中介本人姓名
   • 关联关系：relation_person_post

8.3 搜索字段

首页搜索字段固定为：

1. 名称
2. 证件号
3. 记录类型
4. 关联中介信息

其中“关联中介信息”为一个合并输入框，同时支持：

1. 按关联中介姓名查询
2. 按关联中介证件号查询

8.4 记录类型

联合查询结果中增加派生字段 recordType，仅用于前端分流，不落库：

1. INTERMEDIARY
2. RELATIVE
3. ENTERPRISE_RELATION

九、接口设计

9.1 中介本人接口

保留现有中介主线接口，语义调整为“中介本人”：

1. POST /ccdi/intermediary/person

   • 新增中介本人
   • 固定写入：
     • person_sub_type = 本人
     • related_num_id = null

2. PUT /ccdi/intermediary/person

   • 修改中介本人

3. GET /ccdi/intermediary/person/{bizId}

   • 查询中介本人详情

9.2 中介亲属接口

新增中介名下亲属接口，仍然落 ccdi_biz_intermediary：

1. GET /ccdi/intermediary/{bizId}/relatives

   • 查询某中介名下亲属列表

2. POST /ccdi/intermediary/{bizId}/relative

   • 新增亲属
   • 固定写入：
     • related_num_id = bizId
     • person_sub_type != 本人

3. GET /ccdi/intermediary/relative/{relativeBizId}

   • 查询亲属详情

4. PUT /ccdi/intermediary/relative

   • 修改亲属

5. DELETE /ccdi/intermediary/relative/{relativeBizId}

   • 删除亲属

9.3 中介关联机构关系接口

新增关系表对应接口：

1. GET /ccdi/intermediary/{bizId}/enterprise-relations

   • 查询某中介名下关联机构列表

2. POST /ccdi/intermediary/{bizId}/enterprise-relation

   • 新增关联机构关系

3. GET /ccdi/intermediary/enterprise-relation/{id}

   • 查询单条机构关系详情

4. PUT /ccdi/intermediary/enterprise-relation

   • 修改机构关系

5. DELETE /ccdi/intermediary/enterprise-relation/{id}

   • 删除机构关系

9.4 首页联合查询接口

保留：

• GET /ccdi/intermediary/list

返回统一字段：

1. recordType
2. recordId
3. name
4. certificateNo
5. relatedIntermediaryName
6. relationText
7. createTime

查询条件：

1. name
2. certificateNo
3. recordType
4. relatedIntermediaryKeyword

其中 relatedIntermediaryKeyword 同时匹配：

1. 关联中介姓名
2. 关联中介证件号

9.5 删除接口行为

1. 删除中介本人：

   • 继续使用中介主删除接口
   • 服务层执行本人、亲属、机构关系级联清理

2. 删除亲属：

   • 走亲属删除接口

3. 删除关联机构：

   • 走关联机构关系删除接口

十、前端页面设计

10.1 首页页面

保留页面：

• ruoyi-ui/src/views/ccdiIntermediary/index.vue

页面语义调整为“中介综合库”。

改造内容：

1. 搜索区改为新搜索字段
2. 列表改为三类记录混合展示
3. 新增按钮只允许新增中介本人

10.2 列表操作行为

1. recordType = INTERMEDIARY

   • 详情
   • 修改
   • 删除

2. recordType = RELATIVE

   • 详情 / 编辑亲属
   • 删除亲属

3. recordType = ENTERPRISE_RELATION

   • 详情 / 编辑关联机构关系
   • 删除关联关系

10.3 新增流程

首页新增流程固定为：

1. 点击新增
2. 打开中介本人新增弹窗
3. 保存成功
4. 自动进入该中介详情
5. 在详情中继续维护亲属与关联机构

10.4 中介详情页

中介本人详情建议改为“大弹窗详情维护页”，包含三个区域：

1. 中介基本信息
2. 亲属信息列表
3. 关联机构信息列表

支持在详情中：

1. 编辑中介本人
2. 新增 / 编辑 / 删除亲属
3. 新增 / 编辑 / 删除关联机构关系

10.5 子记录编辑

首页点到亲属或关联机构时：

1. 直接打开对应编辑弹窗
2. 弹窗中展示所属中介姓名，只读
3. 保存成功后刷新首页列表
4. 如当前已打开中介详情，同时刷新详情内子列表

10.6 弹窗拆分建议

当前 EditDialog.vue 同时承担个人和机构两套表单，本次建议拆分为：

1. 中介本人编辑弹窗
2. 亲属编辑弹窗
3. 关联机构关系编辑弹窗

如果实现时考虑最短路径，也允许在现有组件上拆成三个分支表单，但从设计上仍以三类用途明确的编辑组件为目标。

十一、校验与业务规则

11.1 中介本人

1. 新增时固定 person_sub_type = 本人
2. related_num_id 必须为空
3. 证件号仍需保持唯一性校验

11.2 中介亲属

1. person_sub_type 禁止保存为 本人
2. related_num_id 必须指向所属中介本人
3. 首页展示关联关系时直接取 person_sub_type

11.3 关联机构关系

1. social_credit_code 必须存在于实体信息库
2. 同一中介下不允许重复关联同一统一社会信用代码
3. 不允许通过中介模块新增机构主档

十二、数据库与代码改动清单

12.1 后端

预计改动：

1. CcdiIntermediaryController
2. ICcdiIntermediaryService
3. CcdiIntermediaryServiceImpl
4. 中介相关 DTO / VO
5. 新增中介关联机构关系 domain / DTO / VO / mapper / service / controller
6. CcdiIntermediaryMapper.xml
7. 新增机构关系 Mapper XML

12.2 前端

预计改动：

1. ruoyi-ui/src/views/ccdiIntermediary/index.vue
2. SearchForm.vue
3. DataTable.vue
4. DetailDialog.vue
5. EditDialog.vue 或拆分后的三个编辑组件
6. ruoyi-ui/src/api/ccdiIntermediary.js
7. 新增关联机构关系 API

12.3 SQL

预计新增：

1. ccdi_intermediary_enterprise_relation 建表脚本
2. 如需字典补充，再新增对应迁移脚本

十三、测试要点

1. 新增中介本人成功，自动进入详情
2. 在详情中新增亲属成功，首页能查到亲属记录
3. 在详情中新增关联机构关系成功，首页能查到关联机构记录
4. 首页支持按名称、证件号、记录类型、关联中介信息查询
5. 首页点击亲属记录可直接编辑
6. 首页点击关联机构记录可直接编辑
7. 删除中介本人后，亲属记录一并删除
8. 删除中介本人后，关联机构关系一并删除
9. 删除中介本人后，机构主档仍保留
10. 同一中介重复关联同一机构时正确拦截

十四、结论

本次中介库改造采用“中介本人主记录 + 亲属子记录 + 关联机构关系子记录”的主从结构：

1. ccdi_biz_intermediary 负责维护中介本人和亲属
2. ccdi_intermediary_enterprise_relation 负责维护中介与机构的关系
3. 首页以统一列表展示三类记录
4. 新增流程固定为“先建中介本人，再维护子信息”
5. 机构主档继续由实体信息维护功能独立负责

该方案满足当前需求，并保持了最短路径实现与清晰的前后端边界。