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