513 lines
14 KiB
Markdown
513 lines
14 KiB
Markdown
# 工作流平台前端开发指南
|
||
|
||
## 一、项目概述
|
||
|
||
### 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接口
|
||
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 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<T> {
|
||
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 // 排序号
|
||
}
|
||
|
||
// 节点配置示例
|
||
interface NodeConfig {
|
||
startNode: {
|
||
type: 'START'
|
||
name: string
|
||
}
|
||
endNode: {
|
||
type: 'END'
|
||
name: string
|
||
}
|
||
taskNodes: Array<{
|
||
id: string
|
||
type: 'TASK'
|
||
name: string
|
||
executor?: string // 执行器类型
|
||
config?: any // 执行器配置
|
||
}>
|
||
}
|
||
|
||
// 流转配置示例
|
||
interface TransitionConfig {
|
||
transitions: Array<{
|
||
from: string // 源节点ID
|
||
to: string // 目标节点ID
|
||
condition?: string // 流转条件
|
||
}>
|
||
}
|
||
|
||
// 表单定义示例
|
||
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 // 连线属性
|
||
}>
|
||
}
|
||
|
||
// 节点类型数据结构
|
||
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 工作流实例管理
|
||
```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 恢复
|
||
}
|
||
|
||
// 工作流实例数据结构
|
||
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 {
|
||
// 查询接口
|
||
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 更新状态
|
||
}
|
||
|
||
// 节点实例数据结构
|
||
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接口
|
||
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 // 创建时间
|
||
}
|
||
```
|
||
|
||
## 三、页面功能
|
||
|
||
### 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
|
||
|
||
## 四、开发规范
|
||
|
||
### 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: 构建过程或辅助工具的变动
|