工作流机制

本文说明 art-design-pro-server 中工作流模块的核心结构。它适合在理解审批中心、调整流程字段、排查审批状态流转或扩展工作流接口时阅读。

模块入口

工作流模块位于 src/modules/workflow，主要分为 4 类控制器：

控制器	路径	说明
`workflow-categories.controller.ts`	`/api/v1/workflows/categories`	流程分类管理
`workflow-definitions.controller.ts`	`/api/v1/workflows/definitions`	流程定义、表单字段、审批节点和启停状态
`workflow-instances.controller.ts`	`/api/v1/workflows/instances`	流程发起、实例列表、实例详情和撤销
`workflow-tasks.controller.ts`	`/api/v1/workflows/tasks`	待办、已办、审批通过和驳回

核心业务逻辑位于 src/modules/workflow/services：

Service	说明
`workflow-definition.service.ts`	流程定义的创建、复制、编辑、启停、选项和概览
`workflow-instance.service.ts`	流程实例的发起、查询、详情和撤销
`workflow-task.service.ts`	当前账号待办、已办、任务详情和审批动作
`workflow-approval.engine.ts`	审批状态机、节点推进、审批任务创建
`workflow-validation.service.ts`	表单字段、审批节点和定义数据校验

核心概念

概念	说明
流程分类	用于给流程定义分组，便于页面筛选和管理
流程定义	描述一个流程的基础信息、表单字段和审批节点
表单字段	定义发起流程时需要填写的字段结构
审批节点	定义每一阶段的审批人类型、审批人列表和审批模式
流程实例	用户基于某个流程定义发起后的运行中或已结束记录
审批任务	分配给具体审批人的待办或已办记录
流转记录	记录系统推进、审批通过、驳回、撤销等动作

interfaces/workflow.interfaces.ts 中定义了表单字段、审批节点、定义详情、实例详情和任务列表等类型，适合先读。

定义到实例的转换

工作流不是每次都直接读取最新定义执行，而是在发起实例时保存必要快照。这样可以避免流程定义后续被修改时，影响已经发起的流程。

mermaid

flowchart TD
  A["流程定义"] --> B["表单字段配置"]
  A --> C["审批节点配置"]
  B --> D["发起流程实例"]
  C --> D
  D --> E["保存字段值和节点快照"]
  E --> F["创建第一阶段审批任务"]

理解这点很重要：修改流程定义通常只影响之后新发起的流程，不应直接假设会改变历史实例的执行路径。

审批状态机

审批动作由 WorkflowApprovalEngine 统一处理。通过和驳回都会先校验当前任务是否属于当前账号，并且任务状态必须为待处理。

主要流程如下：

mermaid

flowchart TD
  A["审批人提交通过或驳回"] --> B["校验任务归属和状态"]
  B --> C["更新当前任务状态"]
  C --> D["写入审批记录"]
  D --> E{"是否驳回"}
  E -- "是" --> F["取消同节点待处理任务"]
  F --> G["实例标记为 REJECTED"]
  E -- "否" --> H{"当前节点审批模式"}
  H -- "ANY" --> I["取消同节点其他待处理任务"]
  I --> J["推进到下一节点"]
  H -- "ALL" --> K{"是否还有待处理任务"}
  K -- "有" --> L["更新当前任务数量"]
  K -- "没有" --> J
  J --> M{"是否存在下一节点"}
  M -- "有" --> N["创建下一节点任务"]
  M -- "没有" --> O["实例标记为 APPROVED"]

审批模式需要重点关注：

模式	行为
`ANY`	同一节点任意一人通过即可推进，其他待处理任务会被取消
`ALL`	同一节点所有审批任务都通过后才推进

无论哪种模式，只要当前节点出现驳回，实例都会进入驳回状态，并取消同节点未处理任务。

权限与操作日志

工作流接口统一使用 JwtGuard 和 @ApiPermission 声明权限码。涉及新增、编辑、状态变更、复制、删除、发起、撤销、审批通过和驳回的接口，会通过 @OperationLog 写入操作日志。

新增工作流相关接口时，需要同步确认：

控制器是否声明 @UseGuards(JwtGuard) 或继承所在类的守卫。
接口是否补充对应 API_PERMISSION_CODES.WORKFLOW 权限码。
有操作含义的写接口是否添加 @OperationLog。
前端 ApiPermissionCode.WORKFLOW 是否同步对应权限码。
角色权限预设是否需要纳入新权限。

调整流程字段时的注意事项

工作流表单字段由后端保存结构化配置，前端根据字段类型渲染。调整字段类型或新增字段能力时，需要同时看：

位置	说明
`interfaces/workflow.interfaces.ts`	字段配置结构
`dto/create-workflow-definition.dto.ts`	创建定义时的字段校验
`dto/update-workflow-definition.dto.ts`	更新定义时的字段校验
`workflow-validation.service.ts`	字段和节点规则校验
`art-design-pro-ui/src/views/workflow/components/workflow-form-renderer.vue`	前端字段渲染

如果只是新增某个流程定义中的字段，不需要改代码；如果要新增字段类型，才需要同时调整前后端类型、校验和渲染逻辑。

常见问题

已发起的流程没有按最新定义走

优先确认该流程是否在定义修改前已经发起。已发起实例会保留发起时的字段和节点快照，通常不会被后续定义编辑影响。

审批人看不到待办

检查节点审批人配置是否包含当前账号，实例是否已经推进到对应节点，以及任务状态是否仍是 PENDING。

一个人审批通过后，其他人的待办消失

检查当前节点是否使用 ANY 审批模式。该模式下任意一人通过后，同节点其他待办会被取消。

驳回后流程直接结束

当前审批引擎的行为是：任一节点驳回后，实例进入 REJECTED 状态，并取消同节点未处理任务。

工作流机制 ​

模块入口 ​

核心概念 ​

定义到实例的转换 ​

审批状态机 ​

权限与操作日志 ​

调整流程字段时的注意事项 ​

常见问题 ​

已发起的流程没有按最新定义走 ​

审批人看不到待办 ​

一个人审批通过后，其他人的待办消失 ​

驳回后流程直接结束 ​

相关阅读 ​