# 员工亲属资产维护后端实施计划

> **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 "完成亲属资产后端联调验证"
```