TraceStudio-dev/docs/web/FEATURES_TEST.md

前端功能验证清单 (v0.3.0)

已实现功能

✅ 1. Param 绑定模式 (Inspector)

• 三种绑定模式按钮：📝 静态值、🔗 Context、⚡ 暴露端口
• 静态值模式：根据 param 类型显示 input[number] 或 input[text]
• Context 模式：下拉选择 $Global.* 或 $NodeID.* 变量
  • 自动聚合上游节点的 context_vars
  • 格式：$Global.System.Time, $Global.System.User
  • 格式：$NodeID.ContextVar（上游节点变量）
• 暴露端口模式：显示提示 "⚡ 已暴露为输入端口"
  • 点击按钮时自动更新 node.exposedPorts.params
• 数据结构支持：node.bindings[paramName] = { mode, value?, contextRef? }

✅ 2. 连线 EdgeType 标记（Workspace）

• edgeType 推断：基于源输出端口的 type 字段
  • Array/List/Table → edgeType: 'array'
  • 其他 → edgeType: 'scalar'
• 视觉差异：
  • 数组连线：strokeWidth 4px
  • 标量连线：strokeWidth 3px
• 数据持久化：edge.data.edgeType 保存到图元数据
• 执行动画保留边类型宽度

✅ 3. 暴露端口显示（UniversalNode）

• 暴露 Param 作为输入端口
  • 合并 inputs + exposedPorts.params → allInputs
  • 显示标记：⚡ 粉红色端口（#ec4899）、更大尺寸（14x14）
• 暴露 Context 作为输出端口
  • 合并 outputs + exposedPorts.contexts → allOutputs
  • 显示标记：📋 绿色端口（#22c55e）、更大尺寸（14x14）
• 端口指示区域（紫红色背景）：
  • ⚡ Params: param1, param2
  • 📋 Contexts: ctx1, ctx2
• Tooltip：鼠标悬停显示 "⚡ Exposed Param: name" 或 "📋 Context: name"

✅ 4. 数据结构扩展（useStore）

• ParamBindingMode 类型：'static' | 'context' | 'exposed'
• ParamBinding 接口：{ mode, value?, contextRef? }
• NodeSchema.bindings：Record<string, ParamBinding>
• NodeSchema.exposedPorts：{ params: string[], contexts: string[] }
• API 类型扩展：getPlugins 包含 inputs/outputs/param_schema/context_vars

✅ 5. 参数规范化（NodePalette, UniversalNode）

• normalizeParamSchema：Object<name, spec> → Array<{ name, ...spec }>
• 插件加载时统一 param_schema 结构
• UniversalNode 参数提取兼容两种格式

测试场景

场景 1：静态参数值

1. 创建 Transform 节点
2. 在 Inspector 选择 📝 静态值 模式
3. 输入参数值（数字或文本）
4. 验证：node.data[paramName] 更新，node.bindings[paramName] = { mode: 'static', value: ... }

场景 2：Context 绑定

1. 创建两个节点：Loader → Transform
2. Loader 配置 Output 并暴露 context_vars
3. 在 Transform 的 param 选择 🔗 Context 模式
4. 下拉列表应显示：
   - 系统时间 ($Global.System.Time)
   - 当前用户 ($Global.System.User)
   - LoaderNode.Variable ($LoaderNode.Variable)
5. 验证：node.bindings[paramName] = { mode: 'context', contextRef: '$...' }

场景 3：参数暴露

1. 创建 Transform 节点，点击 ⚡ 暴露端口 模式
2. 验证：
   - 节点左侧出现新的粉红色端口（⚡ 14x14）
   - 节点内显示 "⚡ Params: paramName"
   - node.exposedPorts.params 包含该参数
3. 尝试从其他节点连接到该端口

场景 4：连线类型和粗细

1. 创建 Loader (输出 DataTable) → Transform
2. 验证：
   - 连线应为粗线（strokeWidth 4）
   - edge.data.edgeType = 'array'
3. 创建 Loader (输出 Scalar) → Transform
4. 验证：
   - 连线应为细线（strokeWidth 3）
   - edge.data.edgeType = 'scalar'

场景 5：暴露 Context 端口

1. 创建 Loader 节点，配置 context_vars（如 count, result）
2. 点击参数 ⚡ 暴露端口 并选择 Context
3. 验证：
   - 节点右侧出现新的绿色端口（📋 14x14）
   - 节点内显示 "📋 Contexts: ctx1, ctx2"
   - 可从其他节点连接到该 Context 端口

场景 6：完整工作流

1. Loader CSV → 暴露参数 batchSize (📝 静态值 100)
2. Transform → 参数 threshold 绑定到 Loader Context (🔗 $LoaderNode.Threshold)
3. Visualizer → 接收 Transform 的 DataTable (数组连线 4px)
4. 执行并验证数据流

后续优化项

优先级 🔴 高

• 参数绑定 UI 在 Save/Execute 时持久化到后端
• 后端 /api/graph/execute 解析 bindings 并替换参数值
• Dimension Mode 支持：EXPAND / COLLAPSE / BROADCAST（仅数组边）

优先级 🟡 中

• 连线上右键菜单：修改 dimensionMode
• 导入/导出工作流时保存 bindings 和 exposedPorts
• 参数搜索：快速查找可用 Context 变量

优先级 🟢 低

• Param 绑定历史记录（撤销）
• 批量修改参数绑定模式
• 暴露端口的权限控制

已知问题

潜在 Bug

• 删除上游节点时，下游节点的 contextRef 不自动清空
  • 临时方案：手动修改 Inspector 重新选择变量
• 在多窗口拖拽暴露端口可能出现坐标偏移
  • 临时方案：刷新页面或重新连接

UI 优化空间

• Param 绑定按钮间距可再调整
• 暴露端口提示区域背景色过深，可考虑降低 opacity
• Context 下拉列表过长时需要分组或搜索框

验证命令

# 前端编译检查
cd web
npm run build

# 类型检查（忽略 any 警告）
npm run type-check 2>&1 | grep -v "Unexpected any"

# 开发服务启动
npm run dev

变更日志

版本	日期	功能	文件
v0.3.0	2024-01-XX	Param 绑定模式 + EdgeType + 暴露端口	Inspector, UniversalNode, Workspace, useStore
v0.2.0	2024-01-XX	四大属性规范化	API, NodePalette
v0.1.0	2024-01-XX	基础节点系统	-