# 变更提案: admin-frontend-queue-error-details

## 元信息
```yaml
类型: 功能增强
方案类型: implementation
优先级: P1
状态: 已完成
创建: 2026-04-23
```

---

## 1. 需求

### 背景
当前 `admin-frontend` 仪表盘“作业详情”面板仅展示队列概览指标，管理员无法直接查看失败作业的具体报错内容。排查队列异常时，需要额外进入后端或 Horizon 页面，链路过长。

### 目标
- 在 `admin-frontend` 仪表盘“作业详情”面板新增“查看报错详情”入口。
- 点击后弹出失败作业详情弹窗，集中展示失败作业列表、报错摘要、失败时间与队列信息。
- 保持 `apple/DESIGN.md` 约束：纯色分区、单一蓝色强调、低噪音交互。

### 约束条件
```yaml
范围约束: 仅调整 admin-frontend 仪表盘与失败作业弹窗，不改动 Laravel 后端接口行为
视觉约束: 延续 Apple 风格，避免高饱和告警面板和复杂多列控制区
技术约束: 复用现有 Element Plus / axios 能力，不新增第三方依赖
业务约束: 前端需兼容 Horizon 失败作业字段可能存在的格式差异
```

### 验收标准
- [ ] “作业详情”面板新增“查看报错详情”按钮，并符合当前仪表盘视觉基线。
- [ ] 点击按钮后可打开弹窗，展示失败作业总数、失败作业列表、报错摘要、失败时间和队列名。
- [ ] 当失败作业为空时，有明确空状态提示；加载失败时有明确错误反馈。
- [ ] `admin-frontend` 构建通过，产物成功输出到 `public/assets/admin`。

---

## 2. 方案

### 技术方案
1. 在 `src/api/admin.ts` 中新增失败作业接口封装，并在 `src/types/api.d.ts` 中补充失败作业响应类型。
2. 新建 `src/views/dashboard/QueueFailedJobsDialog.vue`，负责弹窗数据加载、失败作业列表渲染、分页与空状态/错误态处理。
3. 在 `src/views/dashboard/DashboardView.vue` 的“作业详情”面板增加“查看报错详情”按钮，并管理弹窗打开状态。

### 影响范围
```yaml
涉及模块:
  - admin-frontend/src/views/dashboard/DashboardView.vue
  - admin-frontend/src/views/dashboard/QueueFailedJobsDialog.vue
  - admin-frontend/src/api/admin.ts
  - admin-frontend/src/types/api.d.ts
  - admin-frontend/src/env.d.ts
  - public/assets/admin (构建产物输出)
预计变更文件: 5-7
```

### 风险评估
| 风险 | 等级 | 应对 |
|------|------|------|
| Horizon 返回字段在不同版本存在差异 | 中 | 前端按多字段兜底提取任务名、队列名和失败时间 |
| 报错文本过长导致弹窗密度过高 | 中 | 默认展示摘要，长文本采用可换行容器，不在主面板直接展开 |
| 构建产物写入子模块后状态不易观察 | 中 | 构建后同时检查根仓和 `public/assets/admin` 子模块状态 |

---

## 3. 成果设计

### 设计方向
- **美学基调**: 黑色作业面板内保留克制的 Apple 风格，弹窗内部以浅灰层次承载错误列表。
- **交互模式**: 主面板只增加一个低干扰入口按钮，详细信息集中放入弹窗，避免仪表盘直接堆叠错误文本。
- **记忆点**: 通过“概览指标 + 详情弹窗”的双层结构，把队列异常从“只看数量”提升到“可直接定位报错”。

### 视觉要素
- **配色**: 继续使用 `#0071e3` 作为交互强调，错误摘要使用低饱和红色辅助标签，不破坏整体黑白基调。
- **排版**: 弹窗头部保持 Apple 风格大标题，内容区采用信息块 + 列表节奏，不做复杂表单式布局。
- **状态**: 提供加载态、空状态、异常态和分页态，确保操作反馈完整。

---

## 4. 技术决策

### admin-frontend-queue-error-details#D001: 使用弹窗承载失败作业详情而非直接在仪表盘展开
**日期**: 2026-04-23
**状态**: ✅采纳
**背景**: 用户要求“添加查看详情报错按钮，并点击后添加弹窗显示所有报错”。
**决策**: 主面板只提供入口按钮，失败作业详情统一放在弹窗内展示。
**理由**: 更符合当前 Apple 风格的克制表达，也避免仪表盘信息密度失控。

### admin-frontend-queue-error-details#D002: 前端兼容式解析 Horizon 失败作业字段
**日期**: 2026-04-23
**状态**: ✅采纳
**背景**: 后端直接透传 Horizon 失败作业记录，字段可能因版本和 payload 结构不同而有差异。
**决策**: 前端通过多字段兜底函数提取任务名、队列名、失败时间与报错摘要。
**理由**: 在不改动后端接口的前提下，提高界面健壮性，减少联调阻塞。