deploy-ease-platform/backend/docs/frontend-guide.md

工作流平台前端开发指南

一、项目概述

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 工作流定义管理

// 工作流定义相关接口
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 工作流实例管理

// 工作流实例相关接口
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 节点实例管理

// 节点实例相关接口
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 工作流日志管理

// 日志相关接口
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. 创建项目

yarn create umi

2. 安装依赖

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. 支持国际化