# 批量重命名失败诊断导出与反馈引导设计

## 背景
当前项目在批量重命名失败时，用户只能看到界面内的失败提示或手动打开 Chrome DevTools 查看控制台日志。对于不懂技术的普通用户来说，这条排障路径门槛过高，常见问题包括：

1. 不知道何时应该收集诊断信息。
2. 不知道该把哪些信息发给开发者。
3. 不会打开 DevTools，也不懂如何复制控制台日志。
4. 即使愿意反馈，也容易被打断或放弃。

因此需要补充一套“低打扰、非阻断、对小白友好”的诊断导出与反馈引导机制：
- 用户在失败结果出现时，能立即看到一个清晰但不突兀的导出入口。
- 点击后可一键下载诊断文件。
- 下载完成后，系统以原地引导的方式告诉用户下一步如何反馈。
- 全流程不强迫用户反馈，也不阻断用户继续重试、返回或关闭界面。

## 目标
- 在批量执行完成且存在失败项时，提供**结果区内联、常显、非阻断**的诊断导出入口。
- 用户点击后，一键下载 JSON 格式诊断文件。
- 下载完成后，原地切换为后续引导条，提供 GitHub、邮件、复制说明、暂不处理四个动作。
- 诊断文件默认包含：
  - 基础环境信息
  - 本次批量任务摘要
  - 失败明细
  - 最近 300 条运行日志
- 默认保留真实文件名，便于开发者排查。

## 非目标
- 不做阻断式 modal、遮罩、二次强提醒。
- 不实现自动上传诊断文件到服务器。
- 不导出 Cookie、Token、Authorization Header 等敏感认证信息。
- 不导出全量 `chrome.storage.local`、页面 DOM、完整 HTML 快照等高噪声或高风险数据。
- 不在本阶段建设完整“诊断中心”或历史诊断列表页面。

## 方案对比

### 方案 A：最小可用版
- 在失败结果区提供“导出诊断”按钮。
- 点击后直接下载诊断文件，不提供后续反馈引导。

**优点**
- 实现简单，开发成本最低。
- 能快速补足“没有导出能力”的核心缺口。

**缺点**
- 对小白用户仍不够友好。
- 用户下载完成后仍可能不知道下一步该做什么。
- 反馈转化率低。

### 方案 B：引导式傻瓜版（推荐）
- 在失败结果区内联显示提示条，包含 `导出诊断` / `暂不处理`。
- 导出成功后，原地替换为引导条，提供：
  - `去 GitHub 反馈`
  - `邮件反馈`
  - `复制说明`
  - `暂不处理`

**优点**
- 最符合普通用户心智：失败 → 下载 → 跟着提示反馈。
- 非阻断，不破坏现有操作流。
- 在体验与落地复杂度之间平衡最好。

**缺点**
- 比最小版多一层 UI 状态管理。
- 需要同时维护 GitHub / 邮件两条反馈文案。

### 方案 C：完整诊断中心
- 除失败场景内联提示外，再增加 popup 或单独页面，支持查看最近失败记录、重复导出、查看日志等。

**优点**
- 功能最完整，可扩展性最好。
- 后续客服和问题回溯能力更强。

**缺点**
- 改动明显更大。
- 存储、状态管理、隐私边界都更复杂。
- 对当前“先补足小白可用导出能力”的目标来说偏重。

**采用方案：B。**

## 交互设计

### 1. 入口出现时机
仅在以下条件同时满足时显示：
- 批量执行已结束。
- `failed > 0`。

若执行全部成功，则不显示任何诊断提示。

### 2. 入口位置与形态
入口位于**现有执行结果视图内部**，建议放在：
- 成功/失败/剩余统计与同步状态之后；
- `重试 / 返回 / 撤销` 操作区之前。

显示为一条轻量内联提示条，而不是卡片弹窗、Toast 或模态框。

**文案示例：**
> 有 3 个文件重命名失败，可导出诊断文件发给开发者排查

**动作：**
- `导出诊断`
- `暂不处理`

### 3. 交互原则
- 默认展开显示，不需要用户额外点开。
- 不阻断任何其它操作。
- 用户可以直接忽略，继续点击 `重试`、`返回` 或关闭面板。
- 点击 `暂不处理` 后，仅隐藏本次结果页中的提示条，不做长期记忆，避免未来用户不明原因地找不到入口。

### 4. 导出后的引导流程
用户点击 `导出诊断` 后：

#### 4.1 导出中状态
- 按钮临时进入 loading：`正在准备诊断…`
- 禁止重复点击。
- 不弹出额外遮罩。

#### 4.2 自动下载诊断文件
文件名建议：
`cloud-drive-renamer-diagnostic-YYYY-MM-DD-HHmm.json`

#### 4.3 原地切换为下载成功引导条
导出成功后，不弹新对话框，而是将原提示条**原地替换**为新的引导条。

**文案示例：**
> 诊断文件已下载到浏览器默认下载位置。如果你愿意反馈问题，可以选择一种方式发送给开发者。

**动作：**
- `去 GitHub 反馈`
- `邮件反馈`
- `复制说明`
- `暂不处理`

### 5. 导出后动作行为

#### 去 GitHub 反馈
- 打开 GitHub Issues 新建页。
- 预填标题与正文模板。
- 明确提示用户：请把刚下载的诊断文件拖到页面上传。

#### 邮件反馈
- 打开默认邮件客户端（`mailto:`）。
- 自动填写收件人、主题、正文模板。
- 正文明确提示：请把刚下载的诊断文件作为附件添加后发送。
- 不尝试自动附加本地文件（浏览器能力与兼容性受限）。

#### 复制说明
- 将一段可直接粘贴到 GitHub 或邮件中的说明模板复制到剪贴板。
- 模板中包含：平台、扩展版本、失败数量、导出时间、诊断文件名等摘要信息。

#### 暂不处理
- 隐藏引导条。
- 不再打扰本次结果页。

## 诊断文件结构设计
诊断文件统一为 JSON，推荐顶层包含四个区块：`meta`、`summary`、`failures`、`logs`。

### 1. meta：基础环境信息
建议字段：
- `taskId`
- `exportedAt`
- `extensionVersion`
- `browserUserAgent`
- `platform`
- `page`
  - 建议仅保留域名与路径，避免多余 query 参数暴露隐私

### 2. summary：本次任务摘要
建议字段：
- `total`
- `success`
- `failed`
- `retried`
- `startedAt`
- `finishedAt`
- `paused`
- `cancelled`
- `ruleConfig`

### 3. failures：失败明细
每一项建议包含：
- `fileId`
- `originalName`
- `targetName`
- `errorMessage`
- `errorCode`（若有）
- `attempt`
- `failedAt`

### 4. logs：最近运行日志
默认保留最近 **300** 条结构化日志。

每条日志建议包含：
- `time`
- `level`
- `module`
- `message`
- `context`

### 不应包含的数据
- Cookie / Token / Authorization Header
- 全量 `chrome.storage.local`
- 页面完整 DOM / HTML
- 无关的成功文件完整明细

## 技术设计

### 1. 结构化日志入口
升级现有 `src/utils/logger.ts`：
- 保留现有 console 输出能力。
- 增加结构化日志对象写入能力。
- 统一日志字段：
  - `time`
  - `level`
  - `module`
  - `message`
  - `context`

推荐提供类似接口：
- `logger.debug(module, message, context?)`
- `logger.info(module, message, context?)`
- `logger.warn(module, message, context?)`
- `logger.error(module, message, context?)`

### 2. 最近日志缓冲区
新增一个诊断日志存储层，例如 `diagnostic-log-store.ts`：
- 维护最近 300 条日志。
- 超出上限时自动丢弃最旧记录。
- 提供：
  - `appendLog(entry)`
  - `getRecentLogs()`
  - `clear()`

建议使用环形缓冲或定长数组策略，保证体积稳定。

### 3. 日志汇总位置
推荐由 background 统一汇总：
- content / popup / dialog / adapter 产生日志；
- 统一发送到 background；
- background 负责写入最近日志缓冲区。

这样导出时只需从统一入口获取日志，避免多处状态不一致。

### 4. 最近失败任务摘要
在批量执行完成后，额外保存一份“最近一次失败任务摘要”，内容即 `summary` + `failures` 所需信息。

建议保存内容：
- `taskId`
- `platform`
- `ruleConfig`
- `startedAt` / `finishedAt`
- `total` / `success` / `failed`
- `retried`
- `failures`

这份摘要可存于 `chrome.storage.local`，只保留最近一次或最近少量失败任务，避免数据膨胀。

### 5. 诊断导出器
新增独立导出器模块，例如 `diagnostic-exporter.ts`：
- 读取最近失败任务摘要。
- 读取最近 300 条结构化日志。
- 组装为诊断 JSON。
- 生成下载文件。

### 6. UI 接入点
优先改动以下组件：
- `file-selector-panel.ts`
  - 控制导出提示条与导出后引导条的状态切换。
  - 负责触发导出与后续动作。
- `config-panel.ts`
  - 渲染结果区内联提示条。
- `popup.ts`
  - 可作为二期能力补充“再次导出最近一次诊断”的手动入口，但不纳入本次 MVP。

## 错误处理

### 导出失败
若诊断文件生成或下载失败：
- 原地显示简洁错误文案：
  > 诊断文件生成失败，请稍后重试
- 提供动作：
  - `重新导出`
  - `暂不处理`

### GitHub / 邮件打开失败
若外链打开失败：
- 退化为自动复制反馈说明。
- 提示用户手动打开反馈渠道。

## 风险与缓解
- **风险：** 结构化日志接入点过多，初期容易漏记关键上下文。  
  **缓解：** 先覆盖执行主链路与失败路径，后续逐步补齐。

- **风险：** 诊断内容过多导致文件膨胀。  
  **缓解：** 将日志上限定为 300 条；任务摘要仅保留必要字段。

- **风险：** 真实文件名带来隐私顾虑。  
  **缓解：** 先按当前产品决策默认保留；后续若需要，可增加“脱敏导出”可选项。

- **风险：** 导出入口过强影响主界面视觉。  
  **缓解：** 使用内联弱提示条，不使用主按钮风格、模态弹窗或 toast 常驻提醒。

## 成功标准
- 普通用户在失败结果页中，不需要打开 DevTools，就能找到诊断导出入口。
- 用户可以在 1 次点击内下载诊断文件。
- 下载后，用户能清楚知道下一步可以去 GitHub 或邮件反馈。
- 整体流程不阻断重试、返回、关闭等原有操作。
- 开发者拿到诊断文件后，可以看到：
  - 本次任务摘要
  - 失败明细
  - 最近 300 条相关运行日志

## 分阶段建议

### MVP
- 结构化日志缓冲（最近 300 条）
- 最近失败任务摘要
- JSON 导出
- 结果区内联提示条
- 导出后原地引导条

### 二期增强
- popup 中再次导出最近一次诊断
- 可选脱敏导出
- 更丰富的错误码分类与模块标记
- 诊断历史记录页面