websafe-kb/docs/frontend-dashboard-design.md

# 本地前端工作台设计文档

> `LAB ONLY` | `AUTHORIZED TARGETS ONLY`

## 1. 设计目标

本地 dashboard 要从“简单索引页”升级成“完整的授权攻防实证工作台”。它需要同时满足三类使用场景：

1. 运行中观察
   - 看当前 run 进度
   - 看失败原因和阻塞点
   - 实时打开日志和证据
2. 复盘分析
   - 查看 timeline、思路、利用路径、来源与修复主题
   - 对比真实版本与 synthetic 复现差异
3. 审阅归档
   - 从一个前端入口点进 `report.md`, `report.html`, `run.json`, 原始日志和截图

## 2. 页面定位

### 2.1 页面名称

- 页面名称：`Authorized Lab Dashboard`
- 页面语境：本地静态前端 + 本地文件 JSON 数据源
- 非目标：在线 SaaS、多用户后端、生产管理台

### 2.2 核心原则

- 所有展示都围绕授权目标
- 失败信息不能被隐藏在深层页面里
- 信息密度高，但必须可折叠、可筛选、可逐层展开
- 日志与原始 JSON 必须能直接预览
- 页面视觉应更生动，但不能牺牲扫描效率
- 默认路由采用正式新 UI，同时保留 `legacy` 回退入口
- 运行期不得依赖外部 HTML、字体 CDN 或图标 CDN

## 3. 信息架构

```mermaid
flowchart LR
  A["Hero + Global Status"] --> B["Sidebar Filters"]
  A --> C["Run Queue List"]
  C --> D["Run Detail Hero"]
  D --> E["Progress Timeline"]
  D --> F["Attack Plan & Reasoning"]
  D --> G["Evidence Explorer"]
  D --> H["Live Log Viewer"]
  D --> I["Sources & Fix Topics"]
  D --> J["当前架构库"]
  D --> K["Raw JSON Panels"]
```

## 4. 页面布局

### 4.1 顶部 Hero

必须展示：

- 页面名称
- 授权实验语境说明
- 刷新按钮
- 自动刷新开关
- 当前同步状态
- 核心 metric cards

视觉要求：

- 不能是纯白表格页
- 需要有分层背景、渐变光晕、轻微动态氛围
- 顶栏 sticky，滚动时仍可看到刷新和状态

### 4.2 左侧侧栏

包含四块：

- Filters
  - 搜索
  - system filter
  - status filter
  - profile filter
- Systems
  - 系统覆盖度
  - browser evidence 覆盖
  - latest update
- Recent Failures
  - 最近 blocker
  - status
  - 原因摘要
- Run Queue View
  - 最近 run 卡片列表
  - 可选中并切换到 detail panel

### 4.3 右侧 Detail Workspace

必须包含：

- Run Hero
  - advisory 标题
  - system / profile / artifact / verification 状态
  - report / bundle / markdown 入口
- Progress Timeline
  - 每一步的时间、状态、说明
- Attack Plan & Reasoning
  - success criteria
  - seed / attack notes
  - failure reason
  - 当前 blocker
- Evidence Explorer
  - reports
  - compose
  - browser evidence
  - request logs
  - container logs
- Live Log Viewer
  - 预览 text/json/html/image
  - refresh preview
  - open artifact
- Sources & Fix Topics
  - official source
  - secondary sources
  - aliases
  - secure code topics
- 当前架构库
  - 项目定位、授权边界、控制面、数据层、地址入口
  - source-map / repro-map 派生的系统分组与默认复现策略
  - 当前生成态、状态分布、最近失败
  - 可折叠查看任意层级信息并打开本地镜像页 / JSON
- Raw JSON
  - run JSON
  - advisory JSON
  - profile JSON

## 5. 交互要求

### 5.1 折叠 / 展开

所有 detail 分区都应支持折叠：

- Progress Timeline
- Attack Plan & Reasoning
- Evidence Explorer
- Live Log Viewer
- Sources & Fix Topics
- Raw JSON sections

折叠要求：

- 默认展开常用分区
- 次级原始数据可以默认收起
- 折叠状态视觉要清晰，不靠小箭头弱提示

### 5.2 Run 切换

- 点击左侧 run card 后，右侧 detail panel 即时刷新
- 当前选中项要有强视觉区别
- URL hash 应保留 `#run=<id>`，方便直接打开特定 run

### 5.3 Artifact 预览

点击 artifact button 后：

- JSON 自动格式化
- 日志文件以 `<pre>` 方式显示
- 图片以内联方式展示
- HTML 报告可 iframe 预览或新窗口打开

### 5.4 自动刷新

- 默认每 5 秒刷新一次 dashboard JSON
- 用户可以关闭自动刷新
- 当前正在查看的 artifact 在自动刷新开启时应支持重新抓取

### 5.5 失败原因高亮

对于 `blocked-*` 和 `triage-manual`：

- 顶部 hero 要显示状态 pill
- reasoning 面板要显示 failure callout
- 左侧 Recent Failures 要保留最近失败摘要

## 6. 展示字段清单

### 6.1 Hero 区

- run_id
- advisory_id
- advisory title
- verification_status
- verification_mode
- artifact_mode
- system_id
- repro_profile_id
- finished_at

### 6.2 Timeline 区

- `timeline[].at`
- `timeline[].step`
- `timeline[].status`
- `timeline[].detail`

### 6.3 Reasoning 区

- advisory summary
- profile seed messages
- profile attack messages
- profile success criteria
- blocked reason

### 6.4 Sources 区

- official_source_url
- secondary_source_urls
- aliases
- secure_code_topics

### 6.5 Evidence 区

- report.html
- report.md
- timeline.mmd
- bundle json
- compose.yaml
- browser screenshots / DOM / console / network
- request logs
- container logs

## 7. 动效与视觉要求

### 7.1 必须有的视觉增强

- 顶部背景渐变和环境光
- status pill 发光色彩区分
- 卡片 hover 浮起
- sticky hero
- 折叠面板开合层次
- gallery 缩略图点击查看

### 7.2 推荐但必须受控

- 状态小圆点 pulse
- 背景网格或轻微数据面纹理
- 面板玻璃感和浅透视阴影

### 7.3 不允许

- 花哨但影响可读性的动画
- 大面积纯装饰 3D 效果
- 自动播放噪音式动效
- 让日志区难以复制文本的视觉处理

## 8. 实时日志与细节查看要求

### 8.1 日志查看器

日志查看器必须支持：

- 选中文件后即刻预览
- JSON 格式化
- text/json/html/image 四类预览
- 打开原文件
- 在自动刷新开启时重新抓取当前文件

### 8.2 重点要看的日志

- compose / environment 文件
- baseline / attack / browser json
- container logs
- request logs
- timeline / bundle

### 8.3 失败排查导向

失败时应优先展示：

- `blocked_reason`
- 当前 step
- 上一个完成 step
- 当前可打开的日志 / 报告 / run bundle
- 对应 advisory 来源与 profile success criteria

## 9. 数据源契约

前端依赖的本地 JSON/文件源：

- `summary.json`
- `runs.json`
- `systems.json`
- `advisories.json`
- `profiles.json`
- `runs/<run-id>/report.html`
- `runs/<run-id>/report.md`
- `runs/<run-id>/run.json`
- `runs/<run-id>/logs/*`
- `runs/<run-id>/assets/*`

前端不直接写这些数据，只读取并展示。

## 10. 路由与文档地址

- `/index.html`
  - 默认正式入口，使用本地化 Lovart UI 外壳
- `/legacy/index.html`
  - 旧版 dashboard 回退入口
- `/docs/project-features.html`
  - 功能说明镜像页
- `/docs/frontend-dashboard-design.html`
  - 设计说明镜像页
- `/docs/secure-code-index.html`
  - secure-code 索引镜像页
- `/docs/design-source.html`
  - Lovart vendor 来源和本地化说明

## 11. 落地约束

- 保持静态前端，不引入长期运行后端
- 本地 `serve-dashboard` 即可查看
- 对于正在跑的 case，前端通过轮询读取新 JSON 实现“近实时”
- 不依赖第三方 CDN UI 库
- 优先使用原生 HTML/CSS/JS，可长期维护

## 12. 验收标准

页面完成后，应满足：

- 能从 run list 切换到 detail panel
- 能折叠与展开各信息区
- 能打开并预览 JSON / text / image / html artifact
- 能看到失败原因、思路、来源、修复主题
- 能筛选 system / status / profile
- 能在自动刷新开启时重新载入 dashboard 数据
- 页面视觉比“普通表格页”更生动，但仍适合高密度阅读