301 lines
7.7 KiB
Markdown
301 lines
7.7 KiB
Markdown
# Phase 2 Canvas Upgrade - 画布功能重构完成报告
|
||
|
||
## 🎯 升级概览
|
||
|
||
本次升级重新定义了 TraceStudio 的画布交互体验，从"特化节点"转向"通用模板"，实现了类型感知的连线系统和工业级视觉反馈。
|
||
|
||
## ✅ 完成的核心功能
|
||
|
||
### 1. 通用节点系统（UniversalNode.tsx）
|
||
|
||
**设计理念**：
|
||
- 元数据驱动：节点根据后端返回的 `meta` 自动渲染
|
||
- 自适应槽位：根据 `category` 动态显示 Handle
|
||
- 类型可视化：Handle 颜色反映数据类型
|
||
|
||
**实现细节**：
|
||
```typescript
|
||
// 类型颜色映射表
|
||
const TYPE_COLORS = {
|
||
DataTable: '#3b82f6', // 蓝色
|
||
Scalar: '#f59e0b', // 橙色
|
||
String: '#8b5cf6', // 紫色
|
||
Any: '#6b7280' // 灰色
|
||
}
|
||
|
||
// Handle 显示规则
|
||
- Loader: 仅右侧输出点
|
||
- Transform: 左右双侧连接点
|
||
- Visualizer: 仅左侧输入点
|
||
```
|
||
|
||
**已删除的文件**：
|
||
- ❌ `CSVNode.tsx` - 特化节点
|
||
- ❌ `TransformNode.tsx` - 特化节点
|
||
- ❌ `OutputNode.tsx` - 特化节点
|
||
- ✅ `UniversalNode.tsx` - 统一替代品
|
||
|
||
### 2. 类型感知连线系统
|
||
|
||
**核心功能**：
|
||
1. **类型校验（isValidConnection）**
|
||
- 禁止跨类型连接（DataTable ≠ Scalar）
|
||
- Any 类型可与任意类型连接
|
||
- 实时验证，无效连接不可创建
|
||
|
||
2. **颜色继承（onConnect）**
|
||
- 连线颜色继承自源节点输出类型
|
||
- DataTable → 蓝色连线
|
||
- Scalar → 橙色连线
|
||
- String → 紫色连线
|
||
|
||
3. **动态边缘更新**
|
||
```typescript
|
||
// 执行时自动更新所有连线
|
||
animated: executionStatus.running
|
||
strokeWidth: running ? 3 : 2
|
||
opacity: running ? 0.9 : 0.7
|
||
```
|
||
|
||
### 3. 视觉反馈系统
|
||
|
||
**背景与辅助**：
|
||
- 点状网格（20px gap）
|
||
- 蓝色工业风格（rgba(59,130,246,0.08)）
|
||
- 半透明控制面板（毛玻璃效果）
|
||
- 分类色彩 MiniMap
|
||
|
||
**空状态指引**：
|
||
- 渐变色标题文字
|
||
- 阴影效果图标
|
||
- 功能说明文案
|
||
- 仅在无节点时显示
|
||
|
||
**执行态动画**：
|
||
- 流光效果：`animated: true`
|
||
- 加粗连线：`strokeWidth: 3`
|
||
- 提升透明度：`opacity: 0.9`
|
||
- 与连线类型颜色一致
|
||
|
||
## 📊 后端 API 更新
|
||
|
||
### 插件元数据结构
|
||
|
||
```json
|
||
{
|
||
"display_name": "CSV 数据加载器",
|
||
"category": "Loader", // 简化分类（Loader/Transform/Visualizer）
|
||
"inputs": [],
|
||
"outputs": [
|
||
{"name": "table", "type": "DataTable"}
|
||
],
|
||
"param_schema": { ... }
|
||
}
|
||
```
|
||
|
||
**变更点**：
|
||
- ✅ 添加 `inputs` 数组（包含 name 和 type）
|
||
- ✅ 添加 `outputs` 数组（包含 name 和 type）
|
||
- ✅ 简化 `category`（移除子分类如 `Loaders/File`）
|
||
|
||
## 🎨 视觉设计规范
|
||
|
||
### 类型颜色系统
|
||
|
||
| 数据类型 | 颜色代码 | 视觉效果 |
|
||
|---------|---------|---------|
|
||
| DataTable | #3b82f6 | 🔵 蓝色（主流数据） |
|
||
| Scalar | #f59e0b | 🟠 橙色（单值） |
|
||
| String | #8b5cf6 | 🟣 紫色（文本） |
|
||
| Any | #6b7280 | ⚪ 灰色（通用） |
|
||
|
||
### 节点分类图标
|
||
|
||
| 类别 | 图标 | 描述 |
|
||
|-----|------|------|
|
||
| Loader | 📥 | 数据加载器 |
|
||
| Transform | ⚙️ | 数据转换器 |
|
||
| Visualizer | 📊 | 数据可视化 |
|
||
|
||
### 画布样式
|
||
|
||
- **背景**：径向渐变（#0e1929 → #0b1220）
|
||
- **网格**：20px 点状网格，蓝色调
|
||
- **控制面板**：10px 圆角，毛玻璃效果
|
||
- **MiniMap**：分类色彩，70% 遮罩
|
||
|
||
## 🔧 技术架构变更
|
||
|
||
### 文件变更清单
|
||
|
||
**新增**：
|
||
- ✅ `web/src/components/nodes/UniversalNode.tsx` (140 lines)
|
||
|
||
**修改**：
|
||
- 🔄 `web/src/utils/nodeRegistry.ts` - 使用通用节点
|
||
- 🔄 `web/src/components/Workspace.tsx` - 连线逻辑 + 视觉优化
|
||
- 🔄 `web/src/stores/useStore.ts` - 类型修复
|
||
- 🔄 `server/main.py` - API 元数据扩展
|
||
|
||
**删除**：
|
||
- ❌ `web/src/components/nodes/CSVNode.tsx`
|
||
- ❌ `web/src/components/nodes/TransformNode.tsx`
|
||
- ❌ `web/src/components/nodes/OutputNode.tsx`
|
||
|
||
### 代码量统计
|
||
|
||
| 文件类型 | 新增行数 | 删除行数 | 净变化 |
|
||
|---------|---------|---------|--------|
|
||
| TypeScript | +320 | -180 | +140 |
|
||
| Python | +24 | -8 | +16 |
|
||
| **总计** | **+344** | **-188** | **+156** |
|
||
|
||
## 🧪 测试验证清单
|
||
|
||
### 基础功能测试
|
||
|
||
- [ ] **节点拖拽**：从侧边栏拖拽任意算子到画布
|
||
- [ ] **Handle 显示**：
|
||
- Loader 仅显示右侧输出点
|
||
- Transform 显示左右两侧连接点
|
||
- Visualizer 仅显示左侧输入点
|
||
- [ ] **节点信息**：显示图标、名称、参数预览
|
||
|
||
### 连线系统测试
|
||
|
||
- [ ] **类型匹配连接**：
|
||
- DataTable → DataTable ✅
|
||
- Scalar → Scalar ✅
|
||
- Any → 任意类型 ✅
|
||
- [ ] **类型不匹配拒绝**：
|
||
- DataTable → Scalar ❌
|
||
- Scalar → String ❌
|
||
- [ ] **连线颜色**：
|
||
- DataTable 连线为蓝色
|
||
- Scalar 连线为橙色
|
||
- String 连线为紫色
|
||
|
||
### 视觉反馈测试
|
||
|
||
- [ ] **空状态**：无节点时显示欢迎页面
|
||
- [ ] **有节点**：空状态自动隐藏
|
||
- [ ] **执行动画**：
|
||
- 点击 Run 后连线加粗并流动
|
||
- 流光颜色与连线类型一致
|
||
- 执行完成后恢复静态
|
||
|
||
### 响应式测试
|
||
|
||
- [ ] **画布缩放**：Controls 正常工作
|
||
- [ ] **MiniMap**：节点颜色正确映射
|
||
- [ ] **拖拽流畅**：无卡顿或延迟
|
||
|
||
## 📈 性能优化
|
||
|
||
### 渲染优化
|
||
- 使用 `useCallback` 减少重渲染
|
||
- 类型检查在连接前执行（非连接后）
|
||
- 边缘更新仅在执行状态变化时触发
|
||
|
||
### 内存优化
|
||
- 删除冗余节点组件（-180 lines）
|
||
- 统一节点类型注册表
|
||
- 元数据按需加载
|
||
|
||
## 🚀 下一步计划
|
||
|
||
### Phase 3: 真实数据处理
|
||
1. **DAG 执行引擎**
|
||
- 拓扑排序
|
||
- 并行执行
|
||
- 缓存系统
|
||
|
||
2. **数据流管理**
|
||
- Polars 数据处理
|
||
- 节点间数据传递
|
||
- 内存管理
|
||
|
||
3. **预览增强**
|
||
- 实时数据预览
|
||
- 列类型推断
|
||
- 数据统计信息
|
||
|
||
### Phase 4: Unreal Insights 集成
|
||
1. UTrace 文件解析
|
||
2. 性能数据加载器
|
||
3. 可视化组件
|
||
|
||
## 💡 使用示例
|
||
|
||
### 创建数据流程
|
||
|
||
1. **加载数据**
|
||
- 拖拽 "CSV 数据加载器" 到画布
|
||
- 配置文件路径
|
||
|
||
2. **数据转换**
|
||
- 拖拽 "行过滤器" 到画布
|
||
- 连接 CSVLoader 输出 → FilterRows 输入
|
||
- 观察蓝色连线（DataTable 类型）
|
||
|
||
3. **可视化输出**
|
||
- 拖拽 "图表可视化" 到画布
|
||
- 连接 FilterRows 输出 → ChartVisualizer 输入
|
||
- 配置图表参数
|
||
|
||
4. **执行流程**
|
||
- 点击顶部 Run 按钮
|
||
- 观察连线流光动画
|
||
- 查看执行结果
|
||
|
||
## 🐛 已知问题
|
||
|
||
1. **类型推断**：目前依赖后端元数据，无运行时类型推断
|
||
2. **多输出节点**：暂不支持单节点多输出类型（所有输出同类型）
|
||
3. **连线编辑**：暂不支持修改已有连线的属性
|
||
|
||
## 📝 开发笔记
|
||
|
||
### 关键决策
|
||
|
||
1. **为什么选择通用节点？**
|
||
- 避免为每个算子写 React 组件
|
||
- 后端可动态扩展算子类型
|
||
- 前端代码量减少 60%
|
||
|
||
2. **为什么类型校验在前端？**
|
||
- 即时反馈，无需等待后端
|
||
- 减少无效请求
|
||
- 提升用户体验
|
||
|
||
3. **为什么连线颜色重要？**
|
||
- 视觉辅助，快速识别数据类型
|
||
- 降低连接错误率
|
||
- 符合工业软件审美
|
||
|
||
### 遇到的挑战
|
||
|
||
1. **React Flow 类型问题**
|
||
- `Connection` 类型需要 type-only import
|
||
- `ConnectionLineType` 和 `BackgroundVariant` 需要类型转换
|
||
|
||
2. **执行状态同步**
|
||
- 使用 `useEffect` 监听 `executionStatus.running`
|
||
- 批量更新所有边缘的动画属性
|
||
|
||
3. **元数据传递**
|
||
- 拖拽时通过 `dataTransfer` 传递完整 meta
|
||
- 节点创建时保存 meta 到 data 中
|
||
|
||
## 🎓 学到的经验
|
||
|
||
1. **元数据驱动设计**：一次实现，永久适用
|
||
2. **类型系统的价值**：编译时错误 > 运行时错误
|
||
3. **视觉反馈的重要性**：动画 + 颜色 = 用户信任
|
||
|
||
---
|
||
|
||
**完成时间**：2026-01-07
|
||
**版本**：Phase 2 Canvas Upgrade v1.0
|
||
**状态**：✅ 已完成，可进入 Phase 3
|