# 中介库主从结构改造后端实施计划 > **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** 将中介库后端从“个人中介 / 机构中介并列维护”改造为“中介本人主记录 + 中介亲属子记录 + 中介机构关系子记录”,并提供统一首页查询、详情维护和级联删除能力。 **Architecture:** 继续以 `CcdiIntermediaryController` 和 `ccdi_biz_intermediary` 为主线,保留中介本人主资源;亲属仍落同表,通过 `person_sub_type` 和 `related_num_id` 表达主从关系;新增 `ccdi_intermediary_enterprise_relation` 作为中介与机构的关系表。首页 `/ccdi/intermediary/list` 改为三路联合查询,返回统一展示字段与 `recordType` 供前端分流。 **Tech Stack:** Java 21, Spring Boot 3, MyBatis Plus, MySQL, JUnit 5, Maven, Markdown --- ## 文件结构与职责 **设计与参考** - `docs/design/2026-04-17-intermediary-library-refactor-design.md` 本次改造的设计基线,实施时不得偏离文档确认的字段、接口与删除规则。 **数据库与 SQL** - `sql/migration/2026-04-17-create-intermediary-enterprise-relation.sql` 创建 `ccdi_intermediary_enterprise_relation`,补索引和唯一约束。 - `sql/migration/2026-04-17-fix-intermediary-person-sub-type-dict.sql` 如需补齐 `person_sub_type` 固定值“本人/配偶/子女/父母/兄弟姐妹/其他”,在此脚本中补充字典数据。 **中介主链路** - `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/controller/CcdiIntermediaryController.java` 继续作为中介模块统一入口,补亲属与机构关系子资源接口。 - `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/service/ICcdiIntermediaryService.java` 增加亲属列表、亲属 CRUD、机构关系列表、机构关系 CRUD、统一联合查询新口径方法。 - `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/service/impl/CcdiIntermediaryServiceImpl.java` 承接中介本人、亲属、机构关系、联合查询和级联删除逻辑。 - `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/mapper/CcdiIntermediaryMapper.java` 保留首页联合查询入口,参数口径调整。 - `ccdi-info-collection/src/main/resources/mapper/info/collection/CcdiIntermediaryMapper.xml` 将首页联合查询改为“本人 + 亲属 + 机构关系”三路 `UNION ALL`。 **亲属与中介本人 DTO / VO** - `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/dto/CcdiIntermediaryQueryDTO.java` 改成新首页查询条件。 - `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/dto/CcdiIntermediaryPersonAddDTO.java` 收敛为“中介本人新增”入参,不再承担亲属语义。 - `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/dto/CcdiIntermediaryPersonEditDTO.java` 收敛为“中介本人编辑”入参。 - `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/dto/CcdiIntermediaryRelativeAddDTO.java` 新增中介亲属新增入参。 - `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/dto/CcdiIntermediaryRelativeEditDTO.java` 新增中介亲属编辑入参。 - `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/vo/CcdiIntermediaryVO.java` 改为首页统一列表 VO。 - `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/vo/CcdiIntermediaryPersonDetailVO.java` 改为中介本人详情 VO。 - `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/vo/CcdiIntermediaryRelativeVO.java` 新增亲属列表 / 详情返回。 **中介机构关系链路** - `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/CcdiIntermediaryEnterpriseRelation.java` 新增中介机构关系实体。 - `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/dto/CcdiIntermediaryEnterpriseRelationAddDTO.java` 新增中介机构关系新增入参。 - `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/dto/CcdiIntermediaryEnterpriseRelationEditDTO.java` 新增中介机构关系编辑入参。 - `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/vo/CcdiIntermediaryEnterpriseRelationVO.java` 新增关系列表 / 详情返回。 - `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/mapper/CcdiIntermediaryEnterpriseRelationMapper.java` 新增关系表 Mapper。 - `ccdi-info-collection/src/main/resources/mapper/info/collection/CcdiIntermediaryEnterpriseRelationMapper.xml` 新增关系表查询 SQL。 **测试** - `ccdi-info-collection/src/test/java/com/ruoyi/info/collection/service/CcdiIntermediaryServiceImplTest.java` 补中介本人、亲属、机构关系和级联删除测试。 - `ccdi-info-collection/src/test/java/com/ruoyi/info/collection/mapper/CcdiIntermediaryMapperTest.java` 补首页联合查询 SQL 测试。 - `ccdi-info-collection/src/test/java/com/ruoyi/info/collection/controller/CcdiIntermediaryControllerTest.java` 补新增接口和子资源接口测试。 ## 实施任务 ### Task 1: 建立关系表和固定口径 SQL **Files:** - Create: `sql/migration/2026-04-17-create-intermediary-enterprise-relation.sql` - Create: `sql/migration/2026-04-17-fix-intermediary-person-sub-type-dict.sql` - Reference: `sql/ccdi_staff_fmy_relation.sql` - Reference: `sql/menu-intermediary.sql` - [ ] **Step 1: 梳理当前 `ccdi_biz_intermediary` 对 `person_sub_type` 的实际使用口径** Run: `rg -n "personSubType|person_sub_type" ccdi-info-collection ruoyi-ui sql -S` Expected: 能定位现有中介与前端表单对该字段的读写位置。 - [ ] **Step 2: 编写关系表建表 SQL** 在 `sql/migration/2026-04-17-create-intermediary-enterprise-relation.sql` 中创建: ```sql CREATE TABLE IF NOT EXISTS `ccdi_intermediary_enterprise_relation` ( `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID', `intermediary_biz_id` VARCHAR(64) NOT NULL COMMENT '所属中介biz_id', `social_credit_code` VARCHAR(18) NOT NULL COMMENT '统一社会信用代码', `relation_person_post` VARCHAR(100) DEFAULT NULL COMMENT '关联角色/职务', `remark` VARCHAR(500) DEFAULT NULL COMMENT '备注', `created_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人', `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', `updated_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人', `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', PRIMARY KEY (`id`), UNIQUE KEY `uk_intermediary_enterprise` (`intermediary_biz_id`, `social_credit_code`), KEY `idx_intermediary_biz_id` (`intermediary_biz_id`), KEY `idx_social_credit_code` (`social_credit_code`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='中介关联机构关系表'; ``` - [ ] **Step 3: 编写 `person_sub_type` 固定值脚本** 在 `sql/migration/2026-04-17-fix-intermediary-person-sub-type-dict.sql` 中补齐: ```sql -- 根据实际字典表结构插入 本人 / 配偶 / 子女 / 父母 / 兄弟姐妹 / 其他 ``` Expected: 后端和前端都能使用一致的固定值。 - [ ] **Step 4: 人工校对 SQL 字段注释与唯一约束** Expected: 能明确表达“只删关系,不删机构主档”的边界。 - [ ] **Step 5: 提交 SQL 与计划中的字段口径** ```bash git add sql/migration/2026-04-17-create-intermediary-enterprise-relation.sql sql/migration/2026-04-17-fix-intermediary-person-sub-type-dict.sql git commit -m "feat: 新增中介机构关系表脚本" ``` ### Task 2: 收敛中介本人与亲属 DTO / VO **Files:** - Modify: `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/dto/CcdiIntermediaryQueryDTO.java` - Modify: `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/dto/CcdiIntermediaryPersonAddDTO.java` - Modify: `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/dto/CcdiIntermediaryPersonEditDTO.java` - Create: `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/dto/CcdiIntermediaryRelativeAddDTO.java` - Create: `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/dto/CcdiIntermediaryRelativeEditDTO.java` - Modify: `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/vo/CcdiIntermediaryVO.java` - Modify: `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/vo/CcdiIntermediaryPersonDetailVO.java` - Create: `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/vo/CcdiIntermediaryRelativeVO.java` - [ ] **Step 1: 修改首页查询 DTO** 将 `CcdiIntermediaryQueryDTO` 调整为: ```java private String name; private String certificateNo; private String recordType; private String relatedIntermediaryKeyword; ``` - [ ] **Step 2: 收敛中介本人新增 DTO** `CcdiIntermediaryPersonAddDTO` 仅保留中介本人字段,并在服务层固定写入: ```java personSubType = "本人"; relatedNumId = null; ``` - [ ] **Step 3: 新增亲属新增 / 编辑 DTO** 亲属 DTO 需要明确: ```java @NotBlank(message = "亲属关系不能为空") private String personSubType; ``` 并在实现中拒绝 `"本人"`。 - [ ] **Step 4: 改造首页统一列表 VO** `CcdiIntermediaryVO` 收敛为: ```java private String recordType; private String recordId; private String name; private String certificateNo; private String relatedIntermediaryName; private String relationText; private Date createTime; ``` - [ ] **Step 5: 新增亲属 VO 并整理详情返回** Expected: 前后端不再复用旧“个人 / 机构并列”字段集合。 - [ ] **Step 6: 提交 DTO / VO 重构** ```bash git add ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/dto ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/vo git commit -m "feat: 调整中介本人亲属传输对象" ``` ### Task 3: 新增中介机构关系实体与 Mapper **Files:** - Create: `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/CcdiIntermediaryEnterpriseRelation.java` - Create: `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/dto/CcdiIntermediaryEnterpriseRelationAddDTO.java` - Create: `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/dto/CcdiIntermediaryEnterpriseRelationEditDTO.java` - Create: `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/vo/CcdiIntermediaryEnterpriseRelationVO.java` - Create: `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/mapper/CcdiIntermediaryEnterpriseRelationMapper.java` - Create: `ccdi-info-collection/src/main/resources/mapper/info/collection/CcdiIntermediaryEnterpriseRelationMapper.xml` - Reference: `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/CcdiCustEnterpriseRelation.java` - Reference: `ccdi-info-collection/src/main/resources/mapper/info/collection/CcdiCustEnterpriseRelationMapper.xml` - [ ] **Step 1: 新建关系实体** ```java @TableName("ccdi_intermediary_enterprise_relation") public class CcdiIntermediaryEnterpriseRelation implements Serializable { @TableId(type = IdType.AUTO) private Long id; private String intermediaryBizId; private String socialCreditCode; private String relationPersonPost; private String remark; } ``` - [ ] **Step 2: 新建关系新增 / 编辑 DTO** 新增 DTO 需要校验: ```java @NotBlank(message = "统一社会信用代码不能为空") private String socialCreditCode; ``` - [ ] **Step 3: 新建关系 VO** VO 需要联查展示: ```java private Long id; private String intermediaryBizId; private String intermediaryName; private String intermediaryPersonId; private String socialCreditCode; private String enterpriseName; private String relationPersonPost; private String remark; private Date createTime; ``` - [ ] **Step 4: 新建 Mapper 与 XML** 需要提供: ```xml