开源地址

https://gitee.com/rainterm/designer-approval
https://github.com/rainterm/designer-approval

审批工作流系统

简介

基于 designer-admin 脚手架二次开发的可视化审批工作流系统，面向企业内部请假、报销、用印等通用审批场景：管理员在线设计流程与表单并发布，员工发起申请，审批人办理待办。

项目特点：

• 开箱即用：流程定义、发起、待办、转办、驳回重提、办理轨迹与附件一应俱全，含请假演示流程，克隆即可试用。
• 可视化设计：bpmn-js 流程画布 + 表单设计 + 节点审批人配置，四步向导完成建模，无需手写 BPMN。
• 审批人配置灵活可插拔：实现 AssigneeTypeHandler 并 @Component 注册即可扩展类型，设计器按元数据自动渲染配置项。

界面预览

内置能力

流程设计

• 向导四步：基础信息（名称、编码 / processDefinitionKey、描述）→ bpmn-js 流程画布（中文面板）→ 发起表单 schema → 按节点配置审批人、多人模式、驳回模式。
• 状态：草稿(0) → 已发布(1) ↔ 停用(2)；仅已发布可发起。
• 发布时后端 enrich BPMN（多实例、assignee 表达式）；审批人 ID 写在 designJson.taskAssignees，不硬编码进 BPMN。

审批人配置

内置类型（均可替换 / 扩展，无需改核心解析逻辑）：

扩展方式：实现 AssigneeTypeHandler（type / label / configFields / resolve）并 @Component 注册；AssigneeTypeRegistry 自动收集。设计器通过 GET /admin-api/approval/definition/assignee-types 拉取类型与字段元数据动态渲染。inputType 约定：user / role / dept / post / ref_node。

多人：OR 或签 / AND 会签（Camunda 多实例）。驳回：PREVIOUS（上一节点）或 INITIATOR（发起人节点，默认）。

发起与办理

• 发起：选已发布流程 → 填表单 / 附件 → 写 appr_instance 并启动 Camunda 实例。
• 待办 / 已办：按当前用户查 Camunda Task。
• 办理：同意 / 驳回（意见 + 附件）；驳回按节点策略回退。
• 转办 / 撤销 / 重提：转办他人；发起人撤销运行中实例；驳回到发起人节点后可改表单重提。

实例状态：running / approved / rejected / cancelled。

附件与轨迹

• 附件阶段落 appr_attachment：start / resubmit / approve / reject / transfer。
• 办理历史落 appr_history：start / approve / reject / transfer / cc / cancel / end 等。

设计

技术栈选择

开发规范

完整约定见 docs/开发规范.md。编码风格以工具可校验的规则为准：

• 后端：根 pom.xml 集成 PMD + P3C，mvn pmd:pmd 扫描。
• 前端：ESLint（eslint.config.js），pnpm run lint / lint:fix。

部署脚本

deploy/ 下提供「本机打包 + Docker 运行」脚本，数据库与应用分开部署：

文档说明

后台设计考虑

分层结构

designer-approval/
├── designer-common/                 # 通用契约（脚手架）
├── designer-framework/              # 技术能力与 SPI（脚手架）
├── designer-module-system/          # 用户 / 角色 / 部门等（脚手架）
├── designer-module-approval/
│   ├── approval-api/                # 跨模块契约（预留）
│   └── approval-service/
│       ├── util/                    # ApprovalJsonUtil / BpmnModelUtil 等工具
│       ├── config/                  # Camunda 引擎装配
│       └── service/                 # 业务能力
│           ├── definition/          # 流程定义用例（接口+实现）
│           ├── runtime/             # 运行时用例 + 通知 / 节点判定 / VO 组装（接口+实现）
│           ├── assignee/            # 审批人类型扩展 + 发起时变量解析（接口+实现）
│           └── bpmn/                # Enricher / Reader / Navigator（接口+实现）
├── designer-server/                 # 启动组装
├── designer-ui/admin-web/           # 前端（含 modules/approval）
├── sql/init/mysql/approval/         # 审批初始化 SQL
├── deploy/                          # Docker 部署
└── docs/                            # 开发规范等

一次审批请求的典型路径：

Controller（definition / instance / task）
    → ApprDefinitionService / ApprRuntimeService
        → Camunda RepositoryService / RuntimeService / TaskService
        → Mapper（appr_definition / instance / history / attachment）
            → MySQL（业务表 + ACT_*）

核心组件

数据模型

业务表（ACT_* 由引擎首次启动创建）：

主要 API 前缀：/admin-api/approval/definition|instance|task。

接口文档

• OpenAPI2 + Knife4j：http://localhost:8080/doc.html
• 生产建议 KNIFE4J_ENABLE=false，或 KNIFE4J_PRODUCTION=true 并限制内网访问。

前端设计考虑

分层结构

审批前端落在业务模块目录，不侵入壳层：

designer-ui/admin-web/src/modules/approval/
├── api/                   # 审批接口
├── menuBadges.js          # 待办 / 待重提角标
├── views/definition/      # 流程设计向导、bpmn-js 扩展
├── views/instance/        # 我的申请 / 全部申请 / 详情
└── views/task/            # 我的审批

路由由菜单 component（如 approval/definition/index）动态解析到 modules/approval/views/...，新增页面只加目录与菜单即可。

流程设计器

• 基于 bpmn-js，扩展 Palette / ContextPad / 属性面板与中文翻译。
• 向导与运行时共用设计产物：bpmnXml + designJson + formSchema。
• 选人、字典文案等复用脚手架公共组件与 useDict。

快速开始（本地开发）

0. 环境要求

cd deploy
./install-env.sh --check   # 仅检查
./install-env.sh           # 按需安装

1. 准备 MySQL 与 Redis

连接信息在 designer-server/src/main/resources/app.yml，支持环境变量覆盖：

• MySQL：DB_HOST / DB_PORT / DB_USER / DB_PASSWORD / DB_NAME
• Redis：REDIS_HOST / REDIS_PORT / REDIS_PASSWORD / REDIS_DB

默认库名 designer_approval。本地也可用 Docker 只起数据库：

cd deploy
cp .env.example .env
./deploy-db.sh        # MySQL + Redis，不自动建表

2. 初始化数据库

脚本为破坏性初始化（DROP TABLE 重建 + 种子数据），仅首次或需要重置时执行，勿对有数据的库重复运行。

# 交互式
bash sql/init/mysql/00-run-init.sh

# 免交互
DB_HOST=127.0.0.1 DB_PORT=3306 DB_USER=root DB_PASSWORD=root DB_NAME=designer_approval \
  bash sql/init/mysql/00-run-init.sh

导入顺序：_base → system → demo → approval。Camunda ACT_* 表在应用首次启动时由引擎自动创建。

3. 启动后端

在 IDE 中运行 com.designer.admin.DesignerApp（模块 designer-server），或：

mvn -pl designer-server -am -DskipTests clean package
java -jar designer-server/target/designer-server.jar

启动后：

• 管理端 API：http://localhost:8080/admin-api
• 健康检查：GET http://localhost:8080/admin-api/system/health
• 接口文档：http://localhost:8080/doc.html

4. 启动前端

cd designer-ui/admin-web
pnpm install
pnpm run dev      # http://localhost:5173
pnpm run build    # 产出 dist/

开发环境已配置 Vite 代理，/admin-api、/app-api、/open-api 转发到 http://localhost:8080。

默认账号

请假 demo 另有 leave_* 账号（见 sql/init/mysql/approval/data.sql）。生产环境务必修改或删除演示账号。

试用请假流程

1. admin 登录 → 审批模块 → 流程设计 → 打开「请假审批」→ 发布
2. leave_staff（或有发起权限的账号）→ 我的申请 → 发起
3. 按节点用 leave_xz / leave_kz 等在 我的审批 中办理

生产部署

数据库与应用分开部署：本机用 JDK / Maven / Node 打包，再构建运行镜像；MySQL、Redis 与应用容器分离。

部署流程

cd deploy

# 1. 检查并按需安装环境
./install-env.sh

# 2. 配置环境变量
cp .env.example .env
vim .env

# 3. 启动 MySQL + Redis（不自动建表）
./deploy-db.sh

# 4. 首次 / 重置时初始化数据库
(cd .. && bash sql/init/mysql/00-run-init.sh)

# 5. 本地打包 + 构建镜像 + 启动 Server / Web
./deploy-app.sh

可选：./deploy-minio.sh 启动本地 MinIO。使用外部数据库时，配置 .env 中 DB_* / REDIS_* 后执行 ./deploy-app.sh 即可。

常用命令

访问入口

日志

• 文件日志：容器内 /app/logs/，挂载在 server_logs 卷。
• 容器 stdout：./logs.sh server；compose 限制 max-size=50m / max-file=5。
• 可通过 solon.logging.appender.file.* 或 LOG_PATH 调整。

发布与运维

• 日常发版只执行 ./deploy-app.sh；--skip-build 可复用已有产物。
• 禁止对生产库重跑破坏性初始化脚本；增量 SQL 按版本执行并登记。
• 修改 .env 默认密码与 VAULT_PASSWORD；多实例时共用 Redis，各实例 Quartz instanceId 须不同。
• 健康检查：GET /admin-api/system/health。