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

## 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. 风险与后续

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