# rule-engine-qlexpress

**Repository Path**: aiobc/rule-engine-qlexpress

## Basic Information

- **Project Name**: rule-engine-qlexpress
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-06
- **Last Updated**: 2026-09-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# QLExpress 规则引擎平台

面向促销、风控、审批等**频繁变更的业务规则**：在 Web 可视化配置 → 编译为 QLExpress 脚本 → 经 MQ 热发布；Compute 只执行已发布快照中的 `script`，配置与执行解耦。

基于 [QLExpress 4.x](https://github.com/alibaba/QLExpress)，补齐官方未提供的可视化配置、在线测试、版本发布与 HTTP/SDK 调用能力。

## 核心能力

- **零代码规则配置**：参数 / 变量 / 函数 / 条件 → 普通规则、规则集、决策表、决策树、评分卡
- **在线测试与发布**：生成测试版 → 命中明细 → 审核发布；支持回滚与下线（附录 C 状态机）
- **热生效执行**：发布后经 MQ 推送，Compute 内存快照执行，无需重启
- **统一调用入口**：`execute` / `batchExecute` / `isExists`；提供 Java Client SDK
- **脚本安全**：QLExpress isolation，阻断 `Runtime.exec` 等高危调用

## 架构亮点

```text
业务/运营                 业务系统
   │                        │
   ▼                        ▼
 UI (:5173)          Client SDK (@EnableRuleEngine)
   │                        │
   ▼                        ▼
 Web (:18801) ──MQ──► Compute (:18802)
  CRUD / 编译 / 发布         仅执行 script（零库）
   │
   ▼
 MySQL（仅 Web）
```

| 设计取舍 | 说明 |
|----------|------|
| **配置 / 执行分离** | Web 负责编译与发布；Compute 禁止读库、禁止 JSON→脚本编译 |
| **Compute 零库** | 运行时状态仅 MQ + 内存快照；冷启动 FULL_SYNC |
| **发布状态机** | 主表仅 DEV/PRD；TEST 只存在于 publish 表（附录 C） |
| **契约优先** | 统一 `ApiResponse`、错误码、鉴权（附录 A）；导入导出（附录 B） |
| **Client SDK** | `Http*Client` + `@EnableRuleEngine`；禁止 OpenFeign 双轨 |

## 技术栈

| 层 | 技术 |
|----|------|
| 运行时 | JDK **21** · Maven 3.9+ · Node.js 20 LTS+ |
| 后端 | Spring Boot **4.1** · QLExpress **4.1.3** · MyBatis-Plus · RabbitMQ · MySQL 8 |
| 前端 | React **19** · Vite **6** · Ant Design **6** · TanStack Query **5** |
| 文档 | springdoc OpenAPI · 附录 A/B/C |

## 模块结构

```text
rule-engine-qlexpress-common/      # 统一响应体、错误码、OpenAPI 公共注解
rule-engine-qlexpress-core/        # 编译器、QLExpress 封装（无 Web/DB）
rule-engine-qlexpress-persistence/ # Entity / Mapper（仅 Web 依赖）
rule-engine-qlexpress-web/         # 配置、发布、MQ 生产（:18801）
rule-engine-qlexpress-compute/     # 执行、MQ 消费（:18802，零库）
rule-engine-qlexpress-client/      # 调用方 SDK
rule-engine-qlexpress-ui/          # React 前端（:5173）
sql/schema/                        # MySQL 建表脚本
docker-compose.yml                 # 本地中间件；`--profile apps` 含 Web / Compute
docs/                              # 需求、附录、工程规范
```

## 快速开始

先确认 Docker 守护进程已启动（`docker info` 能看到 Server）。`--profile` 必须写在 `up` 前面（写成 `docker compose up --profile apps` 不会起 Web/Compute）。

### 1. 应用栈

```bash
docker compose --profile apps up -d --build
```

首次构建镜像可能要十几分钟。只要中间件、本机 `mvn` 跑 Web/Compute 时，改用 `docker compose up -d`。

| 服务 | 地址 | 账号 |
|------|------|------|
| MySQL | localhost:3306 | root / 123456（库 `rule_engine`） |
| Redis | localhost:6379 | — |
| RabbitMQ | localhost:5672 / 管理台 :15672 | guest / guest |

> 默认 `application.yml` 与 compose 一致（MySQL `:3306`、RabbitMQ `guest/guest`）。需要 DEBUG 日志时加 `-Dspring-boot.run.profiles=dev`。若曾用旧 compose，需 `docker compose down -v` 后重建。
>
> **启动顺序**：先 Web 后 Compute。`--profile apps` 已按健康检查编排；本机 `mvn` 启动时须等 Web 就绪再起 Compute，否则可能出现 `8910002`（D3）。

### 2. 后端

若已用 `--profile apps` 起了 Web/Compute，跳过本步。否则：

```bash
mvn -s .mvn/settings.xml clean verify

# Web
mvn -s .mvn/settings.xml -pl rule-engine-qlexpress-web spring-boot:run

# Compute（新终端）
mvn -s .mvn/settings.xml -pl rule-engine-qlexpress-compute spring-boot:run
```

### 3. 前端

```bash
cd rule-engine-qlexpress-ui && npm install && npm run dev
```

打开 http://localhost:5173

| 账号 | 密码 |
|------|------|
| admin@local.com | admin123 |

工作空间 `default`；Compute AccessKey：`dev_access_key` / `dev_access_secret`

### 4. 演示：配置一条规则并执行

1. 登录 → **规则参数** 新建 `phone`（STRING）
2. **条件**：左值 phone，EQ，右值 `13800138000`
3. **普通规则** `phoneRule`，引用条件，动作 `PASS`
4. **保存** → **生成测试版** → 输入 `phone=13800138000` 验证
5. **发布** 后调用 Compute：

```bash
curl -X POST http://localhost:18802/ruleEngine/execute \
  -H "Content-Type: application/json" \
  -d '{
    "dataType": 0,
    "code": "phoneRule",
    "workspaceCode": "default",
    "accessKeyId": "dev_access_key",
    "accessKeySecret": "dev_access_secret",
    "param": { "phone": "13800138000" }
  }'
```

`dataType`：0 普通规则 · 1 规则集 · 2 决策表 · 3 决策树 · 4 评分卡。批量：`POST /ruleEngine/batchExecute`。

### 主链路回归

改五类规则任一类（配置 / 测试版 / 用例 / 发布 / execute）时，至少跑：

```bash
mvn -s .mvn/settings.xml -pl rule-engine-qlexpress-web,rule-engine-qlexpress-compute -am test "-Dsurefire.failIfNoSpecifiedTests=false" "-Dtest=ScenarioW1AcceptanceIntegrationTest,RuleSetDecisionTableIntegrationTest,FiveTypeBatchIntegrationTest,MvpPublishExecuteIntegrationTest,ScoreCardDecisionTreeComputeIntegrationTest,RuleSetDecisionTableComputeIntegrationTest"
```

`-Dsurefire.failIfNoSpecifiedTests=false` 避免 reactor 把 `-Dtest` 套到 core 等无匹配模块时失败。PowerShell 须给带点号的 `-D…` 加引号。Web 覆盖配置→测试版→用例→发布；Compute 覆盖 `execute` / `batchExecute`。

### 5. Client SDK

依赖 `rule-engine-qlexpress-client`（先 `mvn -s .mvn/settings.xml -pl rule-engine-qlexpress-client -am install -DskipTests`）。库不预置规则，须先在 UI 发布到 PRD。

```java
@SpringBootApplication
@EnableRuleEngine
public class App { /* ... */ }
```

```yaml
rule-engine.client:
  base-url: http://localhost:18802
  workspace-code: default
  access-key-id: dev_access_key
  access-key-secret: dev_access_secret
```

```java
@Autowired RuleEngineClient client;

RuleExecuteResponse result = client.execute(
    DataType.GENERAL_RULE, "phoneRule", Map.of("phone", "13800138000"));
```

### 6. API 文档

| 服务 | Swagger UI | 健康检查 |
|------|------------|----------|
| Web | http://localhost:18801/swagger-ui/index.html | `POST /ruleEngine/health/check` · `GET /actuator/health/readiness` |
| Compute | http://localhost:18802/swagger-ui/index.html | `POST /ruleEngine/health/check`（看 `data.ready`）· `GET /actuator/health/readiness` |

## 文档

完整索引见 [docs/README.md](docs/README.md)。

| 想了解… | 去读 |
|---------|------|
| 从零调通 execute | 本文「快速开始」 |
| 产品能力与验收 | [需求文档](docs/requirement/QLExpress规则引擎平台需求文档.md) |
| HTTP 契约 / 错误码 / 鉴权 | [附录 A](docs/requirement/QLExpress规则引擎平台附录A-API规范.md) |
| 导入导出格式 | [附录 B](docs/requirement/QLExpress规则引擎平台附录B-导入导出文件格式.md) |
| 发布状态流转 | [附录 C](docs/requirement/QLExpress规则引擎平台附录C-状态机.md) |
| 模块边界 / 命名 / PR | [工程规范](docs/standards/工程规范.md) |
| Java / Spring / QLExpress | [后端技术规范](docs/standards/后端技术规范.md) |
| React / UI 约定 | [前端技术规范](docs/standards/前端技术规范.md) |
| AI / Agent 协作 | [AGENTS.md](AGENTS.md) |

## 当前状态

一期 MVP、二期 2A/2B（规则集/表/树/卡）及 Compute 零库已交付。文档核销与主链路保活已落地（见上「主链路回归」）。当前路线：**三期（SaaS → DMN → 非 Java 节点 → CEP → AI）**；NFR-01/02 压测记录可与 3A 并行、不挡 3A。见 [需求文档 §11](docs/requirement/QLExpress规则引擎平台需求文档.md)。不设周次闸门。QLExpress Trace 已取消，排障看脚本/入参/结果与条件命中明细，或交给 Agent。

## 许可证

本项目采用 [Apache License 2.0](LICENSE)。

第三方依赖许可证摘要见 [docs/THIRD-PARTY-NOTICES.md](docs/THIRD-PARTY-NOTICES.md)（含 MySQL Connector/J 的 GPLv2 + Universal FOSS Exception 说明）。