# workflow

**Repository Path**: sclx/workflow

## Basic Information

- **Project Name**: workflow
- **Description**: 一个面向固定审批链和有限组合审批场景的轻量级工作流组件。项目聚焦流程定义、流程发起、审批流转、驳回重提、撤回、待办/已办查询和审批记录留痕，不内置用户、角色、组织架构和业务表单语义。
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-05
- **Last Updated**: 2026-06-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 简单工作流

一个面向固定审批链和有限组合审批场景的轻量级工作流组件。项目聚焦流程定义、流程发起、审批流转、驳回重提、撤回、待办/已办查询和审批记录留痕，不内置用户、角色、组织架构和业务表单语义。

## 项目定位

本项目适用于业务系统中常见的“提交后由指定候选对象审批”的基础流程场景，例如单据提交、申请审批和业务审核。流程内核负责审批规则执行和状态流转，调用方负责身份体系、候选对象解析、业务参数校验和审批结果消费。

当前支持：

- 流程定义的新建、修改、启用、停用和查询
- 基于已启用定义发起流程实例
- 审批节点内的会签 `ALL`、或签 `ANY` 及组合审批块
- 审批同意、驳回、提交人撤回
- 驳回到发起方后再次提交
- 待办、已办、我发起、流程详情和审批历史查询
- 下一审批节点候选对象预览
- 基于 MyBatis-Plus 的关系型数据库持久化
- Spring Boot Starter 自动装配
- Thymeleaf Demo 页面

当前不支持：

- 流程图建模和自由流
- 条件分支、动态路由和任意节点跳转
- 转办、委托、加签、减签、抄送、催办
- 子块顺序执行和子块独立恢复

## 模块结构

```text
workflow-parent
├── workflow-core                 # 工作流核心模型、命令、查询、服务接口和默认服务实现
├── workflow-infra-mybatis-plus   # MyBatis-Plus 持久化实现、实体、Mapper 和 Repository
├── workflow-spring-boot-starter  # Spring Boot 自动配置，暴露 WorkflowService
├── workflow-demo-app             # 演示应用，包含页面、示例配置和 schema.sql
└── doc                           # 需求说明、功能设计、数据库设计和完成度文档
```

## 技术栈

- Java 8
- Maven 多模块工程
- Spring Boot `2.3.9.RELEASE`
- MyBatis-Plus `3.4.3.4`
- MySQL
- Thymeleaf

## 快速启动 Demo

### 1. 准备数据库

Demo 默认连接 MySQL，并在启动时执行 `workflow-demo-app/src/main/resources/schema.sql`。

建议先创建数据库：

```sql
create database if not exists workflow
  default character set utf8mb4
  default collate utf8mb4_0900_ai_ci;
```

`schema.sql` 使用 `utf8mb4_0900_ai_ci`，推荐使用 MySQL 8.0+。如使用 MySQL 5.7，需要按实际环境调整排序规则。

### 2. 配置连接信息

Demo 通过环境变量读取数据库配置：

```bash
MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_DATABASE=workflow
MYSQL_USERNAME=workflow
MYSQL_PASSWORD=your_password
```

也可以直接修改：

```text
workflow-demo-app/src/main/resources/application.yml
```

### 3. 构建项目

```bash
mvn clean install
```

### 4. 启动 Demo

```bash
mvn -pl workflow-demo-app spring-boot:run
```

启动成功后访问：

```text
http://localhost:8080
```

Demo 首次启动时会初始化一个示例流程定义：

- 流程编码：`DEMO-LEAVE`
- 流程名称：`演示请假流程`
- 发起人示例：`u001`
- 第一审批人：`u002`
- 第二审批人：`u003`

## 接入方式

业务系统引入 Starter：

```xml
<dependency>
    <groupId>com.company.workflow</groupId>
    <artifactId>workflow-spring-boot-starter</artifactId>
    <version>0.0.1-SNAPSHOT</version>
</dependency>
```

Starter 会自动装配：

- `WorkflowService`
- `WorkflowRepository`
- 默认 `WorkflowIdentityProvider`
- 默认固定用户候选对象解析器
- 默认空实现的业务摘要、节点结果和流程结束通知器
- MyBatis Mapper 扫描

业务代码可直接注入 `WorkflowService`：

```java
@Service
public class OrderApprovalService {

    private final WorkflowService workflowService;

    public OrderApprovalService(WorkflowService workflowService) {
        this.workflowService = workflowService;
    }

    public Long startApproval(StartWorkflowCommand command) {
        return workflowService.startWorkflow(command);
    }
}
```

## 核心 API

主要入口为：

```text
com.company.workflow.core.app.service.WorkflowService
```

按职责可分为：

- 流程定义：`createDefinition`、`updateDefinition`、`listDefinitions`、`getDefinitionDetail`、`enableDefinition`、`disableDefinition`
- 流程发起：`startWorkflow`
- 任务查询：`listTodoTasks`、`pageTodoTasks`、`listDoneTasks`、`pageDoneTasks`
- 实例查询：`listInitiatedInstances`、`pageInitiatedInstances`、`getInstanceDetail`
- 审批历史：`listActionLogs`、`pageActionLogs`
- 审批处理：`approveTask`、`rejectTask`
- 发起方操作：`withdrawInstance`、`resubmitInstance`
- 辅助预览：`getNextNodePreview`

## 扩展点

流程内核通过接口隔离调用方能力，业务系统可以按需覆盖默认 Bean。

| 接口 | 用途 |
| --- | --- |
| `WorkflowIdentityProvider` | 定义默认操作主体类型和默认候选对象类型 |
| `ApprovalCandidateResolver` | 将审批块配置解析为实际候选对象 |
| `BusinessSummaryProvider` | 根据业务上下文生成流程和任务展示摘要 |
| `NodeResultNotifier` | 审批节点进入终态后消费节点结果 |
| `WorkflowEndNotifier` | 流程进入终态后消费最终结果 |

默认内置的 `FixedUserApprovalCandidateResolver` 用于固定用户审批场景。更复杂的角色、岗位、部门或外部系统候选对象解析，应由调用方实现 `ApprovalCandidateResolver` 并提供唯一的 `resolverKey`。

## 数据模型概览

数据库模型分为三层：

- 定义层：`wf_definition`、`wf_definition_version`、`wf_definition_node`、`wf_definition_block`
- 运行层：`wf_instance`、`wf_instance_round`、`wf_node_instance`、`wf_node_candidate_snapshot`、`wf_node_candidate_item`、`wf_task`
- 审计层：`wf_action_log`

核心设计约束：

- 流程定义版本化，运行中实例绑定确定版本
- 审批节点是最小状态记录单位
- 审批块只参与候选对象分发和审批结果计算
- 任务处理和节点状态变更通过乐观锁保证并发一致性
- 提交、审批、驳回、撤回、再次提交和自动关闭均记录审计日志

更完整的表结构说明见：

```text
doc/数据库设计.md
```

## 常用命令

构建全部模块：

```bash
mvn clean install
```

仅构建核心模块及其依赖：

```bash
mvn -pl workflow-core -am clean install
```

启动 Demo：

```bash
mvn -pl workflow-demo-app spring-boot:run
```

打包 Demo：

```bash
mvn -pl workflow-demo-app -am clean package
```

运行打包后的 Demo：

```bash
java -jar workflow-demo-app/target/workflow-demo-app-0.0.1-SNAPSHOT.jar
```

## 文档

项目设计文档位于 `doc` 目录：

- `doc/需求说明.md`
- `doc/功能设计.md`
- `doc/数据库设计.md`
- `doc/开发计划.md`
- `doc/完成度对照表.md`

## 设计原则

本项目保持工作流内核职责单一：

- 内核只处理流程定义、审批规则、状态流转和审计记录
- 用户、角色、组织、权限和业务字段语义由调用方负责
- 持久化实现通过 `WorkflowRepository` 与核心服务解耦
- Spring Boot Starter 只负责装配默认实现，业务方可通过自定义 Bean 替换扩展点