# AProcess

**Repository Path**: qq2820/AProcess

## Basic Information

- **Project Name**: AProcess
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-17
- **Last Updated**: 2026-06-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AProcess — C++ 流程引擎 + 内嵌 Web 管理台

> 基于 **C++20** 的 XML 工作流引擎，内嵌 **Web 可视化管理台**（流程设计 / 发布 / 运行监控 / 任务插件管理）。
> 单一二进制、零外部运行时依赖——Web 服务与流程引擎跑在同一进程。

## 功能概览

| 能力 | 说明 |
|------|------|
| 🎨 可视化设计 | 浏览器中拖拽编排 BPMN 风格节点（开始 / 任务 / 三种网关 / 结束）与连线，配置任务参数与条件表达式，一键生成引擎 XML |
| 📦 流程发布 | SQLite 版本化持久化存储，草稿 / 部署 / 归档状态管理，服务重启后自动恢复已部署流程 |
| 📊 运行监控 | SSE 实时推送，实例列表、活动节点高亮、执行时间线、统计看板 |
| 🔧 任务插件管理 | 运行时加载 / 卸载动态库（`.so` / `.dylib` / `.dll`），任务热插拔 |
| ⚙️ 流程引擎 | 排他 / 包容 / 并行网关、条件求值、多实例并发执行、完整事件监听机制 |

## 快速开始

### 构建方式

项目使用 **CMake (≥ 3.10) + C++20**，无外部包管理器——所有第三方依赖均以源码内联（header-only 或 amalgamation）。

### 启动 Web 管理台

```bash
# 构建（首次）
mkdir build && cd build && cmake .. && make

# 启动（默认端口 8080）
./web_process_manager

# 指定端口
./web_process_manager 9090
```

> 启动时会在当前目录创建 `data/` 目录，用于存放 SQLite 持久化数据库；同时自动从仓库恢复所有 `deployed` 状态的流程定义到引擎。

### 访问地址

```
http://localhost:8080
```

页面提供三个标签页：**🎨 设计器**、**📊 监控**、**🔧 任务管理**。

## 架构

项目由三层相互独立、命名空间不同的引擎层 + 一层新增的 Web 层组成：

```
┌──────────────────────────────────────────────────────────┐
│  浏览器 Web UI（纯 HTML5 Canvas/SVG + 原生 JS，零构建）    │
│   设计器 / 发布 / 监控 / 任务管理                          │
└───────────────┬──────────────────────────────┬───────────┘
          REST / XML                      SSE 实时事件
┌──────────────▼──────────────────────────────▼───────────┐
│  Web 层（web:: 命名空间，新增）                            │
│   WebServer ─ WebProcessController ─ ProcessRepository    │
│                  │              └ DefinitionValidator     │
│                  └ EventBroadcaster（SSE 推送 + 落库）     │
└──────────────┬───────────────────────────────────────────┘
┌──────────────▼───────────────────────────────────────────┐
│  引擎层（现有）                                            │
│   process::  ProcessEngine（执行调度）+ ProcessManager      │
│              （XML 解析 / 实例 / 网关条件）                 │
│   task::     TaskManager + 动态库插件加载器                 │
│   全局       Executor（header-only 线程池）+ Logger         │
└──────────────────────────────────────────────────────────┘
```

- **process 层** — [`ProcessEngine`](include/process/ProcessEngine.h)（执行调度、统计）与 [`ProcessManager`](include/process/ProcessManager.h)（XML 解析、实例创建、网关条件求值）。均为单例（`getInstance()`），使用 Pimpl 惯用法。
- **task 层** — [`task::TaskManager`](include/task/TaskManager.h)（任务注册表、工厂）+ [`DynamicLibraryLoader`](include/task/DynamicLibraryLoader.h)（`dlopen` / `LoadLibrary`）。单例。
- **Executor** — [`Executor`](include/Executor.h)，全局命名空间的 header-only 线程池，`Try()` 返回的包装器在析构时触发回调。
- **Web 层** — [`WebServer`](include/web/WebServer.h)（cpp-httplib 封装，注册路由 / 托管静态资源 / SSE 端点）+ [`WebProcessController`](include/web/WebProcessController.h)（唯一桥接点，把 REST 请求翻译为引擎单例调用）+ [`ProcessRepository`](include/web/ProcessRepository.h)（SQLite CRUD / 版本管理）+ [`EventBroadcaster`](include/web/EventBroadcaster.h)（实现 [`ProcessEventListener`](include/process/ProcessEventListener.h)，把引擎事件转 JSON 推送给 SSE 订阅者并落库）+ [`DefinitionValidator`](include/web/DefinitionValidator.h)（XML 校验）。

> 设计原则：**引擎几乎不改动**。`EventBroadcaster` 只是 `ProcessEventListener` 的一个实现，分别注册到 `ProcessManager` 与 `ProcessEngine`，对引擎零侵入。

## 项目结构

```
AProcess/
├── app/
│   └── main.cpp                    # Web Process Manager 入口（启动引擎 + WebServer）
├── main.cpp                        # CLion 生成的 hello-world 模板（非框架入口）
├── include/
│   ├── Executor.h                  # 全局命名空间，header-only 线程池
│   ├── Logger.h                    # 变参宏日志（LOG_INFO / LOG_ERROR ...）
│   ├── httplib/httplib.h           # cpp-httplib（header-only HTTP）
│   ├── rapidxml/                   # rapidxml（header-only XML）
│   ├── process/                    # ProcessEngine / ProcessManager / ProcessXMLParser / 事件
│   ├── task/                       # TaskManager / ITask / TaskRegistrar / DynamicLibraryLoader
│   └── web/                        # WebServer / WebProcessController / ProcessRepository
│                                   #   / EventBroadcaster / DefinitionValidator
├── src/
│   ├── process/                    # 引擎层实现 → process_framework 静态库
│   ├── task/                       # 任务层实现 → task_framework 静态库
│   ├── sqlite/                     # SQLite amalgamation（sqlite3.c）→ sqlite3_lib 静态库
│   └── web/                        # Web 层实现 → web_framework 静态库
├── web/                            # 前端（纯 HTML/CSS/JS，源文件即产物）
│   ├── index.html                  # 入口页（设计器 / 监控 / 任务管理 标签页）
│   ├── css/style.css
│   └── js/                         # 见下文「前端模块」
├── plans/
│   └── web-process-manager-design.md   # Web 管理台设计方案
├── doc/                            # 中文文档（API、流程、任务插件说明）
├── test/                           # 独立可执行测试（无测试框架）
└── CMakeLists.txt                  # 顶层构建：web_process_manager + 测试目标
```

## REST API

所有响应统一为 JSON：`{ "success": boolean, ... }`，错误时附带 `error` 字段。

### 流程定义

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/processes` | 流程定义列表（含版本号、部署状态） |
| POST | `/api/processes` | 保存草稿到仓库（body 为 XML；`?id=&name=&description=`） |
| GET | `/api/processes/:id` | 获取流程定义详情（含完整 XML） |
| PUT | `/api/processes/:id` | 更新草稿（生成新版本），body 为新 XML |
| DELETE | `/api/processes/:id` | 删除流程定义（所有版本） |
| POST | `/api/processes/:id/deploy` | 部署到引擎（标记 deployed + 加载 XML，`?version=N` 可选） |
| GET | `/api/processes/:id/xml` | 导出流程定义 XML |
| POST | `/api/processes/:id/validate` | 校验仓库中的流程定义（默认最新版本） |
| GET | `/api/processes/:id/versions` | 版本历史 |

### 实例

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/instances` | 创建并启动实例（`?defId=xxx`，body 为参数 JSON） |
| GET | `/api/instances` | 实例列表（`?defId=&state=RUNNING` 过滤） |
| GET | `/api/instances/:id` | 实例状态（含活动节点） |
| POST | `/api/instances/:id/control` | 控制实例（`?action=pause\|resume\|terminate`） |
| GET | `/api/instances/:id/history` | 执行步骤时间线 |

### 实时事件

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/events/stream` | **SSE** 实时事件流（订阅所有实例事件） |

SSE 事件示例：

```
event: node
data: {"instanceId":"proc-1-1","nodeId":"task-002","type":"activated","ts":1718000000}

event: process
data: {"instanceId":"proc-1-1","state":"COMPLETED","ts":1718000005}
```

### 任务插件

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/tasks` | 已注册任务清单 |
| POST | `/api/tasks/libraries` | 加载动态库插件（`?path=xxx` 或 body） |
| DELETE | `/api/tasks/libraries/:name` | 卸载插件 |

### 统计 / 校验

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/stats` | 引擎 / 管理器统计信息 |
| POST | `/api/validate` | 直接校验 XML body（不加载到引擎） |

## 流程定义 XML 格式

流程通过 **BPMN 风格标签** 的 XML 定义，由 [`ProcessXMLParser`](src/process/ProcessXMLParser.cpp) 解析。前端 [`xml-builder.js`](web/js/xml-builder.js) 生成的 XML 与引擎消费的 XML 是同一份（XML 全程直通，不引入 JSON 中间模型）。

### 节点类型

| 标签 | 说明 |
|------|------|
| `startEvent` | 流程起点 |
| `endEvent` | 流程终点 |
| `task` | 执行具体业务逻辑，通过 `taskName` 引用已注册任务 |
| `exclusiveGateway` | 排他网关：基于条件选择**一条**路径 |
| `inclusiveGateway` | 包容网关：基于条件选择**多条**路径并行执行 |
| `parallelGateway` | 并行网关：**无条件**并行执行所有出口路径 |

### 完整示例

> 注意：任务参数使用 `<parameter>` 子元素；条件表达式写在 `<connection>` 的 **`condition` 属性** 上（引擎只解析该属性）。

```xml
<?xml version="1.0" encoding="UTF-8"?>
<process id="example" name="示例流程" version="1.0">
  <description>含排他网关的审批示例</description>

  <nodes>
    <startEvent id="start" name="开始" />

    <task id="task1" name="处理任务" taskName="my-task">
      <parameters>
        <parameter name="key" value="value" />
        <parameter name="strictMode" value="true" />
      </parameters>
    </task>

    <exclusiveGateway id="gw1" name="条件判断" />

    <endEvent id="end1" name="通过" />
    <endEvent id="end2" name="拒绝" />
  </nodes>

  <connections>
    <connection from="start" to="task1" />
    <connection from="task1" to="gw1" />
    <connection from="gw1" to="end1" condition="${approved == true}" />
    <connection from="gw1" to="end2" condition="${approved == false}" />
  </connections>

  <!-- 变量定义（可选） -->
  <variables>
    <variable name="approved" type="boolean" defaultValue="false" />
    <variable name="orderAmount" type="double" defaultValue="0.0" />
  </variables>
</process>
```

### 网关说明

- **排他网关（exclusiveGateway）**：依次求值各出边条件，选择**第一条**满足的路径；若无满足条件者，走默认路径（不带 `condition` 的出边）。
- **包容网关（inclusiveGateway）**：所有满足条件的出边**并行**执行；若无满足者，走默认路径。
- **并行网关（parallelGateway）**：忽略条件，**无条件**并行执行所有出边；join 端等待所有入边完成后再放行。

### 条件表达式语法

格式为 `${变量 操作符 值}`，由引擎对 `ProcessParams` 中的变量求值：

```
${orderAmount > 10000}
${approved == true}
${status != "rejected"}
${score <= 60}
```

## 前端模块

前端为纯 HTML/CSS/JS（无框架、无构建步骤），源文件即最终产物，位于 [`web/js/`](web/js/)：

| 文件 | 职责 |
|------|------|
| [`xml-builder.js`](web/js/xml-builder.js) | 画布模型 → 引擎 XML 生成（严格遵循 [`ProcessXMLParser`](src/process/ProcessXMLParser.cpp) 格式） |
| [`flow-designer.js`](web/js/flow-designer.js) | HTML5 Canvas/SVG 流程图画布（节点拖拽、连线、平移缩放、属性面板） |
| [`api.js`](web/js/api.js) | REST + SSE（`EventSource`）统一封装（`ApiClient`） |
| [`publisher.js`](web/js/publisher.js) | 发布 / 版本管理（保存草稿、部署、校验、删除） |
| [`monitor.js`](web/js/monitor.js) | 运行时监控（SSE 驱动实例列表、实时活动节点高亮、执行时间线、统计看板） |
| [`task-manager.js`](web/js/task-manager.js) | 任务插件管理 UI（加载 / 卸载动态库、任务清单、操作日志） |
| [`toast.js`](web/js/toast.js) | 轻量提示通知组件 |

## 依赖

所有第三方库均以**源码形式内联**，不引入包管理器、不链接任何系统共享库：

| 依赖 | 集成方式 | 用途 |
|------|----------|------|
| **cpp-httplib** | header-only，[`include/httplib/httplib.h`](include/httplib/httplib.h)，直接 `#include` | 内嵌 HTTP 服务（仅用 HTTP，不启用 OpenSSL） |
| **SQLite** | vendored amalgamation，[`src/sqlite/sqlite3.c`](src/sqlite/sqlite3.c) 编译为 `sqlite3_lib` 静态库 | 流程定义 / 实例 / 执行历史的持久化（不链接系统 libsqlite） |
| **rapidxml** | header-only，[`include/rapidxml/`](include/rapidxml/) | XML 解析 |
| **pthreads** | 系统线程库（`Threads::Threads`） | 并发执行 |

> 前端零依赖：纯 HTML/CSS/JS，无 npm / Vite / 打包步骤。

## 构建

### 编译

```bash
mkdir build && cd build
cmake ..
make            # 构建全部：web_process_manager + 测试目标
```

构建产物：
- `web_framework` / `process_framework` / `task_framework` / `sqlite3_lib` — 静态库
- `web_process_manager` — Web 管理台可执行文件

### 测试

测试为带普通 `main()` 的独立可执行文件（无 gtest / catch），成功返回 `0`，失败返回非零：

```bash
cd build
ctest                                  # 运行所有已注册测试

# 直接运行单个测试
./test_process_gateways                # 网关 / 条件求值
./test_concurrent_tasks                # 并发实例
./test_exception_handling              # Executor 异常处理
./test_library_loading                 # 动态库插件加载
```

### 构建 Web Process Manager

```bash
cd build
make web_process_manager               # 单独构建 Web 管理台
./web_process_manager                  # 启动（默认 8080 端口）
```

## 设计文档

Web 管理台的完整设计（架构、数据流、SQLite 模型、API 设计、分阶段实施路线）见：

- [`plans/web-process-manager-design.md`](plans/web-process-manager-design.md)

---

*最后更新：2026-06-16*