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

13 KiB
Raw Blame History

员工亲属实体关联维护后端实施计划

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 映射测试。

  • 为亲属下拉补“只返回有效员工亲属且支持身份证模糊搜索”的测试。

  • 为导入补“成功、亲属不存在失败、亲属无效失败、库内重复、文件内重复”五组测试。

  • 为员工亲属关系状态变更补“有效改无效后自动将实体关联置无效”的事务测试。

验证命令

mvn -pl ccdi-info-collection -am -Dtest=CcdiStaffEnterpriseRelationServiceImplTest,CcdiStaffEnterpriseRelationImportServiceImplTest,CcdiStaffFmyRelationServiceImplTest,CcdiStaffEnterpriseRelationMapperTest test
mvn -pl ccdi-info-collection -am -DskipTests compile

完成标准

  • 列表和详情返回亲属身份证、亲属名称、关联员工字段
  • 新增和导入只允许使用有效员工亲属
  • 亲属下拉搜索接口可按身份证模糊查询有效亲属
  • 导入失败记录可展示亲属名称和亲属语义错误原因
  • 亲属关系从有效改为无效后，对应实体关联自动改为无效
  • 后端定向测试和编译命令可通过
Reference in New Issue View Git Blame Copy Permalink