# Spec: 中介黑名单详细字段与类型化导入

## ADDED Requirements

### Requirement: 支持个人和机构类型的不同字段存储
系统必须能够为个人和机构类型的中介存储不同的字段信息，所有新增字段默认为可选，以保持向后兼容性。

#### Scenario: 个人中介存储详细信息
**Given** 用户创建或编辑个人类型的中介
**When** 填写个人专属字段（人员类型、性别、证件类型、手机号码等）
**Then** 系统应将这些字段保存到数据库
**And** 个人专属字段应与机构专属字段分开存储在同一表中

#### Scenario: 机构中介存储详细信息
**Given** 用户创建或编辑机构类型的中介
**When** 填写机构专属字段（统一社会信用代码、主体类型、法定代表人等）
**Then** 系统应将这些字段保存到数据库
**And** 机构专属字段应与个人专属字段分开存储在同一表中

#### Scenario: 向后兼容性保持
**Given** 系统中存在旧的中介数据（只有基础字段）
**When** 查询或编辑这些旧数据
**Then** 系统应正常工作
**And** 新增字段应允许为空

### Requirement: 支持个人和机构分离的模板下载
系统必须提供独立的个人和机构中介导入模板下载功能。

#### Scenario: 下载个人中介模板
**Given** 用户在中介黑名单管理页面
**When** 点击"下载个人模板"按钮
**Then** 系统应生成包含个人专属字段的 Excel 模板
**And** 模板应包含：姓名、人员类型、人员子类型、性别、证件类型、证件号码、手机号码、微信号、联系地址、所在公司、职位、关联人员ID、关联关系、状态、备注
**And** 模板应包含示例数据便于用户理解

#### Scenario: 下载机构中介模板
**Given** 用户在中介黑名单管理页面
**When** 点击"下载机构模板"按钮
**Then** 系统应生成包含机构专属字段的 Excel 模板
**And** 模板应包含：机构名称、统一社会信用代码、主体类型、企业性质、行业分类、所属行业、成立日期、注册地址、法定代表人、法定代表人证件类型、法定代表人证件号码、股东1-5、状态、备注
**And** 模板应包含示例数据便于用户理解

### Requirement: 支持个人和机构分离的批量导入
系统必须支持使用个人和机构专用模板进行批量导入，并根据模板类型自动设置中介类型。

#### Scenario: 使用个人模板导入个人中介
**Given** 用户准备了一个包含个人中介数据的 Excel 文件
**When** 用户通过"导入个人数据"接口上传文件
**Then** 系统应解析 Excel 数据
**And** 自动设置中介类型为"个人"（1）
**And** 验证必填字段（姓名、证件号码、状态）
**And** 验证可选字段的长度限制
**And** 将数据保存到数据库
**And** 返回导入结果统计（成功数、失败数）

#### Scenario: 使用机构模板导入机构中介
**Given** 用户准备了一个包含机构中介数据的 Excel 文件
**When** 用户通过"导入机构数据"接口上传文件
**Then** 系统应解析 Excel 数据
**And** 自动设置中介类型为"机构"（2）
**And** 验证必填字段（机构名称、状态）
**And** 验证可选字段的长度限制
**And** 将数据保存到数据库
**And** 返回导入结果统计（成功数、失败数）

#### Scenario: 导入数据验证与错误提示
**Given** 用户上传的 Excel 文件包含验证失败的数据
**When** 系统执行导入
**Then** 系统应记录每一行的验证错误
**And** 失败数据不应写入数据库
**And** 返回详细的错误信息，包括行号和错误原因

#### Scenario: 支持更新模式导入
**Given** 用户选择"更新支持"模式
**And** Excel 中包含已存在的中介（通过证件号或统一社会信用代码判断）
**When** 执行导入
**Then** 系统应更新现有记录而不是创建新记录

### Requirement: 支持类型化的详情展示
系统必须提供详情接口，根据中介类型返回包含不同字段的详情信息。

#### Scenario: 查询个人中介详情
**Given** 数据库中存在个人类型的中介记录
**When** 用户调用详情接口查询该记录
**Then** 系统应返回包含个人专属字段的详情 VO
**And** 详情应包含：核心字段 + 个人专属字段（人员类型、性别、证件类型、手机号码、微信号、联系地址、所在公司、职位、关联关系等）
**And** 机构专属字段应不返回或为 null

#### Scenario: 查询机构中介详情
**Given** 数据库中存在机构类型的中介记录
**When** 用户调用详情接口查询该记录
**Then** 系统应返回包含机构专属字段的详情 VO
**And** 详情应包含：核心字段 + 机构专属字段（统一社会信用代码、主体类型、企业性质、法定代表人、股东等）
**And** 个人专属字段应不返回或为 null

#### Scenario: 详情接口返回类型自动识别
**Given** 用户调用详情接口，只提供中介ID
**When** 系统查询到该中介记录
**Then** 系统应根据中介类型自动返回对应类型的 VO
**And** 个人类型返回 CcdiIntermediaryPersonDetailVO
**And** 机构类型返回 CcdiIntermediaryEntityDetailVO

### Requirement: 保持现有功能兼容性
所有新增功能必须保持现有接口和功能的正常运行。

#### Scenario: 列表接口保持简洁
**Given** 用户调用中介黑名单列表接口
**When** 系统返回列表数据
**Then** 应保持现有的简洁字段结构
**And** 列表 VO 应只包含：中介ID、姓名/机构名称、证件号、中介类型、状态、创建时间等核心字段
**And** 不应包含新增的详细字段

#### Scenario: 现有导入接口保持可用
**Given** 用户使用原有的通用导入模板和接口
**When** 执行导入操作
**Then** 系统应正常处理
**And** 兼容只有基础字段的数据

#### Scenario: 现有新增/编辑接口保持可用
**Given** 用户使用现有的新增/编辑接口
**When** 只填写基础字段
**Then** 系统应正常保存
**And** 新增详细字段应保持为空或默认值

### Requirement: 支持按新增字段进行筛选
列表查询接口应支持按新增字段进行筛选。

#### Scenario: 按人员类型筛选个人中介
**Given** 用户在列表页面
**When** 选择人员类型筛选条件（如"中介"）
**Then** 系统应返回匹配该人员类型的个人中介记录

#### Scenario: 按企业性质筛选机构中介
**Given** 用户在列表页面
**When** 选择企业性质筛选条件（如"民企"）
**Then** 系统应返回匹配该企业性质的机构中介记录

#### Scenario: 按数据来源筛选
**Given** 用户在列表页面
**When** 选择数据来源筛选条件（如"批量导入"）
**Then** 系统应返回匹配该数据来源的所有中介记录

### Requirement: 字段加密存储
敏感字段必须进行加密存储。

#### Scenario: 手机号码加密
**Given** 用户输入或导入手机号码
**When** 数据保存到数据库
**Then** 手机号码应加密存储
**And** 查询时解密返回

#### Scenario: 证件号码加密
**Given** 用户输入或导入证件号码（个人或法定代表人）
**When** 数据保存到数据库
**Then** 证件号码应加密存储
**And** 查询时解密返回

## MODIFIED Requirements

无。本提案为纯新增功能，不修改现有需求。

## REMOVED Requirements

无。本提案不删除任何现有功能。

## Cross-References

### Related Capabilities
- `intermediary-blacklist-management` (基础中介黑名单管理功能)
- `excel-import-export` (Excel 导入导出基础功能)

### Dependencies
- 依赖现有 `ccdi_intermediary_blacklist` 表结构
- 依赖 EasyExcel 工具类
- 依赖现有权限控制体系

### Sequencing
1. 首先完成数据库表扩展
2. 然后更新实体类和 DTO/VO
3. 实现 Excel 类和导入导出逻辑
4. 最后更新 Controller 和 Service 层