193 lines
7.0 KiB
Markdown
193 lines
7.0 KiB
Markdown
# 数据模型设计（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 层（可配置）
|