175 lines
13 KiB
Markdown
175 lines
13 KiB
Markdown
# 员工亲属实体关联维护后端实施计划
|
||
|
||
> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||
|
||
**Goal:** 将现有员工实体关联后端链路切换为员工亲属实体关联，支持亲属维度查询展示、有效亲属校验、亲属下拉搜索、异步导入，以及亲属关系失效时自动把对应实体关联置为无效。
|
||
|
||
**Architecture:** 保留现有 `CcdiStaffEnterpriseRelation` 模块和 `ccdi_staff_enterprise_relation` 表，不新增平行模块或新表。查询链路改为 `ccdi_staff_enterprise_relation -> ccdi_staff_fmy_relation -> ccdi_base_staff`，新增和导入统一以有效员工亲属为准入条件，失效联动放在员工亲属关系保存事务内处理。
|
||
|
||
**Tech Stack:** Java 21, Spring Boot 3, MyBatis Plus, Redis, EasyExcel, JUnit 5, MySQL, Markdown
|
||
|
||
---
|
||
|
||
## 文件结构与职责
|
||
|
||
**员工亲属实体关联主链路**
|
||
|
||
- `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/controller/CcdiStaffEnterpriseRelationController.java`
|
||
继续作为实体关联对外入口，补亲属下拉搜索接口，调整列表/详情/导入文案为亲属语义。
|
||
- `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/service/ICcdiStaffEnterpriseRelationService.java`
|
||
补亲属下拉查询方法定义。
|
||
- `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/service/impl/CcdiStaffEnterpriseRelationServiceImpl.java`
|
||
负责列表、详情、新增、编辑、删除、导入任务提交，核心改动是把合法性校验从员工基础信息切到员工亲属关系。
|
||
- `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/service/ICcdiStaffEnterpriseRelationImportService.java`
|
||
保持异步导入接口不变，只切换导入校验语义。
|
||
- `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/service/impl/CcdiStaffEnterpriseRelationImportServiceImpl.java`
|
||
调整导入校验、失败原因和导入日志文案，改为按有效亲属校验并回填亲属名称。
|
||
- `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/mapper/CcdiStaffEnterpriseRelationMapper.java`
|
||
补亲属下拉查询、按亲属身份证批量置无效的方法声明。
|
||
- `ccdi-info-collection/src/main/resources/mapper/info/collection/CcdiStaffEnterpriseRelationMapper.xml`
|
||
调整列表/详情 SQL，增加亲属名称、关联员工字段映射与亲属下拉查询 SQL。
|
||
|
||
**实体关联契约对象**
|
||
|
||
- `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/dto/CcdiStaffEnterpriseRelationQueryDTO.java`
|
||
查询条件切到亲属语义，承接亲属身份证、亲属名称、关联员工、统一社会信用代码、企业名称、状态。
|
||
- `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/dto/CcdiStaffEnterpriseRelationAddDTO.java`
|
||
保持 `personId + socialCreditCode` 主键语义，但 `personId` 改为亲属身份证号。
|
||
- `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/dto/CcdiStaffEnterpriseRelationEditDTO.java`
|
||
保持编辑主键不可变。
|
||
- `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/vo/CcdiStaffEnterpriseRelationVO.java`
|
||
补亲属名称、关联员工身份证、关联员工姓名字段，移除旧的员工本人姓名语义。
|
||
- `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/vo/StaffEnterpriseRelationImportFailureVO.java`
|
||
补亲属名称字段，失败记录切到亲属语义。
|
||
- `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/vo/CcdiStaffEnterpriseRelationOptionVO.java`
|
||
新增亲属下拉返回对象，承接亲属身份证、亲属名称、关联员工身份证、关联员工姓名。
|
||
- `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/excel/CcdiStaffEnterpriseRelationExcel.java`
|
||
模板标题与字段注释切换为亲属语义。
|
||
|
||
**员工亲属关系联动链路**
|
||
|
||
- `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/service/impl/CcdiStaffFmyRelationServiceImpl.java`
|
||
在亲属状态从有效变为无效时，联动调用实体关联 Mapper 把该亲属名下关联记录批量置无效。
|
||
|
||
**测试**
|
||
|
||
- `ccdi-info-collection/src/test/java/com/ruoyi/info/collection/service/CcdiStaffEnterpriseRelationServiceImplTest.java`
|
||
覆盖新增、编辑、亲属下拉查询和无效亲属拦截。
|
||
- `ccdi-info-collection/src/test/java/com/ruoyi/info/collection/service/CcdiStaffEnterpriseRelationImportServiceImplTest.java`
|
||
覆盖导入成功、亲属不存在失败、亲属无效失败、库内重复失败、Excel 内重复失败。
|
||
- `ccdi-info-collection/src/test/java/com/ruoyi/info/collection/service/CcdiStaffFmyRelationServiceImplTest.java`
|
||
增补亲属状态改无效后，实体关联自动改无效的事务联动测试。
|
||
- `ccdi-info-collection/src/test/java/com/ruoyi/info/collection/mapper/CcdiStaffEnterpriseRelationMapperTest.java`
|
||
覆盖列表 SQL 结果映射、亲属下拉查询与批量置无效 SQL。
|
||
|
||
## 实施任务
|
||
|
||
### Task 1: 调整实体关联 DTO / VO / Excel 契约为亲属语义
|
||
|
||
**Files:**
|
||
|
||
- Modify: `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/dto/CcdiStaffEnterpriseRelationQueryDTO.java`
|
||
- Modify: `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/dto/CcdiStaffEnterpriseRelationAddDTO.java`
|
||
- Modify: `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/dto/CcdiStaffEnterpriseRelationEditDTO.java`
|
||
- Modify: `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/vo/CcdiStaffEnterpriseRelationVO.java`
|
||
- Modify: `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/vo/StaffEnterpriseRelationImportFailureVO.java`
|
||
- Create: `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/vo/CcdiStaffEnterpriseRelationOptionVO.java`
|
||
- Modify: `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/excel/CcdiStaffEnterpriseRelationExcel.java`
|
||
- Reference: `docs/superpowers/specs/2026-04-23-staff-family-enterprise-relation-design.md`
|
||
|
||
- [ ] 更新 QueryDTO 字段，新增 `relationName`、`staffPersonName`，保留 `personId` 但注释明确为亲属身份证号。
|
||
- [ ] 更新 AddDTO / EditDTO 注释和校验提示，把所有“身份证号”语义改为“亲属身份证号”。
|
||
- [ ] 在 VO 中增加 `relationName`、`staffPersonId`、`staffPersonName`，移除或停用旧 `personName` 员工本人语义。
|
||
- [ ] 新建下拉 VO，字段至少包含 `relationCertNo`、`relationName`、`staffPersonId`、`staffPersonName`。
|
||
- [ ] 调整 Excel 导入对象标题、注释和列头说明，保证“身份证号”明确指亲属身份证号。
|
||
|
||
### Task 2: 改造 Mapper 查询链路与亲属下拉 SQL
|
||
|
||
**Files:**
|
||
|
||
- Modify: `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/mapper/CcdiStaffEnterpriseRelationMapper.java`
|
||
- Modify: `ccdi-info-collection/src/main/resources/mapper/info/collection/CcdiStaffEnterpriseRelationMapper.xml`
|
||
- Reference: `ccdi-info-collection/src/main/resources/mapper/info/collection/CcdiStaffFmyRelationMapper.xml`
|
||
|
||
- [ ] 在 Mapper 接口中新增 `selectFamilyOptions(query)` 方法，返回 `CcdiStaffEnterpriseRelationOptionVO` 列表。
|
||
- [ ] 在 Mapper 接口中新增 `invalidateByFamilyCertNo(personId)` 批量置无效方法。
|
||
- [ ] 重写列表 SQL，按 `ser.person_id = sfr.relation_cert_no` 回补 `relation_name`、`staff_person_id`、`staff_person_name`。
|
||
- [ ] 重写详情 SQL，确保详情回显与列表字段口径完全一致。
|
||
- [ ] 给查询区补动态条件：亲属身份证号、亲属名称、关联员工、统一社会信用代码、企业名称、状态。
|
||
- [ ] 实现亲属下拉 SQL，仅返回 `is_emp_family = 1 and status = 1` 的有效亲属，并支持 `relation_cert_no` 模糊匹配。
|
||
|
||
### Task 3: 改造 Service / Controller 的查询、新增、编辑与下拉搜索
|
||
|
||
**Files:**
|
||
|
||
- Modify: `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/service/ICcdiStaffEnterpriseRelationService.java`
|
||
- Modify: `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/service/impl/CcdiStaffEnterpriseRelationServiceImpl.java`
|
||
- Modify: `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/controller/CcdiStaffEnterpriseRelationController.java`
|
||
- Reference: `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/controller/CcdiBaseStaffController.java`
|
||
|
||
- [ ] 在 Service 接口中新增亲属下拉查询方法定义。
|
||
- [ ] 在 ServiceImpl 中新增“按亲属身份证查询有效亲属关系”的私有校验方法，统一给新增和导入复用。
|
||
- [ ] 将新增逻辑从“校验员工身份证存在”改为“校验有效亲属存在”，失败时返回亲属语义错误提示。
|
||
- [ ] 保持编辑逻辑中 `personId` 和 `socialCreditCode` 不可修改，只切换错误文案为亲属语义。
|
||
- [ ] 在 Controller 中新增亲属下拉搜索接口，建议路径为 `/familyOptions`。
|
||
- [ ] 调整导入模板接口标题、列表/详情 Swagger 注释和日志标题，全部切换为“员工亲属实体关联”口径。
|
||
|
||
### Task 4: 改造异步导入校验与失败记录
|
||
|
||
**Files:**
|
||
|
||
- Modify: `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/service/impl/CcdiStaffEnterpriseRelationImportServiceImpl.java`
|
||
- Modify: `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/service/ICcdiStaffEnterpriseRelationImportService.java`
|
||
- Modify: `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/domain/vo/StaffEnterpriseRelationImportFailureVO.java`
|
||
- Reference: `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/service/impl/CcdiStaffFmyRelationImportServiceImpl.java`
|
||
|
||
- [ ] 去掉当前导入里对 `ccdi_base_staff` 的存在性校验，改为批量查询有效员工亲属。
|
||
- [ ] 批量缓存有效亲属集合，避免导入时逐行查库。
|
||
- [ ] 对亲属不存在、亲属无效、库内重复、Excel 内重复分别生成明确失败原因。
|
||
- [ ] 在失败记录 VO 中回填亲属名称，便于前端失败弹窗展示。
|
||
- [ ] 更新导入日志标题和 Redis 提示文案，统一为亲属实体关联口径。
|
||
|
||
### Task 5: 在员工亲属关系保存链路中加入失效联动
|
||
|
||
**Files:**
|
||
|
||
- Modify: `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/service/impl/CcdiStaffFmyRelationServiceImpl.java`
|
||
- Modify: `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/mapper/CcdiStaffEnterpriseRelationMapper.java`
|
||
- Modify: `ccdi-info-collection/src/main/resources/mapper/info/collection/CcdiStaffEnterpriseRelationMapper.xml`
|
||
|
||
- [ ] 在 `CcdiStaffFmyRelationServiceImpl.updateRelation` 中保留旧记录查询，识别“有效 -> 无效”状态变更。
|
||
- [ ] 注入 `CcdiStaffEnterpriseRelationMapper`，在状态收缩时按 `relation_cert_no` 批量更新实体关联 `status = 0`。
|
||
- [ ] 保证该联动与亲属关系更新处于同一事务内，避免亲属已失效但实体关联仍有效。
|
||
- [ ] 不实现“无效 -> 有效”反向恢复，严格遵守设计范围。
|
||
|
||
### Task 6: 补后端测试与验证命令
|
||
|
||
**Files:**
|
||
|
||
- Modify: `ccdi-info-collection/src/test/java/com/ruoyi/info/collection/service/CcdiStaffEnterpriseRelationServiceImplTest.java`
|
||
- Modify: `ccdi-info-collection/src/test/java/com/ruoyi/info/collection/service/CcdiStaffEnterpriseRelationImportServiceImplTest.java`
|
||
- Modify: `ccdi-info-collection/src/test/java/com/ruoyi/info/collection/service/CcdiStaffFmyRelationServiceImplTest.java`
|
||
- Modify or Create: `ccdi-info-collection/src/test/java/com/ruoyi/info/collection/mapper/CcdiStaffEnterpriseRelationMapperTest.java`
|
||
|
||
- [ ] 为新增接口补“有效亲属可新增、无效亲属不可新增、亲属不存在不可新增”三组测试。
|
||
- [ ] 为列表查询补“能回填亲属名称和关联员工”的 SQL 映射测试。
|
||
- [ ] 为亲属下拉补“只返回有效员工亲属且支持身份证模糊搜索”的测试。
|
||
- [ ] 为导入补“成功、亲属不存在失败、亲属无效失败、库内重复、文件内重复”五组测试。
|
||
- [ ] 为员工亲属关系状态变更补“有效改无效后自动将实体关联置无效”的事务测试。
|
||
|
||
## 验证命令
|
||
|
||
```bash
|
||
mvn -pl ccdi-info-collection -am -Dtest=CcdiStaffEnterpriseRelationServiceImplTest,CcdiStaffEnterpriseRelationImportServiceImplTest,CcdiStaffFmyRelationServiceImplTest,CcdiStaffEnterpriseRelationMapperTest test
|
||
mvn -pl ccdi-info-collection -am -DskipTests compile
|
||
```
|
||
|
||
## 完成标准
|
||
|
||
- 列表和详情返回亲属身份证、亲属名称、关联员工字段
|
||
- 新增和导入只允许使用有效员工亲属
|
||
- 亲属下拉搜索接口可按身份证模糊查询有效亲属
|
||
- 导入失败记录可展示亲属名称和亲属语义错误原因
|
||
- 亲属关系从有效改为无效后，对应实体关联自动改为无效
|
||
- 后端定向测试和编译命令可通过
|