ccdi/doc/plans/2025-02-08-intermediary-import-history-cleanup.md

中介库导入失败记录清除功能实施计划

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

目标: 在用户重新提交导入时,自动清除上一次导入失败记录的 localStorage 数据和页面按钮显示状态,确保用户只看到最新一次导入的失败信息。

架构: 通过在导入对话框提交时触发事件,通知父组件清除对应类型(个人/实体中介)的导入历史记录,清除操作在文件上传之前执行,确保旧数据不会影响新导入的结果展示。

技术栈: Vue 2.6.12, Element UI 2.15.14, localStorage API, 事件总线模式

---

概述

当前实现中,当导入失败后,页面上会显示"查看导入失败记录"按钮。该按钮的状态保存在 localStorage 中,即使用户刷新页面也能保留。但是,当用户重新提交新的导入时,上一次的失败记录数据不会被清除,导致用户可能看到旧的失败记录。

本功能通过在用户点击"开始导入"按钮时立即清除上一次的导入历史记录,确保每次导入都是干净的状态。

---

Task 1: 修改 ImportDialog.vue - 添加清除历史记录事件触发

文件:

• Modify: ruoyi-ui/src/views/ccdiIntermediary/components/ImportDialog.vue:218

描述: 在 handleSubmit() 方法中,在提交文件上传之前,触发清除历史记录事件。

Step 1: 定位 handleSubmit 方法

打开文件 ruoyi-ui/src/views/ccdiIntermediary/components/ImportDialog.vue,找到第218行的 handleSubmit 方法:

handleSubmit() {
  this.$refs.upload.submit();
},

Step 2: 添加事件触发

在方法体第一行添加事件触发代码:

handleSubmit() {
  // 触发清除历史记录事件
  this.$emit('clear-import-history', this.formData.importType);

  // 提交文件上传
  this.$refs.upload.submit();
},

Step 3: 验证代码逻辑

确认代码逻辑:

• this.formData.importType 的值为 'person' 或 'entity'
• 事件在文件上传之前触发
• 即使事件处理失败也不会影响文件上传流程

Step 4: 保存文件

保存文件修改。

Step 5: 提交代码

git add ruoyi-ui/src/views/ccdiIntermediary/components/ImportDialog.vue
git commit -m "feat: 导入时触发清除历史记录事件"

---

Task 2: 修改 index.vue - 添加事件监听

文件:

• Modify: ruoyi-ui/src/views/ccdiIntermediary/index.vue:98-104

描述: 在 <import-dialog> 组件上添加 @clear-import-history 事件监听。

Step 1: 定位 import-dialog 组件

打开文件 ruoyi-ui/src/views/ccdiIntermediary/index.vue,找到第98-104行的 <import-dialog> 组件:

<!-- 导入对话框 -->
<import-dialog
  :visible.sync="upload.open"
  :title="upload.title"
  @close="handleImportDialogClose"
  @success="getList"
  @import-complete="handleImportComplete"
/>

Step 2: 添加事件监听

在组件上添加 @clear-import-history 事件监听:

<!-- 导入对话框 -->
<import-dialog
  :visible.sync="upload.open"
  :title="upload.title"
  @close="handleImportDialogClose"
  @success="getList"
  @import-complete="handleImportComplete"
  @clear-import-history="handleClearImportHistory"
/>

Step 3: 保存文件

保存文件修改。

Step 4: 提交代码

git add ruoyi-ui/src/views/ccdiIntermediary/index.vue
git commit -m "feat: 监听清除导入历史记录事件"

---

Task 3: 修改 index.vue - 添加事件处理方法 ✅

文件:

• Modify: ruoyi-ui/src/views/ccdiIntermediary/index.vue:488

描述: 在 methods 中添加 handleClearImportHistory 方法来处理清除历史记录的逻辑。

Step 1: 定位插入位置

打开文件 ruoyi-ui/src/views/ccdiIntermediary/index.vue,找到第488行 handleImportComplete 方法的位置。新方法应该插入到该方法之前。

Step 2: 添加事件处理方法

在 handleImportComplete 方法之前添加新方法:

/** 清除导入历史记录 */
handleClearImportHistory(importType) {
  if (importType === 'person') {
    // 清除个人中介导入历史记录
    this.clearPersonImportTaskFromStorage();
    this.showPersonFailureButton = false;
    this.currentPersonTaskId = null;
  } else if (importType === 'entity') {
    // 清除实体中介导入历史记录
    this.clearEntityImportTaskFromStorage();
    this.showEntityFailureButton = false;
    this.currentEntityTaskId = null;
  }
},
/** 处理导入完成 */
handleImportComplete(importData) {
  // ... 现有代码保持不变

Step 3: 验证方法逻辑

确认方法逻辑:

• 根据 importType 参数区分清除个人或实体中介的历史记录
• 调用已存在的 clearPersonImportTaskFromStorage() 或 clearEntityImportTaskFromStorage() 方法
• 重置按钮显示状态 showPersonFailureButton 或 showEntityFailureButton 为 false
• 清空当前任务ID currentPersonTaskId 或 currentEntityTaskId
• 方法利用了现有的辅助方法,遵循 DRY 原则

Step 4: 保存文件

保存文件修改。

Step 5: 提交代码

git add ruoyi-ui/src/views/ccdiIntermediary/index.vue
git commit -m "feat: 实现清除导入历史记录方法"

---

Task 4: 手动测试验证功能

描述: 通过手动测试验证清除历史记录功能是否正常工作。

Step 1: 启动前端开发服务器

cd ruoyi-ui
npm run dev

确认服务器正常运行在 http://localhost

Step 2: 测试个人中介导入失败记录清除

1. 登录系统(用户名: admin, 密码: admin123)
2. 导航到"中介库管理"页面
3. 准备一份包含错误数据的个人中介导入文件
4. 点击"导入"按钮,上传文件并等待导入完成
5. 确认页面上显示"查看个人导入失败记录"按钮
6. 点击该按钮,确认能看到失败记录列表
7. 关闭失败记录对话框
8. 再次点击"导入"按钮,选择任意文件(可以是正确文件)
9. 关键步骤: 点击"开始导入"按钮
10. 预期结果: "查看个人导入失败记录"按钮立即消失
11. 等待导入完成
12. 如果新导入有失败,确认显示的是新的失败记录

Step 3: 测试实体中介导入失败记录清除

1. 准备一份包含错误数据的实体中介导入文件
2. 点击"导入"按钮,切换到"机构中介"标签
3. 上传文件并等待导入完成
4. 确认页面上显示"查看实体导入失败记录"按钮
5. 点击该按钮,确认能看到失败记录列表
6. 关闭失败记录对话框
7. 再次点击"导入"按钮,选择任意文件
8. 关键步骤: 点击"开始导入"按钮
9. 预期结果: "查看实体导入失败记录"按钮立即消失

Step 4: 测试两种类型互不影响

1. 导入个人中介数据(有失败),确认按钮显示
2. 导入实体中介数据(有失败),确认两个按钮都显示
3. 重新导入个人中介
4. 预期结果: 只清除个人中介的失败记录按钮,实体中介按钮仍显示
5. 反之测试重新导入实体中介,确认只清除实体中介按钮

Step 5: 测试边界情况

1. 导入数据(全部成功),确认不显示失败记录按钮
2. 重新导入数据,确认不影响任何状态
3. 打开浏览器开发者工具(F12),查看 Console 是否有错误日志
4. 在 Application -> Local Storage 中,确认 intermediary_person_import_last_task 和 intermediary_entity_import_last_task 数据在点击"开始导入"后被清除

Step 6: 测试快速连续点击

1. 导入数据(有失败),确认按钮显示
2. 打开导入对话框,快速连续多次点击"开始导入"按钮
3. 预期结果: 按钮被禁用(isUploading=true),不会重复提交

Step 7: 记录测试结果

记录每个测试场景的结果:

• ✅ 通过
• ❌ 失败(记录具体问题)

如果所有测试都通过,功能实现完成。

---

Task 5: 代码审查和文档更新

描述: 检查代码质量,更新相关文档。

Step 1: 代码审查清单

• 代码遵循项目现有的代码风格
• 方法命名清晰,语义准确
• 没有重复代码(DRY原则)
• 错误处理适当(localStorage操作失败不会导致流程中断)
• 事件名称符合Vue规范(kebab-case)
• 注释清晰,易于理解

Step 2: 验证改动范围

确认只修改了以下文件:

• ruoyi-ui/src/views/ccdiIntermediary/components/ImportDialog.vue
• ruoyi-ui/src/views/ccdiIntermediary/index.vue

Step 3: 检查是否需要更新API文档

本次改动只涉及前端代码,不涉及API接口,无需更新API文档。

Step 4: 提交最终代码

git status
git log --oneline -5

确认所有改动已提交。

---

附录: 相关文件说明

ImportDialog.vue

导入对话框组件,负责文件上传和导入任务状态轮询。

关键方法:

• handleSubmit(): 提交文件上传
• handleImportComplete(): 处理导入完成,通过事件通知父组件

index.vue

中介库管理主页面,包含列表展示、编辑、导入等功能。

关键数据:

• showPersonFailureButton: 是否显示个人中介失败记录按钮
• showEntityFailureButton: 是否显示实体中介失败记录按钮
• currentPersonTaskId: 当前个人中介导入任务ID
• currentEntityTaskId: 当前实体中介导入任务ID

关键方法:

• clearPersonImportTaskFromStorage(): 清除个人中介导入历史
• clearEntityImportTaskFromStorage(): 清除实体中介导入历史
• handleImportComplete(): 处理导入完成事件
• handleClearImportHistory(): 处理清除历史记录事件(新增)

localStorage 存储结构

个人中介:

{
  "taskId": "uuid-string",
  "hasFailures": true,
  "totalCount": 100,
  "successCount": 95,
  "failureCount": 5,
  "saveTime": 1704067200000
}

实体中介:

{
  "taskId": "uuid-string",
  "hasFailures": true,
  "totalCount": 50,
  "successCount": 48,
  "failureCount": 2,
  "saveTime": 1704067200000
}

---

总结

本实施计划通过最小化的代码改动(3处修改),实现了在用户重新提交导入时自动清除上一次导入失败记录的功能。整个实现遵循了以下原则:

1. YAGNI (You Aren't Gonna Need It): 只实现必要的功能,没有过度设计
2. DRY (Don't Repeat Yourself): 复用现有的 localStorage 清除方法
3. 单一职责: 每个方法只做一件事
4. 防御性编程: localStorage 操作有错误处理,不会影响主流程

实施完成后,用户在重新导入数据时将获得更清晰的用户体验,不会被旧的失败记录混淆。