6.7 KiB
员工亲属实体关联维护前端实施计划
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。
验证命令
cd /Users/wkc/Desktop/ccdi/ccdi/ruoyi-ui
source ~/.nvm/nvm.sh && nvm use
npm run build:prod
完成标准
- 查询区、列表和详情全部切换为亲属语义
- 新增弹窗可按亲属身份证模糊搜索有效亲属，并自动带出亲属名称和关联员工
- 编辑态保持亲属身份证号和统一社会信用代码不可修改
- 导入弹窗、模板文件名、轮询通知和失败记录全部切换为亲属语义
- 本地缓存 key 与历史员工语义隔离
- 已完成
nvm切换、前端构建和 Playwright 真实页面测试