# 工作流数据格式说明

## 1. 节点类型数据示例

```json
{
  "id": 2003,
  "createTime": "2024-12-05 12:40:03",
  "createBy": "system",
  "updateTime": "2024-12-05 12:40:03",
  "updateBy": "system",
  "version": 1,
  "deleted": false,
  "extraData": null,
  "code": "SHELL",
  "name": "Shell脚本节点",
  "description": "执行Shell脚本的任务节点",
  "category": "TASK",
  "icon": "code",
  "color": "#1890ff",
  "executors": [
    {
      "code": "SHELL",
      "name": "Shell脚本执行器",
      "description": "执行Shell脚本，支持配置超时时间和工作目录",
      "configSchema": "{\"type\":\"object\",\"required\":[\"script\"],\"properties\":{\"script\":{\"type\":\"string\",\"title\":\"脚本内容\",\"format\":\"shell\",\"description\":\"需要执行的Shell脚本内容\"},\"timeout\":{\"type\":\"number\",\"title\":\"超时时间\",\"description\":\"脚本执行的最大时间(秒)\",\"minimum\":1,\"maximum\":3600,\"default\":300},\"workingDir\":{\"type\":\"string\",\"title\":\"工作目录\",\"description\":\"脚本执行的工作目录\",\"default\":\"/tmp\"}}}",
      "defaultConfig": null
    }
  ],
  "configSchema": "{\n  \"type\": \"object\",\n  \"properties\": {\n    \"name\": {\n      \"type\": \"string\",\n      \"title\": \"节点名称\",\n      \"minLength\": 1,\n      \"maxLength\": 50\n    },\n    \"description\": {\n      \"type\": \"string\",\n      \"title\": \"节点描述\",\n      \"maxLength\": 200\n    },\n    \"executor\": {\n      \"type\": \"string\",\n      \"title\": \"执行器\",\n      \"enum\": [\"SHELL\"],\n      \"enumNames\": [\"Shell脚本执行器\"]\n    },\n    \"retryTimes\": {\n      \"type\": \"number\",\n      \"title\": \"重试次数\",\n      \"minimum\": 0,\n      \"maximum\": 3,\n      \"default\": 0\n    },\n    \"retryInterval\": {\n      \"type\": \"number\",\n      \"title\": \"重试间隔(秒)\",\n      \"minimum\": 1,\n      \"maximum\": 300,\n      \"default\": 60\n    }\n  },\n  \"required\": [\"name\", \"executor\"]\n}",
  "defaultConfig": "{\"name\": \"Shell脚本\", \"executor\": \"SHELL\", \"retryTimes\": 0, \"retryInterval\": 60}",
  "enabled": true
}
```

## 2. 流程设计数据示例

```json
{
  "nodes": [
    {
      "id": "node_1",
      "type": "START",
      "position": { "x": 100, "y": 100 },
      "data": {
        "name": "开始",
        "description": "流程开始节点",
        "config": {
          "name": "开始",
          "description": "这是一个开始节点"
        }
      }
    }
  ],
  "edges": [
    {
      "id": "edge_1",
      "source": "node_1",
      "target": "node_2",
      "type": "default",
      "data": {
        "condition": null
      }
    }
  ]
}
```

## 3. 关键字段说明

### configSchema（节点配置模式）
**用途**：
1. 前端动态生成配置表单
2. 后端验证配置数据的合法性
3. 提供配置项的约束和验证规则

### defaultConfig（默认配置）
**用途**：
1. 新建节点时的默认值
2. 重置配置时的参考值
3. 必须符合configSchema定义的格式

### executors（执行器定义）
**用途**：
1. 定义节点支持的执行器类型
2. 每个执行器的配置要求
3. 用于任务节点的具体执行逻辑

## 4. 字段关系说明

1. configSchema定义节点的整体配置结构
2. defaultConfig提供符合configSchema的默认值
3. executors中的configSchema定义具体执行器的配置结构
4. 实际节点配置时，executorConfig需要符合选定执行器的configSchema

## 5. 前端实现指南

### 5.1 工作流设计器组件架构

推荐使用组件化设计，主要包含以下组件：

1. **WorkflowDesigner（工作流设计器）**
   - 整体容器组件
   - 负责状态管理
   - 处理快捷键
   - 工具栏集成

2. **NodePanel（节点面板）**
   - 显示可用节点类型
   - 支持拖拽创建节点
   - 节点分类展示

3. **Canvas（画布）**
   - 节点和连线的可视化
   - 处理拖拽和连线
   - 网格背景
   - 缩放和平移

4. **NodeConfig（节点配置）**
   - 动态表单生成
   - 配置验证
   - 实时预览

### 5.2 接口说明

#### 5.2.1 节点类型接口
```typescript
// 获取节点类型列表
GET /api/v1/node-types
Response: {
  code: number;
  data: NodeType[];
  message: string;
}

// 获取单个节点类型详情
GET /api/v1/node-types/{id}
Response: {
  code: number;
  data: NodeType;
  message: string;
}
```

#### 5.2.2 工作流设计接口
```typescript
// 保存工作流设计
POST /api/v1/workflows/{id}/design
Request: {
  nodes: Node[];
  edges: Edge[];
}
Response: {
  code: number;
  data: boolean;
  message: string;
}

// 获取工作流设计
GET /api/v1/workflows/{id}/design
Response: {
  code: number;
  data: {
    nodes: Node[];
    edges: Edge[];
  };
  message: string;
}
```

### 5.3 节点连线实现

#### 5.3.1 连接点（Anchors）
每种类型节点的连接点定义：
```typescript
interface NodeAnchor {
  id: string;
  type: 'input' | 'output';
  position: 'top' | 'right' | 'bottom' | 'left';
  allowMultiple?: boolean;  // 是否允许多条连线
}

const nodeAnchors = {
  START: [
    { id: 'output', type: 'output', position: 'bottom', allowMultiple: true }
  ],
  END: [
    { id: 'input', type: 'input', position: 'top', allowMultiple: false }
  ],
  TASK: [
    { id: 'input', type: 'input', position: 'top', allowMultiple: false },
    { id: 'output', type: 'output', position: 'bottom', allowMultiple: true }
  ],
  GATEWAY: [
    { id: 'input', type: 'input', position: 'top', allowMultiple: false },
    { id: 'output', type: 'output', position: 'bottom', allowMultiple: true }
  ]
};
```

#### 5.3.2 连线验证规则
```typescript
interface ConnectionValidation {
  sourceNode: Node;
  targetNode: Node;
  sourceAnchor: NodeAnchor;
  targetAnchor: NodeAnchor;
}

function validateConnection({
  sourceNode,
  targetNode,
  sourceAnchor,
  targetAnchor
}: ConnectionValidation): boolean {
  // 1. 检查源节点和目标节点是否有效
  if (!sourceNode || !targetNode) return false;

  // 2. 检查是否形成循环
  if (wouldCreateCycle(sourceNode, targetNode)) return false;

  // 3. 检查锚点类型匹配
  if (sourceAnchor.type !== 'output' || targetAnchor.type !== 'input') return false;

  // 4. 检查目标锚点是否已被占用（如果不允许多重连接）
  if (!targetAnchor.allowMultiple && hasExistingConnection(targetNode, targetAnchor)) {
    return false;
  }

  return true;
}
```

#### 5.3.3 连线样式配置
```typescript
const edgeStyles = {
  default: {
    type: 'smoothstep',  // 平滑阶梯线
    animated: false,
    style: {
      stroke: '#b1b1b7',
      strokeWidth: 2
    }
  },
  selected: {
    style: {
      stroke: '#1890ff',
      strokeWidth: 2
    }
  },
  conditional: {
    type: 'smoothstep',
    animated: true,
    style: {
      stroke: '#722ed1',
      strokeWidth: 2,
      strokeDasharray: '5,5'
    }
  }
};
```

### 5.4 状态管理建议

推荐使用状态管理库（如Redux或MobX）管理以下状态：

1. **全局状态**
   - 当前工作流设计
   - 可用节点类型
   - 画布缩放级别
   - 选中的节点/连线

2. **节点状态**
   - 位置信息
   - 配置数据
   - 验证状态

3. **连线状态**
   - 连接关系
   - 条件配置
   - 样式信息

### 5.5 性能优化建议

1. **渲染优化**
   - 使用React.memo()优化节点渲染
   - 实现虚拟滚动
   - 大量节点时使用分层渲染

2. **状态更新优化**
   - 批量更新状态
   - 使用不可变数据结构
   - 实现节点位置的防抖

3. **交互优化**
   - 拖拽时使用节点预览
   - 连线时显示对齐参考线
   - 支持快捷键操作

### 5.6 错误处理

1. **前端验证**
   - 节点配置验证
   - 连线规则验证
   - 数据完整性检查

2. **错误提示**
   - 友好的错误信息
   - 错误定位高亮
   - 操作建议提示

3. **异常恢复**
   - 自动保存
   - 操作撤销/重做
   - 状态恢复机制

## 6. 最佳实践建议

1. **代码组织**
   - 使用TypeScript确保类型安全
   - 遵循组件设计原则
   - 实现完整的测试覆盖

2. **用户体验**
   - 实现撤销/重做功能
   - 支持键盘快捷键
   - 添加操作引导

3. **可扩展性**
   - 支持自定义节点
   - 支持自定义连线样式
   - 预留扩展接口