173 lines
10 KiB
Markdown
173 lines
10 KiB
Markdown
# TraceStudio UI 设计说明
|
||
|
||
本文档面向开发者与 AI 助手，描述当前项目的完整 UI 架构、核心布局、各区域职责、主要交互流，以及当前实现状态（已实现 / 未实现）。目的是让任意 AI 或新开发者阅读后能对界面有明确认知，并在此基础上给出设计或实现建议。
|
||
|
||
---
|
||
|
||
## 一、总体布局（Canvas-first）
|
||
|
||
TraceStudio 的界面采用“Canvas-first”设计：画布（节点编辑区）为主，周边辅以工具面板、侧边栏与状态栏，支持拖拽式节点编辑、属性面板即点即改、以及运行/预览控制。
|
||
|
||
主布局分为：
|
||
|
||
- 顶部导航栏（HeaderBar）
|
||
- 左侧节点库（NodePalette）文件管理器（FileExplorer）
|
||
- 中央画布（Workspace / React Flow Canvas）
|
||
- 右侧属性与 Inspector（Inspector）
|
||
- 底部运行与日志区（RunBar / Console）
|
||
- 全局模态（SettingsModal / FileViewer / CustomNodeEditor）
|
||
|
||
下面按区域逐一说明组件职责与交互。
|
||
|
||
---
|
||
|
||
## 二、组件与职责
|
||
|
||
- HeaderBar
|
||
- 位置：界面最上方，横贯全宽。
|
||
- 职责：项目切换、保存/加载工作流、运行/停止按钮、全局状态指示（当前用户、连接状态）、快速搜索与帮助菜单。
|
||
- 交互要点：
|
||
- `Run`：触发当前图执行（带预览/全量选项）。
|
||
- `Save`：保存 `.tsflow` 工作流到用户目录。
|
||
- `Search`：快速查找节点或命令（按名称模糊匹配）。
|
||
- 当前实现状态：已实现基础布局、运行按钮和用户显示。
|
||
|
||
- NodePalette
|
||
- 位置：左侧竖列（可折叠）。
|
||
- 职责：展示可用算子/节点，支持按类别过滤、拖拽到画布、查看节点文档与快捷预览。
|
||
- 交互要点：
|
||
- 拖拽节点到画布自动创建节点实例并打开 Inspector。
|
||
- 支持搜索与按类别分组。
|
||
- 当前实现状态：已实现节点列表与拖拽，分类与搜索基础功能可用；节点详细文档弹窗待完善。
|
||
|
||
- 文件页签（File Tab）
|
||
- 位置与实现说明：在当前前端实现中，文件管理由独立组件 `FileExplorer.tsx` 提供，并与 `NodePalette` 并列放置在左侧面板（表现为页签或切换视图）。`NodePalette.tsx` 本身仅负责算子列表与拖拽，**并不直接包含完整的文件管理 UI**。
|
||
- 职责：轻量云文件管理器（由 `FileExplorer` 提供），用于浏览、上传、下载、创建、重命名、删除用户文件（存放于 `cloud/users/{username}/`），并作为文件节点（如 `FileLoader` / `UTraceLoader`）的数据来源。
|
||
- 功能要点：
|
||
- 列表视图与缩略视图切换（显示文件名、类型、大小、修改时间、状态标签）。
|
||
- 基本 CRUD：创建文件夹、重命名、删除、移动（带确认与回收站/撤销机制）。
|
||
- 上传/下载：支持单文件与批量上传、断点续传提示（可选），并显示上传进度。
|
||
- 预览：CSV 文本预览、UTRACE 元数据预览（采样展示），二进制/大文件提示下载或使用专用预览器。
|
||
- 拖拽到画布：把文件从 `FileExplorer` 拖到画布时，`Workspace.tsx` 的 `onDrop` 会解析 `dataTransfer` 中的 `application/x-file-path`（或 `application/x-node`）并创建对应节点（例如 `UTraceLoader`、`CSVLoader`）。注意：实现依赖两端协同：`FileExplorer` 必须在 dragstart 时将 `application/x-file-path` 写入 `dataTransfer`，而 `Workspace` 负责解析与创建节点。当前实现：`Workspace` 已支持解析并创建 CSV/UTRACE 节点，`FileExplorer` 提供拖拽回调，但浏览器 dataTransfer 行为需在特定环境下测试。
|
||
- 自定义节点上传：允许用户上传 Python 脚本作为自定义节点源码（受限扩展名和沙箱校验），上传后可选择“注册为节点”或仅存为私有文件。
|
||
- 搜索与过滤：按扩展名、标签、修改时间、文件大小进行筛选。
|
||
- 权限与版本：显示文件权限、支持简单的版本历史（保存快照）与冲突解决提示。
|
||
- 与系统的契约：
|
||
- 所有文件操作必须走后端 API，并受 `server/system_config.yaml` 的 `storage` 与 `security` 配置约束（允许的扩展名、路径限制、父路径遍历阻止等）。
|
||
- File Tab 也将作为 FileLoader 节点参数的来源：节点可以通过文件选择器引用 `cloud/users/{username}/data/...` 路径。
|
||
- 安全与校验：
|
||
- 强制文件名白名单/黑名单检查、禁止 Windows 保留名、禁止路径遍历（`../`）等。
|
||
- 上传的自定义节点代码需要经过静态分析（检测危险 API）并在安全上下文中执行或等待用户确认启用。
|
||
- 当前实现状态：
|
||
- 基础文件浏览与上传 API 已实现（后端 `endpoints_upload.py`）。
|
||
- `FileExplorer.tsx` 实现了文件列表、上传、重命名、删除、下载与在新窗口预览/编辑的原型（含保存功能）。
|
||
- `Workspace.tsx` 的 `onDrop` 实现了基于文件扩展名创建节点（例如 `.csv` 生成 CSV Loader，`.utrace` 可触发工作流导入）。
|
||
- 仍需完善：`FileExplorer` 与 `Workspace` 在拖拽 dataTransfer 的兼容性细节、UTRACE 深度预览、以及“上传自定义节点后自动解析并注册”为可拖拽算子的完整流程。
|
||
|
||
- Workspace（Canvas / React Flow）
|
||
- 位置：中央主区域。
|
||
- 职责：节点编辑、连线、画布缩放/平移、选区操作、切换视图（preview / full results overlay）。
|
||
- 交互要点：
|
||
- 双击节点打开节点面板（或右侧 Inspector）。
|
||
- 连线时显示类型匹配提示（颜色 / tooltip）。
|
||
- 选中节点时显示小型操作工具条（复制、删除、调试/运行单节点）。
|
||
- 当前实现状态：画布与基本连线已实现；类型匹配提示、节点内联调试尚在开发。
|
||
|
||
- Inspector（右侧）
|
||
- 位置：右侧面板，展示被选中节点的参数、输入/输出说明、预览按钮和高级设置。
|
||
- 职责：编辑节点参数、触发节点单独预览、展示执行日志与错误位置、切换采样率（preview/full）。
|
||
- 交互要点：
|
||
- 参数修改即时生效（仅对 UI 预览，未触发图整体执行，除非点 Run）。
|
||
- 错误时高亮对应参数或字段，并提供快速定位按钮。
|
||
- 当前实现状态：属性面板已实现基本参数编辑；错误定位与高级选项待实现。
|
||
|
||
- RunBar / Console（底部）
|
||
- 位置：底部横栏，可收起。
|
||
- 职责：显示执行状态（队列、当前节点、耗时）、日志输出、下载结果入口、缓存与重试控制。
|
||
- 交互要点：
|
||
- 点击日志条目可在画布中定位到产生该日志的节点。
|
||
- 可用按钮停止执行、重试或仅清空缓存。
|
||
- 当前实现状态：基本执行状态显示已实现；日志与节点定位未完全联动。
|
||
|
||
- FileExplorer / FileViewer（侧边或模态）
|
||
- 位置：可作为左侧切换视图或独立模态。
|
||
- 职责：浏览 `cloud/users/{username}/` 目录，上传/下载文件，预览 CSV/UTRACE 文件。
|
||
- 交互要点：
|
||
- 拖拽文件到画布或节点面板自动创建 `FileLoader` 节点并绑定路径。
|
||
- 支持文件权限校验与快速筛选。
|
||
- 当前实现状态：文件浏览与上传接口已实现；UTRACE 预览与绑定还需完善。
|
||
|
||
- CustomNodeEditor（模态）
|
||
- 位置：模态窗口
|
||
- 职责：创建/编辑自定义节点模板（参数、输入输出、示例代码、单元测试设置）。
|
||
- 交互要点：
|
||
- 支持导入 Python 脚本并自动解析 `get_metadata()`。
|
||
- 提供示例工作流导入按钮。
|
||
- 当前实现状态：编辑器雏形存在；自动解析与测试集成未完成。
|
||
|
||
- SettingsModal
|
||
- 位置：全局模态
|
||
- 职责：系统配置（API 地址、缓存策略、unreal 路径、日志等级等）。
|
||
- 当前实现状态：基本设置项和保存机制已有，部分高级项需完善。
|
||
|
||
---
|
||
|
||
## 三、视觉与可用性准则
|
||
|
||
- 主题：深色模式为主，低饱和度高对比强调操作元素（参照 shadcn/ui 工业风）。
|
||
- 可读性：字体尺寸与颜色需保证长时间盯屏舒适度。
|
||
- 动效：连线/节点状态变化使用低频率、轻微动效提示。
|
||
- 无障碍：键盘导航、ARIA 标签、主题对比度需要在后续迭代中验证。
|
||
|
||
---
|
||
|
||
## 四、交互流示例（常见场景）
|
||
|
||
场景 1：快速预览一段 UTrace 数据
|
||
1. 打开 `FileExplorer`，上传或选中 `护送30.utrace`。
|
||
2. 将文件拖拽到画布，自动创建 `UTraceLoader` 节点并在 `Inspector` 显示预览按钮。
|
||
3. 在 Inspector 选择 `preview`（采样），点击预览，结果显示在 `Workspace` 的右侧结果面板。
|
||
|
||
场景 2：创建并运行分析工作流
|
||
1. 从 `NodePalette` 拖入 `UTraceLoader`、`TimeRangeFilter`、`FrameTimeChart`。
|
||
2. 连接连线，设置 `TimeRangeFilter` 的参数（右侧 Inspector）。
|
||
3. 点击 `Run`（HeaderBar），观察 `RunBar` 日志与图表输出。
|
||
|
||
---
|
||
|
||
## 五、已实现 / 未实现 清单（开发优先级）
|
||
|
||
- 已实现（基础）：
|
||
- 画布基础（节点创建、拖拽、连线）
|
||
- NodePalette 列表与拖拽
|
||
- Inspector 基础参数编辑
|
||
- HeaderBar 基础按钮（Run/Save）
|
||
- 文件上传/浏览基础 API
|
||
|
||
- 进行中 / 计划中：
|
||
- 节点内联调试（单节点运行、断点式调试）
|
||
- 日志到节点定位联动
|
||
- 自定义节点自动解析与测试集成
|
||
- UTrace 原生预览与高性能采样
|
||
- 类型匹配的可视提示（连线颜色/tooltip）
|
||
- 无障碍与键盘导航
|
||
|
||
- 未规划 / 后续考虑：
|
||
- 多用户协作实时编辑（多人同时编辑画布）
|
||
- 复杂权限模型（基于角色的细粒度权限）
|
||
- 可视化插件市场（在线搜索/安装节点插件）
|
||
|
||
---
|
||
|
||
## 六、后续建议与校验点（供 AI 或评审使用）
|
||
|
||
- 为每个节点补充 1 页 UI 文档（显示示例、输入输出、参数说明、典型用例）。
|
||
- 在 `NodePalette` 中加入“状态标签”（实验/稳定/弃用），便于用户识别。
|
||
- 定义画布上的“错误灯”与“性能提示”（例如长时运行节点显示黄色警告）。
|
||
- 建议优先实现日志到节点定位联动与自定义节点解析，这两项能显著改善可用性。
|
||
|
||
---
|
||
|
||
## 七、如何参与与验证
|
||
|
||
- 快速验证：运行旧版测试服务器并打开前端，按照“交互流示例”执行一遍。若你需要，我可以生成自动化的 e2e 脚本来做这件事。 |