员工亲属实体关联

docs/reports/implementation/2026-04-22-staff-family-dual-sheet-import-implementation.md

@@ -0,0 +1,48 @@
+# 员工亲属关系维护双 Sheet 导入实施记录
+
+## 本次修改
+- 将员工亲属关系维护顶部两个导入按钮合并为一个统一导入入口。
+- 导入模板改为双 Sheet：
+  - `员工亲属关系信息`
+  - `亲属资产信息`
+- 导入提交入口统一到 `/ccdi/staffFmyRelation/importData`，按有数据的 Sheet 分别提交亲属关系任务和亲属资产任务。
+- 新增 `StaffFmyRelationImportSubmitResultVO`，返回 `relationTaskId`、`assetTaskId` 和提交提示文案。
+- 员工亲属关系失败记录与亲属资产失败记录都增加了 `Sheet`、`Excel行号`、`失败原因` 定位信息。
+- 前端删除独立亲属资产上传弹窗，但保留原有两套轮询和失败记录查看入口。
+
+## 影响范围
+- 后端
+  - `ccdi-info-collection` 员工亲属关系导入控制器、两类异步导入服务、失败记录 VO、导入提交结果 VO、相关控制器测试
+- 前端
+  - `ruoyi-ui/src/views/ccdiStaffFmyRelation/index.vue`
+  - `ruoyi-ui/tests/unit/staff-family-asset-detail-import-ui.test.js`
+
+## 验证情况
+- 后端构建
+  - `sh bin/restart_java_backend.sh restart`
+  - 结果：通过，`ruoyi-admin` 已基于本次代码重新打包并启动成功。
+- 前端单测
+  - `source ~/.nvm/nvm.sh && nvm use 14.21.3 >/dev/null && cd ruoyi-ui && node tests/unit/staff-family-asset-detail-import-ui.test.js`
+  - `source ~/.nvm/nvm.sh && nvm use 14.21.3 >/dev/null && cd ruoyi-ui && node tests/unit/staff-family-asset-submit-flow.test.js`
+  - `source ~/.nvm/nvm.sh && nvm use 14.21.3 >/dev/null && cd ruoyi-ui && node tests/unit/staff-family-asset-maintenance-layout.test.js`
+  - 结果：通过
+- 后端编译/测试
+  - `mvn -pl ccdi-info-collection -am -Dtest=CcdiStaffFmyRelationControllerTest,CcdiAssetInfoControllerTest -Dsurefire.failIfNoSpecifiedTests=false test`
+  - 结果：通过，`Tests run: 10, Failures: 0, Errors: 0`
+- 真实页面实测
+  - 前端端口：`1026`
+  - 使用 Playwright 打开真实页面 `/maintain/staffFmyRelation`
+  - 实测结果：
+    - 页面顶部仅保留一个“导入”按钮
+    - 从页面内下载到新的双 Sheet 模板，实际包含 `员工亲属关系信息`、`亲属资产信息` 两张表
+    - 通过双 Sheet 失败样本上传后，页面同时出现“查看导入失败记录”和“查看亲属资产导入失败记录”两个失败入口
+- 后端接口核验
+  - 使用双 Sheet 失败样本调用 `/ccdi/staffFmyRelation/importData`
+  - 再分别查询 `/ccdi/staffFmyRelation/importFailures/{relationTaskId}` 与 `/ccdi/assetInfo/importFailures/{assetTaskId}`
+  - 返回结果已确认包含：
+    - 亲属关系失败记录：`sheetName=员工亲属关系信息`、`rowNum=2`、`errorMessage=员工身份证号格式不正确`
+    - 亲属资产失败记录：`sheetName=亲属资产信息`、`rowNum=2`、`errorMessage=未找到亲属资产归属员工`
+
+## 后续实测
+- 本轮已完成真实页面双 Sheet 导入实测与失败接口核验。
+- 若后续需要补充界面截图或失败弹窗截图，可直接复用 `output/playwright/base-staff-maintenance-test/` 下本轮产物继续追踪。