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 数据

打开 FileExplorer，上传或选中 护送30.utrace。
将文件拖拽到画布，自动创建 UTraceLoader 节点并在 Inspector 显示预览按钮。
在 Inspector 选择 preview（采样），点击预览，结果显示在 Workspace 的右侧结果面板。

场景 2：创建并运行分析工作流

从 NodePalette 拖入 UTraceLoader、TimeRangeFilter、FrameTimeChart。
连接连线，设置 TimeRangeFilter 的参数（右侧 Inspector）。
点击 Run（HeaderBar），观察 RunBar 日志与图表输出。

五、已实现 / 未实现清单（开发优先级）

已实现（基础）：
- 画布基础（节点创建、拖拽、连线）
- NodePalette 列表与拖拽
- Inspector 基础参数编辑
- HeaderBar 基础按钮（Run/Save）
- 文件上传/浏览基础 API
进行中 / 计划中：
- 节点内联调试（单节点运行、断点式调试）
- 日志到节点定位联动
- 自定义节点自动解析与测试集成
- UTrace 原生预览与高性能采样
- 类型匹配的可视提示（连线颜色/tooltip）
- 无障碍与键盘导航
未规划 / 后续考虑：
- 多用户协作实时编辑（多人同时编辑画布）
- 复杂权限模型（基于角色的细粒度权限）
- 可视化插件市场（在线搜索/安装节点插件）

六、后续建议与校验点（供 AI 或评审使用）

为每个节点补充 1 页 UI 文档（显示示例、输入输出、参数说明、典型用例）。
在 NodePalette 中加入“状态标签”（实验/稳定/弃用），便于用户识别。
定义画布上的“错误灯”与“性能提示”（例如长时运行节点显示黄色警告）。
建议优先实现日志到节点定位联动与自定义节点解析，这两项能显著改善可用性。

七、如何参与与验证

快速验证：运行旧版测试服务器并打开前端，按照“交互流示例”执行一遍。若你需要，我可以生成自动化的 e2e 脚本来做这件事。

10 KiB Raw Permalink Blame History Unescape Escape