11 KiB
11 KiB
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
任务执行顺序建议
- 第一周：完成阶段一（数据库扩展）和阶段二（实体类和 DTO/VO）
- 第二周：完成阶段三（Excel 类）和阶段四（Service 层）
- 第三周：完成阶段五（Controller 层）和阶段六（字典数据）
- 第四周：完成阶段七（测试）和阶段八（文档更新）
并行化建议
- 任务 2.2 和 2.3 可以并行开发
- 任务 2.4 和 2.5 可以并行开发
- 任务 3.1 和 3.2 可以并行开发
- 任务 4.3 和 4.4 可以并行开发
- 任务 5.1 和 5.2 可以并行开发
关键里程碑
- 里程碑 1：数据库扩展完成（任务 1.2）
- 里程碑 2：后端实体类和 DTO/VO 完成（任务 2.5）
- 里程碑 3：Excel 类创建完成（任务 3.2）
- 里程碑 4：Service 层实现完成（任务 4.4）
- 里程碑 5：Controller 层实现完成（任务 5.3）
- 里程碑 6：测试通过，文档更新完成（任务 8.2）