128 lines
7.7 KiB
Markdown
128 lines
7.7 KiB
Markdown
# 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. 安装依赖并启动开发服务器：
|
||
|
||
```bash
|
||
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 覆盖。
|
||
|
||
---
|
||
|
||
|