wkc/ccdi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b7db711906017e7bd0736f1117007145f293ab38
ccdi/docs/reports/implementation/2026-04-23-staff-family-enterprise-relation-implementation.md

5.3 KiB
Raw Blame History

员工亲属实体关联实施记录

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 后端验证

  • 通过定向测试：
mvn -pl ccdi-info-collection -am -Dtest=CcdiStaffEnterpriseRelationServiceImplTest,CcdiStaffEnterpriseRelationImportServiceImplTest,CcdiStaffFmyRelationServiceImplTest,CcdiStaffEnterpriseRelationMapperTest -Dsurefire.failIfNoSpecifiedTests=false test
  • 通过编译验证：
mvn -pl ccdi-info-collection -am -DskipTests compile

4.2 前端验证

  • 通过 Node 版本校验：
cd ruoyi-ui
source ~/.nvm/nvm.sh && nvm use
  • 通过前端构建：
npm run build:prod
  • 已完成真实页面基础访问与展示项核对，详见：

docs/tests/records/2026-04-23-staff-family-enterprise-relation-browser-test-record.md

4.3 旧数据清理

  • 新增并执行脚本：
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. 风险与后续

  • 历史员工本人语义数据未迁移，列表中旧记录的亲属姓名和关联员工可能为空，符合本次设计范围
  • 浏览器导入实操验证受后端测试进程稳定性影响，尚未完成完整上传闭环
  • 若继续补齐导入实操测试，需要先确保后端测试进程在桌面会话中可稳定保活
Reference in New Issue View Git Blame Copy Permalink