414 lines
12 KiB
Markdown
414 lines
12 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.
|
||
> **执行约束：** 仓库约定不开 subagent，执行时使用 `superpowers:executing-plans`；前端 Node 版本必须通过 `nvm` 切换到仓库已验证版本。
|
||
|
||
**Goal:** 将中介库前端导入入口改造为“导入中介信息 + 导入中介实体关联关系”两按钮模式，去掉旧的“个人/机构”切换导入，打通异步轮询、失败记录查看、历史任务恢复，并保持现有手工维护链路继续使用 `bizId` 契约。
|
||
|
||
**Architecture:** 保留 `ruoyi-ui/src/views/ccdiIntermediary/` 作为唯一页面入口，不新增平行页面。导入弹窗继续复用现有 `ImportDialog.vue` 外壳，但改为由父页面通过 `scene`/`importType` 驱动，而不是弹窗内部单选切换；`index.vue` 负责管理两类导入任务状态、失败记录和按钮展示，交互整体对齐员工数据导入页面。
|
||
|
||
**Tech Stack:** Vue 2, Element UI, JavaScript, npm, nvm, Markdown
|
||
|
||
---
|
||
|
||
## 文件结构与职责
|
||
|
||
**设计与计划基线**
|
||
|
||
- `docs/design/2026-04-20-intermediary-import-refactor-design.md`
|
||
已确认的导入边界、字段口径和前端交互基线。
|
||
|
||
**前端源码**
|
||
|
||
- Modify: `ruoyi-ui/src/views/ccdiIntermediary/index.vue`
|
||
负责顶部按钮、两类导入弹窗打开逻辑、异步任务状态恢复、失败记录弹窗和表格刷新。
|
||
- Modify: `ruoyi-ui/src/views/ccdiIntermediary/components/ImportDialog.vue`
|
||
从“内部切换 person/entity”改为“父组件传入导入场景”，支持中介信息导入和实体关联关系导入。
|
||
- Modify: `ruoyi-ui/src/api/ccdiIntermediary.js`
|
||
补两类导入的模板下载、上传、状态查询、失败记录 API。
|
||
|
||
**测试**
|
||
|
||
- Create: `ruoyi-ui/tests/unit/intermediary-import-toolbar.test.js`
|
||
- Create: `ruoyi-ui/tests/unit/intermediary-import-dialog.test.js`
|
||
- Create: `ruoyi-ui/tests/unit/intermediary-import-state.test.js`
|
||
- Create: `ruoyi-ui/tests/unit/intermediary-import-api.test.js`
|
||
- Modify: `ruoyi-ui/tests/unit/intermediary-person-edit-ui.test.js`
|
||
|
||
**依赖参考**
|
||
|
||
- `ruoyi-ui/src/views/ccdiBaseStaff/index.vue`
|
||
参考顶部导入按钮、轮询、失败记录、历史任务恢复。
|
||
- `ruoyi-ui/src/views/ccdiIntermediary/components/ImportDialog.vue`
|
||
继续作为导入弹窗壳子，不重复造一个全新组件。
|
||
- `ruoyi-ui/tests/unit/employee-asset-import-ui.test.js`
|
||
参考导入类单测结构和断言风格。
|
||
|
||
## 实施任务
|
||
|
||
### Task 1: 改造 API 文件为两类导入链路
|
||
|
||
**Files:**
|
||
|
||
- Modify: `ruoyi-ui/src/api/ccdiIntermediary.js`
|
||
- Test: `ruoyi-ui/tests/unit/intermediary-import-api.test.js`
|
||
|
||
- [ ] **Step 1: 先写失败测试，固定 API 方法名与路径**
|
||
|
||
覆盖：
|
||
|
||
```js
|
||
importPersonTemplate
|
||
importPersonData
|
||
getPersonImportStatus
|
||
getPersonImportFailures
|
||
importEnterpriseRelationTemplate
|
||
importEnterpriseRelationData
|
||
getEnterpriseRelationImportStatus
|
||
getEnterpriseRelationImportFailures
|
||
```
|
||
|
||
- [ ] **Step 2: 保留中介信息导入 API**
|
||
|
||
中介信息导入继续使用：
|
||
|
||
```js
|
||
/ccdi/intermediary/importPersonTemplate
|
||
/ccdi/intermediary/importPersonData
|
||
/ccdi/intermediary/importPersonStatus/{taskId}
|
||
/ccdi/intermediary/importPersonFailures/{taskId}
|
||
```
|
||
|
||
- [ ] **Step 3: 新增实体关联关系导入 API**
|
||
|
||
新增：
|
||
|
||
```js
|
||
/ccdi/intermediary/importEnterpriseRelationTemplate
|
||
/ccdi/intermediary/importEnterpriseRelationData
|
||
/ccdi/intermediary/importEnterpriseRelationStatus/{taskId}
|
||
/ccdi/intermediary/importEnterpriseRelationFailures/{taskId}
|
||
```
|
||
|
||
- [ ] **Step 4: 删除前端对旧 `importEntity*` 导入接口的依赖**
|
||
|
||
Expected: 页面不再调用旧“机构中介导入”接口。
|
||
|
||
- [ ] **Step 5: 运行 API 测试**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
cd /Users/wkc/Desktop/ccdi/ccdi/ruoyi-ui
|
||
node tests/unit/intermediary-import-api.test.js
|
||
```
|
||
|
||
Expected: PASS，方法名和 URL 与设计文档一致。
|
||
|
||
- [ ] **Step 6: 提交 API 调整**
|
||
|
||
```bash
|
||
git add ruoyi-ui/src/api/ccdiIntermediary.js ruoyi-ui/tests/unit/intermediary-import-api.test.js
|
||
git commit -m "调整中介导入前端接口"
|
||
```
|
||
|
||
### Task 2: 将导入弹窗改为场景驱动
|
||
|
||
**Files:**
|
||
|
||
- Modify: `ruoyi-ui/src/views/ccdiIntermediary/components/ImportDialog.vue`
|
||
- Test: `ruoyi-ui/tests/unit/intermediary-import-dialog.test.js`
|
||
|
||
- [ ] **Step 1: 先写弹窗行为测试**
|
||
|
||
覆盖：
|
||
|
||
```js
|
||
// 1. 不再渲染“个人中介/机构中介”单选
|
||
// 2. scene=person 时调用中介信息导入地址
|
||
// 3. scene=enterpriseRelation 时调用实体关联关系导入地址
|
||
// 4. 模板文案随场景切换
|
||
```
|
||
|
||
- [ ] **Step 2: 把内部单选切换改成父组件传参**
|
||
|
||
新增 props：
|
||
|
||
```js
|
||
scene: {
|
||
type: String,
|
||
default: 'person'
|
||
}
|
||
```
|
||
|
||
Expected: 弹窗自身不再维护 `formData.importType`。
|
||
|
||
- [ ] **Step 3: 根据 `scene` 计算上传地址和模板地址**
|
||
|
||
```js
|
||
scene === 'person'
|
||
scene === 'enterpriseRelation'
|
||
```
|
||
|
||
- [ ] **Step 4: 按场景返回不同提示文案**
|
||
|
||
中介信息导入提示需要包含：
|
||
|
||
```text
|
||
personSubType 为字典下拉；
|
||
本人行 relatedNumId 为空；
|
||
亲属行 relatedNumId 填关联中介本人证件号码。
|
||
```
|
||
|
||
实体关联关系导入提示需要包含：
|
||
|
||
```text
|
||
只导入中介与机构关系；
|
||
统一社会信用代码必须已存在于系统机构表。
|
||
```
|
||
|
||
- [ ] **Step 5: 运行弹窗测试**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
cd /Users/wkc/Desktop/ccdi/ccdi/ruoyi-ui
|
||
node tests/unit/intermediary-import-dialog.test.js
|
||
```
|
||
|
||
Expected: PASS，弹窗只根据外部场景工作。
|
||
|
||
- [ ] **Step 6: 提交弹窗改造**
|
||
|
||
```bash
|
||
git add ruoyi-ui/src/views/ccdiIntermediary/components/ImportDialog.vue ruoyi-ui/tests/unit/intermediary-import-dialog.test.js
|
||
git commit -m "改造中介导入弹窗场景切换"
|
||
```
|
||
|
||
### Task 3: 改造页面顶部按钮与任务状态
|
||
|
||
**Files:**
|
||
|
||
- Modify: `ruoyi-ui/src/views/ccdiIntermediary/index.vue`
|
||
- Test: `ruoyi-ui/tests/unit/intermediary-import-toolbar.test.js`
|
||
- Test: `ruoyi-ui/tests/unit/intermediary-import-state.test.js`
|
||
|
||
- [ ] **Step 1: 先写按钮与状态测试**
|
||
|
||
覆盖：
|
||
|
||
```js
|
||
// 1. 顶部有两个导入按钮
|
||
// 2. 按钮文案正确
|
||
// 3. 两类失败记录按钮独立显示
|
||
// 4. localStorage 使用两套独立 key
|
||
```
|
||
|
||
- [ ] **Step 2: 在工具栏增加两个导入按钮**
|
||
|
||
按钮文案固定为：
|
||
|
||
```vue
|
||
导入中介信息
|
||
导入中介实体关联关系
|
||
```
|
||
|
||
- [ ] **Step 3: 在页面中维护两套独立任务状态**
|
||
|
||
建议状态结构：
|
||
|
||
```js
|
||
personImportTask
|
||
enterpriseRelationImportTask
|
||
```
|
||
|
||
以及两套本地缓存 key：
|
||
|
||
```js
|
||
ccdi_intermediary_person_import_task
|
||
ccdi_intermediary_enterprise_relation_import_task
|
||
```
|
||
|
||
- [ ] **Step 4: 保持页面原有手工维护链路不变**
|
||
|
||
Expected: 打开详情、新增亲属、查询关系列表等既有逻辑继续走 `bizId`，不因导入改造改变页面其它交互。
|
||
|
||
- [ ] **Step 5: 运行按钮与状态测试**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
cd /Users/wkc/Desktop/ccdi/ccdi/ruoyi-ui
|
||
node tests/unit/intermediary-import-toolbar.test.js
|
||
node tests/unit/intermediary-import-state.test.js
|
||
```
|
||
|
||
Expected: PASS，按钮与任务缓存隔离正确。
|
||
|
||
- [ ] **Step 6: 提交页面状态改造**
|
||
|
||
```bash
|
||
git add ruoyi-ui/src/views/ccdiIntermediary/index.vue ruoyi-ui/tests/unit/intermediary-import-toolbar.test.js ruoyi-ui/tests/unit/intermediary-import-state.test.js
|
||
git commit -m "调整中介导入页面入口状态"
|
||
```
|
||
|
||
### Task 4: 接入失败记录弹窗与完成态刷新
|
||
|
||
**Files:**
|
||
|
||
- Modify: `ruoyi-ui/src/views/ccdiIntermediary/index.vue`
|
||
- Modify: `ruoyi-ui/src/views/ccdiIntermediary/components/ImportDialog.vue`
|
||
- Modify: `ruoyi-ui/tests/unit/intermediary-person-edit-ui.test.js`
|
||
|
||
- [ ] **Step 1: 先写失败记录行为断言**
|
||
|
||
在现有中介页面测试里补充：
|
||
|
||
```js
|
||
// 1. 导入完成且 failureCount > 0 时显示对应失败记录按钮
|
||
// 2. 查看失败记录时调用对应接口
|
||
// 3. 清除历史记录后按钮消失
|
||
```
|
||
|
||
- [ ] **Step 2: 在 `index.vue` 中落两套失败记录弹窗状态**
|
||
|
||
建议状态：
|
||
|
||
```js
|
||
personFailureDialogVisible
|
||
enterpriseRelationFailureDialogVisible
|
||
personFailureList
|
||
enterpriseRelationFailureList
|
||
```
|
||
|
||
- [ ] **Step 3: 对齐员工导入的完成态逻辑**
|
||
|
||
Expected:
|
||
|
||
```js
|
||
导入完成 -> 刷新列表 -> 刷新当前详情(如有) -> 更新失败按钮状态
|
||
```
|
||
|
||
- [ ] **Step 4: 对齐员工导入的历史记录恢复逻辑**
|
||
|
||
页面刷新后如果任务仍在缓存中：
|
||
|
||
```js
|
||
恢复失败记录按钮
|
||
恢复上次导入摘要
|
||
必要时继续轮询
|
||
```
|
||
|
||
- [ ] **Step 5: 运行页面行为测试**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
cd /Users/wkc/Desktop/ccdi/ccdi/ruoyi-ui
|
||
node tests/unit/intermediary-person-edit-ui.test.js
|
||
```
|
||
|
||
Expected: PASS，没有把导入状态逻辑打坏现有详情维护链路。
|
||
|
||
- [ ] **Step 6: 提交失败记录与刷新逻辑**
|
||
|
||
```bash
|
||
git add ruoyi-ui/src/views/ccdiIntermediary/index.vue ruoyi-ui/src/views/ccdiIntermediary/components/ImportDialog.vue ruoyi-ui/tests/unit/intermediary-person-edit-ui.test.js
|
||
git commit -m "补齐中介导入失败记录交互"
|
||
```
|
||
|
||
### Task 5: 做前端验证并回写计划结果
|
||
|
||
**Files:**
|
||
|
||
- Modify: `docs/plans/frontend/2026-04-20-intermediary-import-frontend-implementation.md`
|
||
|
||
- [ ] **Step 1: 使用 nvm 切换到仓库已验证版本**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
cd /Users/wkc/Desktop/ccdi/ccdi/ruoyi-ui
|
||
source ~/.nvm/nvm.sh && nvm use 14.21.3
|
||
```
|
||
|
||
Expected: 输出 `Now using node v14.21.3`。
|
||
|
||
- [ ] **Step 2: 运行前端相关单测脚本**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
cd /Users/wkc/Desktop/ccdi/ccdi/ruoyi-ui
|
||
node tests/unit/intermediary-import-api.test.js
|
||
node tests/unit/intermediary-import-dialog.test.js
|
||
node tests/unit/intermediary-import-toolbar.test.js
|
||
node tests/unit/intermediary-import-state.test.js
|
||
node tests/unit/intermediary-person-edit-ui.test.js
|
||
```
|
||
|
||
Expected: 全部 PASS。
|
||
|
||
- [ ] **Step 3: 执行生产构建验证**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
cd /Users/wkc/Desktop/ccdi/ccdi/ruoyi-ui
|
||
source ~/.nvm/nvm.sh && nvm use 14.21.3 && npm run build:prod
|
||
```
|
||
|
||
Expected: `BUILD SUCCESS`，没有新增语法或模块解析错误。
|
||
|
||
- [ ] **Step 4: 回写执行结果**
|
||
|
||
在计划文档末尾补：
|
||
|
||
```markdown
|
||
- 实际执行的 node / build 命令
|
||
- 各测试脚本 PASS / FAIL 结果
|
||
- 构建结果
|
||
```
|
||
|
||
- [ ] **Step 5: 提交验证结果**
|
||
|
||
```bash
|
||
git add docs/plans/frontend/2026-04-20-intermediary-import-frontend-implementation.md
|
||
git commit -m "补充中介导入前端实施记录"
|
||
```
|
||
|
||
## 验证命令
|
||
|
||
```bash
|
||
cd /Users/wkc/Desktop/ccdi/ccdi/ruoyi-ui
|
||
source ~/.nvm/nvm.sh && nvm use 14.21.3
|
||
node tests/unit/intermediary-import-api.test.js
|
||
node tests/unit/intermediary-import-dialog.test.js
|
||
node tests/unit/intermediary-import-toolbar.test.js
|
||
node tests/unit/intermediary-import-state.test.js
|
||
node tests/unit/intermediary-person-edit-ui.test.js
|
||
source ~/.nvm/nvm.sh && nvm use 14.21.3 && npm run build:prod
|
||
```
|
||
|
||
## 完成标准
|
||
|
||
- 顶部只有“导入中介信息”和“导入中介实体关联关系”两个按钮
|
||
- 导入弹窗不再内部切换“个人/机构”，而是由页面场景驱动
|
||
- 两类导入的模板下载、上传、轮询、失败记录全部独立
|
||
- 现有手工维护链路继续保持 `bizId` 契约
|
||
- 页面支持恢复两类最近一次导入任务状态
|
||
- 导入提示文案已经明确 `personSubType` 字典下拉、`relationType` 废弃、`relatedNumId` 新语义
|
||
- 已使用 `nvm use 14.21.3` 完成前端测试脚本和生产构建验证
|
||
|
||
## 执行结果
|
||
|
||
- Node 命令：
|
||
`source ~/.nvm/nvm.sh && cd ruoyi-ui && nvm use 14.21.3`
|
||
结果：PASS（Now using node v14.21.3）
|
||
- Node 命令：
|
||
`source ~/.nvm/nvm.sh && cd ruoyi-ui && nvm use 14.21.3 >/dev/null && node tests/unit/intermediary-import-api.test.js && node tests/unit/intermediary-import-dialog.test.js && node tests/unit/intermediary-import-toolbar.test.js && node tests/unit/intermediary-import-state.test.js && node tests/unit/intermediary-person-edit-ui.test.js`
|
||
结果：PASS
|
||
- Node 命令：
|
||
`source ~/.nvm/nvm.sh && cd ruoyi-ui && nvm use 14.21.3 >/dev/null && npm run build:prod`
|
||
结果：PASS（构建成功，仅保留原有 bundle size warning）
|