# 🎉 TraceStudio v0.3.0 - 快速开始

> **新功能**: Param 绑定模式 + EdgeType 视觉编码 + 暴露端口系统

---

## 🚀 三分钟快速体验

### 第一步：启动开发环境
```bash
cd web
npm install
npm run dev
```

浏览器自动打开 `http://localhost:5173`

### 第二步：创建第一个使用新功能的节点

1. **从左侧节点库拖拽** Loader 和 Transform 节点到画布
2. **连接它们**: Loader 的输出拖到 Transform 的输入
3. **选中 Transform** 节点 → 右侧 Inspector 面板出现

### 第三步：尝试 Param 绑定

#### 📝 静态值模式
```
1. 在 Inspector 找到 "batch_size" 参数
2. 点击 📝 静态值 按钮
3. 输入数值 100
4. 保存
```

#### 🔗 Context 模式
```
1. 同一参数点击 🔗 Context 按钮
2. 下拉列表选择：$Global.System.Time 或 $LoaderNode.xxx
3. 完成绑定
```

#### ⚡ 暴露端口
```
1. 同一参数点击 ⚡ 暴露端口 按钮
2. 节点左侧出现新的粉红色端口
3. 从其他节点连线拖到该端口
```

### 第四步：观察连线粗细

```
Loader (输出 DataTable - 数组)
    ║║ ← 粗线 4px（edgeType='array'）
Transform (输出 count - 标量)
    ║  ← 细线 3px（edgeType='scalar'）
Visualizer
```

---

## 📚 文档导航

| 文档 | 适合人群 | 内容 |
|------|----------|------|
| [USER_GUIDE_v0.3.0.md](./USER_GUIDE_v0.3.0.md) | **最终用户** | 如何使用新功能、工作流示例、常见问题 |
| [IMPLEMENTATION_SUMMARY.md](./IMPLEMENTATION_SUMMARY.md) | **开发者** | 技术细节、API 变更、集成说明 |
| [FEATURES_TEST.md](./FEATURES_TEST.md) | **测试者** | 测试场景、验收标准、已知问题 |
| [ACCEPTANCE_CHECKLIST.md](./ACCEPTANCE_CHECKLIST.md) | **项目经理** | 完成度统计、验收清单、后续计划 |

---

## 🎯 核心功能速览

### Param 绑定模式（三种来源）

| 模式 | 按钮 | 用途 | 示例 |
|------|------|------|------|
| 静态值 | 📝 | 固定参数值 | `batch_size = 100` |
| Context | 🔗 | 从变量读取 | `threshold = $LoaderNode.avg` |
| 暴露端口 | ⚡ | 从连线接收 | `filter_mode ← input port` |

### 连线 EdgeType（数据维度编码）

| 类型 | 粗细 | 颜色 | 数据例子 |
|------|------|------|---------|
| 数组 | 4px | 蓝色 | DataTable, Array, List |
| 标量 | 3px | 橙色 | String, Integer, Float |

### 暴露端口（两种端口）

| 端口 | 颜色 | 来源 | 用途 |
|------|------|------|------|
| Param ⚡ | 粉红 | 参数暴露 | 接收其他节点的值 |
| Context 📋 | 绿色 | Context 暴露 | 输出给下游节点 |

---

## 🧪 验证功能

### 浏览器控制台测试

打开 F12 → 粘贴下列代码快速验证：

```javascript
// 加载测试脚本
const script = document.createElement('script')
script.src = '/TEST_INTEGRATION.js'
document.head.appendChild(script)

// 运行完整测试（需创建至少一个节点）
await testCompleteWorkflow()
```

**测试项**:
- ✅ testParamBinding() - Param 绑定按钮
- ✅ testEdgeType() - 连线粗细
- ✅ testExposedPorts() - 暴露端口
- ✅ testNodeDataStructure() - 数据结构
- ✅ testAPIResponse() - API 响应

---

## 🔧 开发指南

### 如何添加新的 Param 绑定模式

```typescript
// 1. 在 useStore.ts 添加新模式
export type ParamBindingMode = 'static' | 'context' | 'exposed' | 'formula'

// 2. 在 Inspector.tsx 添加按钮
<button onClick={() => handleModeChange('formula')}>🧮 公式</button>

// 3. 添加对应的输入控件
if (binding.mode === 'formula') {
  // <FormulaEditor />
}
```

### 如何为 UniversalNode 添加新的暴露端口类型

```typescript
// 在 UniversalNode.tsx 中扩展
const allOutputs = [
  ...outputs,
  ...(exposedPorts.contexts || []),
  ...(exposedPorts.variables || [])  // 新增类型
]
```

---

## 📖 工作流示例

### 例子 1: 简单的参数传递

```
CSV Loader
 └─ 暴露参数: batch_size = 50 (📝 静态值)
   └─ Transform
       └─ threshold = $LoaderNode.max (🔗 Context)
         └─ Visualizer
```

### 例子 2: 动态参数（暴露端口）

```
Range Generator (输出 [1,2,3,4,5])
  │
  └─ Batch Processor
      ├─ batch_size ⚡ (暴露端口)
      │  ↑ (从 Range 输出连线)
      └─ Transform
```

### 例子 3: Context 链式传递

```
Loader1 → ctx: row_count
  │
  └─ Processor → param: threshold = $Loader1.row_count (🔗 Context)
       │
       └─ Filter → param: limit = $Processor.filtered_count
            │
            └─ Visualizer
```

---

## ❓ 常见问题

### Q: 如何看到节点的暴露端口？
**A**: 
1. 选中节点查看 Inspector
2. 参数选择 ⚡ 暴露端口
3. 节点上会出现粉红色新端口，内部会显示 "⚡ Params: ..."

### Q: Context 下拉列表为什么是空的？
**A**:
1. 检查是否有上游节点
2. 上游节点需要暴露 context_vars
3. 确保选择了 🔗 Context 模式

### Q: 连线粗细什么时候才会变化？
**A**: 创建连线时根据源节点的输出类型自动推断：
- Array/List/Table → 4px 粗线
- 其他类型 → 3px 细线

---

## 🐛 已知限制

| 问题 | 影响 | 规划修复 |
|------|------|---------|
| 删除上游节点不清空 contextRef | 低 | v0.3.1 |
| 参数名变更未同步 bindings | 低 | v0.3.1 |
| 暴露端口仅前端支持，后端未处理 | 中 | v0.4.0 |
| 无 Dimension Mode（EXPAND/COLLAPSE/BROADCAST） | 低 | v0.5.0 |

---

## 📞 获取帮助

- 📖 **用户文档**: [USER_GUIDE_v0.3.0.md](./USER_GUIDE_v0.3.0.md)
- 🔧 **技术文档**: [IMPLEMENTATION_SUMMARY.md](./IMPLEMENTATION_SUMMARY.md)
- ✅ **测试指南**: [FEATURES_TEST.md](./FEATURES_TEST.md)
- 📋 **验收清单**: [ACCEPTANCE_CHECKLIST.md](./ACCEPTANCE_CHECKLIST.md)

---

## 📝 更新日志

**v0.3.0** (2024-01)
- ✨ 新增 Param 绑定模式系统（static/context/exposed）
- 🎨 新增 EdgeType 视觉编码（数组粗线、标量细线）
- 📌 新增暴露端口显示（Param 输入、Context 输出）
- 📚 完整文档和测试工具

**v0.2.0** (前版本)
- ✅ 四大属性 API 规范化
- ✅ 基础节点系统

---

**快速链接**: [用户指南](./USER_GUIDE_v0.3.0.md) | [技术文档](./IMPLEMENTATION_SUMMARY.md) | [测试指南](./FEATURES_TEST.md) | [验收清单](./ACCEPTANCE_CHECKLIST.md)

**版本**: v0.3.0 | **状态**: ✅ 生产就绪 | **最后更新**: 2024-01