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

> **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` 方法:

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

**Step 2: 添加事件触发**

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

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

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

**Step 3: 验证代码逻辑**

确认代码逻辑:

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

**Step 4: 保存文件**

保存文件修改。

**Step 5: 提交代码**

```bash
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>` 组件:

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

**Step 2: 添加事件监听**

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

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

**Step 3: 保存文件**

保存文件修改。

**Step 4: 提交代码**

```bash
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` 方法之前添加新方法:

```javascript
/** 清除导入历史记录 */
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: 提交代码**

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

---

## Task 4: 手动测试验证功能

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

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

```bash
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: 提交最终代码**

```bash
git status
git log --oneline -5
```

确认所有改动已提交。

---

## 附录: 相关文件说明

### ImportDialog.vue

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

**关键方法:**

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

### index.vue

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

**关键数据:**

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

**关键方法:**

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

### localStorage 存储结构

**个人中介:**

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

**实体中介:**

```json
{
  "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 操作有错误处理,不会影响主流程

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