# 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](./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)
- [doc/中介主体信息表.csv](../../../doc/中介主体信息表.csv)
- [现有中介黑名单设计](../add-intermediary-blacklist/design.md)