hao/websafe-kb
1
0
派生 0
代码 工单 合并请求 1 工作流 软件包 项目 发布 百科 活动
文件
main
websafe-kb/docs/frontend-dashboard-design.md

7.9 KiB
原始文件 永久链接 Blame 文件历史

本地前端工作台设计文档

LAB ONLY | AUTHORIZED TARGETS ONLY

1. 设计目标

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

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

2. 页面定位

2.1 页面名称

  • 页面名称：授权攻防实验工作台
  • 页面语境：本地静态前端 + 本地文件 JSON 数据源
  • 非目标：在线 SaaS、多用户后端、生产管理台

2.2 核心原则

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

3. 信息架构

flowchart LR
  A["Hero + Global Status"] --> B["Sidebar Filters"]
  A --> B1["Top Section Nav"]
  B1 --> C["Overview / Runs / Systems / Architecture / Docs / Data"]
  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
  • 顶部板块菜单
  • 顶部 chips 分类筛选

视觉要求：

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

4.2 左侧侧栏

改为按板块变化，不再固定使用长下拉：

  • Overview
    • 搜索
    • 最近失败
    • 最新运行
    • 系统概览
  • Runs
    • 搜索
    • 最近失败
    • 运行队列
  • Systems
    • 搜索
    • 系统目录
  • Architecture / Docs / Data
    • 对应目录、入口或结构列表

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 应按板块进入不同入口，并通过 query 参数保留筛选与 run=<id>

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
    • 根入口别名
  • /overview/index.html
    • 总览入口
  • /runs/index.html
    • 运行中心
  • /systems/index.html
    • 系统中心
  • /architecture/index.html
    • 架构中心
  • /docs/index.html
    • 文档中心
  • /data/index.html
    • 数据中心
  • /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
  • 能看到失败原因、思路、来源、修复主题
  • 能通过顶部 chips 筛选状态 / 板块 / 漏洞家族
  • 能通过分板块 URL 直接打开 overview / runs / systems / architecture / docs / data
  • 能在自动刷新开启时重新载入 dashboard 数据
  • 页面视觉比“普通表格页”更生动，但仍适合高密度阅读
在新工单中引用 查看 Git Blame 复制永久链接