ccdi/openspec/changes/enhance-intermediary-with-detailed-fields/proposal.md

Proposal: 增强中介黑名单字段并实现类型化模板导入

Change ID

enhance-intermediary-with-detailed-fields

Summary

增强中介黑名单功能，添加个人和机构类型的详细字段，实现类型化的模板下载和导入功能，并添加详情展示接口，根据中介类型展示不同的字段信息。

Motivation

目前中介黑名单功能存在以下问题：

1. 字段过于简单，只有基础的姓名/机构名称、证件号、中介类型、状态、备注
2. 无法区分个人和机构的不同信息需求
3. 只有一个通用的导入模板，无法满足不同类型的详细数据录入
4. 缺少详情展示接口，无法查看完整的个人或机构信息

业务需求：

1. 个人中介需要记录：人员类型、性别、证件类型、手机号码、微信号、联系地址、所在公司、职位、关联关系等详细信息
2. 机构中介需要记录：统一社会信用代码、主体类型、企业性质、行业分类、成立日期、注册地址、法定代表人、股东等详细信息
3. 需要分开的个人和机构导入模板，便于用户分别录入不同类型的数据
4. 需要详情接口展示完整的个人或机构信息

Scope

本提案实现以下功能：

包含的功能

• 1.1 数据库字段扩展

  • 为个人类型添加详细字段（人员类型、性别、证件类型、手机号码、微信号等）
  • 为机构类型添加详细字段（统一社会信用代码、主体类型、企业性质、法定代表人、股东等）
  • 保持现有字段的向后兼容性

• 1.2 模板下载功能增强

  • 个人中介模板下载（包含个人专属字段）
  • 机构中介模板下载（包含机构专属字段）

• 1.3 导入功能增强

  • 支持个人中介批量导入
  • 支持机构中介批量导入
  • 根据模板类型自动识别中介类型

• 1.4 详情展示接口

  • 根据中介类型返回不同的字段信息
  • 个人类型返回个人详细字段
  • 机构类型返回机构详细字段

• 1.5 列表接口优化

  • 保持列表接口简洁，只显示核心字段
  • 支持按新增字段进行筛选

明确排除

• 前端页面的修改（后续独立变更）
• 数据迁移脚本（旧数据保持原样，新字段可为空）

Proposed Design

详见 design.md

Alternatives Considered

选项1：分表存储（个人表和机构表分离）

优点：

• 字段分离清晰
• 查询性能可能更好（表更小）

缺点：

• 需要维护多个表和关联关系
• 列表查询需要联合查询
• 导入导出逻辑复杂化
• 不符合现有设计思路

决定：不采用。单表设计更简洁，通过中介类型区分即可满足需求。

选项2：使用 JSON 字段存储扩展信息

优点：

• 灵活性高，易于扩展
• 不需要修改表结构

缺点：

• 不利于按扩展字段查询和筛选
• 不利于数据验证和约束
• 导入导出逻辑复杂

决定：不采用。使用独立的字段更有利于数据管理和查询。

选项3：在现有基础上添加字段

优点：

• 保持向后兼容
• 实现简单直接

缺点：

• 表会有很多字段（约40+个）
• 个人和机构字段混在一起

决定：采用。这是最直接的方案，通过业务逻辑区分使用哪些字段，数据库层面允许字段为空。

Impact

后端影响

• 数据库：扩展 ccdi_intermediary_blacklist 表，添加约30个新字段
• 实体类：CcdiIntermediaryBlacklist 添加新字段属性
• DTO：创建 CcdiIntermediaryPersonAddDTO 和 CcdiIntermediaryEntityAddDTO
• VO：创建 CcdiIntermediaryPersonDetailVO 和 CcdiIntermediaryEntityDetailVO
• Excel：创建 CcdiIntermediaryPersonExcel 和 CcdiIntermediaryEntityExcel
• Controller：添加两个模板下载接口，修改详情接口
• Service：扩展导入逻辑，支持不同类型的模板

前端影响

• API 接口变更：需要调用新的模板下载接口和详情接口
• 详情页面需要根据类型显示不同字段

数据库影响

• 扩展现有表，添加新字段（默认允许 NULL，保持向后兼容）

Dependencies

• 依赖现有 ccdi_intermediary_blacklist 表和基础功能
• 依赖 EasyExcel 进行 Excel 导入导出

Related Changes

• add-intermediary-blacklist - 基础中介黑名单功能

Open Questions

1. 旧数据处理：

   • 现有数据如何处理？
   • 建议：保持不变，新字段为空，用户可后续编辑补充

2. 必填字段：

   • 新增字段哪些设为必填？
   • 建议：除核心字段外，新字段都设为可选，便于分阶段完善数据

3. 详情接口设计：

   • 是分开的两个接口还是一个接口根据类型返回不同 VO？
   • 建议：一个接口，根据中介类型返回不同的 VO 结构

Success Criteria

• 数据库表扩展完成，添加个人和机构的详细字段
• 可以下载个人中介专用导入模板
• 可以下载机构中介专用导入模板
• 可以使用个人模板批量导入个人中介数据
• 可以使用机构模板批量导入机构中介数据
• 详情接口根据类型返回完整的字段信息
• 现有功能保持正常运行，向后兼容

References

• doc/中介人员信息表.csv
• doc/中介主体信息表.csv
• 现有中介黑名单设计