ccdi/openspec/changes/enhance-intermediary-with-detailed-fields/tasks.md

# Tasks: 增强中介黑名单字段并实现类型化模板导入

## 任务概述

本任务列表将指导完成中介黑名单功能的增强，包括添加个人和机构类型的详细字段、实现类型化的模板下载和导入功能，以及添加详情展示接口。

## 任务清单

### 阶段一：数据库扩展

#### 任务 1.1：生成数据库变更 SQL 脚本
- [ ] 编写 ALTER TABLE 语句，添加个人类型字段（11个字段）
- [ ] 编写 ALTER TABLE 语句，添加机构类型字段（15个字段）
- [ ] 编写 ALTER TABLE 语句，添加通用字段（1个字段：data_source）
- [ ] 添加必要的索引（idx_credit_code, idx_phone_number）
- [ ] 将 SQL 脚本保存到 `sql/` 目录，命名格式：`dpc_intermediary_enhance_YYYYMMDD.sql`

**验证方式**：SQL 语法检查，确保所有字段正确添加

**依赖**：无

---

#### 任务 1.2：执行数据库变更
- [ ] 在开发环境执行 SQL 脚本
- [ ] 验证表结构变更成功
- [ ] 确认所有字段添加成功且类型正确
- [ ] 确认索引创建成功

**验证方式**：DESCRIBE dpc_intermediary_blacklist; SHOW INDEX FROM dpc_intermediary_blacklist;

**依赖**：任务 1.1

---

### 阶段二：后端实体类和 DTO/VO 更新

#### 任务 2.1：更新实体类 DpcIntermediaryBlacklist
- [ ] 添加个人类型字段属性（11个）
- [ ] 添加机构类型字段属性（15个）
- [ ] 添加通用字段属性（1个：dataSource）
- [ ] 保持现有字段不变，确保向后兼容
- [ ] 使用 Lombok @Data 注解

**验证方式**：编译通过，无语法错误

**依赖**：任务 1.2

---

#### 任务 2.2：创建个人中介 DTO
- [ ] 创建 `DpcIntermediaryPersonAddDTO.java`
- [ ] 添加个人专属字段
- [ ] 添加适当的验证注解（@NotBlank, @Size 等）
- [ ] 实现 Serializable 接口

**验证方式**：编译通过，DTO 字段完整

**依赖**：任务 2.1

---

#### 任务 2.3：创建机构中介 DTO
- [ ] 创建 `DpcIntermediaryEntityAddDTO.java`
- [ ] 添加机构专属字段
- [ ] 添加适当的验证注解
- [ ] 实现 Serializable 接口

**验证方式**：编译通过，DTO 字段完整

**依赖**：任务 2.1

---

#### 任务 2.4：创建个人详情 VO
- [ ] 创建 `DpcIntermediaryPersonDetailVO.java`
- [ ] 包含核心字段 + 个人专属字段
- [ ] 添加关联字段名称（如 genderName, certificateTypeName）
- [ ] 添加审计字段
- [ ] 使用 @JsonFormat 注解格式化日期

**验证方式**：编译通过，VO 字段完整

**依赖**：任务 2.2

---

#### 任务 2.5：创建机构详情 VO
- [ ] 创建 `DpcIntermediaryEntityDetailVO.java`
- [ ] 包含核心字段 + 机构专属字段
- [ ] 添加关联字段名称
- [ ] 添加审计字段
- [ ] 使用 @JsonFormat 注解格式化日期

**验证方式**：编译通过，VO 字段完整

**依赖**：任务 2.3

---

### 阶段三：Excel 类创建

#### 任务 3.1：创建个人中介 Excel 类
- [ ] 创建 `DpcIntermediaryPersonExcel.java`
- [ ] 使用 @ExcelProperty 注解定义 Excel 列
- [ ] 使用 @ColumnWidth 注解设置列宽
- [ ] 字段顺序：姓名 -> 人员类型 -> ... -> 备注（共14列）
- [ ] **不在模板中显示**：状态、数据来源字段（由系统自动设置）
- [ ] **添加字典下拉框注解**：
  - `@DictDropdown(dictType = "dpc_indiv_gender")` - 性别字段
  - `@DictDropdown(dictType = "dpc_certificate_type")` - 证件类型字段

**验证方式**：编译通过，Excel 注解正确

**依赖**：任务 2.2

---

#### 任务 3.2：创建机构中介 Excel 类
- [ ] 创建 `DpcIntermediaryEntityExcel.java`
- [ ] 使用 @ExcelProperty 注解定义 Excel 列
- [ ] 使用 @ColumnWidth 注解设置列宽
- [ ] 字段顺序：机构名称 -> 统一社会信用代码 -> ... -> 备注（共17列）
- [ ] **不在模板中显示**：状态、数据来源字段（由系统自动设置）
- [ ] **添加字典下拉框注解**：
  - `@DictDropdown(dictType = "dpc_entity_type")` - 主体类型字段
  - `@DictDropdown(dictType = "dpc_enterprise_nature")` - 企业性质字段

**验证方式**：编译通过，Excel 注解正确

**依赖**：任务 2.3

---

### 阶段四：Service 层实现

#### 任务 4.1：扩展 Service 接口
- [ ] 在 `IDpcIntermediaryBlacklistService` 中添加新方法：
  - `Object selectIntermediaryDetailById(Long intermediaryId)`
  - `String importPersonIntermediary(List<DpcIntermediaryPersonExcel> list, boolean isUpdateSupport)`
  - `String importEntityIntermediary(List<DpcIntermediaryEntityExcel> list, boolean isUpdateSupport)`

**验证方式**：编译通过，接口方法签名正确

**依赖**：任务 2.4, 2.5, 3.1, 3.2

---

#### 任务 4.2：实现详情查询方法
- [ ] 在 `DpcIntermediaryBlacklistServiceImpl` 中实现 `selectIntermediaryDetailById`
- [ ] 根据中介类型返回不同的 VO
- [ ] 个人类型返回 `DpcIntermediaryPersonDetailVO`
- [ ] 机构类型返回 `DpcIntermediaryEntityDetailVO`
- [ ] 填充关联字段名称（字典转换）

**验证方式**：单元测试验证不同类型返回正确的 VO

**依赖**：任务 4.1

---

#### 任务 4.3：实现个人中介导入方法
- [ ] 实现 `importPersonIntermediary` 方法
- [ ] 验证必填字段（姓名、证件号码、状态）
- [ ] 验证字段长度限制
- [ ] 设置中介类型为"1"（个人）
- [ ] 支持更新模式（通过证件号判断是否已存在）
- [ ] 返回导入结果统计

**验证方式**：单元测试验证导入逻辑和错误处理

**依赖**：任务 4.1

---

#### 任务 4.4：实现机构中介导入方法
- [ ] 实现 `importEntityIntermediary` 方法
- [ ] 验证必填字段（机构名称、状态）
- [ ] 验证字段长度限制
- [ ] 设置中介类型为"2"（机构）
- [ ] 支持更新模式（通过统一社会信用代码判断是否已存在）
- [ ] 返回导入结果统计

**验证方式**：单元测试验证导入逻辑和错误处理

**依赖**：任务 4.1

---

### 阶段五：Controller 层实现

#### 任务 5.1：添加模板下载接口（支持字典下拉框）
- [ ] 添加 `POST /dpc/intermediary/importPersonTemplate` 接口
- [ ] 添加 `POST /dpc/intermediary/importEntityTemplate` 接口
- [ ] 使用 `EasyExcelUtil.importTemplateWithDictDropdown()` 生成模板
- [ ] 添加 @Operation 注解用于 Swagger 文档
- [ ] 不需要权限控制（模板下载公开）

**验证方式**：
- 通过 Swagger UI 或 Postman 测试接口
- 下载模板后验证字典下拉框功能是否正常
- 验证下拉选项是否与字典数据一致

**依赖**：任务 3.1, 3.2, 6.1（确保字典数据已配置）

---

#### 任务 5.2：添加类型化导入接口
- [ ] 添加 `POST /dpc/intermediary/importPersonData` 接口
- [ ] 添加 `POST /dpc/intermediary/importEntityData` 接口
- [ ] 添加 updateSupport 参数支持更新模式
- [ ] 添加 @PreAuthorize 权限注解
- [ ] 添加 @Log 注解记录操作日志
- [ ] 添加 @Operation 注解用于 Swagger 文档

**验证方式**：通过 Swagger UI 或 Postman 测试接口

**依赖**：任务 4.3, 4.4

---

#### 任务 5.3：修改详情接口
- [ ] 修改 `GET /dpc/intermediary/{intermediaryId}` 接口
- [ ] 返回类型改为 Object（根据实际类型返回不同 VO）
- [ ] 调用新的 `selectIntermediaryDetailById` 方法
- [ ] 确保前端能够根据类型正确解析响应

**验证方式**：通过 Swagger UI 或 Postman 测试接口，验证不同类型返回不同结构

**依赖**：任务 4.2

---

### 阶段六：字典数据配置

#### 任务 6.1：创建字典数据 SQL 脚本
- [ ] 添加人员类型字典（dpc_person_type）
- [ ] 添加人员子类型字典（dpc_person_sub_type）
- [ ] **添加性别字典（dpc_indiv_gender）** - 用于个人中介下拉框
- [ ] **添加证件类型字典（dpc_certificate_type）** - 用于个人中介下拉框
- [ ] **添加主体类型字典（dpc_entity_type）** - 用于机构中介下拉框
- [ ] **添加企业性质字典（dpc_enterprise_nature）** - 用于机构中介下拉框
- [ ] 添加数据来源字典（dpc_data_source）
- [ ] 将 SQL 脚本保存到 `sql/` 目录

**验证方式**：SQL 语法检查

**依赖**：无

---

#### 任务 6.2：执行字典数据 SQL 并预热缓存
- [ ] 在开发环境执行字典数据 SQL
- [ ] 通过系统管理 > 字典管理验证字典数据
- [ ] **重要**：在每个字典类型页面点击"刷新缓存"按钮，确保字典数据加载到 Redis
- [ ] 验证字典缓存是否生效（可通过测试模板下载确认下拉框是否显示）

**验证方式**：
- 在系统界面中查看字典数据
- 下载模板验证下拉框功能
- 检查 Redis 缓存中的字典数据（`sys_dict_cache:*`）

**依赖**：任务 6.1

---

### 阶段七：测试

#### 任务 7.1：编写单元测试
- [ ] 测试详情查询方法（个人和机构）
- [ ] 测试个人中介导入方法
- [ ] 测试机构中介导入方法
- [ ] 测试数据验证逻辑
- [ ] 测试更新模式

**验证方式**：所有单元测试通过

**依赖**：任务 4.2, 4.3, 4.4

---

#### 任务 7.2：接口集成测试
- [ ] 测试模板下载接口（个人和机构）
- [ ] 测试数据导入接口（个人和机构）
- [ ] 测试详情查询接口
- [ ] 测试列表接口（确保不受影响）
- [ ] 测试现有新增/编辑接口（确保不受影响）

**验证方式**：生成测试脚本并执行，记录测试结果

**依赖**：任务 5.1, 5.2, 5.3

---

#### 任务 7.3：生成测试报告
- [ ] 生成可执行的测试脚本
- [ ] 执行测试并保存所有接口输出
- [ ] 生成测试用例报告（Markdown 格式）
- [ ] 报告保存到 `doc/` 目录

**验证方式**：测试报告完整，所有测试用例通过

**依赖**：任务 7.2

---

### 阶段八：文档更新

#### 任务 8.1：更新 API 文档
- [ ] 更新 `doc/中介黑名单API文档.md`
- [ ] 添加新增接口的文档：
  - 个人模板下载接口
  - 机构模板下载接口
  - 个人数据导入接口
  - 机构数据导入接口
  - 详情接口（说明返回类型变化）
- [ ] 更新数据模型说明

**验证方式**：文档与实际接口一致

**依赖**：任务 5.1, 5.2, 5.3

---

#### 任务 8.2：更新数据库设计文档
- [ ] 更新表结构说明
- [ ] 添加新字段说明
- [ ] 更新索引说明

**验证方式**：文档与实际表结构一致

**依赖**：任务 1.2

---

## 任务执行顺序建议

1. **第一周**：完成阶段一（数据库扩展）和阶段二（实体类和 DTO/VO）
2. **第二周**：完成阶段三（Excel 类）和阶段四（Service 层）
3. **第三周**：完成阶段五（Controller 层）和阶段六（字典数据）
4. **第四周**：完成阶段七（测试）和阶段八（文档更新）

## 并行化建议

- 任务 2.2 和 2.3 可以并行开发
- 任务 2.4 和 2.5 可以并行开发
- 任务 3.1 和 3.2 可以并行开发
- 任务 4.3 和 4.4 可以并行开发
- 任务 5.1 和 5.2 可以并行开发

## 关键里程碑

1. **里程碑 1**：数据库扩展完成（任务 1.2）
2. **里程碑 2**：后端实体类和 DTO/VO 完成（任务 2.5）
3. **里程碑 3**：Excel 类创建完成（任务 3.2）
4. **里程碑 4**：Service 层实现完成（任务 4.4）
5. **里程碑 5**：Controller 层实现完成（任务 5.3）
6. **里程碑 6**：测试通过，文档更新完成（任务 8.2）