工作流模块

概述

工作流模块提供完整的流程引擎能力，支持可视化流程设计、多种节点类型、审批人解析、条件分支、并行处理、子流程、超时处理等功能。

模块路径：backend-fastapi/core/workflow/

API 前缀：/api/core/workflow

数据模型

WorkflowDefinition（流程定义）

python

class WorkflowDefinition(BaseModel):
    __tablename__ = "core_workflow_definition"

    application_id: str     # 所属应用 ID
    name: str               # 流程名称
    code: str               # 流程编码
    workflow_type: str      # 流程类型
    icon: str               # 图标
    icon_bg_color: str      # 图标背景色
    category: str           # 分类
    description: str        # 描述
    status: str             # 状态
    version: int            # 版本号
    form_code: str          # 关联表单编码
    form_name: str          # 关联表单名称
    flow_definition: dict   # 流程定义（JSONB）

WorkflowInstance（流程实例）

python

class WorkflowInstance(BaseModel):
    __tablename__ = "core_workflow_instance"

    workflow_id: str        # 流程定义 ID
    instance_no: str        # 实例编号
    title: str              # 流程标题
    status: str             # 状态
    initiator_id: str       # 发起人 ID
    form_code: str          # 表单编码
    form_data_id: str       # 表单数据 ID
    current_node_id: str    # 当前节点 ID
    current_node_name: str  # 当前节点名称
    started_at: datetime    # 开始时间
    completed_at: datetime  # 完成时间
    parallel_branch_status: dict  # 并行分支状态
    parent_instance_id: str # 父实例 ID（子流程）
    parent_node_id: str     # 父节点 ID
    is_subflow: bool        # 是否子流程
    delay_node_id: str      # 延时节点 ID
    delay_until: datetime   # 延时到期时间

WorkflowTask（任务）

python

class WorkflowTask(BaseModel):
    __tablename__ = "core_workflow_task"

    instance_id: str        # 实例 ID
    node_id: str            # 节点 ID
    node_name: str          # 节点名称
    task_type: str          # 任务类型
    status: str             # 状态
    assignee_id: str        # 处理人 ID
    comment: str            # 处理意见
    handled_at: datetime    # 处理时间
    transferred_to_id: str  # 转交目标人
    parent_task_id: str     # 父任务 ID（加签）
    sign_type: str          # 加签类型
    timeout_at: datetime    # 超时时间
    timeout_action: str     # 超时动作
    timeout_notified: bool  # 是否已通知超时

WorkflowLog（操作日志）

python

class WorkflowLog(BaseModel):
    __tablename__ = "core_workflow_log"

    instance_id: str        # 实例 ID
    node_id: str            # 节点 ID
    node_name: str          # 节点名称
    action: str             # 操作类型
    operator_id: str        # 操作人 ID
    comment: str            # 操作意见
    extra_data: dict        # 额外数据

状态枚举

流程定义状态

值	说明
`draft`	草稿
`published`	已发布
`disabled`	已停用

实例状态

值	说明
`pending`	进行中
`approved`	已通过
`rejected`	已拒绝
`canceled`	已取消

任务类型

值	说明
`approval`	审批
`handle`	办理
`copy`	抄送
`revise`	修订

任务状态

值	说明
`pending`	待处理
`waiting`	等待中
`approved`	已同意
`rejected`	已拒绝
`returned`	已驳回
`transferred`	已转交
`delegated`	已委托
`handled`	已办理
`canceled`	已取消
`read`	已阅

流程引擎

WorkflowEngine

核心引擎类，提供以下方法：

方法	说明
`start(db, definition, form_data, user_id)`	发起流程
`complete_task(db, task, action, comment)`	完成任务
`transfer_task(db, task, to_user_id)`	转交任务
`restart_instance(db, instance)`	重新提交（驳回后）

内部方法

方法	说明
`_advance_to_next(ctx, node)`	推进到下一节点
`_end_instance(ctx, status)`	结束实例
`_handle_return(ctx, task, return_to)`	处理驳回
`_resume_parent_after_subflow(ctx)`	子流程完成后恢复父流程

节点处理器

处理器	节点类型	说明
`ApprovalHandler`	approval	审批节点
`HandleHandler`	handle	办理节点
`CopyHandler`	copy	抄送节点
`ConditionHandler`	condition	条件分支
`ParallelHandler`	parallel	并行分支
`DelayNodeHandler`	delay	延时节点
`NotifyHandler`	notify	通知节点
`ServiceHandler`	service	HTTP 服务调用
`SubflowHandler`	subflow	子流程

审批人解析器

AssigneeResolver 支持以下审批人类型：

类型	说明
`user`	指定用户
`role`	指定角色
`department`	指定部门
`superior`	直属上级
`manager`	部门负责人
`initiator`	发起人
`form_field`	表单字段

条件求值器

ConditionEvaluator 支持以下操作符：

操作符	说明
`eq`	等于
`ne`	不等于
`gt`	大于
`gte`	大于等于
`lt`	小于
`lte`	小于等于
`contains`	包含
`not_contains`	不包含
`in`	在列表中
`not_in`	不在列表中
`empty`	为空
`not_empty`	不为空

多人审批模式

模式	说明
`any`	任一人通过即可
`parallel`	所有人同时审批
`sequential`	依次审批

服务层

WorkflowDefinitionService

方法	说明
`get_list(db, page, page_size, filters)`	获取流程列表
`get_by_id(db, id)`	获取流程详情
`get_by_code(db, code)`	根据编码获取
`create(db, data)`	创建流程
`update(db, id, data)`	更新流程
`delete(db, id)`	删除流程
`publish(db, id)`	发布流程
`disable(db, id)`	停用流程
`copy(db, id)`	复制流程
`get_categories(db)`	获取分类列表

WorkflowInstanceService

方法	说明
`start(db, definition_id, form_data, user_id)`	发起流程
`get_list(db, page, page_size, filters)`	获取实例列表
`get_by_id(db, id)`	获取实例详情
`cancel(db, id, user_id)`	取消流程
`urge(db, id, user_id)`	催办

WorkflowTaskService

方法	说明
`get_pending_tasks(db, user_id, page, page_size)`	获取待办任务
`get_pending_count(db, user_id)`	获取待办数量
`get_handled_tasks(db, user_id, page, page_size)`	获取已办任务
`get_copy_tasks(db, user_id, page, page_size)`	获取抄送任务
`approve(db, task_id, action, comment)`	审批
`handle(db, task_id, comment)`	办理
`transfer(db, task_id, to_user_id)`	转交
`delegate(db, task_id, to_user_id)`	委托
`add_sign(db, task_id, sign_type, to_user_ids)`	加签
`mark_read(db, task_id)`	标记已阅
`revise(db, task_id, form_data)`	修订

API 接口

流程定义

方法	路径	说明
GET	`/list`	获取流程列表
GET	`/categories`	获取分类
GET	`/available-forms`	获取可用表单
GET	`/by-form/{form_code}`	根据表单获取流程
GET	`/code/{code}`	根据编码获取
GET	`/{id}`	获取详情
POST	`/`	创建流程
PUT	`/{id}`	更新流程
DELETE	`/{id}`	删除流程
DELETE	`/batch/delete`	批量删除
POST	`/{id}/publish`	发布
POST	`/{id}/disable`	停用
POST	`/{id}/copy`	复制

流程实例

方法	路径	说明
POST	`/instance/start`	发起流程
GET	`/instance/list`	获取实例列表
GET	`/instance/my-initiated`	我发起的
GET	`/instance/{id}`	获取详情
POST	`/instance/{id}/cancel`	取消
POST	`/instance/{id}/urge`	催办
GET	`/instance/{id}/logs`	获取日志
GET	`/instance/{id}/pending-tasks`	获取待办任务
GET	`/instance/{id}/form-data`	获取表单数据
GET	`/instance/{id}/progress`	获取流程进度

任务

方法	路径	说明
GET	`/task/pending`	我的待办
GET	`/task/pending/count`	待办数量
GET	`/task/handled`	我的已办
GET	`/task/cc`	抄送我的
GET	`/task/{id}`	任务详情
POST	`/task/{id}/approve`	审批
POST	`/task/{id}/handle`	办理
POST	`/task/{id}/transfer`	转交
POST	`/task/{id}/delegate`	委托
POST	`/task/{id}/add-sign`	加签
POST	`/task/{id}/read`	标记已阅
POST	`/task/{id}/revise`	修订

管理员

方法	路径	说明
POST	`/admin/check-timeouts`	检查超时任务
GET	`/admin/timeout-tasks`	获取超时任务

流程定义结构

流程定义采用树形 JSON 结构：

json

{
  "id": "start_1",
  "type": "start",
  "name": "开始",
  "children": [
    {
      "id": "approval_1",
      "type": "approval",
      "name": "部门审批",
      "config": {
        "assignees": [...],
        "multiApproval": "any",
        "emptyAssignee": "skip",
        "timeout": {
          "enabled": true,
          "duration": 24,
          "unit": "hour",
          "action": "auto_approve"
        },
        "formPermissions": [...]
      },
      "children": [...]
    }
  ]
}

节点配置

字段	说明
`assignees`	审批人配置
`multiApproval`	多人审批模式
`emptyAssignee`	无审批人时处理（skip/admin）
`timeout`	超时配置
`formPermissions`	表单字段权限
`conditions`	条件配置（条件节点）
`duration/unit`	延时配置（延时节点）

请求/响应示例

发起流程

请求：

json

POST /api/core/workflow/instance/start
{
  "workflow_id": "wf001",
  "title": "请假申请-张三",
  "form_data": {
    "leave_type": "annual",
    "start_date": "2024-01-15",
    "end_date": "2024-01-17",
    "reason": "年假"
  }
}

审批任务

请求：

json

POST /api/core/workflow/task/{task_id}/approve
{
  "action": "approve",
  "comment": "同意",
  "form_data": null
}

获取流程进度

响应：

json

{
  "nodes": [
    {
      "id": "start_1",
      "name": "开始",
      "status": "completed",
      "handlers": [
        {"user_id": "u001", "name": "张三", "handled_at": "..."}
      ]
    },
    {
      "id": "approval_1",
      "name": "部门审批",
      "status": "active",
      "handlers": [
        {"user_id": "u002", "name": "李四", "status": "pending"}
      ]
    }
  ],
  "returns": []
}

与其他模块的关系

表单模块：流程关联表单（form_code），表单数据存储在表单数据表
用户模块：审批人解析依赖用户、部门、角色信息
通知模块：任务创建/完成时发送通知
调度模块：延时节点和超时处理依赖定时任务

工作流模块 ​

概述 ​

数据模型 ​

WorkflowDefinition（流程定义） ​

WorkflowInstance（流程实例） ​

WorkflowTask（任务） ​

WorkflowLog（操作日志） ​

状态枚举 ​

流程定义状态 ​

实例状态 ​

任务类型 ​

任务状态 ​

流程引擎 ​

WorkflowEngine ​

内部方法 ​

节点处理器 ​

审批人解析器 ​

条件求值器 ​

多人审批模式 ​

服务层 ​

WorkflowDefinitionService ​

WorkflowInstanceService ​

WorkflowTaskService ​

API 接口 ​

流程定义 ​

流程实例 ​

任务 ​

管理员 ​

流程定义结构 ​

节点配置 ​

请求/响应示例 ​

发起流程 ​

审批任务 ​

获取流程进度 ​

与其他模块的关系 ​

工作流模块

概述

数据模型

WorkflowDefinition（流程定义）

WorkflowInstance（流程实例）

WorkflowTask（任务）

WorkflowLog（操作日志）

状态枚举

流程定义状态

实例状态

任务类型

任务状态

流程引擎

WorkflowEngine

内部方法

节点处理器

审批人解析器

条件求值器

多人审批模式

服务层

WorkflowDefinitionService

WorkflowInstanceService

WorkflowTaskService

API 接口

流程定义

流程实例

任务

管理员

流程定义结构

节点配置

请求/响应示例

发起流程

审批任务

获取流程进度

与其他模块的关系