@gadmin2n/schematics 0.0.87 → 0.0.89

package/dist/lib/application/files/gadmin2-game-angle-demo/compose-ctl.sh

@@ -0,0 +1,250 @@
+#!/usr/bin/env bash
+# compose-ctl.sh — gadmin 本地全栈 docker-compose 控制脚本
+#
+# 用法见 `./compose-ctl.sh -h`
+
+set -euo pipefail
+cd "$(dirname "$0")"
+
+# ─── 项目命名（pod / 镜像 prefix 都用这个） ─────────────────────
+# PROJECT_NAME 默认取项目目录的 basename，例如本项目为 "gadmin-test"。
+# - 镜像： <PROJECT_NAME>-{codegen,web,nest-server,temporal-worker}:local
+# - pod ： <PROJECT_NAME>-pod  （仅 podman-compose 有 pod 概念）
+# 通过 export COMPOSE_PROJECT_NAME 让 docker-compose.yml 中的
+# ${COMPOSE_PROJECT_NAME} 变量插值到正确的值。
+PROJECT_NAME="$(basename "$(pwd)")"
+export COMPOSE_PROJECT_NAME="$PROJECT_NAME"
+POD_NAME="${PROJECT_NAME}-pod"
+CODEGEN_IMAGE="${PROJECT_NAME}-codegen:local"
+
+# ─── 最低推荐版本（低于会打 warning 但仍尝试执行） ──────────────
+MIN_DOCKER="20.10"
+MIN_DOCKER_COMPOSE_V2="2.0.0"
+MIN_DOCKER_COMPOSE_V1="1.29.0"
+MIN_PODMAN="4.0.0"
+MIN_PODMAN_COMPOSE="1.0.7"
+
+# 从命令输出中抽取第一个 X.Y(.Z) 形式的版本号
+extract_semver() {
+  printf '%s' "$1" | grep -oE '[0-9]+\.[0-9]+(\.[0-9]+)?' | head -n1
+}
+
+# version_lt "1.0.6" "1.0.7" → 0 (true) 当 $1 < $2
+version_lt() {
+  [ "$1" = "$2" ] && return 1
+  [ "$(printf '%s\n%s\n' "$1" "$2" | sort -V | head -n1)" = "$1" ]
+}
+
+warn_if_old() {
+  local name="$1" actual="$2" minimum="$3"
+  if [ -z "$actual" ]; then
+    echo "[compose-ctl] WARN: 无法检测 $name 版本（最低推荐 $minimum）" >&2
+    return
+  fi
+  if version_lt "$actual" "$minimum"; then
+    echo "[compose-ctl] WARN: $name $actual < 最低推荐 $minimum" >&2
+    echo "[compose-ctl]       可能症状：profiles 不生效 / service_completed_successfully 被忽略 /" >&2
+    echo "[compose-ctl]       depends_on 顺序错乱 / 多阶段构建失败。建议升级。" >&2
+  fi
+}
+
+# ─── 运行时探测 ─────────────────────────────────────────────────
+# shell alias (alias docker=podman) 不会传到 bash 脚本里，所以这里要自己找。
+# DOCKER_CLI / COMPOSE_CLI 用数组以支持 "docker compose" 这种带空格的命令。
+DOCKER_CLI=()
+COMPOSE_CLI=()
+DOCKER_VER=""
+COMPOSE_VER=""
+COMPOSE_KIND=""   # 用于挑选最低推荐版本
+
+detect_runtime() {
+  if command -v docker >/dev/null 2>&1; then
+    DOCKER_CLI=(docker)
+    DOCKER_VER=$(extract_semver "$(docker --version 2>/dev/null)")
+    if docker compose version >/dev/null 2>&1; then
+      COMPOSE_CLI=(docker compose)
+      COMPOSE_VER=$(extract_semver "$(docker compose version 2>/dev/null)")
+      COMPOSE_KIND="docker-compose-v2"
+    elif command -v docker-compose >/dev/null 2>&1; then
+      COMPOSE_CLI=(docker-compose)
+      COMPOSE_VER=$(extract_semver "$(docker-compose --version 2>/dev/null)")
+      # v2 standalone 的版本号也是 2.x，v1 是 1.x
+      case "$COMPOSE_VER" in
+        2.*) COMPOSE_KIND="docker-compose-v2" ;;
+        *)   COMPOSE_KIND="docker-compose-v1" ;;
+      esac
+    fi
+  elif command -v podman >/dev/null 2>&1; then
+    DOCKER_CLI=(podman)
+    DOCKER_VER=$(extract_semver "$(podman --version 2>/dev/null)")
+    if command -v podman-compose >/dev/null 2>&1; then
+      COMPOSE_CLI=(podman-compose)
+      COMPOSE_VER=$(extract_semver "$(podman-compose --version 2>/dev/null | head -n1)")
+      COMPOSE_KIND="podman-compose"
+    elif command -v docker-compose >/dev/null 2>&1; then
+      COMPOSE_CLI=(docker-compose)
+      COMPOSE_VER=$(extract_semver "$(docker-compose --version 2>/dev/null)")
+      case "$COMPOSE_VER" in
+        2.*) COMPOSE_KIND="docker-compose-v2" ;;
+        *)   COMPOSE_KIND="docker-compose-v1" ;;
+      esac
+    fi
+  fi
+
+  if [ ${#DOCKER_CLI[@]} -eq 0 ]; then
+    echo "ERROR: 未找到 docker 或 podman" >&2
+    echo "提示：alias docker=podman 不会传到 bash 脚本，需要真实安装 docker 或 podman 二进制" >&2
+    exit 127
+  fi
+  if [ ${#COMPOSE_CLI[@]} -eq 0 ]; then
+    echo "ERROR: 找到了 ${DOCKER_CLI[*]} 但没找到 compose 命令" >&2
+    echo "提示：装 docker-compose 或 podman-compose" >&2
+    exit 127
+  fi
+
+  echo "[compose-ctl] runtime: ${DOCKER_CLI[*]} ${DOCKER_VER:-?} | compose: ${COMPOSE_CLI[*]} ${COMPOSE_VER:-?}"
+
+  # podman-compose 1.0.7+ 支持 --in-pod=NAME，让所有服务跑在同一个自定义命名 pod 里。
+  # docker-compose 没有 pod 概念，跳过。
+  COMPOSE_GLOBAL_ARGS=()
+  if [ "$COMPOSE_KIND" = "podman-compose" ]; then
+    COMPOSE_GLOBAL_ARGS+=(--in-pod="$POD_NAME")
+  fi
+
+  # 版本检查（只 warn 不 fail）
+  case "${DOCKER_CLI[0]}" in
+    docker) warn_if_old "docker"          "$DOCKER_VER"  "$MIN_DOCKER" ;;
+    podman) warn_if_old "podman"          "$DOCKER_VER"  "$MIN_PODMAN" ;;
+  esac
+  case "$COMPOSE_KIND" in
+    docker-compose-v2) warn_if_old "docker compose"  "$COMPOSE_VER" "$MIN_DOCKER_COMPOSE_V2" ;;
+    docker-compose-v1) warn_if_old "docker-compose"  "$COMPOSE_VER" "$MIN_DOCKER_COMPOSE_V1" ;;
+    podman-compose)    warn_if_old "podman-compose"  "$COMPOSE_VER" "$MIN_PODMAN_COMPOSE" ;;
+  esac
+}
+
+print_help() {
+  cat <<'EOF'
+compose-ctl.sh — gadmin-test 本地全栈 docker-compose 控制脚本
+
+用法:
+  ./compose-ctl.sh [up]        起服务（默认）。codegen 镜像不存在才构建，否则跳过。
+  ./compose-ctl.sh --rebuild   强制重建 codegen 后起服务。
+                               config/ui/** 或 config/prisma/** 改动后用。
+  ./compose-ctl.sh --reset     清数据卷 + 重建 codegen + 起服务（核武器）。
+                               业务数据、temporal 历史全部清空，回到种子数据状态。
+  ./compose-ctl.sh --down      停服务（保留数据）。
+  ./compose-ctl.sh -h, --help  显示本帮助。
+
+运行时:
+  脚本会自动探测 docker / podman，自动选择 compose 命令。
+  优先级: docker compose > docker-compose > podman-compose
+
+  最低推荐版本（低于会打 warning，不阻断执行）：
+    docker            >= 20.10
+    docker compose v2 >= 2.0    (插件形式 / 独立 v2 二进制)
+    docker-compose v1 >= 1.29   (legacy)
+    podman            >= 4.0
+    podman-compose    >= 1.0.7
+
+示例:
+  首次拉代码后:    ./compose-ctl.sh
+  改了 prisma:    ./compose-ctl.sh --rebuild
+  数据库脏了:     ./compose-ctl.sh --reset
+  下班关掉:       ./compose-ctl.sh --down
+EOF
+}
+
+print_post_up_guide() {
+  cat <<'EOF'
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  服务已启动 ✓   首次启动需等 30~60s 让 temporal-server 完成 schema 初始化
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+访问入口:
+  Web 前端          http://localhost:3000
+  Server API        http://localhost:8000          (健康检查 /health/live)
+  Temporal Web UI   http://localhost:8080
+  Temporal gRPC     localhost:7233                 (worker / @temporalio/client)
+  PostgreSQL        localhost:5432                 (用户 kavenma / 密码 kavenma)
+
+库划分 (PG 内):
+  gadmin_demo            业务库 (server + worker, Prisma 管理)
+  temporal               Temporal 元数据库
+  temporal_visibility    Temporal Visibility 库 (PG-only)
+
+常用命令:
+  查看所有服务状态        docker compose ps
+  跟某个服务日志          docker compose logs -f <service>
+                          (service: postgres / temporal-server / temporal-ui /
+                           temporal-worker / server / server-init / web)
+  跟全部日志              docker compose logs -f
+  重启某服务              docker compose restart <service>
+  进容器排查              docker compose exec <service> sh
+
+停止 / 重置:
+  停服务 (保留数据)        ./compose-ctl.sh --down
+  config 改了重建          ./compose-ctl.sh --rebuild
+  清空数据回到种子状态     ./compose-ctl.sh --reset
+
+提示:
+  · 前端开发请用 cd web && yarn dev (本 compose 的 web 是 nginx 静态镜像，无热更新)
+  · server-init 是一次性容器，跑完 push:db + seed 后退出 (Exited 0) 是正常的
+EOF
+}
+
+build_codegen() {
+  echo "[compose-ctl] building codegen image ($CODEGEN_IMAGE) ..."
+  "${COMPOSE_CLI[@]}" "${COMPOSE_GLOBAL_ARGS[@]}" --profile codegen build codegen
+}
+
+up_services() {
+  echo "[compose-ctl] starting services (project=$PROJECT_NAME, pod=$POD_NAME) ..."
+  "${COMPOSE_CLI[@]}" "${COMPOSE_GLOBAL_ARGS[@]}" up -d --build
+  print_post_up_guide
+}
+
+# ─── main ──────────────────────────────────────────────────────
+# 帮助命令不需要运行时，先处理
+case "${1:-up}" in
+  -h|--help)
+    print_help
+    exit 0
+    ;;
+esac
+
+detect_runtime
+
+case "${1:-up}" in
+  up)
+    if "${DOCKER_CLI[@]}" image inspect "$CODEGEN_IMAGE" >/dev/null 2>&1; then
+      echo "[compose-ctl] codegen image exists, skip build (use --rebuild to force)"
+    else
+      build_codegen
+    fi
+    up_services
+    ;;
+  --rebuild|-r)
+    build_codegen
+    # podman-compose 1.x 不会因镜像 ID 变化自动重建容器（docker-compose v2 会）。
+    # --rebuild 既然是为"改了配置/Dockerfile/代码"准备的，强制 recreate 才能让新镜像生效。
+    echo "[compose-ctl] (rebuild) force-recreating containers ..."
+    "${COMPOSE_CLI[@]}" "${COMPOSE_GLOBAL_ARGS[@]}" up -d --build --force-recreate
+    print_post_up_guide
+    ;;
+  --reset)
+    "${COMPOSE_CLI[@]}" "${COMPOSE_GLOBAL_ARGS[@]}" down -v
+    build_codegen
+    up_services
+    ;;
+  --down)
+    "${COMPOSE_CLI[@]}" "${COMPOSE_GLOBAL_ARGS[@]}" down
+    ;;
+  *)
+    echo "unknown option: $1" >&2
+    echo "" >&2
+    print_help >&2
+    exit 1
+    ;;
+esac

package/dist/lib/application/files/gadmin2-game-angle-demo/config/prisma/workflow.prisma

@@ -76,6 +76,7 @@ model WorkflowInstance {
   context         Json?
   result          Json?
   temporalRunId   String?                @db.VarChar(128) @map("temporal_run_id") // Temporal workflow run ID
+  sourceOutboxId  BigInt?                @map("source_outbox_id") // 触发本实例的 outbox 行 id；与 workflowId 组合后唯一，用于 outbox-poller 的幂等 upsert，避免崩溃恢复时产生重复 instance 行
   startedAt       DateTime?              @map("started_at")
   finishedAt      DateTime?              @map("finished_at")
   creator         String                 @default("") @db.VarChar(128) @map("creator")
@@ -85,6 +86,7 @@ model WorkflowInstance {
   workflow       Workflow @relation(fields: [workflowId], references: [id], onDelete: Cascade)
   nodeExecutions WorkflowNodeExecution[]
 
+  @@unique([workflowId, sourceOutboxId], map: "uk_wi_workflow_outbox") // 一个 outbox 事件对一个 workflow 至多一条 instance（NULL 不参与唯一性，正常 execute / cron / webhook 不受影响）
   @@index([workflowId], map: "idx_wi_workflow_id")
   @@index([status], map: "idx_wi_status")
   @@map("t_workflow_instance")
@@ -166,6 +168,7 @@ model WorkflowEventOutbox {
   retryCount  Int       @default(0) @map("retry_count")        // 处理失败重试次数
   lastError   String?   @db.Text @map("last_error")            // 最近一次失败的错误信息
 
-  @@index([createdAt], map: "idx_outbox_created_at")
+  // 注意：未处理事件的部分索引 idx_outbox_unprocessed 由 seed/workflow-event-trigger.ts 维护
+  // （Prisma schema 不支持 WHERE 子句的 partial index）
   @@map("t_workflow_event_outbox")
 }

package/dist/lib/application/files/gadmin2-game-angle-demo/dev/postgres/init.sql

@@ -0,0 +1,12 @@
+-- Bootstrap databases on first postgres container start.
+-- Runs once: only when the named volume `pgdata` is empty.
+-- Reset with `docker compose down -v` to re-run.
+--
+-- Three databases created here:
+--   gadmin_demo         -> server + worker business data (Prisma)
+--   temporal            -> Temporal Server default schema (auto-setup populates tables)
+--   temporal_visibility -> Temporal Server visibility schema (PG-only, no ES locally)
+
+CREATE DATABASE gadmin_demo;
+CREATE DATABASE temporal;
+CREATE DATABASE temporal_visibility;

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

@@ -0,0 +1,170 @@
+# 本地联调环境（docker-compose）
+
+一行命令起一整套服务用于本地集成验证：PostgreSQL + Temporal Server + Temporal Web UI + NestJS Server + Temporal Worker + Web 前端。
+
+> 生产部署走 K8s（参考 `docs/temporal-server-argocd.md`）。本环境**只**用于本地联调与端到端集成验证。
+
+## 启动 / 停止
+
+**推荐：用 `./compose-ctl.sh` 一键起，不用记 codegen 那一步。**
+
+```bash
+# 起所有服务（codegen 镜像不存在才构建，否则跳过）
+./compose-ctl.sh
+
+# 改了 config/ui/** 或 config/prisma/** 后，强制重建 codegen
+./compose-ctl.sh --rebuild
+
+# 完全重置：清数据卷 + 重建 codegen + 起服务（首启会重新初始化 schema/seed）
+./compose-ctl.sh --reset
+
+# 停服务（保留数据）
+./compose-ctl.sh --down
+```
+
+如果想用原生 `docker compose` 命令（脚本就是这两步的封装）：
+
+```bash
+# 起所有服务（后台）
+docker compose up -d
+
+# 跟日志（按 Ctrl+C 退出，服务继续运行）
+docker compose logs -f
+
+# 停服务（保留数据）
+docker compose down
+
+# 完全重置（连数据卷一起删，下次首启会重新初始化 schema）
+docker compose down -v
+
+# 重建某个镜像（改了 Dockerfile / 源码后）
+docker compose build server
+docker compose up -d server
+
+# 改了 config/ui/** 或 config/prisma/** 后，必须先 rebuild codegen 中间镜像
+docker compose --profile codegen build codegen
+docker compose build server web   # 让 server/web 拉到新的生成代码
+docker compose up -d server web
+```
+
+## 访问入口
+
+| 服务 | 地址 | 说明 |
+|------|------|------|
+| Web 前端 | http://localhost:3000 | 生产 nginx 镜像，**不支持热更新** |
+| Server API | http://localhost:8000 | NestJS，健康检查 `/health/live` |
+| Temporal Web UI | http://localhost:8080 | Workflow 可视化 |
+| Temporal gRPC | `localhost:7233` | Worker / `@temporalio/client` 连这里 |
+| PostgreSQL | `localhost:5432` | 用户 `kavenma` / 密码 `kavenma` |
+
+库划分：
+
+- `gadmin_demo` —— 业务库（server + worker 共用，Prisma 管理）
+- `temporal` —— Temporal 元数据库（auto-setup 自动建表）
+- `temporal_visibility` —— Temporal Visibility 库（PG-only，本地不开 ES）
+
+## 与 `temporal/docker-compose.yml` 的区别
+
+| 文件 | 内容 | 用途 |
+|------|------|------|
+| `docker-compose.yml`（本目录） | **完整**栈：PG + Temporal + Server + Worker + Web | 端到端集成验证 |
+| `temporal/docker-compose.yml` | 只有 Temporal Server + UI（连 host PG） | 只想跑 Temporal、复用本机 PG 时使用 |
+
+两个文件互不干扰，可单独使用。
+
+## 前端开发态：不要用本 compose
+
+本 compose 里的 `web` service 是 `nginx + 编译后静态文件`，改前端代码不会热更新。日常前端开发请：
+
+```bash
+cd web
+yarn dev   # Vite dev server，端口 5173，自带 HMR
+```
+
+让 Vite dev server 反代到本 compose 起的 `server`（http://localhost:8000）。
+
+后端开发同理：可以选择只起 `postgres` + `temporal-server` 这两个外部依赖：
+
+```bash
+docker compose up -d postgres temporal-server temporal-ui
+cd server && yarn start:dev
+```
+
+## 启动顺序（depends_on + healthcheck）
+
+```
+postgres (healthy: pg_isready)
+   ├─> server-init  (一次性容器：prisma db push + seed → exit 0)
+   │       ├─> server  (启动 API)
+   │       └─> temporal-worker  (并需 temporal-server healthy)
+   └─> temporal-server (healthy: temporal operator cluster health)
+           ├─> temporal-ui
+           └─> temporal-worker
+server (started)
+   └─> web
+```
+
+首次启动 Temporal 需要跑 schema 初始化（约 30~60s），期间 `temporal-server` 会处于 `starting`，依赖它的 worker 会等待。
+
+`server-init` 跑完 `prisma db push` + `seed` 就退出，`docker compose ps` 里它显示 `Exited (0)` 是正常的，不是故障 —— 见"常见问题"。
+
+## 常见问题
+
+### 端口冲突
+
+```bash
+# 看占用：
+lsof -iTCP:3000 -sTCP:LISTEN
+lsof -iTCP:5432 -sTCP:LISTEN
+lsof -iTCP:7233 -sTCP:LISTEN
+lsof -iTCP:8000 -sTCP:LISTEN
+lsof -iTCP:8080 -sTCP:LISTEN
+```
+
+如本机已有 PG 在 5432，可临时把 `docker-compose.yml` 里 postgres 的 ports 改成 `"5433:5432"`，并把 server / worker 的 `DATABASE_URL` host 改回 `postgres`（容器内通信不变，宿主机端口不影响 docker 网络）。
+
+### `server-init` 显示 `Exited (0)` 是 bug 吗？
+
+**不是。** `server-init` 是一次性容器，启动后跑 `prisma db push` 同步业务表结构，再跑 `seed` 灌默认数据，跑完就退出 ——`docker compose ps` 里看到状态 `Exited (0)` 即代表初始化成功。`server` / `temporal-worker` 在 `depends_on` 里声明了 `condition: service_completed_successfully` 等它跑完。
+
+> ⚠️ **podman-compose 1.x 注意**：实测对 `service_completed_successfully` 的支持不完整，`up -d` 时不会真的等 init 退出就启动 server/worker。NestJS 启动时不立即查表所以一般没问题，但严格的串行保证没了。真 docker-compose v2 没这问题。
+
+要看它做了什么：
+
+```bash
+docker compose logs server-init
+```
+
+如果状态是 `Exited (1)` 或更高，说明 push:db 或 seed 失败了，server / worker 不会启动。看日志排错后用 `docker compose up -d server-init` 重跑（幂等）。
+
+### Temporal schema 初始化失败
+
+```bash
+docker compose logs temporal-server | grep -i schema
+```
+
+最常见原因是 PG 没就绪 server 就启动了。`docker compose down -v` 重置后再 `up -d` 通常解决。
+
+### Server 启动后访问 401 / Cookie 失效
+
+server 镜像里 `TAIHU_*` 用的是 `server/.env` 默认值，对应太湖测试账号。如需走真实账号，先 `docker compose down`，把对应变量加到 shell 环境（或新建项目根 `.env` 文件，compose 会自动读取）后重启。
+
+### 重置数据库（清空所有业务数据）
+
+```bash
+./compose-ctl.sh --reset
+# 等 temporal-server 重新做 schema setup（看日志 `temporal-server` 里出现 "Temporal server started"）
+# server-init 会自动重跑 push:db + seed，业务库回到种子数据状态
+```
+
+## 用到的镜像
+
+| 镜像 | 版本 | 来源 |
+|------|------|------|
+| `postgres` | 15-alpine | docker hub 官方 |
+| `temporalio/auto-setup` | 1.29.6.1 | Docker Hub 上 auto-setup 当前最新（生产 Server 是 1.31.0，auto-setup tag 通常滞后；schema 兼容） |
+| `temporalio/ui` | latest | 仅 UI，跨版本兼容性好 |
+| `gadmin2-codegen:local` | 本地 build | `Dockerfile.codegen`，仅做 `gadmin2 g prisma`，被 server/web 镜像通过 `FROM ${CODEGEN_IMAGE}` 引用；同时被 `server-init` 直接复用其全量依赖 |
+| `gadmin-server` | 本地 build | `Dockerfile.server`，build context = 项目根，依赖 codegen 镜像 |
+| `gadmin-temporal-worker` | 本地 build | `temporal/worker/Dockerfile` |
+| `gadmin-web` | 本地 build | `Dockerfile.web`，nginx 静态镜像，依赖 codegen 镜像 |