# erpnext_bpm

**Repository Path**: fwr567/erpnext_bpm

## Basic Information

- **Project Name**: erpnext_bpm
- **Description**: Enterprise BPM Platform for ERPNext v16
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: version-16
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-07-27
- **Last Updated**: 2026-09-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ERPNext BPM

ERPNext / Frappe v16 图化审批流程引擎（v2.0.0）。

v2 把 v1 的「线性节点子表」重构成了 **BPM Process → BPM Node → BPM Route** 的
有向图模型（类 Camunda / Flowable / Activiti），支持网关、并行、条件跳转、
审批策略、节点事件、插件化动作与通知，同时**完全兼容 v1 的建模方式与前端样式**。

## 功能特性

### 流程建模

- **图模型**：`BPM Process`（流程）→ `BPM Node`（节点）→ `BPM Route`（连线）。
  节点之间靠连线推进，不再依赖行号顺序，天然支持 **跳转、回环、并行分支**。
- **双写兼容**：`BPM Process` 上的 `建模方式` 可选 **子表** 或 **图**。
  选「子表」时仍按 v1 的节点子表建模，保存后自动镜像生成 Node / Route
  （`auto_generated = 1`），引擎统一按图执行。**老流程零改动可用**。
- **网关**：排他网关（按优先级取第一条命中的连线）、并行网关（全部分支同时激活）、
  包容网关（所有命中条件的分支同时激活）；汇聚节点自动等待所有入边到齐。
- **条件构建器**：连线条件支持 **可视化条件行**（字段 / 运算符 / 值 / 与或），
  无需写代码；也保留 **高级脚本**（Python 表达式，可用 `doc`、`instance`）。

### 审批语义

- **审批人**：角色 / 指定用户（逗号分隔）/ 单据用户字段 / 发起人。
- **审批策略**：任一通过、全部通过、**按百分比**、**按人数**、**按权重**；
  否决策略可选 **一票否决** 或 **阈值否决**（剩余人已无法达成阈值时才判定驳回）。
- **审批动作**：同意、驳回、退回任意前置节点、加签、转办；
  实例级动作：撤回、催办、暂停、恢复、终止、重新发起。
- **状态机**：实例状态迁移由 `TRANSITIONS` 表约束，非法迁移直接拒绝。
- **节点事件**：`进入前 / 进入后 / 离开前 / 离开后` 四类钩子，
  处理器支持 **发送通知 / 调用服务端方法 / 触发 Webhook**；
  「离开前」抛异常可阻断流转（用于业务校验）。

### 扩展性

- **插件化动作注册表**：`@register("动作名")` 即可新增审批动作，
  内置 11 个动作（同意/驳回/退回/加签/转办/撤回/催办/暂停/恢复/终止/重新发起）
  会在 migrate 时写入 `BPM Action Definition` 供配置。
- **插件化通知渠道**：内置 12 个 Notifier（系统消息、邮件、企业微信/钉钉/飞书
  **群机器人**、企业微信/钉钉/飞书**自建应用（定向推送给指定员工个人）**、短信、
  自定义 Webhook 等），按 `BPM Settings` 配置分发。
- **权限引擎**：`节点级 → 流程级 → 全局 → 代码默认` 四级解析，
  叠加角色约束（System Manager 恒可；发起人只能操作自己的流程；审批人只能操作自己的任务）。

### 使用体验

- **单据详情页审批面板**：流程进度、节点状态、审批人、审批记录（意见 + 多附件）。
- **BPM 审批中心**（`/app/bpm-center`）：我的待办 / 我的已办 / 我发起的，支持批量审批。
- **隐藏原生提交按钮**：单据类型配了「启用中」的流程时，自动隐藏 Frappe 原生「提交」，
  引导用户走审批流；流程停用后下一次打开单据按钮自动恢复（规则仅由「流程是否启用」决定）。
- **前端模块化**：`public/js/bpm/` 拆成 utils / api / timeline / action_dialog /
  batch_dialog / panel / buttons / submit_guard / index 九个模块，DOM 与样式与 v1 完全一致。

### 性能与安全

- 图加载、动作注册表均带缓存，`after_migrate` 自动失效。
- 任务 / 日志 / 审批人解析全部走批量查询（`frappe.db.get_all` + `frappe.qb`），消除 N+1。
- 条件求值不再使用 `safe_eval` 拼接，优先走结构化条件构建器。

## 安装

```bash
bench get-app --branch version-16 https://gitee.com/fwr567/erpnext_bpm.git
bench --site <site> install-app erpnext_bpm
bench --site <site> migrate
bench build --app erpnext_bpm
bench restart
```

## 从 v1.0.0 升级

```bash
cd apps/erpnext_bpm && git pull origin version-16
bench --site <site> migrate      # 自动执行 v2_0 迁移补丁
bench build --app erpnext_bpm
bench restart
```

`migrate` 会依次执行四个补丁：

| 补丁 | 作用 |
| --- | --- |
| `init_settings` | 补齐 `BPM Settings` 新增开关（Single DocType 新字段不会自动取默认值） |
| `seed_action_definitions` | 把 11 个内置动作写入 `BPM Action Definition` |
| `sync_process_graph` | 存量流程 `建模方式` 置为「子表」，并镜像生成 Node / Route |
| `backfill_instance_state` | 把 v1 的 `current_node_idx` 回填成 v2 的 `current_node_key` / `active_nodes` |

升级是**幂等**的，且不会修改 v1 的任何字段，可随时回滚到 `v1.0.0` tag。

## 目录结构

```
erpnext_bpm/
├── engine.py               # 对外门面：匹配、发起、推进、审批动作（保持 v1 白名单签名）
├── api.py                  # 面板与审批中心 API
├── notify.py               # 通知分发
├── permissions.py          # 任务/实例/日志权限
├── boot.py                 # 注入启用流程的单据类型（供前端隐藏原生提交按钮）
├── install.py              # after_migrate：补默认值 + 清缓存
├── builtin_actions.py      # 11 个内置审批动作
├── core/
│   ├── graph.py            # ProcessGraph / Node / Route，图加载与缓存
│   ├── router.py           # 网关路由：穿透网关求下一批节点
│   ├── runtime.py          # 运行时：进入节点、汇聚、推进、结束
│   ├── policy.py           # 审批策略与否决策略
│   ├── state_machine.py    # 实例状态机
│   ├── conditions.py       # 条件构建器求值与描述
│   ├── events.py           # 节点事件分发
│   ├── actions.py          # 动作注册表
│   ├── permission_engine.py# 四级权限解析
│   ├── settings.py         # Single 默认值补齐
│   ├── sync.py             # 子表 → Node/Route 双写同步
│   └── query.py            # 批量查询工具
├── notifiers/              # 插件式通知渠道
├── patches/v2_0/           # 升级补丁
├── public/js/bpm/          # 前端模块
└── erpnext_bpm/
    ├── doctype/            # BPM Process / Node / Route / Instance / Task / Log ...
    ├── page/bpm_center/    # 审批中心
    └── workspace/bpm/      # BPM 工作区
```

## 文档

- [使用指南](docs/USAGE.md)
- [更新日志](CHANGELOG.md)