359 lines
11 KiB
Markdown
359 lines
11 KiB
Markdown
# Tasks: 增强中介黑名单字段并实现类型化模板导入
|
||
|
||
## 任务概述
|
||
|
||
本任务列表将指导完成中介黑名单功能的增强，包括添加个人和机构类型的详细字段、实现类型化的模板下载和导入功能，以及添加详情展示接口。
|
||
|
||
## 任务清单
|
||
|
||
### 阶段一：数据库扩展
|
||
|
||
#### 任务 1.1：生成数据库变更 SQL 脚本
|
||
- [ ] 编写 ALTER TABLE 语句，添加个人类型字段（11个字段）
|
||
- [ ] 编写 ALTER TABLE 语句，添加机构类型字段（15个字段）
|
||
- [ ] 编写 ALTER TABLE 语句，添加通用字段（1个字段：data_source）
|
||
- [ ] 添加必要的索引（idx_credit_code, idx_phone_number）
|
||
- [ ] 将 SQL 脚本保存到 `sql/` 目录，命名格式：`ccdi_intermediary_enhance_YYYYMMDD.sql`
|
||
|
||
**验证方式**：SQL 语法检查，确保所有字段正确添加
|
||
|
||
**依赖**：无
|
||
|
||
---
|
||
|
||
#### 任务 1.2：执行数据库变更
|
||
- [ ] 在开发环境执行 SQL 脚本
|
||
- [ ] 验证表结构变更成功
|
||
- [ ] 确认所有字段添加成功且类型正确
|
||
- [ ] 确认索引创建成功
|
||
|
||
**验证方式**：DESCRIBE ccdi_intermediary_blacklist; SHOW INDEX FROM ccdi_intermediary_blacklist;
|
||
|
||
**依赖**：任务 1.1
|
||
|
||
---
|
||
|
||
### 阶段二：后端实体类和 DTO/VO 更新
|
||
|
||
#### 任务 2.1：更新实体类 CcdiIntermediaryBlacklist
|
||
- [ ] 添加个人类型字段属性（11个）
|
||
- [ ] 添加机构类型字段属性（15个）
|
||
- [ ] 添加通用字段属性（1个：dataSource）
|
||
- [ ] 保持现有字段不变，确保向后兼容
|
||
- [ ] 使用 Lombok @Data 注解
|
||
|
||
**验证方式**：编译通过，无语法错误
|
||
|
||
**依赖**：任务 1.2
|
||
|
||
---
|
||
|
||
#### 任务 2.2：创建个人中介 DTO
|
||
- [ ] 创建 `CcdiIntermediaryPersonAddDTO.java`
|
||
- [ ] 添加个人专属字段
|
||
- [ ] 添加适当的验证注解（@NotBlank, @Size 等）
|
||
- [ ] 实现 Serializable 接口
|
||
|
||
**验证方式**：编译通过，DTO 字段完整
|
||
|
||
**依赖**：任务 2.1
|
||
|
||
---
|
||
|
||
#### 任务 2.3：创建机构中介 DTO
|
||
- [ ] 创建 `CcdiIntermediaryEntityAddDTO.java`
|
||
- [ ] 添加机构专属字段
|
||
- [ ] 添加适当的验证注解
|
||
- [ ] 实现 Serializable 接口
|
||
|
||
**验证方式**：编译通过，DTO 字段完整
|
||
|
||
**依赖**：任务 2.1
|
||
|
||
---
|
||
|
||
#### 任务 2.4：创建个人详情 VO
|
||
- [ ] 创建 `CcdiIntermediaryPersonDetailVO.java`
|
||
- [ ] 包含核心字段 + 个人专属字段
|
||
- [ ] 添加关联字段名称（如 genderName, certificateTypeName）
|
||
- [ ] 添加审计字段
|
||
- [ ] 使用 @JsonFormat 注解格式化日期
|
||
|
||
**验证方式**：编译通过，VO 字段完整
|
||
|
||
**依赖**：任务 2.2
|
||
|
||
---
|
||
|
||
#### 任务 2.5：创建机构详情 VO
|
||
- [ ] 创建 `CcdiIntermediaryEntityDetailVO.java`
|
||
- [ ] 包含核心字段 + 机构专属字段
|
||
- [ ] 添加关联字段名称
|
||
- [ ] 添加审计字段
|
||
- [ ] 使用 @JsonFormat 注解格式化日期
|
||
|
||
**验证方式**：编译通过，VO 字段完整
|
||
|
||
**依赖**：任务 2.3
|
||
|
||
---
|
||
|
||
### 阶段三：Excel 类创建
|
||
|
||
#### 任务 3.1：创建个人中介 Excel 类
|
||
- [ ] 创建 `CcdiIntermediaryPersonExcel.java`
|
||
- [ ] 使用 @ExcelProperty 注解定义 Excel 列
|
||
- [ ] 使用 @ColumnWidth 注解设置列宽
|
||
- [ ] 字段顺序：姓名 -> 人员类型 -> ... -> 备注（共14列）
|
||
- [ ] **不在模板中显示**：状态、数据来源字段（由系统自动设置）
|
||
- [ ] **添加字典下拉框注解**：
|
||
- `@DictDropdown(dictType = "ccdi_indiv_gender")` - 性别字段
|
||
- `@DictDropdown(dictType = "ccdi_certificate_type")` - 证件类型字段
|
||
|
||
**验证方式**：编译通过，Excel 注解正确
|
||
|
||
**依赖**：任务 2.2
|
||
|
||
---
|
||
|
||
#### 任务 3.2：创建机构中介 Excel 类
|
||
- [ ] 创建 `CcdiIntermediaryEntityExcel.java`
|
||
- [ ] 使用 @ExcelProperty 注解定义 Excel 列
|
||
- [ ] 使用 @ColumnWidth 注解设置列宽
|
||
- [ ] 字段顺序：机构名称 -> 统一社会信用代码 -> ... -> 备注（共17列）
|
||
- [ ] **不在模板中显示**：状态、数据来源字段（由系统自动设置）
|
||
- [ ] **添加字典下拉框注解**：
|
||
- `@DictDropdown(dictType = "ccdi_entity_type")` - 主体类型字段
|
||
- `@DictDropdown(dictType = "ccdi_enterprise_nature")` - 企业性质字段
|
||
|
||
**验证方式**：编译通过，Excel 注解正确
|
||
|
||
**依赖**：任务 2.3
|
||
|
||
---
|
||
|
||
### 阶段四：Service 层实现
|
||
|
||
#### 任务 4.1：扩展 Service 接口
|
||
- [ ] 在 `ICcdiIntermediaryBlacklistService` 中添加新方法：
|
||
- `Object selectIntermediaryDetailById(Long intermediaryId)`
|
||
- `String importPersonIntermediary(List<CcdiIntermediaryPersonExcel> list, boolean isUpdateSupport)`
|
||
- `String importEntityIntermediary(List<CcdiIntermediaryEntityExcel> list, boolean isUpdateSupport)`
|
||
|
||
**验证方式**：编译通过，接口方法签名正确
|
||
|
||
**依赖**：任务 2.4, 2.5, 3.1, 3.2
|
||
|
||
---
|
||
|
||
#### 任务 4.2：实现详情查询方法
|
||
- [ ] 在 `CcdiIntermediaryBlacklistServiceImpl` 中实现 `selectIntermediaryDetailById`
|
||
- [ ] 根据中介类型返回不同的 VO
|
||
- [ ] 个人类型返回 `CcdiIntermediaryPersonDetailVO`
|
||
- [ ] 机构类型返回 `CcdiIntermediaryEntityDetailVO`
|
||
- [ ] 填充关联字段名称（字典转换）
|
||
|
||
**验证方式**：单元测试验证不同类型返回正确的 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 脚本
|
||
- [ ] 添加人员类型字典（ccdi_person_type）
|
||
- [ ] 添加人员子类型字典（ccdi_person_sub_type）
|
||
- [ ] **添加性别字典（ccdi_indiv_gender）** - 用于个人中介下拉框
|
||
- [ ] **添加证件类型字典（ccdi_certificate_type）** - 用于个人中介下拉框
|
||
- [ ] **添加主体类型字典（ccdi_entity_type）** - 用于机构中介下拉框
|
||
- [ ] **添加企业性质字典（ccdi_enterprise_nature）** - 用于机构中介下拉框
|
||
- [ ] 添加数据来源字典（ccdi_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）
|