# designer-approval

**Repository Path**: rainterm/designer-approval

## Basic Information

- **Project Name**: designer-approval
- **Description**: 可视化审批工作流系统，支持流程，表单可视化设计、审批人灵活配置
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-21
- **Last Updated**: 2026-10-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Designer Approval · 审批工作流系统

[![license](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![JDK](https://img.shields.io/badge/JDK-25-orange.svg)](https://adoptium.net/temurin/releases/)
[![Solon](https://img.shields.io/badge/Solon-4.1.0-16A34A.svg)](https://solon.noear.org/)
[![Camunda](https://img.shields.io/badge/Camunda-7.22-FC5D0D.svg)](https://camunda.com/)
[![Vue](https://img.shields.io/badge/Vue-3.5-42b883.svg)](https://vuejs.org/)

## 简介

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

项目特点：

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

## 界面预览

![image-20261021200410505](docs/images/image-20261021200410505.png)

![image-20261021200436774](docs/images/image-20261021200436774.png)

![image-20261021200454840](docs/images/image-20261021200454840.png)

![image-20261021200546874](docs/images/image-20261021200546874.png)

![image-20261021200620088](docs/images/image-20261021200620088.png)

![image-20261021202226739](docs/images/image-20261021202226739.png)

![image-20261021203257331](docs/images/image-20261021203257331.png)

![image-20261021203311652](docs/images/image-20261021203311652.png)

![image-20261021203416509](docs/images/image-20261021203416509.png)

![image-20261021203450060](docs/images/image-20261021203450060.png)

## 内置能力

| 能力 | 说明 |
|---|---|
| 流程设计 | 四步向导：基础信息 → BPMN → 发起表单 → 节点审批人；草稿 / 发布 / 停用 |
| 表单设计 | 可视化字段配置，发起按 schema 渲染；实例保存 schema 快照 |
| 审批人配置 | 发起人 / 用户 / 角色 / 部门 / 上级岗位；Handler 可插拔扩展 |
| 多人模式 | 或签（一人同意即可）/ 会签（全部同意） |
| 发起与办理 | 发起、同意、驳回、转办、撤销；侧栏待办 / 待重提角标 |
| 驳回策略 | 驳回到上一审批节点，或驳回到发起人节点后可改表单重提 |
| 附件 | 发起 / 重提 / 同意 / 驳回 / 转办各阶段可挂附件 |
| 办理轨迹 | 记录发起、同意、驳回、转办、抄送、撤销、结束等动作 |
| 演示流程 | 内置请假 demo（按天数分支 + 上级岗位会签） |

### 流程设计

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

### 审批人配置

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

| 类型 | 含义 |
|---|---|
| `INITIATOR` | 申请发起人本人 |
| `USER` | 指定用户（可多选） |
| `ROLE` | 拥有所选角色的启用用户 |
| `DEPT` | 所选部门下的启用用户 |
| `SUPERIOR_POST` | 以指定节点审批人为基准，按岗位沿部门向上查找任职人 |

扩展方式：实现 `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` 等。

## 设计

### 技术栈选择

| 层 | 选型 | 版本 | 选择理由 |
|---|---|---|---|
| 运行时 | JDK | 25 | 虚拟线程等现代特性 |
| 后端框架 | Solon | 4.1.0 | 轻量、启动快；沿用 designer-admin 脚手架 |
| ORM | MyBatis-Plus | 3.5.x | 业务表 CRUD |
| 流程引擎 | Camunda | 7.22 | 嵌入式引擎，复用业务库，`ACT_*` 自动建表 |
| BPMN 模型 | camunda-bpmn-model | 同引擎 | 发布前 enrich 多实例与 assignee |
| 鉴权 | Sa-Token | 1.46 | 登录与权限（脚手架） |
| 数据库 | MySQL | 8.0.13+ | 业务库 + Camunda 表 |
| 缓存 / 会话 | Redis | 7 | 会话、缓存（脚手架） |
| 前端 | Vue 3.5 + Naive UI + Vite | — | 管理后台 |
| 流程设计器 | bpmn-js + camunda-bpmn-moddle | 18.x | 可视化 BPMN 编辑 |

### 开发规范

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

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

### 部署脚本

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

| 脚本 | 作用 |
|---|---|
| `install-env.sh` | 检查 / 安装 Docker、JDK 25、Maven、Node.js（`--check` 仅检查） |
| `deploy-db.sh` | 启动 MySQL + Redis（不自动建表） |
| `deploy-app.sh` | 本地 Maven + 前端打包，构建镜像并启动 Server / Web |
| `deploy-minio.sh` | 可选，本地 MinIO |
| `stop.sh` / `restart.sh` / `logs.sh` | 停止、重启、查看日志 |

### 文档说明

| 文档 | 说明 |
|---|---|
| [docs/开发规范.md](docs/开发规范.md) | 前后端编码约定、模块依赖、新增业务模块 |
| [docs/SSO.md](docs/SSO.md) | 单点登录（脚手架能力） |
| [deploy/](deploy) | Docker 部署与 Nginx / Dockerfile |
| [sql/init/mysql/approval/](sql/init/mysql/approval) | 审批表结构、菜单字典、请假 BPMN demo |

### 后台设计考虑

#### 分层结构

```
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_*）
```

#### 核心组件

| 类 | 职责 |
|---|---|
| `CamundaEngineConfig` | 嵌入式引擎，共用业务 DataSource，`ACT_*` 自动建表 |
| `ApprovalBpmnEnricher` | 发布前规范化 BPMN（多实例 / assignee 表达式） |
| `ApprovalBpmnReader` | 读取用户任务与扩展属性 |
| `ApprovalBpmnNavigator` | 驳回目标、入边、已走路径推断 |
| `AssigneeTypeHandler` / `AssigneeTypeRegistry` | 审批人类型扩展接口与注册表 |
| `AssigneeResolver` | 解析门面，委托各 Handler |
| `ApprDefinitionService` | 定义 CRUD、发布、启停、审批人类型列表 |
| `ApprRuntimeService` | 运行时编排：发起、办理、转办、撤销、重提 |
| `InstanceAssigneeVariableBuilder` | 发起时按 taskAssignees 解析审批人变量（`assignee`） |
| `ApprovalNotifier` | 待办 / 转办 / 驳回等消息通知（`runtime`） |
| `ApprovalTaskClassifier` | 抄送 / 发起人节点判定与设计数据读取（`runtime`） |
| `ApprInstanceAssembler` | 实例 / 任务 / 历史 VO 组装（`runtime`） |

#### 数据模型

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

| 表 | 说明 |
|---|---|
| `appr_definition` | 流程定义：BPMN、designJson、formSchema、发布状态 |
| `appr_instance` | 审批实例与表单 / 变量快照 |
| `appr_history` | 办理历史 |
| `appr_attachment` | 各阶段附件 |

主要 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. 环境要求

| 组件 | 版本 | 说明 |
|---|---|---|
| JDK | 25+ | 后端编译与运行 |
| Maven | 3.9+ | 后端构建 |
| Node.js | 18+（推荐 22） | 前端构建 |
| pnpm | 10.x | 前端包管理 |
| MySQL | 8.0.13+ | 业务库 + Camunda |
| Redis | 7 | 会话、缓存（必需） |

```bash
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 只起数据库：

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

### 2. 初始化数据库

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

```bash
# 交互式
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`），或：

```bash
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. 启动前端

```bash
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`。

### 默认账号

| 账号 | 密码 | 说明 |
|---|---|---|
| admin | admin123 | 超级管理员（流程设计、全部申请） |
| guest | guest123 | 普通用户（我的申请 / 我的审批） |

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

### 试用请假流程

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

## 生产部署

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

### 部署流程

```bash
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` 即可。

### 常用命令

| 命令 | 说明 |
|---|---|
| `./install-env.sh` | 检查并安装环境（`--check` 仅检查） |
| `./deploy-db.sh` | 启动 MySQL、Redis |
| `./deploy-minio.sh` | 启动本地 MinIO（可选） |
| `./deploy-app.sh` | 本地打包并部署应用 |
| `./deploy-app.sh --skip-build` | 跳过打包，复用已有产物 |
| `./restart.sh app` / `./stop.sh app` | 重启 / 停止应用 |
| `./logs.sh server` | 查看后端容器日志 |

### 访问入口

| 入口 | 默认端口 | 说明 |
|---|---|---|
| 管理后台 | `APP_PORT=80` | 浏览器访问 `http://<服务器IP>` |
| 后端 API | `SERVER_PORT=8080` | 仅绑定 `127.0.0.1`，经 Nginx 转发 |
| 接口文档 | `SERVER_PORT` | 生产建议 `KNIFE4J_ENABLE=false` |

### 日志

- **文件日志**：容器内 `/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`。

## 许可证

本项目基于 [MIT License](LICENSE) 开源，可自由用于商业项目。