TraceStudio-dev/docs/web1.1/1.md

这是一个非常果断且正确的决策。“重构代码”往往比“重写代码”更痛苦，尤其是当核心架构理念（如从“纯前端逻辑”转向“服务端驱动 UI”）发生根本性转变时。

直接制定一份V2 架构规范白皮书，然后让 Copilot 作为一个“执行者”去填空，是最高效的路径。

这份文档将作为你和 AI 协作的最高宪法。所有后续的代码生成都必须通过这份文档的校验。

---

🏗️ TraceStudio V2 架构规范白皮书 (The Blueprint)

核心哲学：服务端定义一切，前端只负责渲染。 架构模式：Server-Driven UI + MVVM (Model-View-ViewModel)

1. 顶层设计原则

1. Single Source of Truth (SSOT)：节点的定义（输入、输出、参数类型、UI 控件类型）完全由后端 Python 代码决定。前端不许硬编码任何节点逻辑。
2. Logic/UI Separation：

• Core (逻辑层)：纯 TypeScript，无 React 依赖。负责数据模型、API 通信、图算法。
• View (视图层)：纯 React。只负责根据 Model 渲染界面，不处理业务逻辑。

3. Protocol First：前后端通过标准化的 JSON Schema 通信。

---

3. 前端目录结构规范 (The Clean Architecture)

基于 V1 的结构进行破坏性重组。严格区分 core 和 components。

web/src/
├── core/                       # [逻辑内核] 禁止引入 React
│   ├── model/                  # 领域模型 (OOP)
│   │   ├── GraphModel.ts       # 图数据结构、连接验证
│   │   ├── NodeModel.ts        # 单个节点的行为与状态
│   │   └── PortModel.ts        # 端口定义
│   ├── services/               # 基础设施
│   │   ├── ApiService.ts       # Axios 封装
│   │   ├── SchemaService.ts    # 拉取并缓存后端节点定义
│   │   └── ExecutionService.ts # 负责图执行与 WebSocket 监听
│   ├── store/                  # 状态管理 (Zustand)
│   │   ├── graphStore.ts       # ViewModel: 持有 GraphModel 实例
│   │   └── uiStore.ts          # 界面状态 (侧边栏显隐等)
│   └── registry/               # 注册表
│       └── WidgetRegistry.ts   # 映射：Schema Type -> React Component
│
├── components/                 # [视图层] 纯 UI
│   ├── _layouts/               # 布局容器 (AppShell, Panel)
│   ├── canvas/                 # 画布相关
│   │   ├── GraphCanvas.tsx     # ReactFlow 包装器 (只读 props)
│   │   └── controls/           # MiniMap, Zoom
│   ├── nodes/                  # 节点渲染
│   │   ├── UniversalNode.tsx   # 通用节点外壳 (Header, Ports)
│   │   └── NodeStatus.tsx      # 运行状态灯
│   ├── panels/                 # 功能面板
│   │   ├── Inspector/          # 属性面板 (重灾区，需严格模块化)
│   │   │   ├── Inspector.tsx   # 遍历 NodeModel.params 渲染 Widget
│   │   │   └── widgets/        # 原子控件库 (Slider, ColorPicker)
│   │   └── Library/            # 节点库
│   └── shared/                 # 通用原子组件 (Button, Input)
│
└── main.tsx

---

4. 关键模块实现规范

4.1 通用节点 (UniversalNode)

前端不再为每个节点写组件。

• 输入：接收 NodeModel 实例。
• 职责：

1. 渲染标题（model.title）。
2. 根据 model.inputs / model.outputs 循环渲染 <Handle />。
3. 渲染状态指示灯（运行中/成功/失败）。 注意：节点本体不渲染参数控件，参数控件只在 Inspector 中显示。

4.2 属性面板 (Inspector) & 控件注册表

这是实现 Server-Driven UI 的核心。

逻辑流程：

1. 用户点击节点 -> uiStore 记录 activeNodeId。
2. Inspector 组件从 store 获取 activeNode (NodeModel)。
3. Inspector 读取 activeNode.schema.parameters。
4. Inspector 遍历参数列表，调用 WidgetRegistry.render(param.widgetType, props)。

WidgetRegistry 伪代码：

const registry = {
  "TimeSlider": (props) => <Slider min={props.min} max={props.max} ... />,
  "Toggle": (props) => <Switch ... />,
  "CodeEditor": (props) => <MonacoEditor ... />
};

---

5. Copilot 执行计划 (Phases)

要求 Copilot 严格按照以下顺序“搭建积木”，切勿跳跃。

✅ Phase 1: 协议与后端基础 (The Foundation)

1. 搭建 Python 后端基础框架（FastAPI）。
2. 实现 Node 基类和 @register_node 装饰器。
3. 实现 /api/schema 接口，确保能输出 JSON 定义。
4. 目标：不写任何前端代码，仅通过 Postman 验证 Schema 输出。

✅ Phase 2: 前端内核 (The Core)

1. 初始化 React + Vite + TypeScript 项目。
2. 创建 src/core/model 目录，实现 GraphModel 和 NodeModel 类。
3. 实现 SchemaService，从后端拉取定义并实例化 NodeModel。
4. 目标：在控制台 (console.log) 能看到完整的图对象结构，无 UI。

✅ Phase 3: 基础渲染 (The Renderer)

1. 集成 React Flow。
2. 实现 UniversalNode 组件，绑定 NodeModel 数据。
3. 实现 GraphCanvas，能够从 graphStore 渲染出节点。
4. 目标：能看到一个个只有标题和端口的“空盒子”节点，能连线。

✅ Phase 4: 交互与参数 (The Interaction)

1. 建立 WidgetRegistry 和基础控件（String, Number, Bool）。
2. 实现 Inspector 面板，点击节点显示动态表单。
3. 实现参数修改的双向绑定（UI -> NodeModel）。
4. 目标：点击节点，右侧面板根据后端定义自动生成控件，且能修改值。

✅ Phase 5: 执行流 (The Execution)

1. 实现前端 ExecutionService，将图序列化发送给后端。
2. 实现后端 GraphExecutor，解析拓扑并按顺序调用 Python 节点的 execute 方法。
3. 目标：点击“运行”，后端打印日志，前端节点状态变绿。

---

下一步指令

如果你同意这份规范，你可以直接向我发送以下指令，我将作为 Phase 1 的开始：

"Gemini，请根据 V2 架构规范，为我生成 Phase 1 (后端基础) 的核心代码。我需要 node_system.py（包含基类和装饰器）以及 main.py（FastAPI 入口和 Schema 导出接口）。"