# 数据模型设计（JSON Schema，前后端统一）

版本: v1.0  
规范: JSON Schema Draft-07  
命名约定: camelCase；所有 ID 均为字符串；时间统一 ISO 8601（UTC）。

一、WorkflowDefinition（工作流定义）
- 描述：前端编辑器生成/后端持久化与部署的核心数据结构
- 说明：MVP 仅支持串行/条件分支；并行/子流程等后续引入

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://example.com/schemas/workflow-definition.json",
  "title": "WorkflowDefinition",
  "type": "object",
  "required": ["id", "name", "nodes", "edges", "schemaVersion"],
  "properties": {
    "id": { "type": "string", "minLength": 1 },
    "name": { "type": "string", "minLength": 1 },
    "description": { "type": "string" },
    "schemaVersion": { "type": "string", "enum": ["1.0"] },
    "nodes": {
      "type": "array",
      "minItems": 1,
      "items": { "$ref": "#/$defs/workflowNode" }
    },
    "edges": {
      "type": "array",
      "items": { "$ref": "#/$defs/workflowEdge" }
    },
    "variables": { "type": "object", "additionalProperties": true },
    "metadata": { "type": "object", "additionalProperties": true }
  },
  "$defs": {
    "position": {
      "type": "object",
      "required": ["x", "y"],
      "properties": {
        "x": { "type": "number" },
        "y": { "type": "number" }
      }
    },
    "workflowNode": {
      "type": "object",
      "required": ["id", "type", "name", "position", "config"],
      "properties": {
        "id": { "type": "string", "minLength": 1 },
        "type": { "type": "string", "minLength": 1 },  
        "name": { "type": "string", "minLength": 1 },
        "position": { "$ref": "#/$defs/position" },
        "config": { "type": "object", "additionalProperties": true }
      }
    },
    "workflowEdge": {
      "type": "object",
      "required": ["source", "target"],
      "properties": {
        "id": { "type": "string" },
        "source": { "type": "string", "minLength": 1 },
        "target": { "type": "string", "minLength": 1 },
        "condition": { "type": "string", "pattern": "^\\$\\{.*\\}$" }  
      }
    }
  }
}
```

示例（最小可用工作流）
```json
{
  "id": "wf_001",
  "name": "HTTP→审批→邮件",
  "schemaVersion": "1.0",
  "nodes": [
    {"id": "n1", "type": "http_request", "name": "Get User", "position": {"x": 100, "y": 100}, "config": {"url": "https://api.example.com/users/1", "method": "GET"}},
    {"id": "n2", "type": "approval", "name": "审批", "position": {"x": 320, "y": 100}, "config": {"assignee": "${workflow.input.approver}", "formFields": [{"id": "approved", "label": "同意?", "type": "boolean", "required": true}]}},
    {"id": "n3", "type": "send_mail", "name": "通知", "position": {"x": 540, "y": 100}, "config": {"to": "${nodes.n1.output.body.email}", "subject": "审批已通过", "content": "Hello"}}
  ],
  "edges": [
    {"source": "n1", "target": "n2"},
    {"source": "n2", "target": "n3", "condition": "${approved == true}"}
  ],
  "variables": {"env": "dev"}
}
```

二、NodeTypeMetadata（节点类型元数据）
- 描述：驱动前端动态表单、字段映射、帮助用户理解节点输入/输出
- 约束：id 唯一、fields 与 outputSchema 必填

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://example.com/schemas/node-type-metadata.json",
  "title": "NodeTypeMetadata",
  "type": "object",
  "required": ["id", "name", "displayName", "category", "fields", "outputSchema"],
  "properties": {
    "id": { "type": "string", "minLength": 1 },        
    "name": { "type": "string", "minLength": 1 },      
    "displayName": { "type": "string" },
    "category": { "type": "string", "enum": ["api", "database", "logic", "notification", "transform", "other"] },
    "icon": { "type": "string" },
    "description": { "type": "string" },
    "fields": {
      "type": "array",
      "minItems": 1,
      "items": { "$ref": "#/$defs/fieldDefinition" }
    },
    "outputSchema": { "type": "object" },
    "implementationClass": { "type": "string" },
    "enabled": { "type": "boolean", "default": true }
  },
  "$defs": {
    "fieldDefinition": {
      "type": "object",
      "required": ["name", "label", "type"],
      "properties": {
        "name": { "type": "string" },
        "label": { "type": "string" },
        "type": { "type": "string", "enum": ["text", "textarea", "number", "select", "code", "key_value", "boolean"] },
        "required": { "type": "boolean", "default": false },
        "supportsExpression": { "type": "boolean", "default": false },
        "supportsFieldMapping": { "type": "boolean", "default": false },
        "options": { "type": "array", "items": {"type": "string"} },
        "defaultValue": {},
        "placeholder": { "type": "string" },
        "language": { "type": "string" }  
      }
    }
  }
}
```

示例（HTTP Request 节点）
```json
{
  "id": "http_request",
  "name": "httpRequest",
  "displayName": "HTTP Request",
  "category": "api",
  "icon": "ApiOutlined",
  "description": "发送 HTTP 请求",
  "fields": [
    {"name": "url", "label": "URL", "type": "text", "required": true, "supportsExpression": true},
    {"name": "method", "label": "Method", "type": "select", "options": ["GET", "POST", "PUT", "DELETE", "PATCH"], "defaultValue": "GET"},
    {"name": "headers", "label": "Headers", "type": "key_value", "supportsFieldMapping": true},
    {"name": "body", "label": "Body", "type": "code", "language": "json", "supportsExpression": true},
    {"name": "timeout", "label": "Timeout(ms)", "type": "number", "defaultValue": 30000}
  ],
  "outputSchema": {
    "type": "object",
    "properties": {
      "statusCode": {"type": "number"},
      "body": {"type": "object"},
      "headers": {"type": "object"},
      "elapsed": {"type": "number"}
    }
  }
}
```

三、表达式（JUEL）约定
- 统一使用 ${...}
- 可访问命名空间：
  - nodes：上游节点数据，如 ${nodes.n1.output.body.email}
  - workflow：输入/变量，如 ${workflow.input.userId}
  - env：环境变量，如 ${env.API_KEY}
- 仅 Map/属性访问；不允许方法/类引用；支持三元表达式

四、执行与日志数据（后端输出/存储）
- NodeExecutionResult（内存/接口响应中的片段）
```json
{
  "status": "success",
  "output": {"statusCode": 200, "body": {"id": 1}},
  "error": null,
  "startTime": "2025-01-01T10:00:00Z",
  "endTime": "2025-01-01T10:00:10Z",
  "durationMs": 10
}
```
- 节点执行日志表（node_execution_logs）建议结构（与 docs/02 一致）：
  - execution_id、node_id、node_type、input(JSON)、output(JSON)、status、started_at、ended_at、duration_ms、error_message

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