# 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 覆盖。

---