# 工作流平台前端开发指南 ## 一、项目概述 ### 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 工作流定义管理 ```typescript // 工作流定义相关接口 interface WorkflowDefinitionAPI { // 基础CRUD接口 list: '/api/v1/workflow-definitions' // 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 启用 } // 工作流定义数据结构 interface WorkflowDefinitionDTO { id: number code: string // 工作流编码 name: string // 工作流名称 description: string // 描述 status: 'DRAFT' | 'PUBLISHED' | 'DISABLED' // 状态 version: number // 版本号 nodeConfig: string // 节点配置(JSON) transitionConfig: string // 流转配置(JSON) formDefinition: string // 表单定义 graphDefinition: string // 图形信息 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 // 排序号 } ``` ### 2.2 工作流实例管理 ```typescript // 工作流实例相关接口 interface WorkflowInstanceAPI { // 基础CRUD接口 list: '/api/v1/workflow-instance' // 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 恢复 } // 工作流实例数据结构 interface WorkflowInstanceDTO { id: number definitionId: number // 工作流定义ID businessKey: string // 业务标识 status: 'RUNNING' | 'COMPLETED' | 'FAILED' | 'CANCELLED' | 'PAUSED' // 状态 startTime: string // 开始时间 endTime: string // 结束时间 variables: string // 工作流变量(JSON) error: string // 错误信息 } ``` ### 2.3 节点实例管理 ```typescript // 节点实例相关接口 interface NodeInstanceAPI { // 查询接口 list: '/api/v1/node-instance' // 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 更新状态 } // 节点实例数据结构 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.4 工作流日志管理 ```typescript // 日志相关接口 interface WorkflowLogAPI { // 基础CRUD接口 list: '/api/v1/workflow-logs' // 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 // 创建时间 } ``` ## 三、页面功能 ### 3.1 工作流定义管理(/workflow/definition) #### 3.1.1 列表页(/workflow/definition/list) - 功能点： - 工作流定义列表展示 - 支持按名称、编码、状态搜索 - 支持创建、编辑、删除操作 - 支持发布、禁用操作 - 支持查看历史版本 - 列表字段： - 工作流编码 - 工作流名称 - 版本号 - 状态 - 创建时间 - 更新时间 - 操作按钮 #### 3.1.2 编辑页(/workflow/definition/edit) - 功能点： 1. 基本信息编辑 - 工作流编码 - 工作流名称 - 描述 - 备注 2. 流程设计器 - 节点拖拽 - 连线绘制 - 节点配置 - 流程校验 3. 表单设计器 - 表单字段配置 - 字段验证规则 - 表单预览 4. 节点配置面板 - 节点基本信息 - 节点类型配置 - 执行条件配置 - 表单关联配置 ### 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 ## 四、开发规范 ### 4.1 项目结构 ``` src/ ├── components/ # 公共组件 │ ├── FlowDesigner/ # 流程设计器组件 │ ├── FormDesigner/ # 表单设计器组件 │ └── NodeConfig/ # 节点配置组件 ├── pages/ # 页面组件 │ └── workflow/ # 工作流相关页面 ├── services/ # API服务 │ └── workflow/ # 工作流相关API ├── models/ # 数据模型 ├── utils/ # 工具函数 ├── constants/ # 常量定义 ├── types/ # TypeScript类型 └── locales/ # 国际化资源 ``` ### 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 ``` 2. 安装依赖 ```bash yarn add @ant-design/pro-components @logicflow/core @logicflow/extension form-render echarts ``` ### 5.2 开发步骤 1. 搭建基础框架和路由(2天) 2. 实现工作流定义CRUD(3天) 3. 开发流程设计器(5天) 4. 开发表单设计器(3天) 5. 实现工作流实例管理(3天) 6. 实现节点实例管理(2天) 7. 实现日志管理(2天) 8. 开发监控大盘(3天) 9. 测试和优化(2天) ### 5.3 测试要求 1. 单元测试覆盖率 > 80% 2. 必须包含组件测试 3. 必须包含集成测试 4. 必须进行性能测试 ### 5.4 部署要求 1. 使用 Docker 部署 2. 配置 Nginx 代理 3. 启用 GZIP 压缩 4. 配置缓存策略 ## 六、注意事项 ### 6.1 性能优化 1. 使用路由懒加载 2. 组件按需加载 3. 大数据列表虚拟化 4. 合理使用缓存 5. 避免不必要的渲染 ### 6.2 安全性 1. 添加权限控制 2. 防止XSS攻击 3. 添加数据验证 4. 敏感信息加密 ### 6.3 用户体验 1. 添加适当的加载状态 2. 提供操作反馈 3. 添加错误处理 4. 支持快捷键操作 5. 添加操作确认 6. 支持数据导出 ### 6.4 兼容性 1. 支持主流浏览器最新版本 2. 支持响应式布局 3. 支持暗黑模式 4. 支持国际化