TraceStudio-dev/docs/web/frontend_v3_spec.md

TraceStudio 前端 V3 开发规范

目标与愿景

• 目标：将 TraceStudio 打造成可编程的分析实验室（Programmable Analysis Lab）。前端负责交互与可视化、节点画布和操作体验。
• 愿景：UI 保持轻量、可声明；所有业务和数据一致性逻辑下沉到 core（纯 TypeScript），UI 仅负责渲染与事件。

架构原则

• Core 与 Components 分离：
  • core（纯 TypeScript，无 React）：StudioRuntime、GraphModel、NodeModel、PortModel、服务（RuntimeService、GraphService）。
  • components（React/TSX）：界面组件，仅通过 RuntimeService 与 core 交互。
• 单一职责：
  • GraphService：图变更与校验（节点/边/端口/暴露/复制/删除等）。
  • RuntimeService：系统编排（启动 / manifest / viewport / autosave / import/export），对外代理并同步投影（syncGraphFromRuntime()）。
  • StudioRuntime：SSOT，真实运行时数据结构与序列化。
• Store（Zustand）仅作 projection/flags：
  • 仅保存 rfNodes, rfEdges, graphVersion, viewport, manifestLoaded, loading, activeNodeId, propertyPanelVisible 等。
  • 禁止在 store 中实现业务逻辑。
• UI 事件流：
  • 高频交互（拖拽、连线）使用本地 state（如 ReactFlow 的 useNodesState/useEdgesState），交互结束时再提交至 RuntimeService/GraphService。
  • 所有最终的 graph 变更通过 GraphService 执行，RuntimeService 负责同步与持久化。

开发约定

• 文件命名：前端 TS/TSX 使用 kebab-case 或 PascalCase（组件）；Core 使用 PascalCase 类名。
• Manifest / node meta：
  • param_schema：建议为数组，每项包含 name, type, label?, widget?, options?, min?, max?。
  • meta.category：建议为数组（也可解析字符串 path），用于 NodePalette 分组。
  • context_vars：显式列出可被 context 模式消费的变量及其类型。
• API 使用：
  • UI 只调用 RuntimeService 或 RuntimeService.graph.*，不直接改 runtime。
  • 服务层返回 boolean/id 或抛错，UI 显示友好提示。
• 错误处理：
  • 服务层应返回可解释错误，UI 使用 toast/Modal 呈现并在图中高亮冲突节点。

性能策略

• 本地优先（local-first UI）：使用本地 React state 优化交互流畅性。
• 防抖/节流：viewport 写入采用 500ms 防抖，其他高频写入点也应参数化。
• 采样策略：预览使用采样，生产使用全量。
• 渲染优化：节点/边组件使用 React.memo、useCallback、useMemo 减少重绘。

UX 规范

• 属性面板：支持 static/context/exposed 三种模式，static<->exposed 切换即时生效（调用 RuntimeService.exposeParam/unexposeParam 并同步）。
• NodePalette：按 category 分组、支持搜索与目录过滤；Files 面板作为并列 tab。
• 右键菜单：UI 负责展示确认，动作委托给 RuntimeService，动作结果用 toast 显示。

测试与验收

• 集成测试覆盖关键流程：create node，connect，expose/unexpose，import/export，autosave/restore。
• 使用 mock manifest 测试不同 param_schema 类型。

扩展点

• custom_nodes/ 插件：后端节点插件实现 TraceNode 并提供 get_metadata()/execute()；前端应支持 render_class->Component 映射。

---

TraceStudio 前端目录与文件说明

本文件对 web/ 代码组织和每个重要文件/目录的作用进行说明，便于前端接手者快速定位与优化。

目录总览

• web/：前端工程根目录（React + Vite + TypeScript）。
• web/src/：应用源代码。

web/src/components

• App.tsx：应用入口，组织 providers、路由和顶层容器。
• AppShell.tsx：应用布局（Header、左侧 NodePalette、画布 Workspace、右侧 PropertyPanel）。
• HeaderBar.tsx：顶部工具栏，包含 Run/Save/Import/Export/Settings。
• Workspace.tsx：ReactFlow 画布实现，负责节点/边本地状态（useNodesState/useEdgesState）、拖拽、连接事件以及调用 RuntimeService 提交变更。
• NodePalette.tsx：左侧节点面板，按 category 分组、支持搜索与 Files tab，拖拽节点到画布。
• PropertyPanel.tsx：右侧属性编辑器，渲染参数控件并调用 RuntimeService.exposeParam/unexposeParam/updateNodeParams。
• UniversalNode.tsx：节点默认渲染器，渲染 title、ports、参数预览和高亮已暴露端口；支持被特定 render_class 覆盖。
• ContextMenu.tsx：右键上下文菜单，UI 部分与 hook (useContextMenuAction) 分离。
• widgets/：小部件（FilePicker.tsx、JsonEditor.tsx 等）。

web/src/core

• api/：与后端交互封装。
  • SchemaApi.ts：获取 manifest、节点元数据等。
  • FileApi.ts、GraphApi.ts：文件与 graph 相关的 REST wrapper（如需）。
• model/：纯 TS Core（无 React）
  • StudioRuntime.ts：SSOT，包含 runtime.graph、manifest 缓存、import/export workflow、viewport 存取方法。
  • GraphModel.ts：图数据结构、节点/边逻辑、upDimension 传播与序列化。
  • NodeModel.ts：单个节点的数据模型，params、inputs/outputs、meta，包含 exposeParamAsInput/removeExposedParam。
  • PortModel.ts：端口模型与 getTypeInfo() 逻辑（type + dim）。
• services/：业务服务
  • RuntimeService.ts：系统级编排（boot、reloadManifest、syncGraphFromRuntime、viewport 防抖、autosave、import/export）。包含 graph 属性指向 GraphService。
  • GraphService.ts：集中处理图变更（create/remove/duplicate node/edge、updateNodeParams、expose/unexpose param、disconnect 等）。
• store/：Zustand projection store
  • runtimeStore.ts：保存视图投影与 flags（rfNodes、rfEdges、graphVersion、viewport、manifestLoaded、loading、activeNodeId、propertyPanelVisible 等）。
• types.ts：共享类型定义。

web/src/tests

• TEST_INTEGRATION.js：集成测试脚本样例；建议迁移到 Jest/Playwright 以实现自动化测试。

交互与依赖关系图（简述）

• UI 组件 -> 调用 -> RuntimeService（或 RuntimeService.graph.*）-> GraphService -> StudioRuntime（SSOT）-> 更新 -> RuntimeService.syncGraphFromRuntime() -> 更新 runtimeStore 投影 -> React 渲染。

关键文件/类说明（快速查找）

• StudioRuntime: web/src/core/model/StudioRuntime.ts
• RuntimeService: web/src/core/services/RuntimeService.ts
• GraphService: web/src/core/services/GraphService.ts
• NodeModel: web/src/core/model/NodeModel.ts
• NodePalette: web/src/components/NodePalette.tsx
• Workspace: web/src/components/Workspace.tsx
• PropertyPanel: web/src/components/PropertyPanel.tsx

推荐的快速启动与手动检查点

1. 安装依赖并启动开发服务器：

cd web
npm install
npm run dev

2. 手动检查点：

• 打开 http://localhost:5173，验证 NodePalette 节点列表与搜索。
• 拖拽节点到画布，检查拖拽流畅性与拖拽结束后节点是否出现在 runtimeStore 投影中。
• 右键节点，尝试 delete/duplicate/disconnect，观察 toast 提示与画布同步。
• 打开 PropertyPanel，切换参数模式到 exposed，确认端口立刻出现在节点上并在 rfEdges 中可连线。

交接建议给前端优化的 AI

• 提供 mock manifest 覆盖所有 param_schema 类型并测试：text, number, range, checkbox, select, context, exposed。
• 做性能剖析（React Profiler），聚焦 Workspace 和 UniversalNode 渲染路径，优化不必要的 re-renders。
• 将 TEST_INTEGRATION.js 迁移到自动化测试框架，增加关键流的 CI 覆盖。

---