新增员工亲属实体关联维护实施计划

docs/plans/backend/2026-04-23-staff-family-enterprise-relation-backend-implementation.md

@@ -0,0 +1,174 @@
+# 员工亲属实体关联维护后端实施计划
+
+> **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
+```
+
+## 完成标准
+
+- 列表和详情返回亲属身份证、亲属名称、关联员工字段
+- 新增和导入只允许使用有效员工亲属
+- 亲属下拉搜索接口可按身份证模糊查询有效亲属
+- 导入失败记录可展示亲属名称和亲属语义错误原因
+- 亲属关系从有效改为无效后，对应实体关联自动改为无效
+- 后端定向测试和编译命令可通过

docs/plans/frontend/2026-04-23-staff-family-enterprise-relation-frontend-implementation.md

@@ -0,0 +1,129 @@
+# 员工亲属实体关联维护前端实施计划
+
+> **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/index.vue` 单页实现，不新建平行页面。前端只改字段语义、查询区、列表列、编辑弹窗和导入文案；下拉搜索改为请求新的有效亲属接口，页面验证继续复用现有导入轮询与失败记录交互骨架。
+
+**Tech Stack:** Vue 2, Element UI, JavaScript, npm, nvm, Playwright, Markdown
+
+---
+
+## 文件结构与职责
+
+**前端页面与 API**
+
+- `ruoyi-ui/src/views/ccdiStaffEnterpriseRelation/index.vue`
+  员工亲属实体关联主页面，负责查询区、表格、详情、编辑弹窗、亲属下拉搜索、导入轮询和失败记录弹窗。
+- `ruoyi-ui/src/api/ccdiStaffEnterpriseRelation.js`
+  继续封装实体关联接口，新增亲属下拉搜索接口方法。
+
+**真实页面测试产物**
+
+- `output/playwright/`
+  保存浏览器测试截图、录屏或导出文件，不纳入 git。
+- `output/spreadsheet/`
+  保存从真实页面模板生成的导入测试文件，不纳入 git。
+
+**测试记录**
+
+- `docs/tests/records/2026-04-23-staff-family-enterprise-relation-browser-test-record.md`
+  实施阶段记录真实页面测试步骤、样本和结果。
+
+## 实施任务
+
+### Task 1: 调整前端 API 契约为亲属语义
+
+**Files:**
+
+- Modify: `ruoyi-ui/src/api/ccdiStaffEnterpriseRelation.js`
+- Reference: `ruoyi-ui/src/api/ccdiBaseStaff.js`
+
+- [ ] 保留现有列表、详情、新增、编辑、删除、导入、状态查询、失败记录接口方法。
+- [ ] 新增亲属下拉接口方法，建议命名为 `listFamilyOptions(query)`，请求后端 `/ccdi/staffEnterpriseRelation/familyOptions`。
+- [ ] 调整接口注释，把“员工实体关系”全部改成“员工亲属实体关联”。
+- [ ] 保持导入接口和轮询接口签名不变，避免页面额外重构。
+
+### Task 2: 重构查询区、列表和详情展示
+
+**Files:**
+
+- Modify: `ruoyi-ui/src/views/ccdiStaffEnterpriseRelation/index.vue`
+- Reference: `docs/superpowers/specs/2026-04-23-staff-family-enterprise-relation-design.md`
+
+- [ ] 将查询区字段调整为亲属身份证号、亲属名称、关联员工、统一社会信用代码、企业名称、状态。
+- [ ] 将列表列调整为亲属身份证、亲属名称、关联员工、企业名称、关联人在企业的职务、状态、数据来源、创建时间。
+- [ ] 将“关联员工”格式化为 `员工姓名（员工身份证号）`，避免只显示姓名。
+- [ ] 详情弹窗基础信息改为亲属口径，移除旧的员工本人姓名展示。
+- [ ] 所有标题、按钮文案、空提示、通知文案统一切换为“员工亲属实体关联”。
+
+### Task 3: 改造新增/编辑弹窗为亲属下拉选择
+
+**Files:**
+
+- Modify: `ruoyi-ui/src/views/ccdiStaffEnterpriseRelation/index.vue`
+
+- [ ] 将现有 `searchStaff` / `staffOptions` 逻辑替换为亲属下拉逻辑，例如 `searchFamilyOptions` / `familyOptions`。
+- [ ] 下拉项展示为“亲属身份证号 + 亲属名称 / 关联员工姓名”。
+- [ ] 选中亲属后，自动回填并只读展示亲属名称、关联员工。
+- [ ] 编辑态下保持亲属身份证号不可改，统一社会信用代码不可改。
+- [ ] 将表单规则中的身份证号提示改为亲属身份证号提示。
+
+### Task 4: 调整导入模板、轮询与失败记录展示
+
+**Files:**
+
+- Modify: `ruoyi-ui/src/views/ccdiStaffEnterpriseRelation/index.vue`
+
+- [ ] 导入弹窗标题改为“员工亲属实体关联数据导入”。
+- [ ] 模板下载文件名改为亲属实体关联口径。
+- [ ] 导入结果通知和失败提示改为亲属语义。
+- [ ] 将本地缓存 key 从旧语义改成新的独立 key，例如 `staff_family_enterprise_relation_import_last_task`，避免与历史员工语义缓存混淆。
+- [ ] 失败记录表格调整为亲属身份证号、亲属名称、企业名称、统一社会信用代码、失败原因。
+- [ ] 保留现有轮询节奏和失败记录清理按钮，不增加额外交互分支。
+
+### Task 5: 补页面级验证与格式化细节
+
+**Files:**
+
+- Modify: `ruoyi-ui/src/views/ccdiStaffEnterpriseRelation/index.vue`
+
+- [ ] 更新 `reset()` 初始化结构，增加 `relationName`、`staffPersonId`、`staffPersonName` 只读回显字段。
+- [ ] 提交前保持最短路径，不额外引入转换层，只剔除展示态字段或在提交前做最小数据拷贝。
+- [ ] 对失败记录、详情弹窗和表格统一复用同一组字段格式化逻辑，避免页面口径分裂。
+- [ ] 确认页面在桌面端与常见笔记本分辨率下不出现标题换行、按钮挤压和表格列错位。
+
+### Task 6: 执行前端构建与真实页面测试
+
+**Files:**
+
+- Create: `docs/tests/records/2026-04-23-staff-family-enterprise-relation-browser-test-record.md`
+- Output only: `output/playwright/`
+- Output only: `output/spreadsheet/`
+
+- [ ] 先在 `ruoyi-ui` 目录执行 `source ~/.nvm/nvm.sh && nvm use`，确认 Node 版本符合仓库要求。
+- [ ] 执行 `npm run build:prod`，确认前端构建通过。
+- [ ] 启动真实前端页面后，使用 Playwright 打开实际业务页面 `ccdiStaffEnterpriseRelation`，禁止使用 prototype 页面。
+- [ ] 在真实页面验证查询、新增、编辑、删除、详情、导入入口、失败记录入口。
+- [ ] 导入测试必须先从页面下载当前模板，再基于模板在 `output/spreadsheet/` 生成测试文件。
+- [ ] 覆盖至少三类导入样本：有效亲属成功导入、无效亲属失败、亲属不存在失败。
+- [ ] 记录页面提示、导入状态变化、失败记录弹窗内容与列表状态是否正确。
+- [ ] 测试完成后关闭本轮启动的前后端进程，并确保 `output/` 测试文件不纳入 git。
+
+## 验证命令
+
+```bash
+cd /Users/wkc/Desktop/ccdi/ccdi/ruoyi-ui
+source ~/.nvm/nvm.sh && nvm use
+npm run build:prod
+```
+
+## 完成标准
+
+- 查询区、列表和详情全部切换为亲属语义
+- 新增弹窗可按亲属身份证模糊搜索有效亲属，并自动带出亲属名称和关联员工
+- 编辑态保持亲属身份证号和统一社会信用代码不可修改
+- 导入弹窗、模板文件名、轮询通知和失败记录全部切换为亲属语义
+- 本地缓存 key 与历史员工语义隔离
+- 已完成 `nvm` 切换、前端构建和 Playwright 真实页面测试