wkc/ccdi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c278d11390844aac34a88b3e7f1f9ce874c5e17c
ccdi/docs/plans/backend/2026-04-17-enterprise-base-info-management-backend-implementation.md
wkc c278d11390 修复
2026-04-20 11:22:10 +08:00

13 KiB
Raw Blame History

实体库管理后端实施计划

For agentic workers: REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 新增独立的实体库管理后端链路，基于 ccdi_enterprise_base_info 支持分页查询、详情、新增、编辑、删除、异步导入、导入状态查询和失败记录查询。

Architecture: 复用现有 CcdiEnterpriseBaseInfo 实体与 Mapper，新增独立的 Controller、Service、DTO、VO、Excel 与导入服务，接口风格与员工信息维护保持一致。riskLevel、entSource、dataSource 统一通过枚举接口对外提供选项，导入采用严格新增策略，数据库重复和 Excel 内重复统一记为失败。

Tech Stack: Java 21, Spring Boot 3, MyBatis Plus, Redis, EasyExcel, JUnit 5, MySQL, Markdown

文件结构与职责

后端源码

  • ccdi-info-collection/src/main/java/com/ruoyi/info/collection/controller/CcdiEnterpriseBaseInfoController.java 实体库管理对外接口入口，提供 CRUD、导入模板、导入任务状态和失败记录查询。
  • ccdi-info-collection/src/main/java/com/ruoyi/info/collection/service/ICcdiEnterpriseBaseInfoService.java 定义实体库管理服务接口。
  • ccdi-info-collection/src/main/java/com/ruoyi/info/collection/service/ICcdiEnterpriseBaseInfoImportService.java 定义异步导入状态与失败记录查询接口。
  • ccdi-info-collection/src/main/java/com/ruoyi/info/collection/service/impl/CcdiEnterpriseBaseInfoServiceImpl.java 承接分页查询、详情、增删改和导入任务提交。
  • ccdi-info-collection/src/main/java/com/ruoyi/info/collection/service/impl/CcdiEnterpriseBaseInfoImportServiceImpl.java 处理异步导入、校验、失败记录落 Redis 与状态回写。
  • ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/dto/CcdiEnterpriseBaseInfoQueryDTO.java 定义查询条件。
  • ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/dto/CcdiEnterpriseBaseInfoAddDTO.java 定义新增入参和校验规则。
  • ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/dto/CcdiEnterpriseBaseInfoEditDTO.java 定义编辑入参与主键不可变约束。
  • ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/vo/CcdiEnterpriseBaseInfoVO.java 承接列表和详情返回。
  • ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/vo/EnterpriseBaseInfoImportFailureVO.java 承接导入失败记录回显。
  • ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/excel/CcdiEnterpriseBaseInfoExcel.java 定义导入模板列、导入字段和字典下拉。
  • ccdi-info-collection/src/main/java/com/ruoyi/info/collection/enums/EnterpriseRiskLevel.java 新增实体风险等级枚举。
  • ccdi-info-collection/src/main/java/com/ruoyi/info/collection/enums/EnterpriseSource.java 新增企业来源枚举。
  • ccdi-info-collection/src/main/java/com/ruoyi/info/collection/controller/CcdiEnumController.java 新增风险等级与企业来源选项接口。
  • ccdi-info-collection/src/main/java/com/ruoyi/info/collection/mapper/CcdiEnterpriseBaseInfoMapper.java 补充分页查询与批量导入方法声明。
  • ccdi-info-collection/src/main/resources/mapper/info/collection/CcdiEnterpriseBaseInfoMapper.xml 补充分页查询、结果映射、批量插入 SQL。

SQL

  • sql/migration/2026-04-17-add-enterprise-base-info-menu.sql 新增“实体库管理”菜单和功能权限。
  • sql/migration/2026-04-17-add-enterprise-base-info-dict-or-enum-seed.sql 如需初始化与导入模板一致的固定值说明，可在脚本中补充注释性或字典性数据；若最终走纯枚举接口，则只保留菜单 SQL。

测试

  • ccdi-info-collection/src/test/java/com/ruoyi/info/collection/service/CcdiEnterpriseBaseInfoServiceImplTest.java 校验新增、编辑、删除、详情和枚举值校验。
  • ccdi-info-collection/src/test/java/com/ruoyi/info/collection/service/CcdiEnterpriseBaseInfoImportServiceImplTest.java 校验导入重复失败、Excel 内重复失败和状态回写。
  • ccdi-info-collection/src/test/java/com/ruoyi/info/collection/mapper/CcdiEnterpriseBaseInfoMapperTest.java 校验分页 SQL 和结果映射关键片段。
  • ccdi-info-collection/src/test/java/com/ruoyi/info/collection/controller/CcdiEnumControllerTest.java 校验新增的枚举选项接口。

实施任务

Task 1: 搭建实体库管理 DTO / VO / Excel 契约

Files:

  • Create: ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/dto/CcdiEnterpriseBaseInfoQueryDTO.java

  • Create: ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/dto/CcdiEnterpriseBaseInfoAddDTO.java

  • Create: ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/dto/CcdiEnterpriseBaseInfoEditDTO.java

  • Create: ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/vo/CcdiEnterpriseBaseInfoVO.java

  • Create: ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/vo/EnterpriseBaseInfoImportFailureVO.java

  • Create: ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/excel/CcdiEnterpriseBaseInfoExcel.java

  • Reference: ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/CcdiEnterpriseBaseInfo.java

  • Reference: ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/excel/CcdiIntermediaryEntityExcel.java

  • 定义 QueryDTO，包含 enterpriseName、socialCreditCode、enterpriseType、enterpriseNature、industryClass、status、riskLevel、entSource。

  • 定义 AddDTO / EditDTO，完整覆盖单表维护字段，并给 socialCreditCode、enterpriseName、status、riskLevel、entSource、dataSource 加基础校验。

  • 在 EditDTO 中保持主键为必填，不新增改主键语义字段。

  • 定义 VO，补齐列表和详情所需字段，并预留 createTime 供前端表格展示。

  • 定义 Excel 对象，列顺序与页面表单一致，并为 enterpriseType、enterpriseNature、legalCertType 使用现有字典下拉；riskLevel、entSource、dataSource 保持文本列，后续由导入服务做枚举校验。

Task 2: 补齐风险等级与企业来源枚举出口

Files:

  • Create: ccdi-info-collection/src/main/java/com/ruoyi/info/collection/enums/EnterpriseRiskLevel.java

  • Create: ccdi-info-collection/src/main/java/com/ruoyi/info/collection/enums/EnterpriseSource.java

  • Modify: ccdi-info-collection/src/main/java/com/ruoyi/info/collection/controller/CcdiEnumController.java

  • 新增 EnterpriseRiskLevel 枚举，口径固定为 1/2/3 对应高/中/低风险，并提供 getCode()、getDesc()、getDescByCode()、contains()。

  • 新增 EnterpriseSource 枚举，口径固定为 GENERAL、EMP_RELATION、CREDIT_CUSTOMER、INTERMEDIARY、BOTH，并提供与现有 DataSource 一致的方法。

  • 在 CcdiEnumController 中新增 /enterpriseRiskLevel 与 /enterpriseSource 两个接口，返回 EnumOptionVO 列表。

  • 保持现有 /dataSource 不变，避免前端重复造轮子。

Task 3: 实现分页查询与 CRUD 服务链路

Files:

  • Modify: ccdi-info-collection/src/main/java/com/ruoyi/info/collection/mapper/CcdiEnterpriseBaseInfoMapper.java

  • Modify: ccdi-info-collection/src/main/resources/mapper/info/collection/CcdiEnterpriseBaseInfoMapper.xml

  • Create: ccdi-info-collection/src/main/java/com/ruoyi/info/collection/service/ICcdiEnterpriseBaseInfoService.java

  • Create: ccdi-info-collection/src/main/java/com/ruoyi/info/collection/service/impl/CcdiEnterpriseBaseInfoServiceImpl.java

  • Create: ccdi-info-collection/src/main/java/com/ruoyi/info/collection/controller/CcdiEnterpriseBaseInfoController.java

  • Reference: ccdi-info-collection/src/main/java/com/ruoyi/info/collection/controller/CcdiBaseStaffController.java

  • Reference: ccdi-info-collection/src/main/java/com/ruoyi/info/collection/service/impl/CcdiBaseStaffServiceImpl.java

  • 在 Mapper 中新增分页查询方法，按 QueryDTO 动态拼装筛选条件。

  • 在 Mapper XML 中新增结果映射和 selectEnterpriseBaseInfoPage SQL，输出 create_time、risk_level、ent_source、data_source 等字段。

  • 在 Service 接口中定义分页、详情、新增、编辑、删除、导出列表、导入任务提交方法。

  • 在 ServiceImpl 中实现主键唯一校验、编辑存在性校验、枚举值校验和删除批量处理。

  • 新建 Controller，接口路径统一使用 /ccdi/enterpriseBaseInfo，返回风格完全对齐员工信息维护。

  • 导入模板下载复用 EasyExcelUtil.importTemplateWithDictDropdown。

Task 4: 实现异步导入与失败记录查询

Files:

  • Create: ccdi-info-collection/src/main/java/com/ruoyi/info/collection/service/ICcdiEnterpriseBaseInfoImportService.java

  • Create: ccdi-info-collection/src/main/java/com/ruoyi/info/collection/service/impl/CcdiEnterpriseBaseInfoImportServiceImpl.java

  • Modify: ccdi-info-collection/src/main/java/com/ruoyi/info/collection/service/impl/CcdiEnterpriseBaseInfoServiceImpl.java

  • Modify: ccdi-info-collection/src/main/java/com/ruoyi/info/collection/controller/CcdiEnterpriseBaseInfoController.java

  • Reference: ccdi-info-collection/src/main/java/com/ruoyi/info/collection/service/impl/CcdiBaseStaffImportServiceImpl.java

  • Reference: ccdi-info-collection/src/main/java/com/ruoyi/info/collection/service/impl/CcdiIntermediaryEntityImportServiceImpl.java

  • 在 ServiceImpl 中提交导入任务，Redis key 建议使用 import:enterpriseBaseInfo:{taskId}。

  • 在导入服务中实现 Excel 行校验，数据库重复与 Excel 内重复统一生成失败记录。

  • 新增 riskLevel、entSource、dataSource 枚举校验，拒绝非法值。

  • 成功记录分批批量插入；导入不支持更新，不提供 updateSupport 分支逻辑。

  • 失败记录写入 Redis，状态统一支持 PROCESSING、SUCCESS、PARTIAL_SUCCESS。

  • Controller 补 /importData、/importStatus/{taskId}、/importFailures/{taskId} 三个接口，分页失败记录方式与员工信息维护一致。

Task 5: 补菜单 SQL 和权限口径

Files:

  • Create: sql/migration/2026-04-17-add-enterprise-base-info-menu.sql

  • Reference: sql/ccdi_staff_fmy_relation_menu.sql

  • Reference: sql/migration/2026-04-13-add-ccdi-account-info-menu.sql

  • 在“信息维护”目录下新增“实体库管理”菜单。

  • 菜单 path 固定为 enterpriseBaseInfo，component 固定为 ccdiEnterpriseBaseInfo/index。

  • 功能权限至少包含 list、query、add、edit、remove、import。

  • SQL 保持幂等写法，避免重复插入菜单。

Task 6: 补后端测试与验证命令

Files:

  • Create: ccdi-info-collection/src/test/java/com/ruoyi/info/collection/service/CcdiEnterpriseBaseInfoServiceImplTest.java

  • Create: ccdi-info-collection/src/test/java/com/ruoyi/info/collection/service/CcdiEnterpriseBaseInfoImportServiceImplTest.java

  • Create: ccdi-info-collection/src/test/java/com/ruoyi/info/collection/mapper/CcdiEnterpriseBaseInfoMapperTest.java

  • Create: ccdi-info-collection/src/test/java/com/ruoyi/info/collection/controller/CcdiEnumControllerTest.java

  • 为新增、编辑、删除、详情和枚举值校验补服务测试。

  • 为导入数据库重复失败、Excel 内重复失败补导入服务测试。

  • 为 Mapper XML 的分页查询关键 SQL 补测试或最小断言。

  • 为新增枚举接口补 Controller 测试。

  • 执行后端验证命令并记录结果。

验证命令

mvn -pl ccdi-info-collection -Dtest=CcdiEnterpriseBaseInfoServiceImplTest,CcdiEnterpriseBaseInfoImportServiceImplTest,CcdiEnterpriseBaseInfoMapperTest,CcdiEnumControllerTest test
mvn -pl ccdi-info-collection -DskipTests compile

执行结果

  • 实际测试命令：mvn -pl ccdi-info-collection -am -Dsurefire.failIfNoSpecifiedTests=false -Dtest=CcdiEnterpriseBaseInfoServiceImplTest,CcdiEnterpriseBaseInfoImportServiceImplTest,CcdiEnterpriseBaseInfoMapperTest,CcdiEnumControllerTest test
  • 测试结果：BUILD SUCCESS，共执行 11 个测试，Failures: 0, Errors: 0, Skipped: 0
  • 实际编译命令：mvn -pl ccdi-info-collection -am -DskipTests compile
  • 编译结果：BUILD SUCCESS

完成标准

  • 后端新增独立 /ccdi/enterpriseBaseInfo 管理接口
  • 列表、详情、新增、编辑、删除链路可用
  • 导入严格新增，数据库重复与 Excel 内重复都进入失败记录
  • riskLevel、entSource、dataSource 均有统一选项口径
  • 菜单 SQL 与权限标识已补齐
  • 后端定向测试与编译验证已执行并记录结果
Reference in New Issue View Git Blame Copy Permalink