# Proposal: 添加中介人员黑名单管理模块

## Change ID
`add-intermediary-blacklist`

## Summary
添加中介人员黑名单管理模块，实现外部中介人员/机构黑名单库的建立和维护。该模块支持 Excel 模板下载、批量导入、增删改查等功能，是系统中信息维护模块的核心子功能之一。

## Motivation
目前系统缺少中介人员黑名单管理功能。用户需要：
1. 建立并维护外部中介人员/机构黑名单库
2. 通过 Excel 批量导入中介名单数据
3. 对中介名单进行增、删、改、查操作
4. 支持按姓名、证件号、机构名称等条件查询
5. 在项目工作台中选择确认后的可疑名单
6. 当员工交易对手命中该库时，系统自动产生高风险预警

## Scope
本提案实现以下功能：

### 包含的功能
- **3.1.1 名单导入**
  - Excel 模板下载（包含必填字段示例）
  - Excel 批量导入中介名单
  - 导入数据验证与错误提示

- **3.1.2 名单维护**
  - 新增中介信息（个人/机构）
  - 编辑中介信息
  - 删除中介信息（带使用检查）
  - 批量删除

- **3.1.3 名单查询**
  - 按姓名/机构名称模糊搜索
  - 按证件号精确搜索
  - 按中介类型筛选（个人/机构）
  - 按状态筛选（有效/失效）

- **3.1.4 名单导出**
  - 导出当前查询结果为 Excel

### 明确排除
- **3.1.5 名单选择**（在项目工作台中选择名单的功能，属于项目工作台模块）
- **3.1.6 自动预警**（命中黑名单产生预警的功能，属于风险分析模块）

## Proposed Design
详见 [design.md](./design.md)

## Alternatives Considered

### 选项1：使用若依代码生成器
**优点**：
- 快速生成标准 CRUD 代码
- 自动生成前端页面和 API
- 符合项目基本规范

**缺点**：
- 需要手动调整 Excel 导入导出逻辑
- 需要手动添加数据验证规则
- 需要手动处理个人/机构两种类型的差异显示

**决定**：部分采用。使用代码生成器生成基础 CRUD 代码，然后手动添加 Excel 导入导出和业务验证逻辑。

### 选项2：完全自定义开发
**优点**：
- 完全控制实现细节
- 可以根据业务需求灵活定制

**缺点**：
- 开发周期较长
- 需要确保代码风格与若依框架一致

**决定**：不采用。中介黑名单管理是标准 CRUD 功能，使用代码生成器可提高开发效率。

## Impact

### 后端影响
- 新建 `ruoyi-dpc` 模块（如果不存在），与若依框架代码分离
- 新增表：`ccdi_intermediary_blacklist`（中介黑名单主表）
- 新增权限：`dpc:intermediary:list`, `dpc:intermediary:query`, `dpc:intermediary:add`, `dpc:intermediary:edit`, `dpc:intermediary:remove`, `dpc:intermediary:export`, `dpc:intermediary:import`
- Controller 层：`ruoyi-dpc/src/main/java/com/ruoyi/dpc/controller/CcdiIntermediaryBlacklistController.java`

### 前端影响
- 新增视图：`ruoyi-ui/src/views/dpcIntermediary/`
- 新增 API：`ruoyi-ui/src/api/dpcIntermediary.js`
- 新增菜单：信息维护 > 中介库管理（注意与数据库中菜单表进行联动修改）

### 数据库影响
- 新增表：`ccdi_intermediary_blacklist`

## Dependencies
- 依赖 EasyExcel 进行 Excel 导入导出（参考 `replace-poi-with-easyexcel` change）
- 依赖若依框架的文件上传功能
- 依赖若依框架的权限系统

## Related Changes
- `replace-poi-with-easyexcel` - 依赖 EasyExcel 替换完成后的 Excel 工具

## Open Questions
1. **证件号校验**：
   - 是否需要添加格式校验？
   - 建议：添加基本格式校验，但不强制要求（可能是历史数据）

2. **删除前的使用检查**：
   - 如何判断中介信息是否在项目中使用？
   - 建议：暂时不实现使用检查，允许直接删除（可在后续版本中添加关联表）

3. **中介类型的数据结构**：
   - 个人和机构是否分开存储？
   - 建议：使用同一张表，通过 `intermediary_type` 字段区分

## Success Criteria
- [ ] 用户可以下载 Excel 导入模板
- [ ] 用户可以通过 Excel 批量导入中介名单
- [ ] 用户可以新增中介信息（个人/机构）
- [ ] 用户可以编辑中介信息
- [ ] 用户可以删除中介信息
- [ ] 用户可以按多种条件查询中介名单
- [ ] 用户可以导出查询结果为 Excel
- [ ] 导入时进行数据验证并提示错误

## References
- [模块设计文档](../../../doc/modules/03-信息维护模块.md)
- [若依开发文档](https://doc.ruoyi.vip/)