145 lines
5.5 KiB
Markdown
145 lines
5.5 KiB
Markdown
# 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)
|