这是一个非常果断且正确的决策。**“重构代码”往往比“重写代码”更痛苦**，尤其是当核心架构理念（如从“纯前端逻辑”转向“服务端驱动 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`。

```text
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 伪代码：**

```typescript
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 导出接口）。"