T2-SD0403/2026Technology-Competition

Fork 0

Files

T

范智鹏 c96c543cfa docs: 审查面板优化设计 spec

2026-07-20 20:47:55 +08:00

7.1 KiB

Raw Permalink Blame History

审查面板优化设计

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. 消息通信（不变）

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 空状态

7.1 KiB Raw Permalink Blame History Unescape Escape