142 lines
7.1 KiB
Markdown
142 lines
7.1 KiB
Markdown
# 审查面板优化设计
|
||
|
||
## 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 空状态 |
|