ccdi/docs/plans/2026-03-13-employee-family-asset-import-split-design.md

# 员工资产导入与亲属资产导入拆分设计

## 背景

当前员工信息维护页 [ccdiBaseStaff/index.vue](/D:/ccdi/ccdi/ruoyi-ui/src/views/ccdiBaseStaff/index.vue) 与员工亲属关系维护页 [ccdiStaffFmyRelation/index.vue](/D:/ccdi/ccdi/ruoyi-ui/src/views/ccdiStaffFmyRelation/index.vue) 共用了 `/ccdi/assetInfo/*` 资产导入接口，导致两类业务边界混淆：

- 员工页的“导入资产信息”应只导入员工本人资产
- 亲属页的“导入亲属资产信息”应只导入员工亲属资产
- 当前共享接口无法同时满足这两条规则，模板、权限、失败文案也容易串用

用户已确认：

- 保留员工页“导入资产信息”按钮
- 员工资产导入与亲属资产导入必须彻底拆分
- 员工亲属资产导入功能只能导入员工亲属的资产信息，不能更新员工的

## 目标

- 将员工资产导入与亲属资产导入拆成两条独立链路
- 员工页只支持员工本人资产导入
- 亲属页只支持亲属资产导入
- 模板、接口、权限、失败提示、任务状态缓存全部分离

## 非目标

- 不改造员工资产手工维护功能
- 不改造亲属资产手工维护功能
- 不新增独立资产菜单页面
- 不调整 `ccdi_asset_info` 表结构

## 现状

当前共用资产导入能力集中在：

- 前端 API：[ccdiAssetInfo.js](/D:/ccdi/ccdi/ruoyi-ui/src/api/ccdiAssetInfo.js)
- 员工页调用点：[ccdiBaseStaff/index.vue](/D:/ccdi/ccdi/ruoyi-ui/src/views/ccdiBaseStaff/index.vue)
- 亲属页调用点：[ccdiStaffFmyRelation/index.vue](/D:/ccdi/ccdi/ruoyi-ui/src/views/ccdiStaffFmyRelation/index.vue)
- 后端控制器：[CcdiAssetInfoController.java](/D:/ccdi/ccdi/ccdi-info-collection/src/main/java/com/ruoyi/info/collection/controller/CcdiAssetInfoController.java)
- 后端导入服务：[CcdiAssetInfoImportServiceImpl.java](/D:/ccdi/ccdi/ccdi-info-collection/src/main/java/com/ruoyi/info/collection/service/impl/CcdiAssetInfoImportServiceImpl.java)

问题点：

- 员工页与亲属页共用同一上传地址 `/ccdi/assetInfo/importData`
- 共用同一模板下载地址 `/ccdi/assetInfo/importTemplate`
- 共用同一任务状态与失败记录查询入口
- 共用同一导入匹配规则，无法表达“员工页仅员工本人、亲属页仅亲属”

## 方案对比

### 方案一：员工资产导入、亲属资产导入完全拆分

- 员工页新增一套独立导入接口
- 亲属页保留现有 `/ccdi/assetInfo/*`
- 两边各自使用独立模板、权限、校验和失败文案

优点：

- 业务边界最清晰
- 后续维护风险最低
- 模板与前端交互不再串用

缺点：

- 需要新增一套员工资产导入 controller/service/api

### 方案二：继续共用接口，通过 `mode` 区分

- 前端调用同一接口
- 后端通过 `mode=employee/family` 分支处理

优点：

- 代码新增较少

缺点：

- 控制器和 service 内分支复杂
- 模板、权限、提示文案仍容易混淆
- 后续扩展时回归风险高

### 方案三：仅修前端入口文案

优点：

- 改动最小

缺点：

- 业务问题未解决
- 实际导入规则仍然混乱

## 最终方案

采用方案一：员工资产导入与亲属资产导入完全拆分。

### 员工资产导入

- 页面入口：员工信息维护页
- 独立接口：
  - `POST /ccdi/baseStaff/asset/importTemplate`
  - `POST /ccdi/baseStaff/asset/importData`
  - `GET /ccdi/baseStaff/asset/importStatus/{taskId}`
  - `GET /ccdi/baseStaff/asset/importFailures/{taskId}`
- 独立前端 API 文件：`ruoyi-ui/src/api/ccdiBaseStaffAsset.js`
- 仅允许导入员工本人资产
- 模板第一列要求填写员工身份证号
- 导入成功后强制写入：
  - `family_id = 员工身份证号`
  - `person_id = 员工身份证号`

### 亲属资产导入

- 页面入口：员工亲属关系维护页
- 保留现有接口：
  - `POST /ccdi/assetInfo/importTemplate`
  - `POST /ccdi/assetInfo/importData`
  - `GET /ccdi/assetInfo/importStatus/{taskId}`
  - `GET /ccdi/assetInfo/importFailures/{taskId}`
- 仅允许导入员工亲属资产
- 模板第一列要求填写亲属证件号
- 导入成功后强制写入：
  - `family_id = 关联员工证件号`
  - `person_id = 亲属证件号`

## 后端设计

### 新增员工资产导入控制面

新增：

- `controller/CcdiBaseStaffAssetImportController.java`
- `service/ICcdiBaseStaffAssetImportService.java`
- `service/impl/CcdiBaseStaffAssetImportServiceImpl.java`
- `domain/excel/CcdiBaseStaffAssetInfoExcel.java`
- `domain/vo/BaseStaffAssetImportFailureVO.java`

员工资产导入匹配规则：

- 仅根据 `ccdi_base_staff.id_card` 匹配
- 若未匹配到员工，导入失败
- 不再兜底匹配亲属关系表
- 若命中员工，则写入 `family_id = person_id = id_card`

亲属资产导入规则调整：

- [CcdiAssetInfoImportServiceImpl.java](/D:/ccdi/ccdi/ccdi-info-collection/src/main/java/com/ruoyi/info/collection/service/impl/CcdiAssetInfoImportServiceImpl.java) 只保留亲属资产逻辑
- 仅根据 `ccdi_staff_fmy_relation.relation_cert_no` 匹配
- 不再匹配员工本人身份证号

### 权限设计

- 员工资产导入接口：`ccdi:employee:import`
- 亲属资产导入接口：`ccdi:staffFmyRelation:import`

禁止再使用同时兼容两个权限的写法，以免接口语义再次混淆。

## 前端设计

### 员工页

[ccdiBaseStaff/index.vue](/D:/ccdi/ccdi/ruoyi-ui/src/views/ccdiBaseStaff/index.vue) 改为：

- 上传地址改为员工资产专用接口
- 模板下载改为员工资产模板
- 任务状态和失败记录查询改为员工资产专用接口
- 提示文案明确为“员工资产数据导入”

### 亲属页

[ccdiStaffFmyRelation/index.vue](/D:/ccdi/ccdi/ruoyi-ui/src/views/ccdiStaffFmyRelation/index.vue) 保持：

- 上传地址仍为 `/ccdi/assetInfo/importData`
- 模板下载仍为亲属资产模板
- 文案继续强调“亲属资产”

## 模板设计

员工资产模板：

- 文件名：`员工资产信息模板_xxx.xlsx`
- 首列表头：`员工身份证号*`

亲属资产模板：

- 文件名：`亲属资产信息模板_xxx.xlsx`
- 首列表头：`亲属证件号*`

## 校验规则

### 员工资产导入

- 员工身份证号不能为空
- 资产必填字段不能为空
- 员工身份证号必须存在于 `ccdi_base_staff.id_card`
- 若填写的是亲属证件号或其他未命中的证件号，直接失败

建议失败文案：

- `未找到员工资产归属员工`
- 或更明确的 `员工资产导入仅支持员工本人证件号`

### 亲属资产导入

- 亲属证件号不能为空
- 资产必填字段不能为空
- 亲属证件号必须存在于 `ccdi_staff_fmy_relation.relation_cert_no`
- 若填写员工本人身份证号且不存在亲属关系映射，直接失败
- 若同一亲属证件号匹配多个员工关系，失败并提示归属不唯一

## 测试要求

后端：

- 员工资产导入：员工本人证件号成功
- 员工资产导入：亲属证件号失败
- 亲属资产导入：亲属证件号成功
- 亲属资产导入：员工本人证件号失败
- 两套模板标题和首列表头不同
- 两套接口权限分别正确

前端：

- 员工页使用员工资产专用上传地址
- 亲属页继续使用 `/ccdi/assetInfo/*`
- 员工页下载员工资产模板
- 亲属页下载亲属资产模板
- 员工页和亲属页的失败记录弹窗文案不混淆

## 风险与回滚

风险：

- 当前仓库内已有共享资产导入代码，拆分时容易遗漏某一处调用
- 若只拆后端不拆前端，页面会继续指向旧接口
- 若模板文案未同步，用户仍可能误用模板

回滚策略：

- 独立提交员工资产导入新增改动
- 独立提交亲属资产导入收敛改动
- 任一阶段出现回归，可按提交粒度回退

## 实现状态

- 2026-03-13 已完成后端拆分实现
- 已新增员工资产独立导入接口 `/ccdi/baseStaff/asset/*`
- 已将 `/ccdi/assetInfo/*` 收敛为亲属资产专用接口
- 已通过后端定向测试验证员工与亲属两套导入链路、模板名称和失败文案拆分生效