182 lines
7.8 KiB
Markdown
182 lines
7.8 KiB
Markdown
# 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 层
|