# GBOX AIoT 可视化规则引擎接入说明

## 目标

平台提供 GBOX 可视化规则画布，用拖拉拽方式编排 S0-S4 状态机、设备事件、条件判断和平台动作。流程编排服务继续负责人工审批、派工和待办流转，不承担实时规则判断。

## 对象化建模方式

规则不是从通用 HTTP 节点开始理解，而是从平台对象开始编排：

1. 选择平台对象，例如 `8寸人脸识别门禁一体机`、房间、热成像模组或工单对象。
2. 选择该对象的触发事件或原子能力，例如面板的 `auth_allow`（认证成功/允许通过）。
3. 选择后续被影响的对象，例如同一台面板、房间、工单、服务包。
4. 选择要执行的动作或原子能力，例如 `AuthControlScreenBanner`（下发屏幕横幅）。
5. 通过 `GBOX规则桥接执行` 节点回写平台，由平台负责 MQTT 下发、动态物料生成、审计和命令回执。

规则画布已安装 GBOX AIoT 自定义节点，左侧分类为 `GBOX AIoT`：

- `平台对象事件`：从平台对象目录选择对象和事件。
- `动态横幅生成`：生成账单、访客补登记、服务提醒等图片物料。
- `对象原子能力动作`：选择目标对象和其绑定的原子能力，例如 `AuthControlScreenBanner`。
- `GBOX规则桥接执行`：把对象化动作提交到平台桥接 API 执行。

平台对象目录接口：

```text
GET /api/rule-engine/catalog
GET /api/rule-engine/bridge/catalog
```

其中 `bridge/catalog` 供规则画布读取，需要 `x-gbox-rule-token`。

典型链路：

```text
8寸人脸识别门禁一体机
  -> auth_allow（认证成功/允许通过）
  -> 动态横幅生成（bill_due / visitor_register）
  -> AuthControlScreenBanner（下发屏幕横幅）
  -> MQTT call: device/pad/{SN}/call
```

## 访问入口

- 平台页面：`规则引擎`
- 规则画布：`/rule-engine/`
- 画布入口接入平台权限体系，不再使用单独的画布用户名/密码。
- 已登录平台且拥有 `rules:write` 权限的账号可进入；超级管理员默认拥有该权限。
- 未登录访问 `/rule-engine/` 会跳回平台首页，已登录但无 `rules:write` 会返回 403。

## 安全边界

- 规则运行时只监听 `127.0.0.1:1880`。
- 画布入口 `/rule-engine/` 由 Nginx 反向代理，并通过 `auth_request` 调平台接口：
  - `GET /api/rule-engine/canvas-auth`
  - 该接口只返回状态码：`204` 允许、`401` 未登录、`403` 无 `rules:write` 权限。
- 规则画布调用平台动作接口必须带 Header：
  - `x-gbox-rule-token: <RULE_ENGINE_BRIDGE_TOKEN>`
- 桥接令牌保存在：
  - `/etc/gbox-platform/gbox.env`
  - `RULE_ENGINE_BRIDGE_TOKEN`

## 事件和动作接口

平台测试事件会转发到本机规则运行入口：

```text
POST http://127.0.0.1:1880/rule-engine-api/gbox/rules/events
```

规则执行后回调平台动作桥接接口：

```text
POST http://127.0.0.1:3000/api/rule-engine/bridge/actions
Header: x-gbox-rule-token
```

当前允许的动作：

- `compose_banner`：云端生成动态物料并下发 `AuthControlScreenBanner`
- `screen_banner`：直接下发横幅
- `remote_open`：下发 `AuthControlRelayCurrentSet`
- `send_panel_command`：下发白名单面板命令
- `create_work_order`：创建治理复核工单
- `record_audit` / `notify_only`：记录规则审计

## 默认模板

平台内置 5 个 S0-S4 规则模板：

- `S0_EMERGENCY_RELEASE_GUARD`
- `S1_AUTH_ALLOW_POST_OPEN_BANNER`
- `S2_VISITOR_TEMP_CODE_REVIEW`
- `S3_OVERCROWDING_REVIEW_ORDER`
- `S4_STANDBY_SERVICE_ROTATION`

模板文件由部署脚本随平台包同步到规则运行时工作目录。

平台也提供下载接口：

```text
GET /api/rule-engine/starter-flow.json
```

## 云端部署

现有部署脚本会自动调用：

```bash
./scripts/cloud/configure-rule-engine.sh
```

该脚本会安装和配置规则运行时、生成令牌、写入后台服务、配置 Nginx `/rule-engine/` 平台权限入口并做本机健康检查。

第三方组件事实信息集中放在 `docs/third-party-notices.md`，不作为普通操作入口文案。