157 lines
5.3 KiB
Markdown
157 lines
5.3 KiB
Markdown
# 员工亲属实体关联实施记录
|
||
|
||
## 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. 风险与后续
|
||
|
||
- 历史员工本人语义数据未迁移，列表中旧记录的亲属姓名和关联员工可能为空，符合本次设计范围
|
||
- 浏览器导入实操验证受后端测试进程稳定性影响，尚未完成完整上传闭环
|
||
- 若继续补齐导入实操测试，需要先确保后端测试进程在桌面会话中可稳定保活
|