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

**模块**: 中介库管理  
**日期**: 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. 机构主档继续由实体信息维护功能独立负责

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