# flow

**Repository Path**: jmash/flow

## Basic Information

- **Project Name**: flow
- **Description**: 基于Jmash的工作流模块。
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-04-27
- **Last Updated**: 2026-08-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# jmash-flow

[Jmash](https://gitee.com/jmash/jmash) 技术框架集成 [Flowable 7](https://www.flowable.com/) + CDI 的工作流实现，提供流程定义、部署、业务办理、流程监控等能力，并通过 gRPC / gRPC-Gateway / Vue 3 组件库对外提供服务。

## 功能特性

- 基于 Flowable 7.2.0 工作流引擎，结合 Jakarta EE CDI 进行依赖注入管理
- 以 gRPC 作为服务接口，并借助 gRPC-Gateway 自动生成 REST API 与 OpenAPI 文档
- 流程管理：流程部署（JSON/XML）、部署删除、流程定义查询、流程图查看
- 业务办理：流程启动、待办/已办/办结查询、任务办理、退回、认领、分配/移交、委托、优先级设置、附件管理
- 流程监控：流程实例与任务的分页查询、暂停/恢复、删除
- 支持多租户、读写分离（MariaDB）、Redis（Jedis）、Shiro + JWT 鉴权、Zipkin 日志链路
- Vue 3 前端组件库，内置 bpmn-js 流程图展示与编辑、动态表单等组件
- 提供 Docker 与 Kubernetes 部署配置

## 模块结构

| 模块 | 说明 |
| --- | --- |
| [jmash-flow-lib](jmash-flow-lib) | Proto 协议定义与 Java gRPC Client，包含 Flowable 校验规则等资源 |
| [jmash-flow-service](jmash-flow-service) | 核心服务：CDI + Flowable 引擎 + gRPC 服务实现 |
| [jmash-flow-gateway](jmash-flow-gateway) | Go 实现的 gRPC-Gateway，提供 REST API 与 OpenAPI 文档 |
| [jmash-flow-vue3](jmash-flow-vue3) | Vue 3 前端组件库（TypeScript + Vite + Element Plus） |
| [jmash-flow-k8s](jmash-flow-k8s) | Docker 与 Kubernetes 部署配置 |

## 技术栈

- 后端：Java 17、Flowable 7.2.0、CDI / SmallRye、gRPC、Hibernate / JPA、MariaDB、Redis（Jedis）、Shiro（Jakarta）、JWT、Zipkin / Brave、Druid、MapStruct
- 网关：Go 1.22、grpc-gateway v2、OpenAPI / Swagger
- 前端：Vue 3、TypeScript、Vite、Element Plus、Pinia、Vue Router、Vue i18n、bpmn-js
- 部署：Docker、Kubernetes

## 环境要求

- JDK 17+
- Maven 3.6+
- Go 1.22+
- Node.js 18+ / pnpm
- MariaDB（或 MySQL）、Redis
- Kubernetes（可选）

## 快速开始

### 1. 后端统一构建与部署（jmash-flow-k8s）

后端（`jmash-flow-lib`、`jmash-flow-service`、`jmash-flow-gateway`）通过 `jmash-flow-k8s` 下的 `cmd0.py` 脚本统一打包、发布与部署：

```sh
cd jmash-flow-k8s

# 打包：Maven 构建服务 + 生成并编译 gRPC 网关
python3 cmd0.py package amd64

# 发布：构建并推送 Docker 镜像
python3 cmd0.py publish amd64

# 部署：部署到 Kubernetes
python3 cmd0.py deploy amd64
```

常用参数：`arch` 可选 `amd64` / `arm64`，此外支持 `--version`、`--namespace`、`--name`、`--replicas`。其他操作包括 `restart`、`delete`、`scale`、`test`、`notest`、`all`（一键完成打包、发布与部署）。

### 2. 构建前端组件库（jmash-flow-vue3）

```sh
cd jmash-flow-vue3
pnpm install
pnpm dev       # 本地开发
pnpm build     # 构建产物
```

## 配置说明

核心服务主要配置位于 `jmash-flow-service/src/main/resources/META-INF/`：

- `microprofile-config.properties`：服务名称、端口、JWT/RSA 密钥、读写数据源、Redis 连接等
- `persistence.xml`：JPA 持久化单元配置
- `beans.xml` / `services/`：CDI 容器与 Flowable `ProcessEngineLookup` 装配
- `module/`：数据库初始化、升级与删除脚本

> 数据库与运行环境的搭建说明此处仅作概述：需准备可用的 MariaDB（或 MySQL）与 Redis 实例，创建读写用户并初始化 `jmash_flow` 库，具体脚本与参数见 `module/` 目录。

## 接口与 API

gRPC 服务定义见 [flow_rpc.proto](jmash-flow-lib/src/main/proto/jmash/flow/flow_rpc.proto)，主要接口分组如下：

- 流程管理：`deployFlow`、`deployFlowXml`、`deleteDeployment`、`findProcDefList`、`findProcDefById`、`findProcDefXmlById`、`findProcDefDiagram`
- 业务办理：`startProcInst`、`findMyTodoTaskPage`、`findMyDoneProcInstPage`、`findMyFinishProcInstPage`、`completeTask`、`gobackTask`、`claimTask`、`assignTask`、`delegateTask`、`resolveTask`、`priorityTask`、`createProcAttachment`、`createTaskAttachment` 等
- 流程监控：`findProcInstPage`、`suspendProcInst`、`deleteProcInst`、`findTaskPage`、`suspendTask`
- 历史与辅助：`findHiTaskinstList`、`findHiProcInstById`、`findHiProcInstVars`、`version`、枚举查询等

网关启动后，可通过 `http://<host>:8090/openapi` 查看 OpenAPI 文档，REST 接口路径以 `/v1/flow/...` 开头。

## 部署

Docker 与 Kubernetes 配置位于 [jmash-flow-k8s](jmash-flow-k8s)，主要包括：

- `Dockerfile`：打包 gRPC 服务与网关为单一容器
- `k8s-configmap.yaml`：服务配置
- `k8s-deployment-template.yaml` / `k8s-service.yaml`：部署与 Service（gRPC `50051`、网关 `8090`）
- `k8s-ingress*.yaml`：Ingress 路由配置

容器同时运行 `jmash-flow-service`（gRPC `50051`）与 `jmash-flow-gateway`（HTTP `8090`），并配置了健康检查探针。

## License

[Apache License 2.0](LICENSE)