From 5b8a8a14829fee185be9deab5c20772cc2ad3ba3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=9A=E8=BE=B0=E5=85=88=E7=94=9F?= Date: Thu, 5 Dec 2024 15:25:08 +0800 Subject: [PATCH] =?UTF-8?q?=E5=A2=9E=E5=8A=A0=E5=B7=A5=E4=BD=9C=E6=B5=81?= =?UTF-8?q?=E4=BB=A3=E7=A0=81=E5=8F=AF=E6=AD=A3=E5=B8=B8=E5=90=AF=E5=8A=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- backend/docs/frontend-guide.md | 1438 ++++++++++++++++++-------------- 1 file changed, 823 insertions(+), 615 deletions(-) diff --git a/backend/docs/frontend-guide.md b/backend/docs/frontend-guide.md index 3998c972..07c46ca7 100644 --- a/backend/docs/frontend-guide.md +++ b/backend/docs/frontend-guide.md @@ -1,661 +1,869 @@ -# 工作流平台前端开发指南 +# 工作流前端对接文档 -## 一、项目概述 +## 一、系统架构 -### 1.1 技术栈 -- 框架：Ant Design Pro -- 语言：TypeScript -- HTTP请求：Umi Request -- 流程设计器：LogicFlow -- 表单设计器：FormRender -- 图表库：ECharts - -### 1.2 开发环境 -- Node.js >= 16 -- yarn >= 1.22 -- TypeScript >= 4.x - -## 二、接口定义 - -### 2.1 工作流定义管理 +### 1.1 整体架构 ```typescript -// 工作流定义相关接口 -interface WorkflowDefinitionAPI { - // 基础CRUD接口 - page: '/api/v1/workflow-definitions/page' // GET 分页查询，支持条件筛选 - list: '/api/v1/workflow-definitions/list' // GET 查询所有（不分页） - create: '/api/v1/workflow-definitions' // POST 创建 - update: '/api/v1/workflow-definitions/{id}' // PUT 更新 - delete: '/api/v1/workflow-definitions/{id}' // DELETE 删除 - get: '/api/v1/workflow-definitions/{id}' // GET 获取详情 - - // 特殊操作接口 - publish: '/api/v1/workflow-definitions/{id}/publish' // POST 发布 - disable: '/api/v1/workflow-definitions/{id}/disable' // POST 禁用 - enable: '/api/v1/workflow-definitions/{id}/enable' // POST 启用 - versions: '/api/v1/workflow-definitions/{code}/versions' // GET 查询所有版本（不分页） +// 系统分层 +interface SystemArchitecture { + presentation: { + views: '页面组件', // 负责页面展示和用户交互 + components: '通用组件', // 可复用的UI组件 + hooks: '业务钩子', // 封装业务逻辑的Hooks + }; + domain: { + models: '数据模型', // 核心业务模型定义 + services: '领域服务', // 业务逻辑封装 + stores: '状态管理', // 全局状态管理 + }; + infrastructure: { + api: 'API封装', // 后端接口调用 + utils: '工具函数', // 通用工具方法 + constants: '常量定义', // 系统常量 + }; +} +``` + +### 1.2 核心模块 +1. **工作流设计器** + - 负责工作流的可视化设计 + - 节点拖拽和连线 + - 属性配置面板 + - 数据验证和保存 + +2. **表单设计器** + - 工作流表单的可视化设计 + - 字段配置和验证规则 + - 布局设计 + - 表单预览 + +3. **工作流引擎** + - 工作流实例管理 + - 节点状态控制 + - 变量管理 + - 日志记录 + +## 二、数据模型 + +### 2.1 工作流定义 +```typescript +interface WorkflowDefinition { + // 基本信息 + id: number; // 工作流定义ID + code: string; // 工作流编码（唯一标识） + name: string; // 工作流名称 + description: string; // 工作流描述 + version: number; // 版本号 + status: WorkflowStatus; // 状态（DRAFT/PUBLISHED/DISABLED） + enabled: boolean; // 是否启用 + + // 节点定义 + nodes: Array<{ + id: number; // 节点定义ID + nodeId: string; // 节点标识（在图中的唯一标识） + name: string; // 节点名称 + type: NodeType; // 节点类型（START/END/TASK/GATEWAY） + config: string; // 节点配置（JSON字符串） + description: string; // 节点描述 + orderNum: number; // 排序号 + }>; + + // 配置数据 + nodeConfig: string; // 节点关系配置（JSON字符串） + transitionConfig: string; // 流转配置（JSON字符串） + formDefinition: string; // 表单定义（JSON字符串） + graphDefinition: string; // 图形布局（JSON字符串） } -// 节点类型相关接口 -interface NodeTypeAPI { - // 查询接口 - list: '/api/v1/node-types' // GET 获取所有可用的节点类型列表（不分页） - getExecutors: '/api/v1/node-types/{type}/executors' // GET 获取指定节点类型支持的执行器列表 -} - -// 分页请求参数 -interface PageQuery { - pageNum: number // 页码，从1开始 - pageSize: number // 每页大小 - sortField?: string // 排序字段 - sortOrder?: 'ascend' | 'descend' // 排序方向 -} - -// 分页响应结构 -interface PageResponse { - records: T[] // 数据列表 - total: number // 总记录数 - pages: number // 总页数 - pageNum: number // 当前页码 - pageSize: number // 每页大小 -} - -// 工作流定义数据结构 -interface WorkflowDefinitionDTO { - id: number - code: string // 工作流编码 - name: string // 工作流名称 - description: string // 描述 - status: 'DRAFT' | 'PUBLISHED' | 'DISABLED' // 状态 - version: number // 版本号 - nodeConfig: string // 节点配置(JSON)，包含节点的基本信息和执行配置 - transitionConfig: string // 流转配置(JSON)，定义节点间的连接和条件 - formDefinition: string // 表单定义(JSON)，定义工作流的表单字段和验证规则 - graphDefinition: string // 图形信息(JSON)，定义节点的位置和连线的样式 - enabled: boolean // 是否启用 - remark: string // 备注 - nodes: NodeDefinitionDTO[] // 节点定义列表 -} - -// 节点定义数据结构 -interface NodeDefinitionDTO { - id: number - nodeId: string // 节点ID - name: string // 节点名称 - type: 'START' | 'END' | 'TASK' | 'GATEWAY' | 'SUB_PROCESS' | 'SHELL' // 节点类型 - config: string // 节点配置(JSON) - description: string // 节点描述 - workflowDefinitionId: number // 工作流定义ID - orderNum: number // 排序号 -} - -// 节点配置示例 +// 节点配置示例（JSON格式） interface NodeConfig { - startNode: { - type: 'START' - name: string - } - endNode: { - type: 'END' - name: string - } - taskNodes: Array<{ - id: string - type: 'TASK' - name: string - executor?: string // 执行器类型 - config?: any // 执行器配置 - }> + // 开始节点配置 + startNode: { + type: 'START'; + name: string; + config?: Record; + }; + + // 任务节点配置 + taskNodes: Array<{ + id: string; + type: 'TASK'; + name: string; + executor?: string; // 执行器类型 + config: { + // Shell执行器配置 + script?: string; // 脚本内容 + timeout?: number; // 超时时间 + workingDir?: string; // 工作目录 + + // Jenkins执行器配置 + jenkinsJob?: string; // Jenkins任务名 + parameters?: Record; // 构建参数 + }; + }>; + + // 网关节点配置 + gatewayNodes: Array<{ + id: string; + type: 'GATEWAY'; + name: string; + gatewayType: 'EXCLUSIVE' | 'PARALLEL' | 'INCLUSIVE'; // 网关类型 + conditions?: Array<{ + expression: string; // 条件表达式 + description: string; // 条件描述 + }>; + }>; + + // 结束节点配置 + endNode: { + type: 'END'; + name: string; + config?: Record; + }; } // 流转配置示例 interface TransitionConfig { - transitions: Array<{ - from: string // 源节点ID - to: string // 目标节点ID - condition?: string // 流转条件 - }> + transitions: Array<{ + from: string; // 源节点ID + to: string; // 目标节点ID + condition?: string; // 流转条件（网关节点使用） + priority?: number; // 优先级（条件分支使用） + }>; } -// 表单定义示例 -interface FormDefinition { - fields: Array<{ - name: string // 字段名 - label: string // 字段标签 - type: 'input' | 'select' | 'date' | 'number' // 字段类型 - required?: boolean // 是否必填 - options?: Array<{ // 选项（用于select类型） - label: string - value: any - }> - rules?: Array<{ // 验证规则 - type: string - message: string - }> - }> -} - -// 图形定义示例 +// 图形布局示例 interface GraphDefinition { - nodes: Array<{ - id: string - type: string - x: number // 节点X坐标 - y: number // 节点Y坐标 - properties?: any // 节点属性 - }> - edges: Array<{ - source: string // 源节点ID - target: string // 目标节点ID - properties?: any // 连线属性 - }> + nodes: Array<{ + id: string; // 节点ID + type: string; // 节点类型 + x: number; // X坐标 + y: number; // Y坐标 + properties?: { // 节点属性 + width?: number; + height?: number; + color?: string; + icon?: string; + }; + }>; + edges: Array<{ + source: string; // 源节点ID + target: string; // 目标节点ID + points?: Array<{ // 连线控制点 + x: number; + y: number; + }>; + properties?: { // 连线属性 + style?: string; + arrow?: string; + label?: string; + }; + }>; } - -// 节点类型数据结构 -interface NodeTypeDTO { - code: string // 节点类型编码 - name: string // 节点类型名称 - description: string // 节点类型描述 - category: 'BASIC' | 'TASK' | 'GATEWAY' | 'EVENT' // 节点类型分类 - icon: string // 节点图标 - color: string // 节点颜色 - executors?: Array<{ // 支持的执行器列表 - code: string // 执行器编码 - name: string // 执行器名称 - description: string // 执行器描述 - configSchema: any // 执行器配置模式 - }> - configSchema?: any // 节点配置模式 - defaultConfig?: any // 默认配置 -} - -// 节点类型示例数据 -const nodeTypes = [ - { - code: 'START', - name: '开始节点', - description: '工作流的开始节点', - category: 'BASIC', - icon: 'play-circle', - color: '#52c41a' - }, - { - code: 'END', - name: '结束节点', - description: '工作流的结束节点', - category: 'BASIC', - icon: 'stop', - color: '#ff4d4f' - }, - { - code: 'TASK', - name: '任务节点', - description: '执行具体任务的节点', - category: 'TASK', - icon: 'code', - color: '#1890ff', - executors: [ - { - code: 'SHELL', - name: 'Shell脚本', - description: '执行Shell脚本', - configSchema: { - type: 'object', - properties: { - script: { - type: 'string', - title: '脚本内容', - format: 'shell' - }, - timeout: { - type: 'number', - title: '超时时间(秒)', - default: 300 - } - } - } - }, - { - code: 'JENKINS', - name: 'Jenkins任务', - description: '触发Jenkins构建任务', - configSchema: { - type: 'object', - properties: { - job: { - type: 'string', - title: 'Job名称' - }, - parameters: { - type: 'object', - title: '构建参数' - } - } - } - } - ] - }, - { - code: 'GATEWAY', - name: '网关节点', - description: '控制流程流转的节点', - category: 'GATEWAY', - icon: 'fork', - color: '#faad14', - configSchema: { - type: 'object', - properties: { - type: { - type: 'string', - title: '网关类型', - enum: ['PARALLEL', 'EXCLUSIVE', 'INCLUSIVE'], - enumNames: ['并行网关', '排他网关', '包容网关'] - } - } - } - } -]; ``` -### 2.2 工作流实例管理 +### 2.2 工作流实例 +```typescript +interface WorkflowInstance { + id: number; // 实例ID + definitionId: number; // 工作流定义ID + businessKey: string; // 业务标识 + status: InstanceStatus; // 状态 + startTime: string; // 开始时间 + endTime: string; // 结束时间 + variables: string; // 工作流变量（JSON字符串） + error: string; // 错误信息 +} + +interface NodeInstance { + id: number; // 实例ID + workflowInstanceId: number; // 工作流实例ID + nodeId: string; // 节点ID + nodeType: NodeType; // 节点类型 + status: NodeStatus; // 节点状态 + startTime: string; // 开始时间 + endTime: string; // 结束时间 + input: string; // 输入参数（JSON字符串） + output: string; // 输出结果（JSON字符串） + error: string; // 错误信息 +} +``` + +## 三、接口定义 + +### 3.1 工作流定义接口 +```typescript +interface WorkflowDefinitionAPI { + // 基础CRUD + create: { + url: '/api/v1/workflow-definitions', + method: 'POST', + data: WorkflowDefinitionDTO, + response: Response + }; + + update: { + url: '/api/v1/workflow-definitions/{id}', + method: 'PUT', + data: WorkflowDefinitionDTO, + response: Response + }; + + delete: { + url: '/api/v1/workflow-definitions/{id}', + method: 'DELETE', + response: Response + }; + + getById: { + url: '/api/v1/workflow-definitions/{id}', + method: 'GET', + response: Response + }; + + page: { + url: '/api/v1/workflow-definitions/page', + method: 'GET', + params: PageQuery, + response: Response> + }; + + // 特殊操作 + publish: { + url: '/api/v1/workflow-definitions/{id}/publish', + method: 'POST', + response: Response + }; + + disable: { + url: '/api/v1/workflow-definitions/{id}/disable', + method: 'POST', + response: Response + }; + + enable: { + url: '/api/v1/workflow-definitions/{id}/enable', + method: 'POST', + response: Response + }; +} +``` + +### 3.2 工作流实例接口 ```typescript -// 工作流实例相关接口 interface WorkflowInstanceAPI { - // 基础CRUD接口 - page: '/api/v1/workflow-instance/page' // GET 分页查询，支持条件筛选 - list: '/api/v1/workflow-instance/list' // GET 查询所有（不分页） - get: '/api/v1/workflow-instance/{id}' // GET 获取详情 - - // 实例操作接口 - create: '/api/v1/workflow-instance' // POST 创建实例 - start: '/api/v1/workflow-instance/{id}/start' // POST 启动 - cancel: '/api/v1/workflow-instance/{id}/cancel' // POST 取消 - pause: '/api/v1/workflow-instance/{id}/pause' // POST 暂停 - resume: '/api/v1/workflow-instance/{id}/resume' // POST 恢复 -} + // 实例操作 + start: { + url: '/api/v1/workflow-instances/start', + method: 'POST', + data: { + workflowCode: string; // 工作流编码 + businessKey: string; // 业务标识 + variables?: Record; // 工作流变量 + }, + response: Response + }; + + terminate: { + url: '/api/v1/workflow-instances/{id}/terminate', + method: 'POST', + data: { + reason?: string; // 终止原因 + }, + response: Response + }; + + pause: { + url: '/api/v1/workflow-instances/{id}/pause', + method: 'POST', + response: Response + }; + + resume: { + url: '/api/v1/workflow-instances/{id}/resume', + method: 'POST', + response: Response + }; -// 工作流实例数据结构 -interface WorkflowInstanceDTO { - id: number - definitionId: number // 工作流定义ID - businessKey: string // 业务标识 - status: 'RUNNING' | 'COMPLETED' | 'FAILED' | 'CANCELLED' | 'PAUSED' // 状态 - startTime: string // 开始时间 - endTime: string // 结束时间 - variables: string // 工作流变量(JSON) - error: string // 错误信息 + // 查询接口 + getById: { + url: '/api/v1/workflow-instances/{id}', + method: 'GET', + response: Response + }; + + page: { + url: '/api/v1/workflow-instances/page', + method: 'GET', + params: PageQuery & { + status?: InstanceStatus; + startTime?: string; + endTime?: string; + keyword?: string; + }, + response: Response> + }; } ``` -### 2.3 节点实例管理 +## 四、组件设计 + +### 4.1 工作流设计器 ```typescript -// 节点实例相关接口 -interface NodeInstanceAPI { - // 查询接口 - page: '/api/v1/node-instance/page' // GET 分页查询，支持条件筛选 - list: '/api/v1/node-instance/list' // GET 查询所有（不分页） - get: '/api/v1/node-instance/{id}' // GET 获取详情 - findByWorkflow: '/api/v1/node-instance/workflow/{workflowInstanceId}' // GET 查询工作流下的节点（不分页） - findByStatus: '/api/v1/node-instance/workflow/{workflowInstanceId}/status/{status}' // GET 查询指定状态的节点（不分页） - - // 节点操作 - updateStatus: '/api/v1/node-instance/{id}/status' // PUT 更新状态 +// 1. 设计器组件 +interface WorkflowDesigner { + // 属性定义 + props: { + value?: WorkflowDefinition; // 工作流定义数据 + readOnly?: boolean; // 是否只读 + onChange?: (value: WorkflowDefinition) => void; // 数据变更回调 + }; + + // 子组件 + components: { + ToolBar: '工具栏', // 撤销、重做、缩放等操作 + NodePanel: '节点面板', // 可用节点列表 + Canvas: '画布', // 节点拖拽和连线 + ConfigPanel: '配置面板', // 节点和连线配置 + MiniMap: '小地图' // 导航缩略图 + }; + + // 核心方法 + methods: { + // 初始化设计器 + initialize(definition: WorkflowDefinition): void; + + // 添加节点 + addNode(nodeData: NodeData): void; + + // 连接节点 + connect(source: string, target: string): void; + + // 更新节点配置 + updateNodeConfig(nodeId: string, config: any): void; + + // 更新连线配置 + updateEdgeConfig(edgeId: string, config: any): void; + + // 验证数据 + validate(): ValidationResult; + + // 导出数据 + exportData(): WorkflowDefinition; + }; } -// 节点实例数据结构 -interface NodeInstanceDTO { - id: number - workflowInstanceId: number // 工作流实例ID - nodeId: string // 节点ID - nodeType: 'START' | 'END' | 'TASK' | 'GATEWAY' | 'SUB_PROCESS' | 'SHELL' // 节点类型 - name: string // 节点名称 - status: 'PENDING' | 'RUNNING' | 'COMPLETED' | 'FAILED' | 'CANCELLED' | 'PAUSED' | 'SKIPPED' // 状态 - startTime: string // 开始时间 - endTime: string // 结束时间 - config: string // 节点配置(JSON) - input: string // 输入参数(JSON) - output: string // 输出结果(JSON) - error: string // 错误信息 - preNodeId: string // 前置节点ID +// 2. 节点配置面板 +interface NodeConfigPanel { + props: { + node: NodeData; // 节点数据 + nodeType: NodeType; // 节点类型 + onChange: (config: any) => void; // 配置变更回调 + }; + + // 配置表单定义 + forms: { + // 基础配置（所有节点都有） + BaseConfig: { + name: string; // 节点名称 + description?: string; // 节点描述 + }; + + // 任务节点配置 + TaskConfig: { + executor: string; // 执行器类型 + config: Record; // 执行器配置 + }; + + // 网关节点配置 + GatewayConfig: { + type: 'EXCLUSIVE' | 'PARALLEL' | 'INCLUSIVE'; + conditions?: Array<{ + expression: string; + description: string; + }>; + }; + }; +} + +// 3. 连线配置面板 +interface EdgeConfigPanel { + props: { + edge: EdgeData; // 连线数据 + sourceNode: NodeData; // 源节点 + targetNode: NodeData; // 目标节点 + onChange: (config: any) => void; // 配置变更回调 + }; + + // 配置表单定义 + forms: { + condition?: string; // 流转条件 + priority?: number; // 优先级 + description?: string; // 说明 + }; } ``` -### 2.4 工作流日志管理 +### 4.2 表单设计器 ```typescript -// 日志相关接口 -interface WorkflowLogAPI { - // 基础CRUD接口 - page: '/api/v1/workflow-logs/page' // GET 分页查询，支持条件筛选 - list: '/api/v1/workflow-logs/list' // GET 查询所有（不分页） - create: '/api/v1/workflow-logs' // POST 创建 - - // 特殊查询接口 - getWorkflowLogs: '/api/v1/workflow-logs/workflow/{workflowInstanceId}' // GET 查询工作流日志（不分页） - getNodeLogs: '/api/v1/workflow-logs/node/{workflowInstanceId}/{nodeId}' // GET 查询节点日志（不分页） - record: '/api/v1/workflow-logs/record' // POST 记录日志 -} - -// 日志数据结构 -interface WorkflowLogDTO { - id: number - workflowInstanceId: number // 工作流实例ID - nodeId: string // 节点ID - message: string // 日志内容 - level: 'INFO' | 'WARN' | 'ERROR' // 日志级别 - detail: string // 详细信息 - createTime: string // 创建时间 +interface FormDesigner { + props: { + value?: FormDefinition; // 表单定义数据 + onChange?: (value: FormDefinition) => void; // 数据变更回调 + }; + + // 可用的字段类型 + fieldTypes: { + input: '单行文本', + textarea: '多行文本', + number: '数字', + select: '下拉选择', + radio: '单选', + checkbox: '多选', + date: '日期', + datetime: '日期时间', + file: '文件上传' + }; + + // 字段属性定义 + fieldProperties: { + name: string; // 字段名 + label: string; // 字段标签 + type: string; // 字段类型 + required?: boolean; // 是否必填 + defaultValue?: any; // 默认值 + placeholder?: string; // 占位提示 + description?: string; // 字段描述 + options?: Array<{ // 选项（用于select/radio/checkbox） + label: string; + value: any; + }>; + validation?: Array<{ // 验证规则 + type: string; // 规则类型 + message: string; // 错误消息 + params?: any; // 规则参数 + }>; + }; } ``` -## 三、页面功能 +## 五、状态管理 -### 3.1 工作流定义管理(/workflow/definition) - -#### 3.1.1 列表页(/workflow/definition/list) -- 功能点： - - 工作流定义列表展示 - - 支持按名称、编码、状态搜索 - - 支持创建、编辑、删除操作 - - 支持发布、禁用操作 - - 支持查看历史版本 -- 列表字段： - - 工作流编码 - - 工作流名称 - - 版本号 - - 状态 - - 创建时间 - - 更新时间 - - 操作按钮 - -#### 3.1.2 编辑页(/workflow/definition/edit) -- 功能点： - 1. 基本信息编辑 - - 工作流编码 - - 工作流名称 - - 描述 - - 备注 - 2. 流程设计器 - - 节点拖拽和布局 - - 连线绘制和调整 - - 节点配置（nodeConfig） - - 基本信息配置 - - 执行器类型选择 - - 执行器参数配置 - - 流转配置（transitionConfig） - - 连线条件配置 - - 优先级设置 - - 条件表达式编辑 - - 流程校验 - 3. 表单设计器（formDefinition） - - 表单字段配置 - - 字段类型选择 - - 字段属性设置 - - 选项配置（针对select类型） - - 字段验证规则 - - 必填验证 - - 格式验证 - - 自定义验证 - - 表单布局设计 - - 表单预览 - 4. 图形布局（graphDefinition） - - 节点位置调整 - - 连线样式设置 - - 自动布局 - - 缩放和居中 - 5. 版本管理 - - 版本历史查看 - - 版本对比 - - 版本回滚 - - 创建新版本 - -### 3.2 工作流实例管理(/workflow/instance) - -#### 3.2.1 列表页(/workflow/instance/list) -- 功能点： - - 工作流实例列表展示 - - 支持按工作流名称、状态、时间搜索 - - 支持启动、暂停、恢复、取消操作 -- 列表字段： - - 实例ID - - 工作流名称 - - 业务标识 - - 状态 - - 开始时间 - - 结束时间 - - 操作按钮 - -#### 3.2.2 详情页(/workflow/instance/detail) -- 功能点： - 1. 基本信息展示 - - 实例ID - - 工作流名称 - - 状态 - - 时间信息 - 2. 流程图展示 - - 显示当前节点 - - 节点状态标识 - - 流程进度展示 - 3. 变量信息 - - 变量列表 - - 变量历史值 - 4. 日志信息 - - 操作日志 - - 执行日志 - - 错误日志 - -### 3.3 监控大盘(/workflow/monitor) -- 功能点： - 1. 统计信息 - - 总工作流数 - - 运行中实例数 - - 完成实例数 - - 失败实例数 - 2. 状态分布 - - 饼图展示各状态占比 - - 支持时间范围筛选 - 3. 执行时长统计 - - 平均执行时长 - - 最长执行时长 - - 执行时长分布 - 4. 异常情况统计 - - 异常类型分布 - - 异常趋势图 - - 异常节点TOP5 - -### 3.4 节点类型管理(/workflow/node-type) - -#### 3.4.1 列表页(/workflow/node-type/list) -- 功能点： - - 节点类型列表展示 - - 支持按编码、名称、分类搜索 - - 支持创建、编辑、删除操作 - - 支持启用、禁用操作 -- 列表字段： - - 节点类型编码 - - 节点类型名称 - - 分类 - - 图标 - - 状态 - - 创建时间 - - 更新时间 - - 操作按钮 - -#### 3.4.2 编辑页(/workflow/node-type/edit) -- 功能点： - 1. 基本信息编辑 - - 节点类型编码 - - 节点类型名称 - - 描述 - - 分类 - - 图标 - - 颜色 - 2. 执行器配置 - - 执行器列表管理 - - 添加/删除执行器 - - 配置执行器参数 - - 执行器配置模式定义 - - JSON Schema编辑器 - - 配置项验证规则 - 3. 节点配置 - - 配置模式定义 - - 默认配置设置 - - 配置预览 - -### 3.5 组件升级 -1. NodeTypePanel（节点类型面板） - ```typescript - interface NodeTypePanelProps { - value?: NodeTypeDTO // 节点类型数据 - onChange?: (value: NodeTypeDTO) => void // 数据变更回调 - readOnly?: boolean // 是否只读 - } - ``` - -2. ExecutorConfig（执行器配置） - ```typescript - interface ExecutorConfigProps { - executors: Array<{ - code: string - name: string - description: string - configSchema: any - }> // 执行器列表 - onChange?: (executors: any[]) => void // 配置变更回调 - } - ``` - -3. SchemaEditor（配置模式编辑器） - ```typescript - interface SchemaEditorProps { - value?: any // 配置模式数据 - onChange?: (value: any) => void // 数据变更回调 - onValidate?: (errors: any[]) => void // 验证回调 - } - ``` - -### 3.6 开发计划调整 -1. 节点类型管理开发（3天） - - 实现节点类型CRUD接口 - - 开发节点类型列表页面 - - 开发节点类型编辑页面 - - 实现执行器配置功能 - - 实现配置模式编辑器 - -2. 流程设计器升级（2天） - - 改造节点面板，支持从节点类型创建节点 - - 实现节点配置面板，支持动态表单 - - 添加执行器选择功能 - -## 四、开发规范 - -### 4.1 项目结构 -``` -src/ - ├── components/ # 公共组件 - │ ├── FlowDesigner/ # 流程设计器组件 - │ ├── FormDesigner/ # 表单设计器组件 - │ └── NodeConfig/ # 节点配置组件 - ├── pages/ # 页面组件 - │ └── workflow/ # 工作流相关页面 - ├── services/ # API服务 - │ └── workflow/ # 工作流相关API - ├── models/ # 数据模型 - ├── utils/ # 工具函数 - ├── constants/ # 常量定义 - ├── types/ # TypeScript类型 - └── locales/ # 国际化资源 +### 5.1 工作流设计器状态 +```typescript +interface DesignerState { + // 画布状态 + canvas: { + scale: number; // 缩放比例 + position: { // 画布位置 + x: number; + y: number; + }; + selectedElements: { // 选中的元素 + nodes: string[]; // 节点ID列表 + edges: string[]; // 连线ID列表 + }; + }; + + // 历史记录 + history: { + undoStack: HistoryItem[]; // 撤销栈 + redoStack: HistoryItem[]; // 重做栈 + canUndo: boolean; // 是否可撤销 + canRedo: boolean; // 是否可重做 + }; + + // 节点数据 + nodes: Record; // 节点数据映射 + edges: Record; // 连线数据映射 + + // 配置面板 + configPanel: { + visible: boolean; // 是否显示 + type: 'node' | 'edge'; // 配置类型 + elementId?: string; // 当前配置的元素ID + }; +} ``` -### 4.2 命名规范 -- 文件命名：使用 PascalCase - - 组件文件：`FlowDesigner.tsx` - - 类型文件：`WorkflowTypes.ts` - - 工具文件：`FlowUtils.ts` -- 变量命名：使用 camelCase - - 普通变量：`flowInstance` - - 布尔值：`isRunning`、`hasError` -- 常量命名：使用 UPPER_CASE - - `MAX_NODE_COUNT` - - `DEFAULT_CONFIG` - -### 4.3 组件开发规范 -1. 使用函数组件和 Hooks -2. 使用 TypeScript 类型声明 -3. 添加必要的注释 -4. 实现错误处理 -5. 添加加载状态 -6. 做好性能优化 - -### 4.4 代码提交规范 -- feat: 新功能 -- fix: 修复bug -- docs: 文档更新 -- style: 代码格式 -- refactor: 重构 -- test: 测试 -- chore: 构建过程或辅助工具的变动 - -## 五、开发流程 - -### 5.1 环境搭建 -1. 创建项目 -```bash -yarn create umi +### 5.2 工作流实例状态 +```typescript +interface InstanceState { + // 实例数据 + instance: { + current?: WorkflowInstance; // 当前实例 + nodes: NodeInstance[]; // 节点实例列表 + variables: Record; // 工作流变量 + }; + + // 操作权限 + permissions: { + canTerminate: boolean; // 是否可终止 + canPause: boolean; // 是否可暂停 + canResume: boolean; // 是否可恢复 + }; + + // 日志数据 + logs: { + workflow: WorkflowLog[]; // 工作流日志 + nodes: Record; // 节点日志 + }; +} ``` -2. 安装依赖 -```bash -yarn add @ant-design/pro-components @logicflow/core @logicflow/extension form-render echarts +## 六、工作流设计器使用示例 + +### 6.1 基础使用 +```typescript +// 1. 创建工作流 +const createWorkflow = async (definition: WorkflowDefinition) => { + try { + // 验证数据 + const validationResult = workflowDesigner.validate(); + if (!validationResult.valid) { + message.error('工作流数据验证失败：' + validationResult.errors.join(', ')); + return; + } + + // 提交数据 + const response = await WorkflowDefinitionAPI.create(definition); + if (response.code === 200) { + message.success('工作流创建成功'); + return response.data; + } else { + message.error('工作流创建失败：' + response.message); + } + } catch (error) { + message.error('系统错误：' + error.message); + } +}; + +// 2. 加载工作流 +const loadWorkflow = async (id: number) => { + try { + const response = await WorkflowDefinitionAPI.getById(id); + if (response.code === 200) { + // 初始化设计器 + workflowDesigner.initialize(response.data); + return response.data; + } else { + message.error('加载工作流失败：' + response.message); + } + } catch (error) { + message.error('系统错误：' + error.message); + } +}; + +// 3. 保存工作流 +const saveWorkflow = async (id: number) => { + try { + // 获取设计器数据 + const definition = workflowDesigner.exportData(); + + // 验证数据 + const validationResult = workflowDesigner.validate(); + if (!validationResult.valid) { + message.error('工作流数据验证失败：' + validationResult.errors.join(', ')); + return; + } + + // 提交数据 + const response = await WorkflowDefinitionAPI.update(id, definition); + if (response.code === 200) { + message.success('工作流保存成功'); + return response.data; + } else { + message.error('工作流保存失败：' + response.message); + } + } catch (error) { + message.error('系统错误：' + error.message); + } +}; ``` -### 5.2 开发步骤 -1. 搭建基础框架和路由(2天) -2. 实现工作流定义CRUD(3天) -3. 开发流程设计器(5天) -4. 开发表单设计器(3天) -5. 实现工作流实例管理(3天) -6. 实现节点实例管理(2天) -7. 实现日志管理(2天) -8. 开发监控大盘(3天) -9. 测试和优化(2天) +### 6.2 节点配置示例 +```typescript +// 1. Shell节点配置 +const ShellNodeConfig = { + type: 'TASK', + name: 'Shell脚本', + executor: 'SHELL', + config: { + script: '#!/bin/bash\necho "Hello World"', + timeout: 300, + workingDir: '/tmp' + } +}; -### 5.3 测试要求 -1. 单元测试覆盖率 > 80% -2. 必须包含组件测试 -3. 必须包含集成测试 -4. 必须进行性能测试 +// 2. Jenkins节点配置 +const JenkinsNodeConfig = { + type: 'TASK', + name: 'Jenkins构建', + executor: 'JENKINS', + config: { + jenkinsJob: 'my-project-build', + parameters: { + BRANCH: 'master', + ENV: 'prod' + } + } +}; -### 5.4 部署要求 -1. 使用 Docker 部署 -2. 配置 Nginx 代理 -3. 启用 GZIP 压缩 -4. 配置缓存策略 +// 3. 网关节点配置 +const GatewayNodeConfig = { + type: 'GATEWAY', + name: '条件分支', + gatewayType: 'EXCLUSIVE', + conditions: [ + { + expression: '${status} == "SUCCESS"', + description: '执行成功' + }, + { + expression: '${status} == "FAILED"', + description: '执行失败' + } + ] +}; +``` -## 六、注意事项 +### 6.3 数据验证示例 +```typescript +// 1. 节点配置验证 +const validateNodeConfig = (node: NodeData): ValidationResult => { + const errors: string[] = []; + + // 基础验证 + if (!node.name) { + errors.push('节点名称不能为空'); + } + + // 任务节点特殊验证 + if (node.type === 'TASK') { + if (!node.executor) { + errors.push('请选择执行器'); + } + + // Shell执行器验证 + if (node.executor === 'SHELL') { + if (!node.config.script) { + errors.push('脚本内容不能为空'); + } + } + + // Jenkins执行器验证 + if (node.executor === 'JENKINS') { + if (!node.config.jenkinsJob) { + errors.push('Jenkins任务名不能为空'); + } + } + } + + // 网关节点特殊验证 + if (node.type === 'GATEWAY') { + if (!node.gatewayType) { + errors.push('请选择网关类型'); + } + if (node.gatewayType === 'EXCLUSIVE' && (!node.conditions || node.conditions.length === 0)) { + errors.push('请配置分支条件'); + } + } + + return { + valid: errors.length === 0, + errors + }; +}; -### 6.1 性能优化 -1. 使用路由懒加载 -2. 组件按需加载 -3. 大数据列表虚拟化 -4. 合理使用缓存 -5. 避免不必要的渲染 +// 2. 流程验证 +const validateWorkflow = (definition: WorkflowDefinition): ValidationResult => { + const errors: string[] = []; + + // 1. 基础信息验证 + if (!definition.name) { + errors.push('工作流名称不能为空'); + } + if (!definition.code) { + errors.push('工作流编码不能为空'); + } + + // 2. 节点验证 + const nodes = JSON.parse(definition.nodeConfig); + + // 验证开始节点 + if (!nodes.startNode) { + errors.push('必须有一个开始节点'); + } + + // 验证结束节点 + if (!nodes.endNode) { + errors.push('必须有一个结束节点'); + } + + // 验证任务节点 + if (!nodes.taskNodes || nodes.taskNodes.length === 0) { + errors.push('至少需要一个任务节点'); + } + + // 3. 连线验证 + const transitions = JSON.parse(definition.transitionConfig).transitions; + + // 验证是否有孤立节点 + const connectedNodes = new Set(); + transitions.forEach(t => { + connectedNodes.add(t.from); + connectedNodes.add(t.to); + }); + + const allNodes = [ + nodes.startNode, + ...nodes.taskNodes, + ...(nodes.gatewayNodes || []), + nodes.endNode + ]; + + allNodes.forEach(node => { + if (!connectedNodes.has(node.id)) { + errors.push(`节点 ${node.name}(${node.id}) 未连接`); + } + }); + + // 4. 验证是否有环 + if (hasCircle(transitions)) { + errors.push('流程中存在循环'); + } + + return { + valid: errors.length === 0, + errors + }; +}; +``` -### 6.2 安全性 -1. 添加权限控制 -2. 防止XSS攻击 -3. 添加数据验证 -4. 敏感信息加密 +## 七、最佳实践 -### 6.3 用户体验 -1. 添加适当的加载状态 -2. 提供操作反馈 -3. 添加错误处理 -4. 支持快捷键操作 -5. 添加操作确认 -6. 支持数据导出 +### 7.1 性能优化 +1. **大数据量处理** + - 使用虚拟滚动 + - 分页加载数据 + - 按需渲染节点 -### 6.4 兼容性 -1. 支持主流浏览器最新版本 -2. 支持响应式布局 -3. 支持暗黑模式 -4. 支持国际化 \ No newline at end of file +2. **状态管理** + - 合理使用缓存 + - 避免频繁更新 + - 使用不可变数据 + +3. **渲染优化** + - 组件懒加载 + - 合理使用memo + - 避免不必要的重渲染 + +### 7.2 错误处理 +1. **前端验证** + - 实时验证 + - 提供错误提示 + - 防止无效操作 + +2. **异常捕获** + - 全局错误处理 + - 友好的错误提示 + - 错误日志记录 + +3. **数据恢复** + - 自动保存 + - 本地缓存 + - 操作回滚 + +### 7.3 用户体验 +1. **交互设计** + - 拖拽操作流畅 + - 实时预览效果 + - 快捷键支持 + +2. **反馈机制** + - 操作提示 + - 加载状态 + - 成功/失败反馈 + +3. **辅助功能** + - 自动布局 + - 查找/替换 + - 导入/导出 + +## 八、常见问题 + +### 8.1 配置相关 +1. **节点配置问题** + - Q: 如何处理不同类型节点的配置？ + - A: 使用统一的配置接口，通过类型区分不同的配置表单 + +2. **数据同步问题** + - Q: 如何保持前端展示数据与后端数据一致？ + - A: 实现定期自动保存和加载机制 + +3. **验证问题** + - Q: 如何确保工作流数据的正确性？ + - A: 实现多层次的验证机制，包括实时验证和提交验证 + +### 8.2 性能相关 +1. **大型工作流** + - Q: 如何处理节点数量很多的工作流？ + - A: 实现分区渲染和虚拟滚动 + +2. **频繁操作** + - Q: 如何处理频繁的拖拽和连线操作？ + - A: 使用节流和防抖优化性能 + +3. **数据量大** + - Q: 如何处理大量的历史数据？ + - A: 实现分页加载和懒加载机制 + +## 九、开发规范 + +### 9.1 代码规范 +1. **命名规范** + - 组件使用大驼峰命名 + - 方法使用小驼峰命名 + - 常量使用大写下划线 + +2. **注释规范** + - 组件必须有文档注释 + - 复杂逻辑需要注释 + - 保持注释的及时更新 + +3. **类型规范** + - 使用TypeScript + - 定义清晰的接口 + - 避免any类型 + +### 9.2 提交规范 +1. **提交信息** + - feat: 新功能 + - fix: 修复bug + - docs: 文档更新 + - style: 代码格式 + - refactor: 重构 + - test: 测试 + - chore: 构建过程或辅助工具的变动 + +2. **分支管理** + - master: 主分支 + - develop: 开发分支 + - feature: 功能分支 + - hotfix: 紧急修复分支 + +### 9.3 测试规范 +1. **单元测试** + - 组件测试 + - 方法测试 + - 工具函数测试 + +2. **集成测试** + - 流程测试 + - 接口测试 + - 兼容性测试 + +3. **E2E测试** + - 用户操作测试 + - 场景测试 + - 性能测试 \ No newline at end of file