docs: 审查面板优化设计 spec

2026-07-20 20:47:55 +08:00
parent a734cdf009
commit c96c543cfa
1 changed files with 141 additions and 0 deletions
@@ -0,0 +1,141 @@
+# 审查面板优化设计
+
+## 1. 背景
+
+当前 `src/panel/webview.ts` 是审查报告面板的实现，其 UI 与设计规格 `review-panel-ui.md` 及原型 `review-panel-preview.html` 存在显著差距。本次优化将 `webview.ts` 的渲染代码对齐到原型设计，同时根据讨论调整：
+
+- **移除** diff 代码对比展示（UI 参考 `review-panel-ui.md` 中不涉及 diff 的部分）
+- **移除**「撤销上次修复」按钮（修复功能尚未完工）
+- **保留**「批量修复」按钮在底部操作栏中
+
+## 2. 变更范围
+
+只涉及一个文件：`src/panel/webview.ts`。
+
+- 架构不变（内联 HTML/CSS/JS、单例模式、postMessage 通信）
+- 数据结构不变（`MergedReport`、`PanelMessage`）
+- 消息通信协议不变
+
+## 3. CSS 主题适配策略
+
+将原型中固定的深色主题色映射到 VSCode CSS 变量，确保深色/浅色双主题兼容：
+
+| 角色 | 原型固定值 | Webview 变量 |
+|------|-----------|-------------|
+| 主体背景 | `#0d1117` | `var(--vscode-editor-background)` |
+| 卡片背景 | `#161b22` | `var(--vscode-sideBar-background)` |
+| 主文本 | `#e6edf3` | `var(--vscode-foreground)` |
+| 次要文本 | `#8b949e` | `var(--vscode-descriptionForeground)` |
+| 边框 | `#21262d` / `#30363d` | `var(--vscode-panel-border)` |
+| 错误色 | `#f48771` | `#E06C75` |
+| 警告色 | `#d29922` | `#D19A66` |
+| 信息色 | `#58a6ff` | `#61AFEF` |
+| Tab 激活色 | `#f78166` | `#7C3AED` |
+| 按钮主色 | `#238636` | `#7C3AED` |
+| Hover/expanded 边框 | `#58a6ff` | `var(--vscode-focusBorder)` |
+
+## 4. 页面结构
+
+```
+┌──────────────────────────────────────────────────────┐
+│ [SVG 图标] 净码特工 · 代码审查报告                    │
+│ fileName · language · X.Xs                           │
+├──────────────────────────────────────────────────────┤
+│ ⚠ 降级横幅（条件）                                    │
+├──────────────────────────────────────────────────────┤
+│ ✖ 执行错误框（条件，列出 report.errors[]）             │
+├──────────────────────────────────────────────────────┤
+│ [总计问题] [错误] [警告] [建议]                       │
+├──────────────────────────────────────────────────────┤
+│ 🔧 静态分析 [!] [!]    📋 自定义 [!]    🤖 AI [!]    │
+├──────────────────────────────────────────────────────┤
+│ ┌ 问题条目（可展开/折叠） ──────────────────────────┐ │
+│ │ ▌● BADGE ruleId  消息...        L行号  [🔧 修复] │ │
+│ │ ├── 展开后 ──────────────────────────────────────┤ │
+│ │ │ 原文: ...                                      │ │
+│ │ │ 💡 建议: ...                                   │ │
+│ └──────────────────────────────────────────────────┘ │
+├──────────────────────────────────────────────────────┤
+│ [🔄 重新审查] [📄 导出报告] [⚙️ 设置] [🔧 批量修复]   │
+└──────────────────────────────────────────────────────┘
+```
+
+## 5. 组件细节
+
+### 5.1 Header
+- SVG 图标（对勾文件 icon）+ 标题「净码特工 · 代码审查报告」
+- 元信息行：`fileName · language · X.Xs`
+- 使用 `var(--vscode-foreground)` 和 `var(--vscode-descriptionForeground)`
+- 与原型一致，图标 stroke 颜色使用 `#61AFEF`
+
+### 5.2 降级横幅 + 错误框
+- `report.errors.length > 0`：显示红色 `banner-error` + `errors-box`（列出每条错误）
+- `report.degraded && report.errors.length === 0`：显示黄色 `banner-warn`「⚠ 部分 AI 功能不可用」
+- 否则不显示横幅
+
+### 5.3 统计卡片
+- 四张卡片：总计问题 / 错误 / 警告 / 建议
+- 支持 `min-width: 100px` 自适应换行
+- 带 `1px solid var(--vscode-panel-border)` 边框和 `8px` 圆角
+
+### 5.4 Tab 标签页
+- 三个 Tab，每个显示按严重级别拆分的彩色徽章（错误/警告/建议计数）
+- Tab 底部激活线使用 `#7C3AED`
+- Tab 内容顶部有 section header：`{工具摘要} · {N} 个问题` +「全部修复」按钮
+
+### 5.5 问题条目
+
+每条问题卡片结构：
+
+| 元素 | 说明 |
+|------|------|
+| 左侧色条 | 5px 宽圆角竖条，红色/黄色/蓝色对应严重级别 |
+| 小圆点 | 同色 8px 圆点，辅助标识 |
+| Badge 标签 | `Linter`(灰) / `自定义`(紫) / `AI`(蓝) |
+| ruleId | 等宽字体，最大宽度 180px 溢出省略 |
+| 消息文本 | 单行省略，14px 字号 |
+| 行号 | `L{N}` 格式，灰色背景，等宽字体 |
+| 🔧 修复按钮 | 仅 fixable 条目显示，点击后变 `⏳...` 并禁用 |
+
+**展开详情**（点击条目切换）：
+- 原文对照（linter 条目）：`原文: {原始消息}`
+- 修复建议（有 suggestion 时）：蓝色背景框
+- AI 分类标签（仅 AI 条目）：`🎯 {category}`
+- 动画：`fadeSlideIn 0.2s ease`
+- 展开时条目边框高亮
+
+**点击行为**：
+- 点击行身（非按钮区域）：展开/折叠详情
+- 点击行号区域或空白区：`postMessage('navigate')` 跳转到编辑器对应行
+- 点击 🔧 修复：`postMessage('fix')` 触发修复，按钮显示 `⏳...` 并禁用
+
+### 5.6 底部操作栏
+- 四个按钮：🔄 重新审查 / 📄 导出报告 / ⚙️ 设置 / 🔧 批量修复
+- 重新审查使用主色（紫色）
+
+### 5.7 空状态
+- 某 tab 无问题：居中斜体文字
+- 静态分析：`未发现任何问题`
+- 自定义规则：`未发现规则违规`
+- AI 审查：`无 AI 审查建议`
+
+## 6. 消息通信（不变）
+
+```typescript
+interface PanelMessage {
+  type: 'navigate' | 'rerun' | 'export' | 'settings' | 'fix' | 'fixAll';
+  line?: number;
+  ruleId?: string;
+  source?: 'linter' | 'custom' | 'ai';
+}
+```
+
+## 7. 错误/边界状态处理
+
+| 场景 | 表现 |
+|------|------|
+| `errors` 非空但 AI 成功 | banner-error + errors-box + 正常三个 tab |
+| `degraded`（AI 部分失败） | banner-warn + 静态分析和自定义规则正常显示 |
+| linter 全失败（无问题） | banner-error + errors-box + 三个 tab 均为空状态 |
+| AI 未配置 | 不启动 AI，`aiCount=0`，AI tab 显示无建议 |
+| 文件无问题 | 无 banner，总计为 0，各 tab 空状态 |