@gadmin2n/schematics 0.0.72 → 0.0.74

package/dist/lib/application/files/gadmin2-game-angle-demo/temporal/README.md

@@ -0,0 +1,278 @@
+# Temporal Workflow Runtime
+
+本目录包含 Workflow 执行引擎的所有组件。
+
+## 架构
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Temporal Server                            │
+│               (调度中心，不执行业务代码)                        │
+│                                                              │
+│  ┌──────────┐  ┌──────────────┐  ┌────────────────────┐    │
+│  │ 状态存储  │  │  任务队列管理  │  │  历史/可见性引擎    │    │
+│  │ (PG)     │  │  (分发任务)    │  │  (查询/搜索)       │    │
+│  └──────────┘  └──────┬───────┘  └────────────────────┘    │
+│                        │                                     │
+└────────────────────────┼─────────────────────────────────────┘
+                         │  gRPC (任务分发 + 状态回报)
+                         ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    Temporal Worker                            │
+│                (你的代码，执行业务逻辑)                         │
+│                                                              │
+│  ┌─────────────────┐    ┌──────────────────────────┐        │
+│  │  Workflow 代码    │    │  Activity 代码            │        │
+│  │  (DSL 解释器)    │    │  (HTTP调用/DB/通知/...)   │        │
+│  └─────────────────┘    └──────────────────────────┘        │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Server vs Worker
+
+| | Server | Worker |
+|--|--------|--------|
+| 谁提供的 | Temporal 官方 Docker 镜像 | **你写的代码** |
+| 执行业务逻辑？ | ❌ 完全不碰 | ✅ 全部在这里 |
+| 有状态？ | ✅ 持久化到 PG | ❌ 无状态，可随时重启/扩容 |
+| 挂了怎么办 | 所有 workflow 暂停 | Server 保留进度，Worker 恢复后继续 |
+| 能横向扩展？ | 可以但复杂 | **随便加**，同一 task queue 多个 Worker |
+
+**一句话：Server 是"大脑"（调度+记忆），Worker 是"手脚"（干活）。**
+
+## 目录结构
+
+```
+temporal/
+├── package.json              # 便捷脚本
+├── docker-compose.yml        # Temporal Server + Web UI
+├── config/
+│   └── development-sql.yaml  # Server 动态配置
+├── sql/
+│   └── create-event-trigger.sql  # Outbox 表 + PG 触发器函数
+└── worker/                   # DSL 解释器 Worker
+    ├── package.json
+    ├── tsconfig.json
+    ├── .env                  # Worker 环境变量
+    └── src/
+        ├── index.ts          # Worker 启动入口
+        ├── config.ts         # 配置读取
+        ├── outbox-poller.ts  # 事件轮询器（扫描 outbox 表触发 workflow）
+        ├── workflows/
+        │   └── dsl-workflow.ts   # 核心：DSL 动态解释器
+        ├── activities/
+        │   ├── index.ts
+        │   ├── http-request.ts   # HTTP 调用
+        │   ├── db-query.ts       # 数据库查询
+        │   ├── db-execute.ts     # 数据库写入
+        │   ├── send-notification.ts  # 多渠道通知
+        │   ├── code-execute.ts   # 沙箱 JS 执行
+        │   └── reporting.ts      # 状态回写到业务 DB
+        └── dsl/
+            ├── types.ts      # DSL 类型定义
+            ├── graph.ts      # DAG 解析 + 拓扑排序
+            ├── context.ts    # 变量/上下文管理
+            └── condition.ts  # 条件表达式求值
+```
+
+## 快速启动
+
+```bash
+cd temporal
+
+# 1. 启动 Temporal Server（复用项目现有 PostgreSQL）
+npm run up
+
+# 2. 安装 Worker 依赖
+npm run worker:install
+
+# 3. 启动 Worker（开发模式）
+npm run worker:dev
+```
+
+## 工作流程
+
+```
+1. 用户在前端点击 "Run" 按钮
+       │
+       ▼
+2. NestJS 调用 temporalService.startWorkflow()
+       │
+       ▼
+3. Temporal Server 收到请求，创建记录，放入 task queue
+       │
+       ▼
+4. Worker 长轮询 Server，收到新任务
+       │
+       ▼
+5. Worker 执行 dslWorkflow()：
+   - 解析 DSL JSON → DAG
+   - 拓扑排序确定执行顺序
+   - 逐节点执行对应 Activity
+   - 条件节点做分支选择
+   - 并行节点用 Promise.all
+   - 审批节点等待 Signal
+       │
+       ▼
+6. 每个节点执行结果回写到 t_workflow_node_execution
+       │
+       ▼
+7. Workflow 完成/失败 → 更新 t_workflow_instance 状态
+```
+
+## 环境变量
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `TEMPORAL_ADDRESS` | `localhost:7233` | Temporal Server gRPC 地址 |
+| `TEMPORAL_NAMESPACE` | `default` | Temporal 命名空间 |
+| `TEMPORAL_TASK_QUEUE` | `workflow-execution` | 任务队列名称 |
+| `DATABASE_URL` | (见 .env) | Worker 回写状态用的数据库连接 |
+
+## 常用命令
+
+```bash
+npm run up           # 启动 Server + UI
+npm run down         # 停止 Server + UI
+npm run logs         # 查看 Server 日志
+npm run worker:dev   # 开发模式启动 Worker
+npm run worker:build # 编译 Worker
+npm run worker:start # 生产模式启动 Worker
+```
+
+## Web UI
+
+启动后访问 http://localhost:8080 可查看：
+- 运行中的 Workflow 列表
+- Workflow 执行历史
+- 单个 Workflow 的事件时间线
+- Worker 连接状态
+
+---
+
+## Event Trigger（数据库事件触发 Workflow）
+
+通过 Transactional Outbox 模式，当业务表发生变更时自动触发对应的 Workflow。
+
+### 原理
+
+```
+┌─────────────┐    INSERT/UPDATE/DELETE    ┌──────────────────────────┐
+│  任何来源    │ ────────────────────────→  │  PostgreSQL               │
+│  (NestJS /  │                            │                           │
+│   外部系统)  │                            │  AFTER TRIGGER            │
+└─────────────┘                            │  → INSERT INTO outbox     │
+                                           │   (同一事务，保证不丢)     │
+                                           └─────────────┬─────────────┘
+                                                         │
+                                                   outbox 表中有新行
+                                                         │
+                                                         ▼
+                                           ┌──────────────────────────┐
+                                           │  Worker                   │
+                                           │  outbox-poller.ts         │
+                                           │                           │
+                                           │  每 10s 扫描一次：        │
+                                           │  1. SELECT 未处理行        │
+                                           │  2. 匹配 event_trigger    │
+                                           │  3. 启动 Temporal workflow │
+                                           │  4. 标记行为已处理         │
+                                           └──────────────────────────┘
+```
+
+### 为什么选轮询而不是 PG LISTEN/NOTIFY
+
+| | PG NOTIFY | Outbox 轮询 |
+|--|--|--|
+| Worker 离线期间 | ❌ 事件丢失 | ✅ 事件留在表中，恢复后处理 |
+| 可靠性 | best-effort | **at-least-once（事务保证）** |
+| 复杂度 | 需要长连接 + 去重 | 只需定时 SELECT |
+| 延迟 | <100ms | ≤ 轮询间隔（默认 10s） |
+
+### 支持的操作类型
+
+| 数据库操作 | eventName 示例 |
+|-----------|---------------|
+| 新增记录 | `t_order.insert` |
+| 修改记录 | `t_order.update` |
+| 删除记录 | `t_order.delete` |
+
+### eventName 通配符匹配
+
+在 Workflow DSL 的 `event_trigger` 节点中配置 `eventName`：
+
+| eventName 配置 | 触发条件 |
+|---|---|
+| `t_order.insert` | 仅该表新增时触发 |
+| `t_order.update` | 仅该表修改时触发 |
+| `t_order.delete` | 仅该表删除时触发 |
+| `t_order.*` | 该表任何变更都触发 |
+| `*.insert` | 所有表的新增都触发 |
+
+### 使用步骤
+
+**Step 1：创建 outbox 表 + 通用触发器函数（只需执行一次）**
+
+```bash
+psql -d gadmin_demo -f temporal/sql/create-event-trigger.sql
+```
+
+**Step 2：给需要监听的表挂触发器**
+
+```sql
+-- 只监听 INSERT
+CREATE TRIGGER trg_order_workflow
+  AFTER INSERT ON t_order
+  FOR EACH ROW EXECUTE FUNCTION notify_workflow_event();
+
+-- 监听所有变更（INSERT + UPDATE + DELETE）
+CREATE TRIGGER trg_order_workflow
+  AFTER INSERT OR UPDATE OR DELETE ON t_order
+  FOR EACH ROW EXECUTE FUNCTION notify_workflow_event();
+
+-- 只在特定条件下触发（例如状态变为 APPROVED）
+CREATE OR REPLACE FUNCTION notify_order_approved() RETURNS trigger AS $$
+BEGIN
+  IF NEW.status = 'APPROVED' AND (OLD.status IS NULL OR OLD.status != 'APPROVED') THEN
+    INSERT INTO t_workflow_event_outbox (event_name, payload)
+    VALUES ('t_order.status_approved', row_to_json(NEW)::jsonb);
+  END IF;
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE TRIGGER trg_order_approved
+  AFTER UPDATE ON t_order
+  FOR EACH ROW EXECUTE FUNCTION notify_order_approved();
+```
+
+**Step 3：在 Workflow 编辑器中配置 event_trigger 节点**
+
+```json
+{
+  "type": "event_trigger",
+  "config": {
+    "eventName": "t_order.insert",
+    "filterExpression": "data.amount > 100"
+  }
+}
+```
+
+- `eventName`：匹配规则（支持通配符）
+- `filterExpression`（可选）：JS 表达式，对 payload 的过滤条件
+
+**Step 4：发布 Workflow**
+
+发布后 Worker 的 outbox-poller 会自动匹配新事件到该 Workflow。
+
+### 配置
+
+| 环境变量 | 默认值 | 说明 |
+|---------|--------|------|
+| `EVENT_POLL_INTERVAL_MS` | `10000` | 轮询间隔（毫秒） |
+
+### 注意事项
+
+- Outbox 表会持续增长，建议定期清理已处理的旧行（如保留 7 天）
+- 同一个 eventName 可以匹配多个 Workflow，它们会并行启动
+- `filterExpression` 在 Worker 侧求值，不满足条件的事件仍会写入 outbox 但不触发 workflow

package/dist/lib/application/files/gadmin2-game-angle-demo/temporal/config/development-sql.yaml

@@ -0,0 +1,5 @@
+# Temporal dynamic configuration for development
+# See: https://docs.temporal.io/references/dynamic-configuration
+system.forceSearchAttributesCacheRefreshOnRead:
+  - value: true
+    constraints: {}

package/dist/lib/application/files/gadmin2-game-angle-demo/temporal/docker-compose.yml

@@ -0,0 +1,25 @@
+services:
+  temporal:
+    image: temporalio/auto-setup:latest
+    ports:
+      - "7233:7233"
+    environment:
+      - DB=postgres12
+      - DB_PORT=5432
+      - POSTGRES_USER=kavenma
+      - POSTGRES_PWD=kavenma
+      - POSTGRES_SEEDS=host.docker.internal
+      - DYNAMIC_CONFIG_FILE_PATH=config/dynamicconfig/development-sql.yaml
+    volumes:
+      - ./config:/etc/temporal/config/dynamicconfig
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+
+  temporal-ui:
+    image: temporalio/ui:latest
+    ports:
+      - "8080:8080"
+    environment:
+      - TEMPORAL_ADDRESS=temporal:7233
+    depends_on:
+      - temporal

package/dist/lib/application/files/gadmin2-game-angle-demo/temporal/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "gadmin-temporal",
+  "private": true,
+  "scripts": {
+    "up": "docker compose up -d",
+    "down": "docker compose down",
+    "logs": "docker compose logs -f",
+    "worker:install": "cd worker && npm install",
+    "worker:dev": "cd worker && npm run dev",
+    "worker:build": "cd worker && npm run build",
+    "worker:start": "cd worker && npm start"
+  }
+}

package/dist/lib/application/files/gadmin2-game-angle-demo/temporal/sql/create-event-trigger.sql

@@ -0,0 +1,87 @@
+-- ============================================================================
+-- Workflow Event Trigger — Outbox Pattern (轮询方案)
+-- ============================================================================
+-- 当业务表发生 INSERT/UPDATE/DELETE 时，触发器将事件写入 outbox 表。
+-- Worker 的 outbox-poller 定时扫描未处理事件，匹配并触发对应的 workflow。
+--
+-- 优点：
+--   - 事务保证不丢事件（outbox INSERT 与业务操作在同一事务）
+--   - Worker 重启不会丢事件（积压事件恢复后立即处理）
+--   - 无需 PG LISTEN/NOTIFY，逻辑更简单
+--
+-- 使用方式：
+--   1. 执行本文件创建 outbox 表和通用触发器函数
+--   2. 对需要监听的表创建触发器（见下方示例）
+-- ============================================================================
+
+-- ─── Outbox 表 ───────────────────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS t_workflow_event_outbox (
+  id           BIGSERIAL PRIMARY KEY,
+  event_name   VARCHAR(128) NOT NULL,      -- e.g. "t_order.insert"
+  payload      JSONB NOT NULL,             -- 行数据
+  processed    BOOLEAN DEFAULT FALSE,
+  created_at   TIMESTAMP DEFAULT NOW(),
+  processed_at TIMESTAMP,
+  retry_count  INT NOT NULL DEFAULT 0,     -- 处理失败重试次数; >= MAX_RETRIES 视为终态失败
+  last_error   TEXT                        -- 最近一次失败的错误信息(成功时不清空,排障用)
+);
+
+-- 只扫未处理行的局部索引
+CREATE INDEX IF NOT EXISTS idx_outbox_unprocessed
+  ON t_workflow_event_outbox (created_at)
+  WHERE processed = FALSE;
+
+-- ─── 通用触发器函数 ──────────────────────────────────────────────────────────
+
+CREATE OR REPLACE FUNCTION notify_workflow_event() RETURNS trigger AS $$
+DECLARE
+  event_payload jsonb;
+  event_name text;
+BEGIN
+  -- 拼接事件名：表名.操作 (e.g. "t_order.insert")
+  event_name := TG_TABLE_NAME || '.' || lower(TG_OP);
+
+  -- 构建 payload
+  IF (TG_OP = 'DELETE') THEN
+    event_payload = row_to_json(OLD)::jsonb;
+  ELSE
+    event_payload = row_to_json(NEW)::jsonb;
+  END IF;
+
+  -- 写入 outbox（与业务操作同一事务，保证不丢）
+  INSERT INTO t_workflow_event_outbox (event_name, payload)
+  VALUES (event_name, event_payload);
+
+  RETURN COALESCE(NEW, OLD);
+END;
+$$ LANGUAGE plpgsql;
+
+-- ============================================================================
+-- 示例
+-- ============================================================================
+
+-- 监听 t_order 表的 INSERT
+-- CREATE TRIGGER trg_order_workflow
+--   AFTER INSERT ON t_order
+--   FOR EACH ROW EXECUTE FUNCTION notify_workflow_event();
+
+-- 监听 t_order 表的所有变更
+-- CREATE TRIGGER trg_order_workflow
+--   AFTER INSERT OR UPDATE OR DELETE ON t_order
+--   FOR EACH ROW EXECUTE FUNCTION notify_workflow_event();
+
+-- 只在特定条件下写入 outbox（例如状态变为 APPROVED）
+-- CREATE OR REPLACE FUNCTION notify_order_approved() RETURNS trigger AS $$
+-- BEGIN
+--   IF NEW.status = 'APPROVED' AND (OLD.status IS NULL OR OLD.status != 'APPROVED') THEN
+--     INSERT INTO t_workflow_event_outbox (event_name, payload)
+--     VALUES ('t_order.status_approved', row_to_json(NEW)::jsonb);
+--   END IF;
+--   RETURN NEW;
+-- END;
+-- $$ LANGUAGE plpgsql;
+--
+-- CREATE TRIGGER trg_order_approved
+--   AFTER UPDATE ON t_order
+--   FOR EACH ROW EXECUTE FUNCTION notify_order_approved();

package/dist/lib/application/files/gadmin2-game-angle-demo/temporal/worker/.env

@@ -0,0 +1,7 @@
+# Temporal Worker Environment
+TEMPORAL_ADDRESS=localhost:7233
+TEMPORAL_NAMESPACE=default
+TEMPORAL_TASK_QUEUE=workflow-execution
+
+# Database (same as server)
+DATABASE_URL=postgresql://kavenma:kavenma@127.0.0.1:5432/gadmin_demo?schema=public

package/dist/lib/application/files/gadmin2-game-angle-demo/temporal/worker/SANDBOX.md

@@ -0,0 +1,122 @@
+# Code 节点沙箱方案
+
+## 当前方案：Node.js `vm` 模块
+
+```typescript
+// activities/code-execute.ts
+const vm = await import('vm');
+const sandbox = { data, items, result: undefined };
+const context = vm.createContext(sandbox);
+new vm.Script(`result = (function() { ${script} })()`).runInContext(context, { timeout });
+```
+
+**优点：** 零依赖，零开销，简单直接
+**缺点：** 隔离性有限，恶意代码可通过原型链逃逸访问 Node.js API
+**适用：** 内部管理后台，脚本由可信管理员编写
+
+---
+
+## 备选方案：isolated-vm（强隔离）
+
+当需要执行**不可信用户代码**时，切换到 `isolated-vm`。
+
+### 什么是 isolated-vm
+
+- V8 引擎 Isolate 接口的 Node.js 封装
+- 在独立 V8 实例中执行代码，和主进程**零共享内存**
+- 无法访问 Node.js API（fs、net、process 等全部不可用）
+- 周下载量 100万+，生产级稳定
+- `vm2` 已停止维护（不可修复的逃逸漏洞），`isolated-vm` 是社区推荐替代
+
+### 层级结构
+
+```
+Isolate (V8 引擎实例)       ← 创建开销 ~5ms，可复用
+  └── Context (执行上下文)    ← 创建开销 <1ms，每次新建保证隔离
+        └── Script (编译后代码) ← 可缓存
+```
+
+### 推荐实现：复用 Isolate + 每次新 Context
+
+```typescript
+// activities/code-execute.ts（isolated-vm 版本）
+import ivm from 'isolated-vm';
+
+// Worker 启动时创建一个 Isolate（复用，不用每次新建）
+const isolate = new ivm.Isolate({ memoryLimit: 128 }); // 128MB 内存上限
+
+export async function codeExecute(input: CodeExecuteInput): Promise<CodeExecuteOutput> {
+  const { script, mode = 'runOnceForAll', timeout = 5000, data, items } = input;
+
+  if (mode === 'runOnceForEach' && Array.isArray(items)) {
+    const results: any[] = [];
+    for (const item of items) {
+      const result = await runInSandbox(script, { item, data }, timeout);
+      results.push(result);
+    }
+    return { result: results };
+  }
+
+  const result = await runInSandbox(script, { data, items: items || [] }, timeout);
+  return { result };
+}
+
+async function runInSandbox(
+  script: string,
+  globals: Record<string, any>,
+  timeout: number,
+): Promise<any> {
+  // 每次执行创建新 Context（<1ms），保证执行间完全隔离
+  const context = await isolate.createContext();
+
+  try {
+    const jail = context.global;
+
+    // 注入变量（深拷贝进 Isolate，主进程对象不可直接访问）
+    for (const [key, value] of Object.entries(globals)) {
+      await jail.set(key, new ivm.ExternalCopy(value).copyInto());
+    }
+
+    // 执行脚本
+    const wrapped = `(function() { ${script} })()`;
+    const result = await context.eval(wrapped, { timeout });
+
+    return result;
+  } finally {
+    context.release(); // 释放 Context 内存，Isolate 继续复用
+  }
+}
+```
+
+### 性能对比
+
+| 策略 | 每次执行开销 | 内存 |
+|------|------------|------|
+| 每次新建 Isolate | ~5ms | 每次分配独立堆 |
+| **复用 Isolate + 每次新 Context** | **<1ms** | 共享 Isolate 堆 |
+| 复用 Isolate + 复用 Context | ~0 | ⚠️ 执行间状态泄漏 |
+
+推荐第二种：性能和隔离性的最佳平衡。
+
+### 安全保障
+
+| 防护 | 说明 |
+|------|------|
+| 内存限制 | `memoryLimit: 128` → 超限直接 kill |
+| CPU 限制 | `timeout` 参数 → 超时抛异常 |
+| 网络隔离 | 无 `require`/`import`，无法访问 `net`/`http` |
+| 文件系统隔离 | 无 `fs` 模块 |
+| 进程隔离 | 无 `process`/`child_process` |
+| 原型链隔离 | 独立 V8 堆，原型链攻击无效 |
+
+### 何时切换
+
+- ✅ 当前 `vm` 方案：适用于内部可信用户（管理员自己写脚本）
+- 🔄 切换到 `isolated-vm`：当开放给外部用户或非技术人员编写脚本时
+
+### 切换步骤
+
+1. 依赖已在 `package.json` 中（`"isolated-vm": "^5.x"`）
+2. 替换 `activities/code-execute.ts` 的实现（如上）
+3. 接口不变，调用方无需修改
+4. 测试：验证 `runOnceForAll` 和 `runOnceForEach` 两种模式