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

189 lines
13 KiB
Markdown
Raw Normal View History

修复
2026-04-17 16:01:41 +08:00
# 实体库管理后端实施计划
> **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`
- [x] 定义 QueryDTO，包含 `enterpriseName`、`socialCreditCode`、`enterpriseType`、`enterpriseNature`、`industryClass`、`status`、`riskLevel`、`entSource`。
- [x] 定义 AddDTO / EditDTO，完整覆盖单表维护字段，并给 `socialCreditCode`、`enterpriseName`、`status`、`riskLevel`、`entSource`、`dataSource` 加基础校验。
- [x] 在 EditDTO 中保持主键为必填，不新增改主键语义字段。
- [x] 定义 VO，补齐列表和详情所需字段，并预留 `createTime` 供前端表格展示。
- [x] 定义 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`
- [x] 新增 `EnterpriseRiskLevel` 枚举，口径固定为 `1/2/3` 对应高/中/低风险，并提供 `getCode()`、`getDesc()`、`getDescByCode()`、`contains()`。
- [x] 新增 `EnterpriseSource` 枚举，口径固定为 `GENERAL`、`EMP_RELATION`、`CREDIT_CUSTOMER`、`INTERMEDIARY`、`BOTH`，并提供与现有 `DataSource` 一致的方法。
- [x] 在 `CcdiEnumController` 中新增 `/enterpriseRiskLevel` 与 `/enterpriseSource` 两个接口，返回 `EnumOptionVO` 列表。
- [x] 保持现有 `/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`
- [x] 在 Mapper 中新增分页查询方法，按 QueryDTO 动态拼装筛选条件。
- [x] 在 Mapper XML 中新增结果映射和 `selectEnterpriseBaseInfoPage` SQL，输出 `create_time`、`risk_level`、`ent_source`、`data_source` 等字段。
- [x] 在 Service 接口中定义分页、详情、新增、编辑、删除、导出列表、导入任务提交方法。
- [x] 在 ServiceImpl 中实现主键唯一校验、编辑存在性校验、枚举值校验和删除批量处理。
- [x] 新建 Controller，接口路径统一使用 `/ccdi/enterpriseBaseInfo`，返回风格完全对齐员工信息维护。
- [x] 导入模板下载复用 `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`
- [x] 在 ServiceImpl 中提交导入任务，Redis key 建议使用 `import:enterpriseBaseInfo:{taskId}`。
- [x] 在导入服务中实现 Excel 行校验，数据库重复与 Excel 内重复统一生成失败记录。
- [x] 新增 `riskLevel`、`entSource`、`dataSource` 枚举校验，拒绝非法值。
- [x] 成功记录分批批量插入；导入不支持更新，不提供 `updateSupport` 分支逻辑。
- [x] 失败记录写入 Redis，状态统一支持 `PROCESSING`、`SUCCESS`、`PARTIAL_SUCCESS`。
- [x] 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`
- [x] 在“信息维护”目录下新增“实体库管理”菜单。
- [x] 菜单 path 固定为 `enterpriseBaseInfo`，component 固定为 `ccdiEnterpriseBaseInfo/index`。
- [x] 功能权限至少包含 `list`、`query`、`add`、`edit`、`remove`、`import`。
- [x] 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`
- [x] 为新增、编辑、删除、详情和枚举值校验补服务测试。
- [x] 为导入数据库重复失败、Excel 内重复失败补导入服务测试。
- [x] 为 Mapper XML 的分页查询关键 SQL 补测试或最小断言。
- [x] 为新增枚举接口补 Controller 测试。
- [x] 执行后端验证命令并记录结果。
## 验证命令
```bash
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 Copy Permalink