orc-order-v2/docs/superpowers/specs/2026-05-12-frontend-bugfix-quality-design.md

# 前端 Bug 修复 + 代码质量提升设计文档

日期: 2026-05-12
状态: 待审核

## 背景

通过全面审计 Web 前端（Vue 3 + Element Plus），发现了 50+ 个问题。本文档聚焦于前端高优先级 Bug 修复和代码质量改进，分 3 个阶段执行。

## 阶段 1：关键 Bug 修复

### 1.1 修复 fetchUser 未调用

**问题**: `Layout.vue` 在 `onMounted` 时未调用 `authStore.fetchUser()`。页面刷新后 `authStore.username` 为空，头像显示 "U" 而非用户名首字母。

**修复**: 在 `Layout.vue` 的 `onMounted` 中添加 `await authStore.fetchUser()`。

**影响文件**: `web/frontend/src/views/Layout.vue`

### 1.2 修复静默吞错

**问题**: 以下文件的 catch 块完全为空，API 失败时用户无任何反馈：

| 文件 | 函数 | 行号 |
|------|------|------|
| `files/Images.vue` | `loadData()` | 165 |
| `files/Tables.vue` | `loadData()` | 161 |
| `files/Orders.vue` | `loadData()` | 168 |
| `Sync.vue` | `checkStatus()` | 127 |
| `Tasks.vue` | `loadStats()` | 207 |
| `Logs.vue` | `loadStats()` | 164 |
| `files/Images.vue` | `deleteFile()` | 272 |
| `files/Tables.vue` | `deleteFile()` | 250 |
| `files/Orders.vue` | `deleteFile()` | 242 |

**修复**: 所有 catch 块添加 `ElMessage.error()` 提示，使用中文错误消息。

**影响文件**: 上述 6 个 Vue 文件

### 1.3 修复 loading 状态管理

**问题**: `Images.vue`、`Tables.vue`、`Orders.vue` 的 `loadData()` 中 `loading.value = false` 不在 `finally` 块中。异常发生时 loading 转圈卡住。

**修复**: 统一改为 `try { ... } finally { loading.value = false }` 模式。

**影响文件**: `files/Images.vue`、`files/Tables.vue`、`files/Orders.vue`

### 1.4 修复内存统计回退逻辑

**问题**: `Memory.vue` 当 API 不返回 stats 时，从 `items.value`（当前页 50 条）计算置信度统计，显示为全局数据，严重误导用户。

**修复**: 移除误导性回退逻辑，当 stats 不可用时显示 "暂无统计数据" 占位。

**影响文件**: `web/frontend/src/views/Memory.vue`

### 1.5 添加全局错误处理

**问题**: `main.ts` 没有 `app.config.errorHandler`，未捕获的 Vue 错误只输出到 console.warn，用户无感知。

**修复**: 在 `main.ts` 注册全局错误处理器：

```typescript
app.config.errorHandler = (err, instance, info) => {
  console.error('Vue error:', err, info)
  ElMessage.error('操作失败，请稍后重试')
}
```

**影响文件**: `web/frontend/src/main.ts`

---

## 阶段 2：代码质量 — 提取共享逻辑

### 2.1 提取 useDebounce composable

**问题**: `useDebounce` 函数在 4 个文件中完全重复（Memory.vue:166-174, Barcodes.vue:190-198, Tasks.vue:144-152, Logs.vue:107-115）。

**修复**: 创建 `web/frontend/src/composables/useDebounce.ts`：

```typescript
import { ref } from 'vue'

export function useDebounce(fn: Function, delay = 300) {
  const timer = ref<ReturnType<typeof setTimeout> | null>(null)
  return (...args: any[]) => {
    if (timer.value) clearTimeout(timer.value)
    timer.value = setTimeout(() => fn(...args), delay)
  }
}
```

4 个文件改为 `import { useDebounce } from '@/composables/useDebounce'`。

**影响文件**:
- 新建: `web/frontend/src/composables/useDebounce.ts`
- 修改: `Memory.vue`、`Barcodes.vue`、`Tasks.vue`、`Logs.vue`

### 2.2 提取文件视图共享逻辑

**问题**: `Images.vue`、`Tables.vue`、`Orders.vue` 有大量重复代码：
- `statusType()`、`statusText()`、`fmtTime()` 函数完全相同
- 预览对话框模板 + 逻辑 + CSS 完全相同
- 详情对话框模板 + 逻辑完全相同
- 分页、多选、排序模式完全相同
- 批量删除模式完全相同

**修复**: 创建 3 个共享 composable：

#### `composables/useFileUtils.ts`
```typescript
export function statusType(status: string): string { ... }
export function statusText(status: string): string { ... }
export function fmtTime(t: string): string { ... }
```

#### `composables/useFilePreview.ts`
```typescript
export function useFilePreview() {
  // previewVisible, previewContent, previewTitle, previewLoading
  // openPreview(), closePreview()
  return { ... }
}
```

#### `composables/useFileSelection.ts`
```typescript
export function useFileSelection(fetchFn: Function) {
  // selectedFiles, currentPage, pageSize, total, sortProp, sortOrder
  // handleSelectionChange(), handlePageChange(), handleSortChange(), toggleSelectAll()
  return { ... }
}
```

3 个文件视图改为使用这些 composable，每个文件预计减少 100-150 行重复代码。

**影响文件**:
- 新建: `composables/useFileUtils.ts`、`composables/useFilePreview.ts`、`composables/useFileSelection.ts`
- 修改: `files/Images.vue`、`files/Tables.vue`、`files/Orders.vue`

### 2.3 清理死代码

| 文件 | 死代码 | 行号 |
|------|--------|------|
| `Layout.vue` | `navItems` 数组（未被引用） | 175-183 |
| `stores/processing.ts` | `pollTaskStatus` 函数（未被调用） | 124-129 |
| `router/index.ts` | `routeLoadingTimer` 逻辑（无消费者） | 87-94 |
| `Barcodes.vue` | `Plus` 图标导入（未使用） | 186 |

**影响文件**: 上述 4 个文件

---

## 阶段 3：小改进

### 3.1 修改密码表单验证

**问题**: `Layout.vue` 的修改密码对话框无任何验证：无最小长度要求、无确认密码字段。

**修复**:
- 添加 el-form 验证规则：密码最少 6 位
- 添加确认密码字段，验证两次输入一致
- 提交前调用 `formRef.validate()`

**影响文件**: `web/frontend/src/views/Layout.vue`

### 3.2 修复 Layout.vue 冗余代码

**问题**: `navigator.onLine !== false` 冗余（`navigator.onLine` 已经是 boolean）。

**修复**: 改为 `navigator.onLine`。

**影响文件**: `web/frontend/src/views/Layout.vue`

### 3.3 后端批量删除端点

**问题**: 前端批量删除是 N+1 API 调用（每个文件 2 次请求），50 个文件 = 100 次 HTTP 请求。

**修复**:
- 后端添加 `POST /api/files/batch-delete` 端点，接受 `files: [{directory, filename}]` 数组
- 前端批量删除改为单次 API 调用

**影响文件**:
- 新建/修改: `web/backend/routers/files.py`
- 修改: `files/Images.vue`、`files/Tables.vue`、`files/Orders.vue`

---

## 不在范围内

以下问题记录但不在本次修复范围内：
- 响应式布局（仅 Dashboard 有 @media 查询）
- 键盘快捷键
- 类型感知配置编辑器
- 后端安全问题（路径遍历、登录限流等）
- WebSocket 认证 token 刷新
- 产品记忆批量操作/导出
- 任务取消支持

## 验证标准

1. 页面刷新后头像正确显示用户名首字母
2. API 失败时用户看到错误提示 toast
3. loading 状态不会卡住
4. 统计数据准确或显示占位
5. 未捕获的 Vue 错误有用户提示
6. useDebounce 在 4 个文件中通过 import 使用，无重复定义
7. 3 个文件视图使用共享 composable，每个文件减少 100+ 行
8. 4 处死代码已清理
9. 修改密码表单有验证规则和确认字段
10. 批量删除为单次 API 调用