@gadmin2n/schematics 0.0.88 → 0.0.90

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

@@ -48,8 +48,6 @@ temporal/
 ├── 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
@@ -120,6 +118,311 @@ npm run worker:dev
 7. Workflow 完成/失败 → 更新 t_workflow_instance 状态
 ```
 
+## 数据库表分工
+
+Temporal 体系下有 **两类 PG 表**，分布在不同 schema，互不干扰：
+
+| 类别 | 所在 schema | 谁来写 | 典型表 | 用途 |
+|------|------------|--------|--------|------|
+| **Temporal 系统表** | `temporal` (Server 启动时自动建表) | 仅 Temporal Server | `executions`、`history_node`、`history_tree`、`current_executions`、`task_queues`、`tasks`、`timer_tasks`、`shard`、`namespaces` | Workflow 状态机、事件历史、任务队列、定时器、分片协调 |
+| **业务表** | `public` (Prisma 管理) | NestJS / Worker Activity | `t_workflow`、`t_workflow_version`、`t_workflow_instance`、`t_workflow_node_execution`、`t_workflow_event_outbox` | 业务可见的工作流定义、实例、节点执行记录、事件触发 outbox |
+
+> Temporal Server **从不读写**业务表；业务代码（NestJS / Worker Activity）**从不读写** Temporal 系统表。两者通过 `temporal_run_id` 字段（保存在 `t_workflow_instance` 上）建立关联。
+
+## 两种触发场景的时序图
+
+### 场景 A：NestJS 主动调用 `temporalService.startWorkflow()`
+
+入口：用户在前端点 "Run"，或 Agenda 定时任务 / 其他业务代码主动调用 `WorkflowService.executeWorkflow()`。
+
+```
+┌────────┐   ┌──────────────────┐   ┌─────────────────┐   ┌────────────────┐   ┌────────────┐
+│Frontend│   │ NestJS           │   │ PostgreSQL      │   │ Temporal Server│   │ Worker     │
+│        │   │ WorkflowService  │   │ (业务 schema)    │   │ (gRPC :7233)   │   │ (long-poll)│
+└───┬────┘   └────────┬─────────┘   └────────┬────────┘   └───────┬────────┘   └─────┬──────┘
+    │ POST /run       │                      │                    │                   │
+    ├────────────────►│                      │                    │                   │
+    │                 │ SELECT t_workflow + t_workflow_version    │                   │
+    │                 ├─────────────────────►│                    │                   │
+    │                 │◄─────────────────────┤ 校验 PUBLISHED/enabled                  │
+    │                 │                      │                    │                   │
+    │                 │ INSERT t_workflow_instance (status=PENDING)│                   │
+    │                 ├─────────────────────►│                    │                   │
+    │                 │◄──── instanceId ─────┤                    │                   │
+    │                 │                      │                    │                   │
+    │                 │ temporalService.startWorkflow('dslWorkflow', …)               │
+    │                 ├──────────────────────────────────────────►│                   │
+    │                 │                      │  写 temporal.executions / history_node │
+    │                 │                      │  + 投递 WorkflowTask 到 task_queues    │
+    │                 │                      │◄───────────────────┤                   │
+    │                 │◄──── temporalRunId ──────────────────────┤                   │
+    │                 │                      │                    │                   │
+    │                 │ UPDATE t_workflow_instance SET temporal_run_id│                │
+    │                 ├─────────────────────►│                    │                   │
+    │                 │                      │                    │ PollWorkflowTask  │
+    │                 │                      │                    │◄──────────────────┤
+    │                 │                      │                    ├──── task ────────►│
+    │                 │                      │                    │                   │ 执行 dslWorkflow()
+    │                 │                      │                    │                   │ ──┐
+    │                 │                      │                    │ ScheduleActivity  │ <─┘
+    │                 │                      │                    │◄──────────────────┤
+    │                 │                      │                    ├── activity task ─►│
+    │                 │                      │                    │                   │ Activity 内调用
+    │                 │                      │                    │                   │ reporting.ts:
+    │                 │                      │◄────── INSERT/UPDATE t_workflow_node_execution ─┤
+    │                 │                      │◄────── UPDATE t_workflow_instance (RUNNING/DONE)┤
+    │                 │                      │                    │ CompleteActivity  │
+    │                 │                      │                    │◄──────────────────┤
+    │                 │                      │                    │                   │
+    │                 │                      │                    │ … 直到 Workflow 完成 …
+    │◄────── 200 OK { instanceId, temporalRunId } ────────────────┤                   │
+```
+
+**涉及的 PG 表：**
+
+| 表 | 操作 | 写入方 |
+|----|------|--------|
+| `t_workflow`、`t_workflow_version` | SELECT | NestJS（取 DSL + 校验状态） |
+| `t_workflow_instance` | INSERT (PENDING) → UPDATE (temporal_run_id) → UPDATE (status) | NestJS 创建；Worker `reporting.ts` 在执行中改 |
+| `t_workflow_node_execution` | INSERT/UPDATE 每个节点 | Worker `reporting.ts`（Activity 内调用） |
+| `temporal.executions` / `current_executions` | INSERT (新 WorkflowExecution) → UPDATE 状态 | Temporal Server（Frontend / History Service） |
+| `temporal.history_node` / `history_tree` | INSERT 事件（Started / ActivityScheduled / Completed …） | Temporal Server |
+| `temporal.task_queues` / `tasks` | INSERT/DELETE Workflow & Activity Task | Temporal Server（Matching Service） |
+| `temporal.timer_tasks` | 节点超时、Workflow 总超时、Sleep 节点 | Temporal Server |
+
+---
+
+### 场景 B：Worker `outbox-poller` 因业务表变更触发
+
+入口：业务表（如 `t_order`）发生 INSERT/UPDATE/DELETE → AFTER 触发器写一行到 `t_workflow_event_outbox` → Worker 进程内 outbox-poller 扫到。
+
+```
+┌────────────┐   ┌────────────────┐   ┌─────────────────────┐   ┌────────────────┐   ┌──────────────┐
+│ 业务来源    │   │ PostgreSQL     │   │ Worker              │   │ Temporal Server│   │ Worker       │
+│ (任意 INSERT│   │ (业务 schema)  │   │ outbox-poller.ts    │   │ (gRPC :7233)   │   │ dslWorkflow  │
+│  /UPDATE)  │   │                │   │ (Worker 进程内)     │   │                │   │ (同一进程)    │
+└─────┬──────┘   └───────┬────────┘   └──────────┬──────────┘   └───────┬────────┘   └──────┬───────┘
+      │ INSERT/UPDATE t_order                    │                      │                   │
+      ├─────────────────►│                       │                      │                   │
+      │                  │ AFTER TRIGGER notify_workflow_event()        │                   │
+      │                  │ INSERT t_workflow_event_outbox (同事务)       │                   │
+      │                  │                       │                      │                   │
+      │                  │ ◄── 每 10s ─────────  │ UPDATE outbox        │                   │
+      │                  │                       │ SET processed=true   │                   │
+      │                  │                       │ ... FOR UPDATE SKIP LOCKED                │
+      │                  ├──── 未处理事件批 ────►│                      │                   │
+      │                  │                       │                      │                   │
+      │                  │ SELECT t_workflow JOIN t_workflow_version    │                   │
+      │                  │ WHERE status='PUBLISHED' AND is_enabled      │                   │
+      │                  ├──────────────────────►│ matchEventName + filterExpression         │
+      │                  │                       │                      │                   │
+      │                  │ INSERT t_workflow_instance (creator='event_trigger')             │
+      │                  │◄──────────────────────┤                      │                   │
+      │                  ├──── instanceId ──────►│                      │                   │
+      │                  │                       │ temporalClient.workflow.start('dslWorkflow', …)
+      │                  │                       ├─────────────────────►│                   │
+      │                  │                       │                      │ 写 temporal.executions
+      │                  │                       │                      │ + 投递 WorkflowTask│
+      │                  │                       │◄────── runId ────────┤                   │
+      │                  │ UPDATE t_workflow_instance SET temporal_run_id│                   │
+      │                  │◄──────────────────────┤                      │                   │
+      │                  │                       │                      │ PollWorkflowTask  │
+      │                  │                       │                      │◄──────────────────┤
+      │                  │                       │                      ├──── task ────────►│
+      │                  │                       │                      │                   │ 执行节点 + Activity
+      │                  │◄──────── INSERT/UPDATE t_workflow_node_execution ─────────────────┤
+      │                  │◄──────── UPDATE t_workflow_instance (status, ended_at) ──────────┤
+      │                  │                       │                      │                   │
+      │                  │ (失败时) UPDATE t_workflow_event_outbox       │                   │
+      │                  │ SET processed=false, retry_count=n            │                   │
+      │                  │◄──────────────────────┤                      │                   │
+```
+
+**涉及的 PG 表：**
+
+| 表 | 操作 | 写入方 |
+|----|------|--------|
+| 业务表（如 `t_order`） | 任意 DML | 业务来源 |
+| `t_workflow_event_outbox` | INSERT（触发器，业务事务内）→ UPDATE processed/retry_count（poller） | DB Trigger + outbox-poller |
+| `t_workflow`、`t_workflow_version` | SELECT 已发布且启用的最新版本 | outbox-poller |
+| `t_workflow_instance` | INSERT (PENDING, creator='event_trigger') → UPDATE temporal_run_id → UPDATE status | outbox-poller 创建；Worker `reporting.ts` 在执行中改 |
+| `t_workflow_node_execution` | INSERT/UPDATE 每个节点 | Worker `reporting.ts` |
+| `temporal.executions` / `history_node` / `task_queues` / `tasks` / `timer_tasks` | 同场景 A | Temporal Server |
+
+---
+
+---
+
+### 场景 C：Temporal Schedule API（定时任务触发，`cron_trigger`）
+
+> ✅ **当前状态**：已实现。`WorkflowService.publish()` 解析 DSL 中的 `cron_trigger` 节点，调 `TemporalService.upsertCronSchedule()` 注册 Temporal Schedule；`toggleEnabled` / `remove` 联动 pause/unpause/delete schedule。Worker 新增 `cronTriggerWorkflow`，由 Schedule 触发后创建 `t_workflow_instance(creator='cron')` 并以子工作流方式执行 `dslWorkflow`。
+
+入口：Workflow 中包含 `cron_trigger` 节点（带 `cronExpression` 配置），点击 Publish 时由 NestJS 把 cron 表达式注册到 Temporal Server 的 Schedule 子系统；之后由 **Server 自己**按时间触发，无需 NestJS / Worker 长跑组件。
+
+```
+┌────────┐   ┌──────────────────┐   ┌─────────────────┐   ┌──────────────────────────┐   ┌────────────┐
+│Frontend│   │ NestJS           │   │ PostgreSQL      │   │ Temporal Server          │   │ Worker     │
+│        │   │ WorkflowService  │   │ (业务 schema)    │   │ (Schedule + Workflow)    │   │ (long-poll)│
+└───┬────┘   └────────┬─────────┘   └────────┬────────┘   └───────┬──────────────────┘   └─────┬──────┘
+    │ POST /:id/publish│                     │                    │                             │
+    ├────────────────►│                      │                    │                             │
+    │                 │ 解析 DSL：找 cron_trigger 节点              │                             │
+    │                 │ UPDATE t_workflow SET status='PUBLISHED'   │                             │
+    │                 ├─────────────────────►│                    │                             │
+    │                 │                      │                    │                             │
+    │                 │ client.schedule.create({                  │                             │
+    │                 │   scheduleId: `wf-${workflowId}-cron`,    │                             │
+    │                 │   spec:{ cronExpressions:['0 2 * * *'] }, │                             │
+    │                 │   action:{ type:'startWorkflow',          │                             │
+    │                 │     workflowType:'cronTriggerWorkflow',   │                             │
+    │                 │     args:[{ workflowId, versionId, dsl }] │                             │
+    │                 │   }                                       │                             │
+    │                 │ })                                        │                             │
+    │                 ├──────────────────────────────────────────►│                             │
+    │                 │                      │                    │ Server 写 temporal.schedules + │
+    │                 │                      │                    │ 内部 timer 任务              │
+    │                 │◄──── ok ──────────────────────────────────┤                             │
+    │◄── 200 OK ──────┤                      │                    │                             │
+    │                 │                      │                    │                             │
+    ⋮                 ⋮                      ⋮         (等到 cron 时间到，Server 自动起 Workflow)  ⋮
+    │                 │                      │                    │                             │
+    │                 │                      │                    │ Server: 写 executions /     │
+    │                 │                      │                    │ history_node + 投 WorkflowTask│
+    │                 │                      │                    │                             │
+    │                 │                      │                    │             PollWorkflowTask│
+    │                 │                      │                    │◄────────────────────────────┤
+    │                 │                      │                    ├──── task ──────────────────►│
+    │                 │                      │                    │                             │ 1) cronTriggerWorkflow:
+    │                 │                      │                    │                             │   Activity:createInstance
+    │                 │                      │ INSERT t_workflow_instance (creator='cron')      │
+    │                 │                      │◄──────────────────────────────────────────────── ┤
+    │                 │                      │                    │                             │ 2) executeChildWorkflow
+    │                 │                      │                    │                             │   ('dslWorkflow', { instanceId, dsl, … })
+    │                 │                      │                    │                             │ ─→ 与场景 A 第 5 步起完全一致
+    │                 │                      │ INSERT/UPDATE t_workflow_node_execution          │
+    │                 │                      │◄──────────────────────────────────────────────── ┤
+    │                 │                      │ UPDATE t_workflow_instance (status, ended_at)    │
+    │                 │                      │◄──────────────────────────────────────────────── ┤
+```
+
+**编辑/取消调度时：**
+
+| 用户操作 | NestJS 调用 | 说明 |
+|----------|-------------|------|
+| 修改 cron 表达式（发布新版本） | `client.schedule.getHandle(id).update(...)` | 原 schedule 改 spec，不会丢历史 |
+| 暂停 / 启用 Workflow | `handle.pause()` / `handle.unpause()` | Server 跳过触发但保留 schedule |
+| 删除 Workflow / 取消发布 | `handle.delete()` | 同时清掉 schedule，避免遗留 |
+
+**涉及的 PG 表：**
+
+| 表 | 操作 | 写入方 |
+|----|------|--------|
+| `t_workflow` | UPDATE status | NestJS（发布动作） |
+| `t_workflow_instance` | INSERT (creator='cron') → UPDATE status | Worker `cronTriggerWorkflow` 内的 createInstance Activity |
+| `t_workflow_node_execution` | INSERT/UPDATE | Worker `reporting.ts` |
+| `temporal.schedules` / `schedules_by_namespace` | INSERT/UPDATE/DELETE schedule 记录 | Temporal Server（Frontend Service） |
+| `temporal.executions` / `history_node` / `task_queues` | 同场景 A | Temporal Server（Schedule 触发后） |
+
+**为什么不用 outbox-poller 模式 / AgendaService？**
+
+| 方案 | 缺点 |
+|------|------|
+| Worker 内 cron-poller（仿 outbox-poller） | 多 Worker 实例需自己加分布式锁，且会跟 Temporal 状态机割裂 |
+| 复用 AgendaService | Agenda 跑在 NestJS 进程，Workflow 调度跨两个时序源，故障定位复杂 |
+| **Temporal Schedule API** ✅ | Server 原生支持，自动持久化到 `temporal.schedules`，UI 可见、支持 pause/backfill/skip |
+
+---
+
+### 场景 D：NestJS Public 端点（外部 webhook 触发，`webhook_trigger`）
+
+> ✅ **当前状态**：已实现（HMAC 严格模式）。`POST /api/workflow/webhook/:path` 由 `WorkflowController.receiveWebhook` 接收，路由用 `@AllowUnauthorizedRequest()` 跳过登录态。请求必须带 `X-Workflow-Timestamp`（±5min）+ `X-Workflow-Signature: sha256=HEX(HMAC_SHA256(secret, "{ts}.{rawBody}"))`。验签失败 / 路径未匹配 / 时间戳过期分别返回 401 / 404 / 401。
+
+入口：外部系统（如 GitHub / Stripe / 内部其他服务）按 Workflow 编辑器配置的 `webhookPath` 发 HTTP 请求 → NestJS 公开路由（无需登录态）匹配 published workflow 并复用 `executeWorkflow()` 流程。
+
+```
+┌──────────┐   ┌────────────────────┐   ┌──────────────────┐   ┌─────────────────┐   ┌────────────────┐   ┌────────────┐
+│ 外部系统  │   │ NestJS             │   │ NestJS           │   │ PostgreSQL      │   │ Temporal Server│   │ Worker     │
+│ (任何 HTTP│   │ WebhookController  │   │ WorkflowService  │   │ (业务 schema)    │   │ (gRPC :7233)   │   │ (long-poll)│
+│  客户端)  │   │ @Public            │   │                  │   │                 │   │                │   │            │
+└────┬─────┘   └──────────┬─────────┘   └────────┬─────────┘   └────────┬────────┘   └───────┬────────┘   └─────┬──────┘
+     │ POST /api/workflow/webhook/:path          │                      │                    │                   │
+     │ Headers: X-Signature, body=payload        │                      │                    │                   │
+     ├──────────────────►│                       │                      │                    │                   │
+     │                   │ (可选) 校验签名 / IP 白名单                    │                      │                    │
+     │                   │                       │                      │                    │                   │
+     │                   │ SELECT workflow JOIN version 找含 webhook_trigger 节点          │                   │
+     │                   │ 且 config.webhookPath = :path 的最新发布版本                       │                   │
+     │                   ├──────────────────────────────────────────────►│                    │                   │
+     │                   │◄──────── 0 / 1 / N 个匹配 workflow ───────────┤                    │                   │
+     │                   │                       │                      │                    │                   │
+     │                   │ 对每个匹配的 workflow（通常仅 1 个）：           │                      │                    │
+     │                   │ executeWorkflow(workflowId, { context: { headers, query, body } }, creator='webhook')   │
+     │                   ├──────────────────────►│                      │                    │                   │
+     │                   │                       │ INSERT t_workflow_instance (creator='webhook', context=请求体)   │
+     │                   │                       ├─────────────────────►│                    │                   │
+     │                   │                       │◄────── instanceId ───┤                    │                   │
+     │                   │                       │                      │                    │                   │
+     │                   │                       │ temporalService.startWorkflow('dslWorkflow', …)               │
+     │                   │                       ├──────────────────────────────────────────►│                   │
+     │                   │                       │                      │ 写 executions / history_node          │
+     │                   │                       │                      │ + 投 WorkflowTask  │                   │
+     │                   │                       │◄────── runId ────────────────────────────┤                   │
+     │                   │                       │ UPDATE t_workflow_instance SET temporal_run_id│                │
+     │                   │                       ├─────────────────────►│                    │                   │
+     │                   │◄── { instanceId } ────┤                      │                    │ PollWorkflowTask  │
+     │                   │                       │                      │                    │◄──────────────────┤
+     │◄── 202 Accepted { instanceIds } ──────────┤                      │                    ├── task ──────────►│
+     │ (异步：webhook 立刻返回，工作流后台跑)        │                      │                    │                   │ 执行 dslWorkflow
+     │                   │                       │                      │ INSERT/UPDATE t_workflow_node_execution│
+     │                   │                       │                      │◄──────────────────────────────────────┤
+     │                   │                       │                      │ UPDATE t_workflow_instance (status)   │
+     │                   │                       │                      │◄──────────────────────────────────────┤
+```
+
+**关键设计点：**
+
+| 关注点 | 推荐做法 |
+|--------|----------|
+| 鉴权 | NestJS Controller 用 `@Public()` 跳过登录态，但每个 workflow 自带 `webhookSecret`，请求需带 `X-Signature: HMAC_SHA256(secret, body)` |
+| 路径冲突 | `webhookPath` 必须在 published workflow 间唯一（Publish 时校验冲突，或用 `wf_${workflowId}` 做后缀） |
+| 同步 vs 异步 | 默认异步：返回 `202 Accepted { instanceId }`，由前端轮询 `/instance/:id` 看结果。同步模式可选：等到 workflow 完成再返回（注意网关超时） |
+| 多 workflow 订阅同一路径 | 与 outbox 一致：并行启动多个 instance，各自独立 |
+| 重放保护 | 校验 `X-Timestamp` 在 ±5min 内 + payload 哈希做去重（可选，存 Redis 5min TTL） |
+
+**涉及的 PG 表：**
+
+| 表 | 操作 | 写入方 |
+|----|------|--------|
+| `t_workflow`、`t_workflow_version` | SELECT 含 `webhook_trigger` 节点的最新发布版本 | NestJS `WebhookController` |
+| `t_workflow_instance` | INSERT (creator='webhook') → UPDATE temporal_run_id → UPDATE status | NestJS 创建；Worker `reporting.ts` 改状态 |
+| `t_workflow_node_execution` | INSERT/UPDATE | Worker `reporting.ts` |
+| `temporal.executions` / `history_node` / `task_queues` | 同场景 A | Temporal Server |
+
+**为什么不让 Worker 自己开 HTTP 端口接收 webhook？**
+
+- Worker 是无状态计算节点，不应面向公网；外部网络/网关/WAF 都暴露在 NestJS 那一层
+- NestJS 已有完善的 Guard、Logger、Swagger、错误处理体系，复用更合适
+- 校验签名、限流、IP 白名单等都属于"边界关注点"，归属 Web 层
+
+---
+
+### 一句话对比（四种触发场景）
+
+| | 场景 A：NestJS startWorkflow | 场景 B：Outbox Poller | 场景 C：Temporal Schedule | 场景 D：NestJS Webhook |
+|--|------------------------------|------------------------|----------------------------|--------------------------|
+| **当前状态** | ✅ 已实现 | ✅ 已实现 | ✅ 已实现 | ✅ 已实现（HMAC 严格） |
+| 触发点 | 用户/定时业务调用 NestJS | 业务表 DML → 触发器 → outbox | Server 内置 cron 调度 | 外部 HTTP POST |
+| 入口节点 | （任何，无 trigger 节点） | `event_trigger` | `cron_trigger` | `webhook_trigger` |
+| 谁创建 `t_workflow_instance` | NestJS `WorkflowService` | Worker `outbox-poller` | Worker（cronTriggerWorkflow 内 Activity） | NestJS `WorkflowService` |
+| 谁调用 `workflow.start()` | NestJS `TemporalService` | Worker `outbox-poller` | **Temporal Server 自己**（Schedule 系统） | NestJS `TemporalService` |
+| 是否走 Temporal Server | ✅ | ✅ | ✅（且 schedule 本身也由 Server 持久化） | ✅ |
+| `creator` 字段 | 登录用户 | `'event_trigger'` | `'cron'` | `'webhook'` |
+| 触发延迟 | <100ms | ≤ 轮询间隔（默认 10s） | 由 Server 内部 timer 控制（秒级精度） | <100ms |
+| 失败重试 | Workflow/Activity 自带重试 | outbox 行重试 ≤ `OUTBOX_MAX_RETRIES` | Schedule 不重试触发；Workflow 内部正常重试 | NestJS 直接返回 4xx/5xx；webhook 客户端自己决定是否重投 |
+| 多实例并发安全 | NestJS 多 Pod 各自 OK | `FOR UPDATE SKIP LOCKED` 防重复消费 | Server 单一 schedule 实例，天然不重复 | NestJS 多 Pod 各自 OK |
+
+**关键点：** 不论从哪个入口触发，只要调用了 `temporalClient.workflow.start()`（或 Schedule 间接调用），就一定要经过 Temporal Server 的调度（写 history → 入 task queue → Worker long-poll 拉取），Server 是**唯一的状态权威**。Worker 内部直接读写业务表只发生在 Activity 执行阶段（`reporting.ts` 写 `t_workflow_node_execution` / `t_workflow_instance`，outbox-poller 写 outbox 与 instance），这是绕不过 Server 的——但写 Workflow 历史和调度本身仍由 Server 完成。
+
 ## 环境变量
 
 | 变量 | 默认值 | 说明 |
@@ -213,10 +516,16 @@ npm run worker:start # 生产模式启动 Worker
 
 **Step 1：创建 outbox 表 + 通用触发器函数（只需执行一次）**
 
+Outbox 表 `t_workflow_event_outbox` 由 Prisma 模型 `WorkflowEventOutbox` 维护，跟随 `prisma migrate` 流程自动建表；通用触发器函数 `notify_workflow_event()` 和未处理事件的部分索引 `idx_outbox_unprocessed` 由 seed 脚本创建：
+
 ```bash
-psql -d gadmin_demo -f temporal/sql/create-event-trigger.sql
+# server 目录
+cd server
+yarn seed
 ```
 
+幂等可重复执行。详见 `server/seed/workflow-event-trigger.ts`。
+
 **Step 2：给需要监听的表挂触发器**
 
 ```sql

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

@@ -0,0 +1,152 @@
+# Temporal Worker — 后续改造 TODO
+
+本文档汇总 worker 在"重启 / 升级"场景下还可以做的改造。
+已完成项不在此列；当前已完成：
+
+- ✅ DSL 图环检测（`dsl-workflow.ts` `executeGraph` 加迭代上限）
+- ✅ Outbox Poller 事务边界（每行一个事务 + 确定性 workflowId 幂等保护）
+- ✅ Graceful Shutdown（`worker.shutdown()` + `outboxPoller.stop()` + health server）
+- ✅ Outbox 重试时 t_workflow_instance 残留行 —— `WorkflowInstance` 加 `sourceOutboxId`，`(workflow_id, source_outbox_id)` 复合 UNIQUE，`matchAndTrigger` 改为 `INSERT ... ON CONFLICT DO UPDATE`
+- ✅ DSL 提交时 DAG 校验（`dsl-validate.util.ts` + 在 `WorkflowService.publish()` 调用，循环图 / 缺 trigger / 重复 id / 悬空 edge 全部 400）
+- ✅ Activity Timeout 分级（`httpActs` / `dbActs` / `notifyActs` / `codeActs` / `reportActs` 各自独立 timeout & retry policy）
+
+---
+
+## P0 — Activity 缺少 Heartbeat 与 Cancellation 响应
+
+**位置**：`src/activities/http-request.ts`、`db-query.ts`、`db-execute.ts`、`code-execute.ts`
+
+**问题**：Activity 不调 `Context.current().heartbeat()`，也不监听 `Context.current().cancellationSignal`。
+Worker 收到 SIGTERM 后 `worker.shutdown()` 会向 in-flight Activity 发 cancel，但当前实现完全不响应，
+必须等 `startToCloseTimeout: 60s` 自然超时。极端场景（HTTP 卡住、code-execute vm timeout 失效）
+会一直占用 worker 进程到 grace period 结束被 SIGKILL，Temporal 端再等心跳超时才能重派。
+
+**改造示例（http-request）**：
+
+```ts
+import { Context } from '@temporalio/activity';
+
+export async function httpRequest(input: HttpRequestInput): Promise<HttpRequestOutput> {
+  const ctx = Context.current();
+  const controller = new AbortController();
+  ctx.cancellationSignal.addEventListener('abort', () => controller.abort());
+
+  const heartbeatTimer = setInterval(() => ctx.heartbeat(), 5_000);
+  try {
+    const response = await axios({ ...axiosConfig, signal: controller.signal });
+    return { status: response.status, data: response.data, headers: response.headers as any };
+  } finally {
+    clearInterval(heartbeatTimer);
+  }
+}
+```
+
+**db-query / db-execute**：把 PG client 的 query 包成可取消（pg 8.x 支持 `client.cancel()`），
+并在每条长查询前 `ctx.heartbeat()`。
+
+**code-execute**：vm 不支持外部中断，至少应在 `runOnceForEach` 每个 item 之间检查 `ctx.cancellationSignal.aborted` 并提前 return。
+
+---
+
+## P1 — Worker Build IDs (Workflow Versioning)
+
+**问题**：`src/index.ts` 的 `Worker.create({...})` 没有传 `buildId`。
+所有版本的 worker 都从同一 task queue 拉 task，包括老 workflow 的 history replay。
+`dsl-workflow.ts` 是动态解释器，但解释器自身的代码改动也会破坏 determinism：
+
+- 改 BFS 调度顺序（`queue.shift`）→ 老 workflow replay 失败
+- 改 `for_each` 的 batch concurrency 处理 → 老 workflow replay 失败
+- 改 `parallel` 的 `Promise.all` vs `Promise.race` → 老 workflow replay 失败
+
+**改造**：
+
+```ts
+const worker = await Worker.create({
+  connection,
+  namespace: config.temporal.namespace,
+  taskQueue: config.temporal.taskQueue,
+  workflowsPath: require.resolve('./workflows/dsl-workflow'),
+  activities,
+  buildId: process.env.WORKER_BUILD_ID || require('../package.json').version,
+  useVersioning: true,
+});
+```
+
+部署时还需通过 Temporal CLI 把新 buildId 标记为 default：
+
+```bash
+temporal task-queue versioning add-new-default \
+  --task-queue workflow-execution \
+  --build-id v1.2.0
+```
+
+> Temporal 1.21+ 支持 Worker Build IDs；1.24+ 有更易用的 Worker Deployment API，可一并评估。
+
+---
+
+## P1 — `for_each` 节点不响应 Cancel
+
+**位置**：`src/workflows/dsl-workflow.ts` 的 `for_each` 分支（约 L319-355）
+
+**问题**：item 数量很大时（比如 1000 条），`for (let i = 0; i < items.length; i += concurrency)`
+循环中途用户/系统 cancel 不会立即退出，必须等循环跑完。
+
+**改造**：每个 batch 前检查 cancel 标志：
+
+```ts
+for (let i = 0; i < items.length; i += concurrency) {
+  if (isCancelled()) throw new CancellationScope().cancel;   // ← 加这一行
+  const batch = items.slice(i, i + concurrency);
+  // ...
+}
+```
+
+---
+
+## P2 — Activity Timeout 业务级覆盖
+
+**当前状态**：dsl-workflow.ts 已按职责类别拆出 `httpActs` / `dbActs` / `notifyActs` / `codeActs` / `reportActs`，
+各自 timeout 和 retry 独立。但仍是**类别级**配置，业务在 DSL 里指定 `input.timeout` 只透传到 axios/vm 内部，
+没法影响 Temporal Activity 的 `startToCloseTimeout`。
+
+**进一步改造**：通过 `Context.current().heartbeat()` + 业务级 timeout 透传，让 DSL 的 `config.timeoutSec`
+也能影响 Activity 调度层。例如：
+
+```ts
+case 'http_request': {
+  const proxyOpts = config.timeoutSec
+    ? { startToCloseTimeout: `${config.timeoutSec}s`, retry: { maximumAttempts: 3 } }
+    : undefined;
+  const httpProxy = proxyOpts
+    ? proxyActivities<...>({ ...proxyOpts })
+    : httpActs;
+  return { output: await httpProxy.httpRequest(config as any) };
+}
+```
+
+**注意**：Workflow 内 `proxyActivities` 是确定性配置，运行时动态创建会破坏 replay。
+更稳妥的做法是预先创建 N 个 timeout 档（如 30s / 120s / 600s），DSL 指定档位而非任意数值。
+
+---
+
+## P3 — 进程级兜底 + Health Server 强断
+
+**位置**：`src/index.ts`
+
+```ts
+// 缺崩溃日志兜底
+process.on('uncaughtException', (err) => {
+  console.error('[Worker] uncaughtException:', err);
+  void shutdown('uncaughtException');
+  setTimeout(() => process.exit(1), 30_000).unref();
+});
+process.on('unhandledRejection', (reason) => {
+  console.error('[Worker] unhandledRejection:', reason);
+});
+
+// healthServer.close() 不会主动断 keep-alive 连接，K8s probe 长连接会拖慢退出
+await new Promise<void>((resolve) => {
+  healthServer.close(() => resolve());
+  healthServer.closeAllConnections?.();   // Node 18.2+
+});
+```

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

@@ -0,0 +1,12 @@
+node_modules
+dist
+.env.*
+.git
+*.log
+.claude
+.vscode
+.idea
+tests
+vitest.config.ts
+*.md
+coverage

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

@@ -0,0 +1,79 @@
+# syntax=docker/dockerfile:1
+#
+# Temporal Worker 镜像
+#
+# Build context: temporal/worker/
+#   docker build -t gadmin-workflow-worker -f temporal/worker/Dockerfile temporal/worker
+#
+# Worker 通过 require.resolve('./workflows/dsl-workflow') 在运行时加载已编译的
+# workflow JS，无需 bundleWorkflowCode 预打包。
+#
+# 为什么用 node:20-slim 不用 node:20-alpine：
+#   @temporalio/core-bridge 的 native binding 是 glibc 二进制。alpine 用 musl libc，
+#   会在 require 时报 "Error relocating ...: __register_atfork: symbol not found" 直接崩。
+#   slim 是 debian-bookworm-slim 基底，glibc，体积也只比 alpine 大几十 MB。
+
+# ─── 阶段 1：构建 ────────────────────────────────────────────
+FROM node:20-slim AS builder
+
+WORKDIR /app
+
+# 禁止 husky 在无 .git 环境下报错
+ENV HUSKY=0
+
+# 先复制依赖描述文件，源码未变时此层可复用缓存
+COPY package.json yarn.lock ./
+
+# 安装全量依赖（含 devDependencies，用于 TypeScript 编译）
+RUN --mount=type=cache,target=/root/.yarn \
+    yarn install --frozen-lockfile
+
+# 复制源码与 tsconfig
+COPY tsconfig.json ./
+COPY src/ ./src/
+
+# 编译 TypeScript → dist/
+RUN yarn build
+
+# ─── 阶段 2：运行 ────────────────────────────────────────────
+FROM node:20-slim AS runner
+
+# 时区：与 server 保持一致。debian-slim 不预装 tzdata，需要 apt 装一下。
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends tzdata && \
+    rm -rf /var/lib/apt/lists/* && \
+    ln -snf /usr/share/zoneinfo/Asia/Shanghai /etc/localtime && \
+    echo "Asia/Shanghai" > /etc/timezone
+ENV TZ=Asia/Shanghai
+
+WORKDIR /app
+
+# 优雅关闭：让 Node 进程（PID 1）直接收到 SIGTERM 后调用 worker.shutdown()
+STOPSIGNAL SIGTERM
+
+ENV HUSKY=0 \
+    NODE_ENV=production
+
+# 先复制依赖描述文件
+COPY --chown=node:node package.json yarn.lock ./
+
+# 只安装 production 依赖，大幅减少镜像体积
+RUN --mount=type=cache,target=/root/.yarn \
+    yarn install --production --frozen-lockfile
+
+# 从构建阶段复制编译产物（不带源码）
+COPY --from=builder --chown=node:node /app/dist ./dist
+
+# 切换到非 root 用户（node 镜像内置 uid/gid 1000）
+USER node
+
+# Worker 仅出站连接 Temporal Server (7233) 与 PostgreSQL；额外暴露 :8081 供 K8s probe 访问 health 端点
+EXPOSE 8081
+
+# 容器健康检查：调用 worker 内置的 /health/live 端点。
+# debian-slim 不带 wget/curl，用 node 自带 http 模块代替（零额外依赖、~10ms 开销）。
+HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=3 \
+    CMD node -e "require('http').get('http://127.0.0.1:8081/health/live',r=>process.exit(r.statusCode===200?0:1)).on('error',()=>process.exit(1))" || exit 1
+
+# exec form 确保 node 作为 PID 1 直接接收 SIGTERM
+CMD ["node", "dist/index.js"]