# flowable-jet **Repository Path**: bitcarton/flowable-jet ## Basic Information - **Project Name**: flowable-jet - **Description**: a flowable jet - **Primary Language**: Java - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2026-10-20 - **Last Updated**: 2026-11-15 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # flowable-jet > **跑示例工程 / 公网部署请看 [docs/STARTUP.md](docs/STARTUP.md)** —— 三件套(服务端 9040 + 业务端 9770 + 前端 5300)的建表、启动、登录、Nginx 配置和上线前检查都在那里。 基于 **Flowable 7** 的审批流程业务封装。服务端一个 starter 里跑引擎、模型、任务、分组、业务绑定和 REST 接口;客户端一个 starter 负责**可靠地**接收审批状态变更事件。 目标是让接入方不再重写「建模型 → 设计表单 → 部署 → 发起 → 审批 → 通知业务系统」这套样板代码。 ## 特性 - **双端 starter**:服务端 `flowable-jet-spring-boot3-starter`,业务方 `flowable-jet-spring-boot3-client-starter`,两边都自动装配,接入成本是「引一个依赖 + 实现一个接口」。 - **审批事件不丢**(核心):状态变更先落本地消息表,再投递;投递失败按退避策略重投,超过次数进死信;消费端幂等去重。全程可查询、可补偿。 - **模型 / 表单 / 分组 / 业务绑定**:一个流程模型绑定一份 `formJson`(form-create 规则),业务类型绑定一个流程定义版本。 - **审批动作不止通过/驳回**:转办、前加签、发起人撤回、打回到指定节点开箱可用,边界规则(并行分支、加签未回签、伪造目标节点)在服务层拦截。 - **鉴权三件套**:请求头身份透传(`X-User-*`)、数据权限(一条流程只对关系人可见)、服务间 HMAC 签名,三者可独立开关。 - **不侵入事务边界**:`JdbcHelper` 用 `TransactionAwareDataSourceProxy` 包装数据源,调用方加 `@Transactional` 就自动参与,不加则各自提交。 - **前端配套**:`flowable-jet-web`(Vue 3 + Element Plus + bpmn-js),含设计器、审批中心、表单设计。 ## 模块 | 模块 | 说明 | |---|---| | `flowable-jet-common` | `JdbcHelper`(极简 JDBC 封装)、`ParamHelper`、分页结果、Feign 客户端 | | `flowable-jet-core` | 业务核心:模型、任务、配置、分组、消息表。**不依赖 Spring** | | `flowable-jet-spring-boot3-starter` | 服务端自动装配 + 42 个 REST 接口 + 重试扫描任务 + 鉴权过滤器 | | `flowable-jet-spring-boot3-client-starter` | 客户端自动装配:事件接收、死信接收、幂等、回调 SPI | | `flowable-jet-test` / `flowable-jet-test-client` | 服务端 / 客户端示例应用 | 技术栈:Java 17、Spring Boot 3.4.2、Flowable 7.1.0、MySQL 8.0。 ## 架构 ```mermaid flowchart LR subgraph 服务端 R[/flow_jet/**] --> SF[X-App-Id 验签
FlowJetSignFilter] SF --> AF[X-User-* 身份
FlowJetAuthFilter] AF --> B[BizFlowModelService
BizFlowTaskService] A[Flowable 引擎] <--> B B --> C[(biz_flow_business
biz_flow_tasker)] B --> D[(biz_flow_message_log
本地消息表)] B -.数据权限 FlowJetAccessGuard.-> C D --> E{FlowMessageSender} E -->|event-type=kafka| F[[Kafka]] E -->|event-type=default| G[Spring 进程内事件] H[FlowMsgRetryTask
30s 扫描重投] --> D end subgraph 客户端 F --> I[KafkaProcessEventReceiver] I --> J[(幂等表)] I --> K[ApprovalStatusNotify
业务方实现] I -.失败重试耗尽.-> L[[DLT 死信队列]] L --> M[KafkaDeadEventReceiver] M --> N[(biz_flow_dead_letter)] end ``` ## 快速开始 ### 1. 建表 ```bash mysql -uroot -p < sql/flowable-jet.sql ``` 只建 `biz_*` 业务表;Flowable 引擎表(`ACT_*` / `FLW_*`)由引擎首次启动自动创建,**不要手工建**。 ### 2. 引依赖 ```xml com.bitcarton flowable-jet-spring-boot3-starter 1.0.0 ``` ### 3. 配置 ```yaml spring: datasource: url: jdbc:mysql://localhost:3306/flowable_jet?useSSL=false&serverTimezone=UTC username: root password: your-password flowable-jet: web-enabled: true # 是否暴露 /flow_jet/** REST 接口 event-type: kafka # kafka | default(default 走 Feign 直连业务系统) topic: flow_jet_msg ``` ### 4. 注册当前用户(必做) 引擎不知道「谁在操作」,接入方必须提供一个 `Supplier`: ```java @Bean public Supplier currentUser() { return () -> FlowUser.builder().id(120001L).realName("张三").build(); } ``` 未注册该 Bean 且 `auth.enabled=false`(默认)时,接口在**首次取人时**抛 `FlowOaException("未提供当前用户:请注册一个 Supplier 类型的 Bean")` —— 不是启动时抛,读接口同样会触发。接入登录体系后,把它换成「从当前请求上下文取人」即可。若想改用请求头透传,必须**同时**设 `auth.enabled=true`,此时框架自动回退到 `FlowUserContext::get`,可以不注册该 Bean(见 [鉴权](#鉴权));既想保留 Bean 又想用请求头,把 Bean 写成 `return FlowUserContext::get` 即可。 ### 5. 发起第一个流程 ```bash # 建模型 curl -X POST localhost:9040/flow_jet/def/create \ -H 'Content-Type: application/json' \ -d '{"key":"leave","name":"请假流程","category":"人事","isForm":1}' # 取模型(拿 modelId 去设计器画图)—— 注意参数在 URL 上 curl -X POST 'localhost:9040/flow_jet/def/get_flow?modelId=' # 部署(bpmn + svg 必须同时提交,Flowable 不产图) curl -X POST localhost:9040/flow_jet/def/deploy \ -H 'Content-Type: application/json' \ -d '{"modelId":"","bpmn":"","svg":""}' # 可发起的流程列表 curl -X POST localhost:9040/flow_jet/def/oa_list -d '{}' -H 'Content-Type: application/json' ``` ## 接口一览 所有接口统一前缀 `/flow_jet`,**全部是 `POST`**,除标注外参数都在 JSON body 里。标 **Q** 的是 `@RequestParam`,参数必须放 URL —— 塞进 body 会直接 400。共 **42 个**:`/def` 13 + `/task` 19 + `/config` 4 + `/group` 6(客户端 starter 不提供任何 REST 端点)。完整路径 = 分组前缀 + 下表端点名。 **`/flow_jet/def`(13)** | 端点 | 参数 | 作用 | |---|---|---| | `create` | body `BizFlowRequest` | 创建流程模型 | | `get_flow` | **Q** `modelId` | 取模型(含草稿 editor source,给设计器画图) | | `deploy` | body `FlowDeployRequest` | 部署,生成 `ACT_RE_PROCDEF` 新版本 | | `temp_save` | body `FlowDeployRequest` | 暂存草稿,只写 Model 的 editor source,**不部署** | | `createForm` | body `FlowFormRequest` | 创建/保存表单 `formJson` | | `getForm` | **Q** `modelId` | 取表单定义 | | `oa_list` | 无参 | 可发起的流程列表(**当前不过滤未部署模型**,见[已知限制](#已知限制)) | | `flow_def_list` | body `FlowDefRequest` | 流程版本分页 | | `page_flow` | body `BizModelRequest` | 流程管理分页 | | `start_flow` | body `FlowStartRequest` | 发起表单流程 | | `start_biz_flow` | body `FlowBizStartRequest` | 发起业务流程(带 `bizId` / `bizType` / `ccUserIds`) | | `resubmit` | body `ResubmitRequest` | 重新提交(表单流程) | | `biz_resubmit` | body `BizResubmitRequest` | 重新提交(业务流程) | **`/flow_jet/task`(19)** | 端点 | 参数 | 作用 | |---|---|---| | `todo_list` | body `TaskToDoRequest` | 待办(未认领 + 已认领) | | `finished_list` | body | 已办理 | | `start_by_me_list` | body | 我发起的 | | `claim` | **Q** `taskId` | 认领 | | `transfer` | body `TaskTransferRequest` | 转办 | | `cancel` | body `TaskCancelRequest` | 发起人撤回(直接删除流程实例) | | `delegate` | body `TaskAddSignRequest` | 前置加签 | | `urge` | body `TaskUrgeRequest` | 催办(带频控) | | `cc_list` | body `CcListRequest` | 抄送我的(收件箱) | | `cc_unread_count` | 无参 | 抄送未读数 | | `cc_read` | **Q** `ccId` | 标记已读 | | `cc_add` | body `TaskCcRequest` | 发起人补抄送 | | `reject_targets` | **Q** `taskId` | 可打回的目标节点列表 | | `return` | body `TaskReturnRequest` | 打回到指定节点 | | `task_detail` | **Q** `taskId` | 任务详情 | | `approve_detail` | **Q** `processInstanceId` | 审批详情 | | `biz_approve_detail` | **Q** `bizId` | 业务审批详情 | | `trace` | **Q** `taskId` | 流程追踪(时间轴 + 高亮节点) | | `complete` | body `TaskCompleteRequest` | 审批通过 / 驳回 | **`/flow_jet/config`(4)**:`page`(body)、`get_version_list`(body)、`flowConfig`(**Q** `bizType`)、`saveConfig`(body)。 **`/flow_jet/group`(6)**:`page`、`list`、`add`、`add_group_user`、`page_work_group_user`、`search_user`(全部 body;`search_user` 需要接入方提供 `UserFindProvider`,否则抛异常)。 返回统一为 `Rt`:`{ code: 0, data: ... }`。 注意 `code` 与 HTTP 状态码不是一回事:**过滤器层拒绝**(缺身份头、验签失败)直接返回 HTTP 401;**业务层拒绝**(权限不足、状态不允许)由 `FlowJetExceptionHandler` 转成 HTTP 200 + `code=-1` + `msg` 说明。前端判断要看 `code`,别只看状态码。该 advice 目前**默认装配且配置项关不掉**,见[已知限制](#已知限制)。 ## 审批动作 除了 `complete`(通过/驳回),还有四个动作。转办 / 前加签 / 撤回 / 催办的留痕**不写 taskId** —— 动作执行后原任务已销毁或归属已变,写进去会按 `task_id` 抢占流转轨迹的展示槽位。 > 例外:**打回 `returnTask` 的留痕写了 `taskId`**(`BizFlowTaskService.java:685`),与该方法自身 Javadoc「留痕不写 taskId」以及本段旧描述矛盾,属当前实现的历史遗留,详见[已知限制](#已知限制)。 | 动作 | 端点 | 请求体 | 谁能做 | |---|---|---|---| | 转办 | `/task/transfer` | `taskId` `toUserId` `toUserName` `comment` | 当前办理人 | | 前加签 | `/task/delegate` | `taskId` `toUserId` `toUserName` `comment` | 当前办理人 | | 撤回 | `/task/cancel` | `processInstanceId` `reason` | 发起人本人 | | 催办 | `/task/urge` | `processInstanceId` `message` | 发起人本人(同一流程 `urge-interval` 分钟内只允许一次) | | 打回 | `/task/return` | `taskId` `targetActivityId` `comment` | 当前办理人(先调 `/task/reject_targets` 取候选节点) | **催办**只留痕:写一条 `taker_type=2` 的 `biz_flow_tasker`,不改业务状态、不发状态事件;办理人在待办列表通过 `urgeTime` 看到"被催办"标记,发起人在"我发起的"里操作。频控按流程实例查最近催办留痕计算。 **抄送**是知会不是任务:不办理、不阻塞流程、不进待办,只写 `biz_flow_cc`(独立于动作轨迹表 —— 收件箱按 `to_user_id` 查 + 已读状态,和轨迹按实例查是两个方向)。入口两处:发起时请求体带 `ccUserIds`(`start_biz_flow`),或发起人补抄送 `/task/cc_add`;写入自动去重并排除发起人自己。抄送人自动进数据权限关系人(`checkInstanceReadable` 直接放行)。节点级"审批通过自动抄送"依赖流程设计器配置,跟 JSON→BPMN 一起做。 **前加签**用 Flowable 原生 delegation:`delegateTask` 让任务进入 `PENDING`、`assignee` 换成加签人、`owner` 记原办理人;加签人办理时自动 `resolveTask`,任务回到原办理人手上。只做「前」加签 —— 同意后由原办理人收尾,不需要多人会签;需要多人签的应该在流程设计阶段就用会签节点定死。 两个必须自己处理的坑: 1. **`complete` 不校验 `DelegationState`**。加签人点「通过」时 Flowable 会直接推进流程,`owner` 永远等不到回签。所以 `completeTask` 里对 `PENDING` 分支强制走 `resolveTask` 并忽略 `approved`。 2. **`delegateTask` 只在 `owner` 为空时才写 owner**。任务如果转过办,`owner` 还是转办前的人,回签会把任务还给错人。所以代码先显式 `setOwner(taskId, 当前assignee)` 再 delegate。 同一任务加签上限 3 次(`MAX_ADD_SIGN_TIMES`),计数是任务本地变量 `addSignTimes`,转办不换 taskId 所以计数沿用;超过直接拒绝,避免「我加给你、你加给我」无限循环。 **打回**用 `changeActivityStateBuilder().moveActivityIdTo(from, to)`,原子完成「杀掉当前任务 + 在目标节点重新生成待办」,历史全部保留。四个边界: - 目标节点必须是本流程**历史上办结过**的节点,防伪造 `activityId` 凭空跳; - 实例存在多个进行中任务(并行分支、会签进行中)时拒绝 —— `moveActivityIdTo` 只挪一条执行流,会烂; - 任务处于加签 `PENDING` 时拒绝,先回签再谈; - 只有打回到**发起节点**(历史最早办结的节点)才把业务状态置 `5-已退回` 并通知业务系统;打回中间节点对业务侧完全透明。下次审批通过时状态从 `5` 回到 `1`,不会卡死。 ## 可靠事件链路 这是本项目相对「发个 MQ 就完事」的区别所在。 **服务端**(`BizFlowMsgSendService`) 1. 流程状态变更 → 事件 JSON 写入 `biz_flow_message_log`,`status=0`。 2. 立即尝试投递;成功置 `status=1`,失败置 `status=2` 并写入 `next_retry_time`(按重试次数退避)。 3. `FlowMsgRetryTask` 每 `retry-interval` 秒扫描 `status IN (0,2) AND retry_count < retry-count` 的记录重投。注意 `next_retry_time` 字段目前**只写不读**,退避实际上是靠扫描周期的固定间隔,不是按次退避。 **客户端** 1. `KafkaProcessEventReceiver` 收到事件 → 查幂等表去重 → 调业务方实现的 `ApprovalStatusNotify` → ack。 2. 抛异常则走 `DefaultErrorHandler`:按 `FixedBackOff` 重试 `event-dead-count` 次,仍失败投递到 DLT。 3. `KafkaDeadEventReceiver` 把 DLT 消息落 `biz_flow_dead_letter`,供人工补偿/重放。 **上线前必须确认的三件事**(都是实际踩过的坑): 1. **producer 的 `value.serializer` 必须是 JSON**。死信 recoverer 投递的是消费端反序列化后的**对象**,沿用默认 `StringSerializer` 会 `SerializationException`,死信永远发不出去 → 重试耗尽后无限重投。 2. **`biz_flow_dead_letter` 表必须先建**。表不存在时死信消费者抛 `SQLException` 被兜底 catch 吞掉并 ack,死信静默丢失。 3. **`ack-mode: manual` 时主监听器必须自己 `ack.acknowledge()`**。否则 offset 不前进,重启后旧消息重放。 ## 事务 `createModel` / `startFlow` 这类方法内部既有 Flowable 写库,也有 `biz_*` 写库。要它们同生共死: ```java @Service public class YourService { private final BizFlowModelService flowModelService; @Transactional // 事务边界由调用方开 public Boolean createFlow(BizFlowModelRequest req) { return flowModelService.createModel(req); } } ``` `JdbcHelper` 已被 `TransactionAwareDataSourceProxy` 包装:有事务时拿事务连接,无事务时行为和普通 JDBC 一致,core 不需要依赖 Spring。 前提是引擎、事务管理器、`JdbcHelper` 用的是**同一个 `DataSource` Bean**(用 `flowable-spring-boot-starter` 默认满足)。 ## 鉴权 三层各管一件事,**默认全关**,不开和以前完全一样: | 层 | 解决 | 开关 | 实现 | |---|---|---|---| | 身份透传 | 「你是谁」 | `auth.enabled` | `FlowJetAuthFilter`,取 `X-User-Id` 等头塞进 `FlowUserContext` | | 数据权限 | 「你能不能看这条」 | `auth.check-data-permission` | `FlowJetAccessGuard`,六类关系人白名单 | | 服务间签名 | 「调用方是不是可信系统」 | `sign.enabled` | `FlowJetSignFilter`,`X-App-Id` + HMAC-SHA256 | ```yaml flowable-jet: auth: enabled: true check-data-permission: true admin-ids: [1] # 超管白名单,跳过数据权限 # 头名可改,适配已有网关 user-id-header: X-User-Id user-name-header: X-User-Name real-name-header: X-Real-Name tenant-id-header: X-Tenant-Id sign: enabled: true time-window: 300000 # 毫秒,±5 分钟 apps: biz-a: 5f1c9d... # appId → appSecret ``` **身份透传**:`X-User-Id` 必填,其余可选。开启后没有这个头的请求直接 HTTP 401。身份写进 `FlowUserContext`(ThreadLocal),请求结束在 `finally` 里清理 —— 线程池复用线程,不清会串号。 身份来源的优先级只有一条规则:**注册了 `Supplier` Bean 就永远是它说了算**,`auth.enabled` 不会覆盖它。想让请求头生效,就**不要**注册那个 Bean(未注册 + `auth.enabled=true` 时自动回退到 `FlowUserContext`);如果既想保留 Bean 又想用请求头,把 Bean 写成 `return FlowUserContext::get` 即可。 **数据权限**:一条流程只对关系人可见,命中任一即放行 —— 发起人 / `biz_flow_tasker` 留痕办理人 / 当前任务的 assignee 或候选人 / 候选组成员 / 历史 assignee / `admin-ids`。挂在五个读接口上:`task_detail` `approve_detail` `biz_approve_detail` `trace` `reject_targets`。 **服务间签名**:带 `X-App-Id` 的请求必须验签,**不带头的放行**(浏览器走身份透传,服务间走签名,互不干扰)。签名串固定为: ``` appId \n timestamp \n nonce \n METHOD \n path?query \n body ``` 客户端 starter 的 `FlowJetSignInterceptor` 是**无条件注册**的(`FlowJetClientAutoConfiguration.java:70-73`,方法上没有任何 `@ConditionalOnProperty`),填不填 `app-key` / `app-secret` 都会给每个 Feign 请求加上四个头。两个值为空时构造器会用**随机 UUID** 兜底(`FlowJetSignInterceptor.java:22-35`),服务端一旦开了验签就会判「未知接入方」而 401。所以实际规则是: - 服务端 `sign.enabled=true` → 客户端**必须**配对 `app-key` / `app-secret`; - 服务端没开验签 → 这些头不影响调用,但拦截器依然在; - 接入方 classpath 没有 OpenFeign → 这个无条件 Bean 会让应用启动失败(见[已知限制](#已知限制))。 ```yaml flowable-jet-client: app-key: biz-a app-secret: 5f1c9d... ``` 验签通过后请求打上 `FLOW_JET_SIGNED` 标记,身份过滤器见到它时会放行「只有签名、没有用户头」的调用 —— 否则服务间调 Feign 会被 401 挡死。 > 旧版文档写的是「填上 `app-key` 才注册拦截器」,与实现不符,已按代码更正。 三个边界要说在前面: 1. **nonce 缓存是本机内存**(`ConcurrentHashMap`,容量 `sign.nonce-max-size`,超了按时间窗清理)。多实例部署时各实例各存一份,窗口内重放打到另一台实例仍能过 —— 要严格就换 Redis 共享,或在网关层做幂等。 2. **`apps` 配置是默认实现**。`AppSecretProvider` 是 SPI,密钥要落库/走配置中心就自己实现一个 Bean 覆盖 `PropertiesAppSecretProvider`,不用改框架。 3. **`auth.enable-tenant` 开启多租户后**:登录用户缺 `X-Tenant-Id` 或格式错直接 HTTP 401;查询统一按 `tenant_id = ? OR tenant_id IS NULL` 过滤(存量 NULL 行对所有租户可见,不迁移);Feign 系统调用走验签放行,租户在 body 里显式传(`start_biz_flow` 的 `tenantId`)。 ## 配置项 > 下面按**代码里是否真的被读取**分成三张表。`FlowJetProperties` / `FlowJetClientProperties` 里的字段比这里列的多,多出来的都是「字段存在、没有读取点」,已全部放进第三张表,避免文档承诺零实现。 ### 服务端 `flowable-jet.*` —— 生效 | 配置 | 默认值 | 说明 | |---|---|---| | `web-enabled` | `true` | 是否注册 `/flow_jet/**` 接口(`@ConditionalOnProperty`) | | `event-type` | 空 | `kafka` / `default`;**必须显式配置**,`@Value("${flowable-jet.event-type}")` 没有默认值兜底,留空启动报 `Could not resolve placeholder` | | `topic` | `flow_jet_msg` | Kafka 主题 | | `retry-enabled` | `true` | 消息重投扫描开关 | | `retry-interval` | `30` | 扫描间隔(秒);由 `@Scheduled` 占位符读取,有 `:30` 兜底 | | `retry-batch-size` | `100` | 每轮扫描条数 | | `retry-count` | `3` | 单条消息最大重试次数 | | `urge-interval` | `5` | 催办频控(分钟),同一流程间隔内只允许催一次 | | `auth.enabled` | `false` | 身份透传开关;关闭时不注册 `FlowJetAuthFilter` / `FlowJetAccessGuard` | | `auth.check-data-permission` | `true` | 数据权限开关,**依赖 `auth.enabled=true`** | | `auth.enable-tenant` | `true` | 多租户;开启后缺 `X-Tenant-Id` 或格式错直接 HTTP 401 | | `auth.admin-ids` | 空 | 免数据权限校验的用户 ID 白名单 | | `auth.user-id-header` / `user-name-header` / `real-name-header` / `tenant-id-header` | `X-User-Id` / `X-User-Name` / `X-Real-Name` / `X-Tenant-Id` | 头名,适配已有网关 | | `sign.enabled` | `false` | 服务间验签开关 | | `sign.apps` | 空 | `appId → appSecret` 映射,默认密钥来源 | | `sign.time-window` | `300000` | 签名有效期(毫秒),双向容差 | | `sign.nonce-max-size` | `100000` | nonce 缓存上限,超了按时间窗清理 | ### 服务端 `flowable-jet.*` —— 当前不生效 这些字段**只被 `FlowConfig.configure()` 读取**,而 `FlowConfig` 没进 `AutoConfiguration.imports`(只有 3 个自动配置类),也不会被接入方的组件扫描扫到,因此 `configure()` 不会执行。写进 yml 不会报错,但引擎仍走 Flowable 自己的默认值。详见[已知限制](#已知限制)。 | 配置 | Java 默认值 | 说明 | |---|---|---| | `database-schema-update` | `"true"` | Flowable 建表策略 | | `database-schema` | `null` | schema | | `use-lock-for-database-schema-update` | `false` | schema 更新锁 | | `history-level` | `AUDIT` | 历史级别 | | `async-executor-activate` / `async-history-executor-activate` | `true` / `true` | 异步执行器开关 | | `db-history-used` | `true` | 历史表开关 | | `activity-font-name` / `label-font-name` / `annotation-font-name` | `宋体` | 流程图字体 | | `deployment-name` | `SpringBootAutoDeployment` | 部署名 | | `custom-mybatis-mappers` / `custom-mybatis-xml-mappers` | `null` | 自定义 mapper 类 / XML | | `form-field-validation-enabled` | `false` | 表单字段校验 | | `lock-poll-rate` / `schema-lock-wait-time` | `10s` / `5m` | 锁轮询 / 锁等待 | 另有一批**字段存在但全项目无任何读取点**(纯死配置):`web-ex-handler`、`check-process-definitions`、`rest-api-enabled`、`db-identity-used`(`@Deprecated`)、`process-definition-location-prefix`、`process-definition-location-suffixes`、`jpa-enabled`、`enable-history-cleaning`、`history-cleaning-cycle`、`history-cleaning-after`、`history-cleaning-batch-size`。其中 `web-ex-handler` 尤其要注意:`@ConditionalOnProperty` 拼出的 key 是 `flowable-jet.web-ex-handler.enabled`,与字段 key 不是同一个,`havingValue="true" + matchIfMissing=true` 导致全局异常处理器**默认恒装配**且按文档写法关不掉(见[已知限制](#已知限制))。 > 两处源码注释仍写着旧前缀 `flowable.oa.web-enabled` / `flowable.oa.retry-enabled`(`FlowJetWebAutoConfiguration.java:36`、`FlowJetRetryAutoConfiguration.java:13`),实际前缀是 `flowable-jet`。 ### 客户端 `flowable-jet-client.*` | 配置 | 默认值 | 说明 | |---|---|---| | `event-type` | `default` | 接收方式,`default`(同进程 Spring 事件)/ `kafka`,**必须与服务端一致** | | `topic` | `flow_jet_msg` | 订阅主题,与服务端 `topic` 一致 | | `event-dead` | `false` | 是否启用死信处理 | | `event-dead-topic` | `flow_jet_msg_dlt` | 死信主题 | | `event-dead-group` | `flow_jet_msg_dead_group` | 死信消费组 | | `event-dead-count` | `3` | 重试次数 | | `event-dead-retry` | `1000` | 重试间隔(毫秒) | | `event-dead-in-db` | `false` | 死信是否落 `biz_flow_dead_letter`(表必须先建) | | `feign-oa-name` | 空 | `@FeignClient` 的 `name`(走注册中心时必配) | | `feign-oa-url` | 空 | 服务端地址,如 `http://127.0.0.1:9040` | | `feign-oa-context-path` | 空 | 服务端 context-path 前缀 | | `app-key` / `app-secret` | 空 / 空 | 签名凭证;**不控制拦截器是否注册**,见[鉴权](#鉴权) | | `web-ex-handler` | `false` | **死配置**:字段无任何读取点,条件拼的是 `flowable-jet-client.web-ex-handler.enabled` | 客户端回调:`ApprovalStatusNotify` **有默认实现** `DefaultApprovalStatusNotify`,可以不写;但它依赖 `FlowBillServiceFactory` 按 `bizType` 找业务单据,所以接入方**必须提供至少一个 `FlowBillService`**(否则收到事件时抛 `IllegalArgumentException`)。`FlowBillServiceFactory` 本身有默认实现 `DefaultFlowBillServiceFactory`,可按需覆盖。 ## 数据表与建表 主脚本 `sql/flowable-jet.sql` 共 **12 张** `CREATE TABLE IF NOT EXISTS`,头部自带 `CREATE DATABASE IF NOT EXISTS flowable_jet` + `USE flowable_jet`(`:12-15`), **只能在服务端库执行**;客户端库不要整份跑,见下方「客户端库」。 Flowable 的 `ACT_*` / `FLW_*` 引擎表由引擎首次启动自建,不要手工建。 | # | 表 | 用途 | |---|---|---| | 1 | `biz_model` | 流程模型业务属性(分类、是否自定义表单) | | 2 | `biz_model_form` | 模型绑定的表单 `formJson` | | 3 | `biz_flow_model_resource` | 部署时的流程图 SVG | | 4 | `biz_model_def` | 每次部署的流程定义版本快照 | | 5 | `biz_flow_config` | 业务类型 → 流程定义版本绑定 | | 6 | `biz_flow_business` | 审批单(一次发起一条,`business_status` / `finished`) | | 7 | `biz_flow_tasker` | 办理记录(补人名与审批意见,动作留痕) | | 8 | `biz_work_group` | 审批人分组(`key_word` 即 Flowable groupId) | | 9 | `biz_flow_message_log` | 本地消息表(可靠事件,`status` 0/1/2/3) | | 10 | `biz_flow_event_idempotent` | 客户端消费幂等表 | | 11 | `biz_flow_dead_letter` | Kafka 死信落库(唯一使用自增主键的表) | | 12 | `biz_flow_cc` | 抄送表(收件箱、已读态) | 主键统一 bigint 雪花 ID(由 `FlowIdGenerator` 生成),全部 `IF NOT EXISTS` 可重复执行。 **客户端库**只需要两张框架表:`biz_flow_event_idempotent` 和(开启 `event-dead-in-db` 时)`biz_flow_dead_letter`。 现成脚本在 `flowable-jet-spring-boot3-client-starter/flowable-jet-client.sql`; 也可以从主脚本第 216 / 230 行复制那两段 DDL 过去执行。示例工程还额外需要 `jet_user`(服务端)与 `lims_contract`(客户端业务表),这两张**仓库里没有 DDL**,见 [STARTUP.md §2.1](docs/STARTUP.md)。 ## 前端 配套前端 `flowable-jet-web`:Vue 3 + Vite + Element Plus + bpmn-js。含流程设计器(flowable 命名空间属性面板)、表单设计器、发起申请、审批中心、详情(时间轴 + 流程图)、流程模型 / 版本 / 业务绑定 / 分组。 审批动作在详情页收口:加签任务会显示成「回签」双态卡片(加签人办理时只回签、不推进流程),打回弹窗先拉 `/task/reject_targets` 让审批人选目标节点,撤回按钮只对发起人且流程未结束时出现。前端会带 `X-User-*` 头,服务端开 `auth.enabled` 时要保证网关或登录态把这些头填对。 后端无 CORS 配置,开发期走 vite proxy,生产期用网关反代或自行补 `CorsFilter`。 ## 路线图 - [x] 双端 starter、可靠事件链路、42 个接口 - [x] 转办 / 会签(多实例节点)/ 前加签 - [x] 发起人撤回 / 打回到指定节点 / 发起人催办 - [x] 全局异常处理(`FlowJetExceptionHandler`) - [x] 鉴权一期:身份透传 + 数据权限 + 服务间 HMAC 签名 - [x] 多租户隔离(查询按 `tenant_id = ? OR tenant_id IS NULL` 过滤,存量 NULL 行不迁移) - [x] 发起抄送 / 补抄送 / 抄送收件箱(已读、未读数) - [ ] 超时提醒 - [ ] 仿钉钉审批流配置器(JSON 为唯一真源,服务端 JSON → BPMN 转换) ## 演示 `flowable-jet-test`(服务端,端口 **9040**)与 `flowable-jet-test-client`(客户端,端口 **9770**)是两个最小可运行示例,改一下 `application.yml` 里的数据源和 Kafka 地址即可起。 完整三件套(含前端 5300)的启动、建表、登录、Nginx 与公网部署步骤见 [docs/STARTUP.md](docs/STARTUP.md)。 --- ## 接入手册 > 这一节是「接到自己的业务系统」的完整清单。示例工程怎么跑是另一件事,见 STARTUP.md。 ### 服务端接入 **1. 依赖**(版本 `1.0.0`,Java 17 / Spring Boot 3.4.2 / Flowable 7.1.0) ```xml com.bitcarton flowable-jet-spring-boot3-starter 1.0.0 ``` **2. 建表**:在服务端库执行 `sql/flowable-jet.sql`(12 张 `biz_*`,脚本自带建库 + `USE`)。引擎表自动建。 **3. 提供当前用户**:默认配置(`auth.enabled=false`)下**必须**注册一个 `Supplier` Bean,否则读写接口在**首次取人时**抛 `FlowOaException("未提供当前用户…")`(不是启动时抛)。若改用请求头透传,必须同时设 `auth.enabled=true`,此时框架自动回退到 `FlowUserContext::get`,可以不注册该 Bean。 ```java @Bean public Supplier currentUser() { return () -> FlowUser.builder() .id(120001L).username("zhangsan").realName("张三") .tenantId(1L).build(); } ``` **4. 最小配置** ```yaml flowable-jet: web-enabled: true event-type: kafka # 必填;default 是同进程事件,跨进程收不到 topic: flow_jet_msg ``` **自动装配入口**:`META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports` 里注册了 3 个类 —— `FlowJetAutoConfiguration`(服务/DAO/消息)、`FlowJetWebAutoConfiguration`(REST + 过滤器 + 异常处理器)、`FlowJetRetryAutoConfiguration`(重投扫描)。`FlowConfig` **不在这份清单里**,见[已知限制](#已知限制)。 ### 客户端接入 **1. 依赖** ```xml com.bitcarton flowable-jet-spring-boot3-client-starter 1.0.0 ``` **2. 自己引可选依赖**:client starter 把 `spring-cloud-starter-openfeign` 和 `spring-kafka` 都声明为 `provided`(不传递给宿主)。接入方需要按自己用的通道显式引入;**注意即使完全不用 Feign,当前版本也必须引 OpenFeign**,否则无条件注册的签名拦截器会让应用启动失败(见[已知限制](#已知限制))。 **3. 启动类加 Feign 扫描**:`BizFlowFeign` 在 `flowable-jet-common` 包下,不在接入方的扫描范围内,必须显式扫到: ```java @EnableFeignClients(basePackages = { "com.bitcarton.flowable.common.feign", // BizFlowFeign "com.yourcompany.yourapp.feign" // 自己的 Feign 接口 }) ``` 示例见 `flowable-jet-test-client` 的 `FlowJetClientApp.java:8-11`(服务端主类不需要加)。 **4. 提供业务单据服务**:必须注册至少一个 `FlowBillService`,`DefaultApprovalStatusNotify` 会按事件里的 `bizType` 找到它回调 `updateProcessStatus`。不提供时收到审批事件会抛 `IllegalArgumentException`。`ApprovalStatusNotify` 本身有默认实现,通常不用写。 **5. 客户端库建表**:`flowable-jet-spring-boot3-client-starter/flowable-jet-client.sql`(幂等表 + 死信表)。业务表自己建。 **6. 最小配置** ```yaml flowable-jet-client: event-type: kafka # 必须与服务端一致 topic: flow_jet_msg feign-oa-url: http://127.0.0.1:9040 app-key: biz-a app-secret: 5f1c9d... ``` 两端 `event-type` 不一致是最常见的「审批通过但业务状态不变」:服务端 `default` 发的是**同进程 Spring 事件**,跨进程永远到不了客户端。 ## SPI 与可覆盖 Bean | 端 | 接口 / 类型 | 默认实现 | 是否必须 | 说明 | |---|---|---|---|---| | 服务端 | `Supplier` | 无 | **默认配置下必须** | 或开 `auth.enabled=true` 走请求头 | | 服务端 | `UserFindProvider` | 无 | 可选 | 不提供时 `/group/search_user` 抛异常 | | 服务端 | `AppSecretProvider` | `PropertiesAppSecretProvider`(读 `sign.apps`) | 可选 | 密钥落库/配置中心时覆盖 | | 服务端 | `FlowIdGenerator` | `DefaultFlowIdGenerator` | 可选 | 雪花 ID | | 服务端 | `BizFlowStatus` | `DefaultBizFlowStatus` | 可选 | 0草稿 1进行中 2通过 3驳回 4撤销 | | 服务端 | `FlowMessageSender` | 按 `event-type` 二选一 | 可选 | `ApplicationEventMessageSender` / `KafkaEventMessageSender` | | 服务端 | `JdbcHelper` / `BizDao` / 各 `Biz*Service` / 4 个 `*Api` | 内部 Bean | 可选 | 均 `@ConditionalOnMissingBean`,可整体替换 | | 客户端 | `FlowBillService` | **无** | **必须** | 审批结果回写业务单据 | | 客户端 | `BillTypeEnum` | 无 | 必须(配合上一条) | 提供 `getCode()` / `getName()` | | 客户端 | `ApprovalStatusNotify` | `DefaultApprovalStatusNotify` | 可选 | 想完全自己处理事件时覆盖 | | 客户端 | `FlowBillServiceFactory` | `DefaultFlowBillServiceFactory` | 可选 | 按 `bizType` 路由 | | 客户端 | `ProcessEventReceiver` | 按 `event-type` 二选一 | 框架自选 | 空标记接口 | `FlowJetAccessGuard`(数据权限)只在 `auth.enabled=true` 且 `BizDao` / `BizWorkGroupService` 存在时才注册。 ## BPMN 设计规则与流程语义 画图时最容易踩的几条,全部对应 `BizFlowModelService` / `BizFlowTaskService` 的实现: | 规则 | 说明 | |---|---| | **发起人变量用 `${starterId}`** | `startFlow` / `startBizFlow` / `resubmit` 都会把发起人 ID 写进流程变量(`BizFlowModelService.java:466/:676/:592`)。发起节点写 `flowable:assignee="${starterId}"`。 | | **不要用 `${initiator}`** | 代码只在发起时调 `Authentication.setAuthenticatedUserId(userId)`(`:774`,`finally` 清空 `:813`);BPMN 未声明 `flowable:initiator` 时该变量为 null,任务没有办理人,待办里查不到。 | | **只有 `userTask` 会停留** | `serviceTask` / 网关不会生成待办;流程必须至少有一个 `userTask`。 | | **其余可用变量** | `formDataJson`(表单 JSON 字符串)、`businessName`、`approved`、`additionalVariables` 透传;会签集合由 `setMiUser()` 按节点 `candidateUsers` 或调用方传入的 `assigneeList` 填充,候选人为空直接抛「会签节点[...]未配置审批人」。 | | **驳回怎么走** | `complete(approved=false)` **先** `taskService.complete(...)`;若流程仍在跑(BPMN 没画驳回结束分支)且 `!approved`,才补一次 `runtimeService.deleteProcessInstance(...)` 终止(`BizFlowTaskService.java:986-998`)。发起人「撤回」`cancel` 则是无条件直接删除实例(`:475`)。 | | **打回起点是节点 key,不是 taskId** | `moveActivityIdTo(from, to)` 的 `from` = 当前运行时任务的 `task.getTaskDefinitionKey()`,`to` = 请求体 `targetActivityId`(`:670-673`)。目标必须是**本流程历史上办结过**的节点,候选由 `/task/reject_targets` 给出;并行分支 / 会签进行中(实例内任务数 > 1)或加签 `PENDING` 时直接拒绝。 | | **打回发起节点才改业务状态** | 只有目标 = 全部已办结历史任务里 `startTime` 最早那条的节点,才置 `businessStatus=5` 并发 `RETURN` 事件;打回中间节点对业务侧透明。 | | **重新提交不新开实例** | `resubmit` / `bizResubmit` 校验:运行时实例还在、待办恰好 1 条、assignee 是本人、`businessStatus==5`;然后 `complete` 当前任务、状态 `5→1`、`finished=0`、写留痕(`BizFlowModelService.java:533-617`)。 | | **草稿 ≠ 发布** | `temp_save` 只把 BPMN/SVG 写进 Model 的 editor source(`ACT_GE_BYTEARRAY`),不产生流程定义;`deploy` 才生成 `ACT_RE_PROCDEF` 新版本。改了图不重新部署,会按旧版本发起。 | | **加签** | 同一任务最多 3 次;任务处于 `PENDING` 时点「通过」会强制 `resolveTask` 并忽略 `approved`,让任务回到原办理人。 | | **抄送** | 入口两处:发起请求带 `ccUserIds`,或 `/task/cc_add` 补抄送;写 `biz_flow_cc`,自动去重并排除发起人自己;抄送人自动进数据权限关系人。节点级「审批通过自动抄送」依赖流程设计器配置,当前未实现(见路线图)。 | ## 身份链路 ``` 浏览器 ──(JWT/登录态 + X-User-* 头)──► 网关 ──► FlowJetSignFilter ──► FlowJetAuthFilter ──► REST 业务系统 ──(Feign + X-App-Id 签名)────────────► 同上(验签通过打 FLOW_JET_SIGNED 标记,可无用户头) ``` - 业务系统用 Feign 调审批服务时,**必须自己加一个 `RequestInterceptor` 透传 `X-User-Id` / `X-Tenant-Id` 等头**,否则开了 `auth.enabled` 的服务端会直接 401。示例见 `flowable-jet-test-client/.../filter/FeignHeaderInterceptor.java`。 - 验签通过且没有用户头 → `FlowJetAuthFilter` 直接放行,身份交给宿主的 `Supplier` 决定;`FlowJetAccessGuard.signedCall()` 同时跳过数据权限校验。这是服务间调用的设计取舍。 - 多租户开启后,查询统一按 `tenant_id = ? OR tenant_id IS NULL` 过滤,存量 NULL 行对所有租户可见(不迁移)。 - nonce 防重放缓存是**进程内 `ConcurrentHashMap`**,多实例部署时窗口内重放打到另一台仍能过;要严格就换 Redis 共享或在网关做幂等。 ## 构建与发布 **环境**(本机实测):JDK 17、Maven `D:\soft\apache-maven-3.8.8`(固定用这套)、本地仓库 `D:\repository`。 ```bash # 全量跑 core 测试:21/21(ApprovalFlow 5 + MsgReliability 8 + TaskReturnBoundary 8) D:/soft/apache-maven-3.8.8/bin/mvn.cmd -o -pl flowable-jet-core -am test # 编译示例三件套后端 D:/soft/apache-maven-3.8.8/bin/mvn.cmd -o -pl flowable-jet-test,flowable-jet-test-client -am compile ``` 测试用 **H2 1.4.200 + 真实 Flowable 引擎**(H2 2.x 与 Flowable 7.1.0 的 `IDENTITY` 不兼容),surefire 锁 3.5.2。 **发布**:根 `pom.xml` 有 `release` profile(`central-publishing-maven-plugin` 0.10.0 + `maven-gpg-plugin` 3.2.7),另外常驻 `maven-source-plugin` / `maven-javadoc-plugin`,并声明了 `licenses` / `scm` / `developers`。 ⚠️ **发版前必改**:两个 starter 和两个示例工程的 `` 是 `spring-boot-starter-parent:3.4.2`,**不是根 `flowable-jet`**,所以根 pom 的 release profile / 元数据对它们无效。实测 `mvn -o -P release -pl <模块> maven-help-plugin:3.5.2:effective-pom`: | 模块 | `central-publishing-maven-plugin` | `maven-gpg-plugin` | |---|---|---| | `flowable-jet-core`(parent = 根 pom) | 1 | 1 | | `flowable-jet-spring-boot3-starter`(parent = Spring Boot) | 0 | 0 | 从根执行 `mvn deploy -P release` 时,这四个模块不会被签名、也不会被 Central 插件收集。修法:把 parent 改回根 pom,**同时补 `spring-boot-dependencies` BOM**,否则会丢掉 Spring Boot 的依赖版本管理。 另外,四个模块都**没有加 `spring-boot-configuration-processor`**,不会生成 `spring-configuration-metadata.json`,接入方 IDE 里写 `flowable-jet.*` 没有补全和校验;测试目前只覆盖 `core`,`common` / 两个 starter 零测试、无 CI。 ## 已知限制 以下都是**当前代码的实际行为**,不是计划中的功能;写配置或排障时按这张表判断,别按「应该有」推断。 | # | 现象 | 位置 | 影响 / 建议 | |---|---|---|---| | 1 | `FlowConfig` 没进自动装配,16 个 `flowable-jet.*` 引擎配置写了不生效 | `FlowConfig.java:12`、`AutoConfiguration.imports`(3 行) | 建表策略、历史级别、异步执行器、字体、自定义 mapper 全走 Flowable 默认值;把 `FlowConfig` 加进 imports 或改成 `@AutoConfiguration` | | 2 | `web-ex-handler` 是死配置,全局 `@ControllerAdvice` 默认恒装配且按文档写法关不掉 | `FlowJetWebAutoConfiguration.java:96`、`FlowJetClientAutoConfiguration.java:78` | 条件 key 拼成 `...web-ex-handler.enabled`,字段 key 是 `...web-ex-handler`;`matchIfMissing=true` 使 advice 默认注册,其 `@ExceptionHandler(Exception.class)` 会把接入方异常统一转成 `Rt.fail("服务异常,请联系管理员")`。接入方自己的 advice 要靠 `@Order` 抢在前面 | | 3 | `FlowJetSignInterceptor` 无条件注册 | `FlowJetClientAutoConfiguration.java:70-73` | openfeign 是 `provided`,接入方不引就 `NoClassDefFoundError: feign/RequestInterceptor` 启动失败;填不填 `app-key` 都加签,空值用随机 UUID,服务端开验签时 401。建议加 `@ConditionalOnClass` + `@ConditionalOnProperty("app-key")` | | 4 | `oaList` 不过滤未部署模型 | `BizFlowModelService.java:396` | 只保存过草稿的模型出现在「发起申请」列表,点进去 `getProcessDefId()` 抛「流程定义不存在」;改图不重新部署会按旧版本发起 | | 5 | `event-type` 留空启动失败 | `FlowJetAutoConfiguration.java:97-98` | `@ConditionalOnProperty(matchIfMissing=true)` 说允许缺失,但 `@Value("${flowable-jet.event-type}")` 无 `:default` 兜底,实测抛 `PlaceholderResolutionException`。**必须显式配置**;建议改成 `@Value("${flowable-jet.event-type:default}")` | | 6 | 打回留痕写了 `taskId` | `BizFlowTaskService.java:685` | 与该方法 Javadoc「留痕不写 taskId」及本文旧描述矛盾,可能影响流转轨迹展示槽位;其余四个动作确实没写 | | 7 | `next_retry_time` 只写不读 | 可靠事件链路 | 退避实际靠固定扫描周期,不是按次退避 | | 8 | nonce 缓存是进程内存 | `FlowJetSignFilter` | 多实例部署时窗口内重放打到另一台实例仍能过 | | 9 | 节点级「审批通过自动抄送」未实现 | 路线图 | 目前只有发起时 `ccUserIds` 和 `/task/cc_add` 两个入口 | | 10 | 发布配套不全 | 见[构建与发布](#构建与发布) | parent 不统一、无配置元数据、starter 零测试 | ## 故障速查 | 现象 | 原因 | 处理 | |---|---|---| | 启动报 `Could not resolve placeholder 'flowable-jet.event-type'` | 没显式配 `event-type` | 两端都补 `event-type: kafka` 或 `default` | | 启动报 `NoClassDefFoundError: feign/RequestInterceptor` | 接入方没引 OpenFeign,但拦截器无条件注册 | 先显式引入 openfeign;长期按已知限制 #3 加条件注解 | | 写 `flowable-jet.history-level` 没反应 | `FlowConfig` 未装配 | 见已知限制 #1;改用 Flowable 原生 `flowable.*` 配置 | | 自己的 `@ControllerAdvice` 不生效 / 异常都被转成「服务异常」 | 框架的全局 advice 默认注册 | 给自己的 advice 加 `@Order`,或按已知限制 #2 修条件注解 | | 发起报「流程定义不存在」 | 模型只保存过草稿,没点部署 | `/def/deploy` 重新发布;改图后也要重新部署 | | 发起后待办里查不到任务 | 用了 `${initiator}` 或流程里没有 `userTask` | 改 `${starterId}`,确认至少一个 `userTask` | | 审批通过后业务状态不变 | 两端 `event-type` 不一致 / Kafka 不通 / 客户端库缺幂等表 | 查服务端 `biz_flow_message_log.status`(1 已发送 / 2 待重试 / 3 死信),见 STARTUP.md §2.5 | | Feign 调审批接口 401 | 业务系统没透传 `X-User-*` 头 | 加 `RequestInterceptor` 透传身份头,或走签名链路 | | 打回下拉「无数据」 | 前端组件库缺 `rejectTargets` / `returnTask` 方法 | 组件库已补齐,重新 `npm run build:lib` | | `mvn -o` 报 `Cannot access aliyunmaven ... offline` | Maven 版本 / 仓库不对 | 固定 `D:/soft/apache-maven-3.8.8` + `D:\repository`;联网跑一次补来源标记后可离线 | | 生产环境所有接口 404 | `vite server.proxy` 只在 dev 生效 | 配 Nginx 反代,见 STARTUP.md §4.3 | ## 文档索引 | 想干什么 | 看哪里 | |---|---| | 接入到自己的业务系统 | [快速开始](#快速开始) + [接入手册](#接入手册) | | 跑示例三件套 / 公网部署 / 账号 / Nginx | [docs/STARTUP.md](docs/STARTUP.md) | | 查接口 | [接口一览](#接口一览) | | 查配置项 / 为什么写了没反应 | [配置项](#配置项) + [已知限制](#已知限制) | | 画 BPMN / 驳回 / 打回 / 重新发起 | [BPMN 设计规则与流程语义](#bpmn-设计规则与流程语义) | | 建表 | [数据表与建表](#数据表与建表) | | 身份 / 签名 / 租户 | [鉴权](#鉴权) + [身份链路](#身份链路) | | 发版 / 跑测试 | [构建与发布](#构建与发布) | | 出错了 | [故障速查](#故障速查) + STARTUP.md §5 |