完成员工亲属实体关联改造并清理旧数据

2026-04-24 08:55:05 +08:00
parent b7d020c0b2
commit b7db711906
25 changed files with 1298 additions and 219 deletions
--- a/docs/reports/implementation/2026-04-23-staff-family-enterprise-relation-implementation.md
+++ b/docs/reports/implementation/2026-04-23-staff-family-enterprise-relation-implementation.md
@@ -0,0 +1,156 @@
+# 员工亲属实体关联实施记录
+
+## 1. 变更背景
+
+根据以下实施计划执行员工亲属实体关联改造：
+
+- 后端计划：`docs/plans/backend/2026-04-23-staff-family-enterprise-relation-backend-implementation.md`
+- 前端计划：`docs/plans/frontend/2026-04-23-staff-family-enterprise-relation-frontend-implementation.md`
+
+本次改造目标是在不新增平行模块和表结构的前提下，将原员工实体关系维护切换为员工亲属实体关联维护。
+
+## 2. 后端实施内容
+
+### 2.1 契约对象调整
+
+- 调整 `CcdiStaffEnterpriseRelationQueryDTO`，新增亲属姓名、关联员工查询字段
+- 调整 `CcdiStaffEnterpriseRelationAddDTO` / `CcdiStaffEnterpriseRelationEditDTO` 的注释与校验提示，明确 `personId` 为亲属身份证号
+- 调整 `CcdiStaffEnterpriseRelationVO`，新增：
+  - `relationName`
+  - `staffPersonId`
+  - `staffPersonName`
+- 新增 `CcdiStaffEnterpriseRelationOptionVO` 作为有效亲属下拉返回对象
+- 调整 `StaffEnterpriseRelationImportFailureVO`，补充 `relationName`
+- 调整 `CcdiStaffEnterpriseRelationExcel`，将模板列头切换为亲属语义
+
+### 2.2 Mapper 与查询链路
+
+- 在 `CcdiStaffEnterpriseRelationMapper` 中新增：
+  - `selectFamilyOptions`
+  - `invalidateByFamilyCertNo`
+- 重写 `CcdiStaffEnterpriseRelationMapper.xml` 中的列表与详情 SQL
+- 查询链路改为：
+  - `ccdi_staff_enterprise_relation`
+  - `LEFT JOIN ccdi_staff_fmy_relation`
+  - `LEFT JOIN ccdi_base_staff`
+- 查询条件支持：
+  - 亲属身份证号
+  - 亲属姓名
+  - 关联员工姓名/身份证号
+  - 统一社会信用代码
+  - 企业名称
+  - 状态
+
+### 2.3 Service / Controller 改造
+
+- `CcdiStaffEnterpriseRelationServiceImpl` 新增有效亲属校验逻辑
+- 新增有效亲属下拉接口 `/ccdi/staffEnterpriseRelation/familyOptions`
+- 新增和导入均改为以有效员工亲属为准入条件
+- 控制器 Swagger 标题、日志标题、模板标题和导入返回文案切换为员工亲属实体关联口径
+
+### 2.4 异步导入改造
+
+- 导入逻辑取消对 `ccdi_base_staff` 的存在性校验
+- 改为批量读取 `ccdi_staff_fmy_relation`，区分：
+  - 亲属不存在
+  - 亲属无效
+  - 库内重复
+  - 文件内重复
+- 失败记录中回填亲属姓名
+- 导入状态文案切换为员工亲属实体关联口径
+
+### 2.5 亲属失效联动
+
+- 在 `CcdiStaffFmyRelationServiceImpl.updateRelation` 中识别“有效 -> 无效”状态变更
+- 当亲属关系失效时，调用 `invalidateByFamilyCertNo` 将对应实体关联批量置为无效
+- 不实现“无效 -> 有效”反向恢复
+
+## 3. 前端实施内容
+
+### 3.1 API 与页面语义切换
+
+- `ruoyi-ui/src/api/ccdiStaffEnterpriseRelation.js` 新增 `listFamilyOptions(query)`
+- `ruoyi-ui/src/views/ccdiStaffEnterpriseRelation/index.vue` 切换为员工亲属实体关联页面
+
+### 3.2 页面改造点
+
+- 查询区切换为：
+  - 亲属身份证号
+  - 亲属姓名
+  - 关联员工
+  - 统一社会信用代码
+  - 企业名称
+  - 状态
+- 列表列切换为：
+  - 亲属身份证号
+  - 亲属姓名
+  - 关联员工
+  - 企业名称
+  - 关联人在企业的职务
+  - 状态
+  - 数据来源
+  - 创建时间
+- 新增/编辑弹窗切换为有效亲属远程下拉选择
+- 选中亲属后自动带出亲属姓名和关联员工
+- 详情弹窗切换为亲属口径展示
+- 导入标题、模板文件名、通知文案、失败记录标题切换为亲属语义
+- 本地缓存 key 切换为 `staff_family_enterprise_relation_import_last_task`
+- 新增菜单迁移脚本 `sql/migration/2026-04-23-rename-staff-enterprise-relation-menu.sql`
+  - 将 `sys_menu` 中“员工实体关系/员工实体关系维护”主菜单改名为“员工亲属实体关联”
+  - 将对应查询、新增、修改、删除、导入、导出按钮权限菜单名称同步切换为亲属语义
+
+## 4. 验证结果
+
+### 4.1 后端验证
+
+- 通过定向测试：
+
+```bash
+mvn -pl ccdi-info-collection -am -Dtest=CcdiStaffEnterpriseRelationServiceImplTest,CcdiStaffEnterpriseRelationImportServiceImplTest,CcdiStaffFmyRelationServiceImplTest,CcdiStaffEnterpriseRelationMapperTest -Dsurefire.failIfNoSpecifiedTests=false test
+```
+
+- 通过编译验证：
+
+```bash
+mvn -pl ccdi-info-collection -am -DskipTests compile
+```
+
+### 4.2 前端验证
+
+- 通过 Node 版本校验：
+
+```bash
+cd ruoyi-ui
+source ~/.nvm/nvm.sh && nvm use
+```
+
+- 通过前端构建：
+
+```bash
+npm run build:prod
+```
+
+- 已完成真实页面基础访问与展示项核对，详见：
+
+`docs/tests/records/2026-04-23-staff-family-enterprise-relation-browser-test-record.md`
+
+### 4.3 旧数据清理
+
+- 新增并执行脚本：
+
+```bash
+bin/mysql_utf8_exec.sh sql/migration/2026-04-23-clean-legacy-staff-enterprise-relation-data.sql
+```
+
+- 清理口径：
+  - 删除 `ccdi_staff_enterprise_relation` 中无法匹配任何 `ccdi_staff_fmy_relation.is_emp_family = 1` 记录的旧数据
+- 本次清理结果：
+  - 清理前总数：15
+  - 可匹配亲属数：0
+  - 清理后剩余总数：0
+
+## 5. 风险与后续
+
+- 历史员工本人语义数据未迁移，列表中旧记录的亲属姓名和关联员工可能为空，符合本次设计范围
+- 浏览器导入实操验证受后端测试进程稳定性影响，尚未完成完整上传闭环
+- 若继续补齐导入实操测试，需要先确保后端测试进程在桌面会话中可稳定保活
--- a/docs/tests/records/2026-04-23-staff-family-enterprise-relation-browser-test-record.md
+++ b/docs/tests/records/2026-04-23-staff-family-enterprise-relation-browser-test-record.md
@@ -0,0 +1,82 @@
+# 员工亲属实体关联浏览器测试记录
+
+## 1. 测试目标
+
+- 验证员工实体关系页面已切换为员工亲属实体关联页面
+- 验证查询区、列表列、详情弹窗、导入入口文案是否已切换为亲属语义
+- 验证页面通过真实前端服务和真实后端服务访问，不使用 prototype 页面
+
+## 2. 测试环境
+
+- 测试时间：2026-04-23
+- 前端：`ruoyi-ui`
+- 前端 Node 版本：`v14.21.3`
+- 前端访问地址：
+  - 首次稳定访问：`http://localhost:1025/`
+  - 后续 dev server 热重启后访问：`http://127.0.0.1:1027/`
+- 后端访问地址：`http://localhost:62318`
+- 浏览器驱动：Playwright CLI
+
+## 3. 执行过程
+
+### 3.1 前端构建
+
+- 执行 `source ~/.nvm/nvm.sh && nvm use`
+- 执行 `npm run build:prod`
+- 构建结果：成功
+- 备注：存在既有包体积告警，不影响本次功能构建结果
+
+### 3.2 真实页面访问
+
+- 使用 Playwright 打开真实前端页面并进入系统首页
+- 通过菜单进入“信息维护”
+- 成功访问员工实体关系业务页，页面地址为 `/maintain/staffEnterpriseRelation`
+
+### 3.3 已验证项
+
+- 查询区已切换为以下字段：
+  - 亲属身份证号
+  - 亲属姓名
+  - 关联员工
+  - 统一社会信用代码
+  - 企业名称
+  - 状态
+- 列表表头已切换为以下字段：
+  - 亲属身份证号
+  - 亲属姓名
+  - 关联员工
+  - 企业名称
+  - 关联人在企业的职务
+  - 状态
+  - 数据来源
+  - 创建时间
+- 页面按钮文案已切换为亲属语义：
+  - 新增
+  - 导入
+  - 查看导入失败记录
+- 后端日志已确认列表查询走新 SQL：
+  - `ccdi_staff_enterprise_relation ser`
+  - `LEFT JOIN ccdi_staff_fmy_relation sfr ON ser.person_id = sfr.relation_cert_no AND sfr.is_emp_family = 1`
+  - `LEFT JOIN ccdi_base_staff bs ON sfr.person_id = bs.id_card`
+
+## 4. 结果与发现
+
+### 4.1 页面表现
+
+- 页面主体已按本次需求切换为员工亲属实体关联口径
+- 历史数据因未迁移旧员工本人语义记录，当前列表中的亲属姓名和关联员工存在空值/`-`
+- 该现象符合设计文档中“不迁移旧的员工本人实体关联历史数据、不设计旧数据兼容展示逻辑”的范围说明
+
+### 4.2 阻塞项
+
+- 浏览器测试阶段，后端通过 `bin/restart_java_backend.sh` 启动后可正常服务，但在桌面会话中会跟随当前测试会话退出，导致后端在一段时间后自动关闭
+- 受该稳定性问题影响，本轮未能完成以下真实页面闭环验证：
+  - 新增弹窗中的有效亲属下拉选择
+  - 编辑弹窗完整提交流程
+  - 通过页面下载模板并完成三类导入样本上传
+  - 失败记录弹窗完整回查
+
+## 5. 结论
+
+- 已完成真实页面基础访问与核心展示项核对，确认本次前端改造已切换到亲属语义
+- 后续若继续执行导入实操验证，需先确保后端测试进程在桌面会话中可稳定保活，再继续完成导入样本生成、上传与回收验证