From 1ceb3d603d07c9e28ff57b877432ede044f7ec71 Mon Sep 17 00:00:00 2001
From: Zain <lhlyzh@outlook.com>
Date: Thu, 19 Mar 2026 16:14:02 +0800
Subject: [PATCH] docs: add diagnostic export feedback design

---
 ...03-19-diagnostic-export-feedback-design.md | 326 ++++++++++++++++++
 1 file changed, 326 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-03-19-diagnostic-export-feedback-design.md

diff --git a/docs/superpowers/specs/2026-03-19-diagnostic-export-feedback-design.md b/docs/superpowers/specs/2026-03-19-diagnostic-export-feedback-design.md
new file mode 100644
index 0000000..ec97ccc
--- /dev/null
+++ b/docs/superpowers/specs/2026-03-19-diagnostic-export-feedback-design.md
@@ -0,0 +1,326 @@
+# 批量重命名失败诊断导出与反馈引导设计
+
+## 背景
+当前项目在批量重命名失败时，用户只能看到界面内的失败提示或手动打开 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 中再次导出最近一次诊断
+- 可选脱敏导出
+- 更丰富的错误码分类与模块标记
+- 诊断历史记录页面