311 lines
10 KiB
Markdown
311 lines
10 KiB
Markdown
# 员工亲属资产维护后端实施计划
|
||
|
||
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
|
||
|
||
**Goal:** 为员工亲属关系维护页面补齐亲属资产的后端聚合保存、详情查询、删除级联和异步导入能力。
|
||
|
||
**Architecture:** 以 `CcdiStaffFmyRelation` 为聚合根扩展 `assetInfoList`，由资产模块负责持久化和导入，由亲属关系服务负责在新增、编辑、删除、详情等场景中协调资产数据。编辑时通过固定的 `family_id + person_id` 覆盖重建亲属资产，不引入额外关联字段。
|
||
|
||
**Tech Stack:** Java 21, Spring Boot 3, MyBatis Plus, MyBatis XML, Redis, EasyExcel, Lombok
|
||
|
||
---
|
||
|
||
### Task 1: 补齐资产表 SQL 与索引设计
|
||
|
||
**Files:**
|
||
- Create: `D:\ccdi\ccdi\sql\ccdi_asset_info.sql`
|
||
- Check: `D:\ccdi\ccdi\docs\plans\2026-03-12-staff-family-asset-maintenance-design.md`
|
||
|
||
**Step 1: 写出资产表建表 SQL**
|
||
|
||
- 新增 `ccdi_asset_info`
|
||
- 主键使用 `asset_id BIGINT AUTO_INCREMENT`
|
||
- 字段包含 `family_id`、`person_id` 和资产业务字段
|
||
- 审计字段遵循项目现有风格
|
||
|
||
**Step 2: 为归属查询补索引**
|
||
|
||
- 添加 `idx_family_id`
|
||
- 添加 `idx_person_id`
|
||
- 添加联合索引 `idx_family_person`
|
||
|
||
**Step 3: 自查字段口径**
|
||
|
||
- 确认 `family_id` 保存员工证件号
|
||
- 确认 `person_id` 保存亲属证件号
|
||
- 确认不新增 `relation_id`
|
||
|
||
**Step 4: 记录执行命令**
|
||
|
||
Run: `Get-Content 'D:\ccdi\ccdi\sql\ccdi_asset_info.sql'`
|
||
Expected: 能看到完整建表语句与索引定义
|
||
|
||
**Step 5: 提交**
|
||
|
||
```bash
|
||
git add sql/ccdi_asset_info.sql
|
||
git commit -m "新增亲属资产表结构设计"
|
||
```
|
||
|
||
### Task 2: 创建资产领域对象与映射接口
|
||
|
||
**Files:**
|
||
- Create: `D:\ccdi\ccdi\ccdi-info-collection\src\main\java\com\ruoyi\info\collection\domain\CcdiAssetInfo.java`
|
||
- Create: `D:\ccdi\ccdi\ccdi-info-collection\src\main\java\com\ruoyi\info\collection\domain\dto\CcdiAssetInfoDTO.java`
|
||
- Create: `D:\ccdi\ccdi\ccdi-info-collection\src\main\java\com\ruoyi\info\collection\domain\vo\CcdiAssetInfoVO.java`
|
||
- Create: `D:\ccdi\ccdi\ccdi-info-collection\src\main\java\com\ruoyi\info\collection\domain\excel\CcdiAssetInfoExcel.java`
|
||
- Create: `D:\ccdi\ccdi\ccdi-info-collection\src\main\java\com\ruoyi\info\collection\domain\vo\AssetImportFailureVO.java`
|
||
- Create: `D:\ccdi\ccdi\ccdi-info-collection\src\main\java\com\ruoyi\info\collection\mapper\CcdiAssetInfoMapper.java`
|
||
- Create: `D:\ccdi\ccdi\ccdi-info-collection\src\main\resources\mapper\info\collection\CcdiAssetInfoMapper.xml`
|
||
|
||
**Step 1: 创建领域实体与 DTO/VO**
|
||
|
||
- `CcdiAssetInfo` 映射表字段
|
||
- `CcdiAssetInfoDTO` 承载亲属关系聚合保存时的子表数据
|
||
- `CcdiAssetInfoVO` 用于详情回显
|
||
|
||
**Step 2: 创建 Excel 与失败记录对象**
|
||
|
||
- `CcdiAssetInfoExcel` 用于模板下载与导入解析
|
||
- `AssetImportFailureVO` 仅返回失败记录
|
||
|
||
**Step 3: 定义 Mapper 能力**
|
||
|
||
- 按 `family_id + person_id` 查询资产列表
|
||
- 按 `family_id + person_id` 删除资产
|
||
- 批量插入资产
|
||
- 导入场景下按亲属证件号查询归属员工候选
|
||
|
||
**Step 4: 运行编译检查**
|
||
|
||
Run: `mvn -pl ccdi-info-collection -am -DskipTests compile`
|
||
Expected: 新增类与 XML 能被正常加载，无编译错误
|
||
|
||
**Step 5: 提交**
|
||
|
||
```bash
|
||
git add ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain ccdi-info-collection/src/main/java/com/ruoyi/info/collection/mapper ccdi-info-collection/src/main/resources/mapper/info/collection/CcdiAssetInfoMapper.xml
|
||
git commit -m "新增亲属资产领域对象与映射"
|
||
```
|
||
|
||
### Task 3: 实现资产服务与导入服务
|
||
|
||
**Files:**
|
||
- Create: `D:\ccdi\ccdi\ccdi-info-collection\src\main\java\com\ruoyi\info\collection\service\ICcdiAssetInfoService.java`
|
||
- Create: `D:\ccdi\ccdi\ccdi-info-collection\src\main\java\com\ruoyi\info\collection\service\ICcdiAssetInfoImportService.java`
|
||
- Create: `D:\ccdi\ccdi\ccdi-info-collection\src\main\java\com\ruoyi\info\collection\service\impl\CcdiAssetInfoServiceImpl.java`
|
||
- Create: `D:\ccdi\ccdi\ccdi-info-collection\src\main\java\com\ruoyi\info\collection\service\impl\CcdiAssetInfoImportServiceImpl.java`
|
||
|
||
**Step 1: 实现基础资产服务**
|
||
|
||
- 查询当前亲属资产列表
|
||
- 按归属键删除资产
|
||
- 批量保存资产
|
||
- 过滤空行并校验必填字段、数值、日期
|
||
|
||
**Step 2: 实现资产导入异步服务**
|
||
|
||
- 初始化 Redis 状态
|
||
- 解析 Excel 数据
|
||
- 通过 `relation_cert_no` 反查亲属关系
|
||
- 识别无法匹配和归属不唯一场景
|
||
- 仅缓存失败记录
|
||
|
||
**Step 3: 明确 Redis Key 规则**
|
||
|
||
- 状态 key：`import:assetInfo:{taskId}`
|
||
- 失败 key：`import:assetInfo:{taskId}:failures`
|
||
|
||
**Step 4: 运行编译检查**
|
||
|
||
Run: `mvn -pl ccdi-info-collection -am -DskipTests compile`
|
||
Expected: 服务接口与实现均编译通过
|
||
|
||
**Step 5: 提交**
|
||
|
||
```bash
|
||
git add ccdi-info-collection/src/main/java/com/ruoyi/info/collection/service
|
||
git commit -m "实现亲属资产服务与导入服务"
|
||
```
|
||
|
||
### Task 4: 扩展亲属关系 DTO 与 VO 聚合资产列表
|
||
|
||
**Files:**
|
||
- Modify: `D:\ccdi\ccdi\ccdi-info-collection\src\main\java\com\ruoyi\info\collection\domain\dto\CcdiStaffFmyRelationAddDTO.java`
|
||
- Modify: `D:\ccdi\ccdi\ccdi-info-collection\src\main\java\com\ruoyi\info\collection\domain\dto\CcdiStaffFmyRelationEditDTO.java`
|
||
- Modify: `D:\ccdi\ccdi\ccdi-info-collection\src\main\java\com\ruoyi\info\collection\domain\vo\CcdiStaffFmyRelationVO.java`
|
||
|
||
**Step 1: 为新增 DTO 增加 `assetInfoList`**
|
||
|
||
- 类型使用 `List<CcdiAssetInfoDTO>`
|
||
- 保持与前端子表数据结构一致
|
||
|
||
**Step 2: 为编辑 DTO 增加 `assetInfoList`**
|
||
|
||
- 与新增 DTO 保持一致
|
||
- 保留现有校验规则
|
||
|
||
**Step 3: 为详情 VO 增加 `assetInfoList`**
|
||
|
||
- 类型使用 `List<CcdiAssetInfoVO>`
|
||
- 用于详情和编辑回显
|
||
|
||
**Step 4: 编译验证**
|
||
|
||
Run: `mvn -pl ccdi-info-collection -am -DskipTests compile`
|
||
Expected: DTO、VO 依赖关系正常
|
||
|
||
**Step 5: 提交**
|
||
|
||
```bash
|
||
git add ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/dto/CcdiStaffFmyRelationAddDTO.java ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/dto/CcdiStaffFmyRelationEditDTO.java ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/vo/CcdiStaffFmyRelationVO.java
|
||
git commit -m "扩展亲属关系聚合资产字段"
|
||
```
|
||
|
||
### Task 5: 改造亲属关系服务聚合保存与详情查询
|
||
|
||
**Files:**
|
||
- Modify: `D:\ccdi\ccdi\ccdi-info-collection\src\main\java\com\ruoyi\info\collection\service\impl\CcdiStaffFmyRelationServiceImpl.java`
|
||
- Check: `D:\ccdi\ccdi\ccdi-info-collection\src\main\resources\mapper\info\collection\CcdiStaffFmyRelationMapper.xml`
|
||
|
||
**Step 1: 注入资产服务**
|
||
|
||
- 在服务实现中注入 `ICcdiAssetInfoService`
|
||
|
||
**Step 2: 改造详情查询**
|
||
|
||
- 查询亲属关系主记录
|
||
- 按 `personId + relationCertNo` 查询资产列表
|
||
- 回填 `assetInfoList`
|
||
|
||
**Step 3: 改造新增逻辑**
|
||
|
||
- 保存亲属关系
|
||
- 回填资产归属键
|
||
- 批量保存资产
|
||
|
||
**Step 4: 改造编辑逻辑**
|
||
|
||
- 查询旧记录
|
||
- 校验证件类型、证件号码未被修改
|
||
- 更新主记录
|
||
- 删除旧资产
|
||
- 保存新资产列表
|
||
|
||
**Step 5: 改造删除逻辑**
|
||
|
||
- 根据待删 ID 先查询关系记录
|
||
- 循环按 `family_id + person_id` 删除资产
|
||
- 再批量删除亲属关系
|
||
|
||
**Step 6: 编译验证**
|
||
|
||
Run: `mvn -pl ccdi-info-collection -am -DskipTests compile`
|
||
Expected: 亲属关系服务改造后可通过编译
|
||
|
||
**Step 7: 提交**
|
||
|
||
```bash
|
||
git add ccdi-info-collection/src/main/java/com/ruoyi/info/collection/service/impl/CcdiStaffFmyRelationServiceImpl.java
|
||
git commit -m "改造亲属关系聚合保存亲属资产"
|
||
```
|
||
|
||
### Task 6: 新增资产导入控制器并接入下载模板与状态查询
|
||
|
||
**Files:**
|
||
- Create: `D:\ccdi\ccdi\ccdi-info-collection\src\main\java\com\ruoyi\info\collection\controller\CcdiAssetInfoController.java`
|
||
|
||
**Step 1: 添加模板下载接口**
|
||
|
||
- `POST /ccdi/assetInfo/importTemplate`
|
||
|
||
**Step 2: 添加导入接口**
|
||
|
||
- `POST /ccdi/assetInfo/importData`
|
||
- 解析 Excel 后提交异步任务
|
||
|
||
**Step 3: 添加状态与失败记录接口**
|
||
|
||
- `GET /ccdi/assetInfo/importStatus/{taskId}`
|
||
- `GET /ccdi/assetInfo/importFailures/{taskId}`
|
||
|
||
**Step 4: 核对权限标识**
|
||
|
||
- 使用 `ccdi:staffFmyRelation:import` 还是新增独立权限
|
||
- 若采用独立权限，记录需同步补菜单 SQL
|
||
|
||
**Step 5: 编译验证**
|
||
|
||
Run: `mvn -pl ccdi-info-collection -am -DskipTests compile`
|
||
Expected: 控制器注册正常
|
||
|
||
**Step 6: 提交**
|
||
|
||
```bash
|
||
git add ccdi-info-collection/src/main/java/com/ruoyi/info/collection/controller/CcdiAssetInfoController.java
|
||
git commit -m "新增亲属资产导入控制器"
|
||
```
|
||
|
||
### Task 7: 补充亲属关系编辑防御校验
|
||
|
||
**Files:**
|
||
- Modify: `D:\ccdi\ccdi\ccdi-info-collection\src\main\java\com\ruoyi\info\collection\service\impl\CcdiStaffFmyRelationServiceImpl.java`
|
||
|
||
**Step 1: 查询旧记录**
|
||
|
||
- 编辑保存前按 `id` 查询旧关系
|
||
|
||
**Step 2: 比较证件类型与证件号码**
|
||
|
||
- 若值发生变化，抛出业务异常
|
||
|
||
**Step 3: 明确错误文案**
|
||
|
||
- 返回“关系人证件类型/证件号码不允许修改”
|
||
|
||
**Step 4: 编译验证**
|
||
|
||
Run: `mvn -pl ccdi-info-collection -am -DskipTests compile`
|
||
Expected: 校验逻辑编译通过
|
||
|
||
**Step 5: 提交**
|
||
|
||
```bash
|
||
git add ccdi-info-collection/src/main/java/com/ruoyi/info/collection/service/impl/CcdiStaffFmyRelationServiceImpl.java
|
||
git commit -m "限制编辑亲属证件信息变更"
|
||
```
|
||
|
||
### Task 8: 执行后端回归验证
|
||
|
||
**Files:**
|
||
- Check: `D:\ccdi\ccdi\ccdi-info-collection\src\main\java\com\ruoyi\info\collection\controller\CcdiStaffFmyRelationController.java`
|
||
- Check: `D:\ccdi\ccdi\ccdi-info-collection\src\main\java\com\ruoyi\info\collection\controller\CcdiAssetInfoController.java`
|
||
|
||
**Step 1: 编译后端模块**
|
||
|
||
Run: `mvn -pl ccdi-info-collection -am clean compile`
|
||
Expected: BUILD SUCCESS
|
||
|
||
**Step 2: 启动应用后手工验证接口**
|
||
|
||
Run: `mvn -pl ruoyi-admin -am spring-boot:run`
|
||
Expected: 应用可正常启动
|
||
|
||
**Step 3: 验证关键场景**
|
||
|
||
- 查询亲属关系详情返回 `assetInfoList`
|
||
- 新增/编辑亲属关系能保存资产
|
||
- 删除亲属关系后资产被同步删除
|
||
- 亲属资产导入可生成任务状态和失败记录
|
||
|
||
**Step 4: 整理验证记录**
|
||
|
||
- 将实际验证结果补充到开发记录或 PR 描述
|
||
|
||
**Step 5: 提交**
|
||
|
||
```bash
|
||
git add .
|
||
git commit -m "完成亲属资产后端联调验证"
|
||
```
|