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

> **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 真实页面测试