# Vue Flow 工作流设计器架构文档

## 数据模型对齐

本项目严格遵循 `docs/04-数据模型设计.md` 的规范，确保前后端数据结构完全一致。

### 核心数据模型

#### 1. NodeTypeMetadata（节点类型元数据）
```typescript
interface NodeTypeMetadata {
  id: string              // 节点类型唯一标识（如 http_request）
  name: string            // 驼峰命名（如 httpRequest）
  displayName: string     // 显示名称
  category: NodeCategory  // 节点分类：api | database | logic | notification | transform | other
  fields: FieldDefinition[] // 字段定义（驱动动态表单）
  outputSchema: {...}     // 输出 Schema（JSON Schema 格式）
}
```

**对应后端接口：** `GET /api/node-types`

**用途：**
- 驱动前端动态表单生成
- 构建字段映射树
- 提供节点面板展示信息

#### 2. WorkflowDefinition（工作流定义）
```typescript
interface WorkflowDefinition {
  id: string
  name: string
  schemaVersion: '1.0'  // 固定为 "1.0"
  nodes: WorkflowNode[] // 节点列表
  edges: WorkflowEdge[] // 边列表
  variables?: Record<string, any>
  metadata?: Record<string, any>
}
```

**关键约束：**
- `WorkflowNode.type` 必须对应 `NodeTypeMetadata.id`
- `WorkflowEdge.condition` 必须是完整的 `${...}` 表达式
- 所有表达式支持的命名空间：
  - `nodes`: 上游节点数据，如 `${nodes.n1.output.body.email}`
  - `workflow`: 工作流输入/变量，如 `${workflow.input.approver}`
  - `env`: 环境变量，如 `${env.API_KEY}`

#### 3. FieldDefinition（字段定义）
```typescript
interface FieldDefinition {
  name: string
  label: string
  type: FormFieldType  // text | textarea | number | select | code | key_value | boolean
  required?: boolean
  supportsExpression?: boolean      // 是否支持 ${...} 表达式
  supportsFieldMapping?: boolean    // 是否显示字段选择器
  options?: string[]                // select 类型的选项
  language?: string                 // code 类型的语言
  defaultValue?: any
}
```

**表单渲染规则：**
- `supportsExpression=true`: 显示表达式切换按钮（静态值 ↔ 表达式）
- `supportsFieldMapping=true`: 显示字段选择器图标，点击可选择上游节点字段

### 字段映射机制

#### 构建字段树
从 `outputSchema` 构建字段路径树，最多展开 3 层：

```
HTTP Request (n1)
└── output
    ├── statusCode: number
    ├── body: object
    │   ├── id: number
    │   ├── name: string
    │   └── email: string
    ├── headers: object
    └── elapsed: number
```

#### 生成表达式
选择字段后，生成完整的表达式：
```
选择：HTTP Request (n1) → output → body → email
生成：${nodes.n1.output.body.email}
```

### 前后端类型映射

| 前端类型 | 后端类型 | 说明 |
|---------|---------|------|
| `NodeTypeMetadata` | `NodeTypeMetadata` | 完全一致 |
| `WorkflowDefinition` | `WorkflowDefinition` | 完全一致 |
| `WorkflowNode` | `WorkflowNode` | 完全一致 |
| `WorkflowEdge` | `WorkflowEdge` | 完全一致 |
| `VueFlowNode` | - | 前端扩展（包含渲染状态） |
| `VueFlowEdge` | - | 前端扩展（包含视觉样式） |

### 核心流程

#### 1. 加载节点类型
```typescript
// 从后端获取节点类型元数据
GET /api/node-types
→ NodeTypeMetadata[]

// 前端按分类分组展示
grouped = {
  api: [httpRequest, ...],
  database: [databaseQuery, ...],
  ...
}
```

#### 2. 拖拽创建节点
```typescript
// 用户从节点面板拖拽到画布
drag: { nodeTypeId: 'http_request', metadata: NodeTypeMetadata }

// 创建节点实例
node: WorkflowNode = {
  id: 'n1',
  type: 'http_request',
  name: 'Get User',
  position: { x: 100, y: 100 },
  config: {}  // 空配置，等待用户填写
}
```

#### 3. 配置节点
```typescript
// 根据 NodeTypeMetadata.fields 动态生成表单
fields.forEach(field => {
  if (field.supportsFieldMapping) {
    // 显示字段选择器
    // 获取上游节点的 outputSchema
    // 构建字段树供用户选择
  }
})

// 用户选择字段后，生成表达式
config.to = '${nodes.n1.output.body.email}'
```

#### 4. 保存工作流
```typescript
// 将 VueFlowNode 转换为 WorkflowNode
workflow: WorkflowDefinition = {
  id: 'wf_001',
  name: 'HTTP→审批→邮件',
  schemaVersion: '1.0',
  nodes: nodes.map(n => ({
    id: n.id,
    type: n.type,
    name: n.data.name,
    position: n.position,
    config: n.data.config
  })),
  edges: edges.map(e => ({
    source: e.source,
    target: e.target,
    condition: e.condition
  }))
}

// 提交到后端
POST /api/workflows
```

### 技术栈

- **Vue 3**: Composition API
- **Pinia**: 状态管理
- **Vue Flow**: 流程图渲染
- **Ant Design Vue**: UI 组件库
- **TypeScript**: 类型安全

### 目录结构

```
vue-flow-design/
├── components/
│   ├── NodePalette.vue          # 节点面板（左侧）
│   ├── FieldMappingSelector.vue # 字段映射选择器
│   ├── NodeConfigPanel.vue      # 节点配置面板（右侧）
│   └── nodes/
│       ├── BaseNode.vue         # 通用节点组件
│       ├── HttpRequestNode.vue  # 特定节点（可选）
│       └── ...
├── mock/
│   ├── nodeTypes.ts             # Mock 节点类型数据
│   └── workflows.ts             # Mock 工作流数据
├── utils/
│   ├── fieldTree.ts             # 字段树构建工具
│   └── expression.ts            # 表达式解析工具
├── index.vue                    # 主组件
├── ARCHITECTURE.md              # 本文档
└── README.md                    # 使用说明
```

### 关键设计决策

1. **类型定义完全对齐**：前端 TypeScript 类型与后端数据模型一一对应
2. **字段映射表达式生成**：自动生成符合 `${...}` 格式的表达式
3. **动态表单渲染**：基于 `NodeTypeMetadata.fields` 动态生成表单
4. **Schema 验证**：保存时验证 `schemaVersion = '1.0'`
5. **表达式命名空间**：严格遵循 `nodes`、`workflow`、`env` 三种命名空间

### Checklist（前后端对齐要点）

- [x] WorkflowDefinition 使用 schemaVersion 固定为 "1.0"
- [x] WorkflowEdge.condition 必须为完整 ${...} 字符串
- [x] NodeTypeMetadata.id 与 WorkflowNode.type 对齐（如 http_request）
- [x] 字段映射组件输出"完整表达式"字符串（含 ${}）
- [x] 输出结构以 outputSchema 为准
- [x] 前端展示字段树最多展开 3 层（可配置）

### 下一步实现

1. ✅ TypeScript 类型定义
2. ✅ Mock 数据（符合规范）
3. ⏳ Pinia Store 更新（适配新类型）
4. ⏳ 节点面板组件
5. ⏳ 字段映射选择器
6. ⏳ 动态配置面板
7. ⏳ 集成测试

