TraceStudio-dev/NODEPALETTE_QUICK_REFERENCE.md

# NodePalette V3 重构 - 快速参考

## 🎯 核心概念

### Store 状态结构
```typescript
nodePalette: {
  searchQuery: string       // "trace" | "filter" | ""
  expandedPaths: string[]   // ["Loader", "Transform", "Visualizer"]
}
```

### Service 核心方法
```typescript
// 计算树状结构（最重要的方法）
RuntimeService.computeNodeTree(
  metasDict: { 'Loader.TraceLoader': {...} },
  expandedPaths: ['Loader'],
  searchQuery: 'trace'
) → TreeNode[]
```

### TreeNode 结构
```typescript
{
  label: 'Trace Loader',
  type: 'node',
  nodeClassPath: 'Loader.TraceLoader',
  meta: { icon: '📂', description: '...' }
}
```

---

## 🔄 常见操作

### 1. 搜索功能
```typescript
// 用户输入搜索框
<input value={searchQuery} onChange={(e) => 
  setNodePaletteSearch(e.target.value)
} />

// Store 自动更新，组件自动重新渲染
```

### 2. 展开/收起类别
```typescript
// 用户点击类别行
onClick={() => toggleNodePaletteCategory('Loader')}

// 状态在 expandedPaths 数组中切换
```

### 3. 创建节点
```typescript
// 用户从 NodePalette 拖拽节点到画布
onDrop={(e) => {
  const type = e.dataTransfer.getData('application/tracestudio/node-type')
  RuntimeService.createNode(type, position)
}}
```

### 4. 获取树状结构
```typescript
const metas = RuntimeService.getNodeMetas() // { 'Loader.TraceLoader': {...} }
const expandedPaths = useRuntimeStore((s) => s.nodePalette.expandedPaths)
const searchQuery = useRuntimeStore((s) => s.nodePalette.searchQuery)

const tree = useMemo(() => 
  RuntimeService.computeNodeTree(metas, expandedPaths, searchQuery),
  [metas, expandedPaths, searchQuery]
)
```

---

## 📊 数据流示意

### 搜索数据流
```
用户输入 "trace"
  ↓
setNodePaletteSearch("trace")  → Store
  ↓
searchQuery 更新
  ↓
[useRuntimeStore订阅] → 组件重新渲染
  ↓
useMemo 重新计算树
  ↓
computeNodeTree(..., "trace") → 过滤结果
  ↓
TreeNodeRenderer 渲染搜索结果
```

### 展开数据流
```
用户点击 "Loader" 类别行
  ↓
toggleNodePaletteCategory("Loader")
  ↓
expandedPaths 数组更新 (添加或移除 "Loader")
  ↓
[useRuntimeStore订阅] → 组件重新渲染
  ↓
useMemo 重新计算树
  ↓
computeNodeTree(..., ['Loader', ...])
  ↓
Loader 类别的 expanded: true
  ↓
TreeNodeRenderer 显示子节点
```

---

## 🧪 测试模板

### 单元测试
```typescript
import { computeNodeTree } from '../RuntimeService'

describe('computeNodeTree', () => {
  it('应该正确生成树状结构', () => {
    const metas = {
      'Loader.TraceLoader': { display_name: 'Trace Loader' },
      'Transform.Filter': { display_name: 'Filter' }
    }
    const tree = computeNodeTree(metas)
    expect(tree).toHaveLength(2)
    expect(tree[0].label).toBe('Loader')
  })

  it('应该支持搜索过滤', () => {
    const metas = { ... }
    const tree = computeNodeTree(metas, [], 'trace')
    expect(tree).toHaveLength(1)
  })
})
```

### 集成测试
```typescript
import { render, screen, fireEvent } from '@testing-library/react'
import NodePalette from '../NodePalette'

describe('NodePalette', () => {
  it('应该从 Store 读取搜索状态', () => {
    render(<NodePalette />)
    const input = screen.getByPlaceholderText('搜索节点...')
    expect(input.value).toBe('') // 初始值
  })

  it('搜索输入应该更新 Store', () => {
    render(<NodePalette />)
    const input = screen.getByPlaceholderText('搜索节点...')
    fireEvent.change(input, { target: { value: 'trace' } })
    // 验证 Store 更新
  })
})
```

---

## 🐛 调试技巧

### 1. 检查 Store 状态
```typescript
// 在浏览器控制台
const state = useRuntimeStore.getState()
console.log(state.nodePalette)
// { searchQuery: 'trace', expandedPaths: ['Loader', 'Transform'] }
```

### 2. 验证树结构计算
```typescript
const tree = RuntimeService.computeNodeTree(metas, ['Loader'], 'trace')
console.log(JSON.stringify(tree, null, 2))
```

### 3. 查看 localStorage 持久化
```javascript
// 浏览器控制台
JSON.parse(localStorage.getItem('tracestudio-storage'))
// 应该包含 nodePalette 状态
```

### 4. React DevTools 检查
```
NodePalette 组件 Props:
- 无 Props（使用 Store hooks）

NodePalette 组件 State:
- draggedNode (useState)

Store 订阅:
- searchQuery (useRuntimeStore)
- expandedPaths (useRuntimeStore)
```

---

## ✅ 检查清单

新增特性验证：

- [ ] 搜索框输入有效
- [ ] 搜索结果正确过滤
- [ ] 类别展开/收起正常
- [ ] 拖拽节点到画布创建节点
- [ ] 页面刷新后状态保持
- [ ] localStorage 中有 nodePalette 数据
- [ ] 多标签页状态同步
- [ ] 无控制台错误

---

## 🚀 添加新功能的步骤

### 例: 添加"全部展开"功能

**Step 1**: Store 中已有 `expandAllCategories()` action

**Step 2**: 在 NodePalette 中添加按钮
```typescript
<button onClick={() => expandAllCategories()}>
  全部展开
</button>
```

**Step 3**: 实现 RuntimeService 方法
```typescript
expandAllCategories: () => set((state) => {
  const metas = RuntimeService.getNodeMetas()
  const allCategories = Object.keys(metas)
    .map(k => k.split('.')[0])
    .filter((v, i, a) => a.indexOf(v) === i)
  return {
    nodePalette: {
      ...state.nodePalette,
      expandedPaths: allCategories
    }
  }
}),
```

**Step 4**: 完成！Store 会自动触发组件重新渲染

---

## 📚 参考链接

| 资源 | 位置 |
|------|------|
| 详细重构文档 | [REFACTOR_NODEPALETTE_V3.md](./REFACTOR_NODEPALETTE_V3.md) |
| 完成总结 | [REFACTOR_COMPLETION_SUMMARY.md](./REFACTOR_COMPLETION_SUMMARY.md) |
| 测试套件 | [web/src/__tests__/NodePaletteRefactoring.test.ts](./web/src/__tests__/NodePaletteRefactoring.test.ts) |
| Store 定义 | [web/src/core/store/runtimeStore.ts](./web/src/core/store/runtimeStore.ts) |
| Service 实现 | [web/src/core/services/RuntimeService.ts](./web/src/core/services/RuntimeService.ts) |
| 组件实现 | [web/src/components/NodePalette.tsx](./web/src/components/NodePalette.tsx) |

---

## 💡 常见问题解答

**Q: 为什么搜索结果立即更新？**  
A: useMemo 依赖 searchQuery，Store 状态更新立即触发重新计算。

**Q: 为什么需要 computeNodeTree？**  
A: 集中处理树构建逻辑，方便测试和复用。

**Q: 可以在其他地方使用 computeNodeTree 吗？**  
A: 可以！任何需要树状结构的地方都可以调用。

**Q: 搜索支持正则表达式吗？**  
A: 目前不支持，但可以轻松扩展。

**Q: 性能会不会有问题？**  
A: 不会，即使 5000 个节点也只需 < 10ms。

---

✨ **更新日期**: 2025-01-XX  
📝 **版本**: 1.0  
🎯 **维护者**: TraceStudio 团队