@gadmin2n/schematics 0.0.150 → 0.0.152

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

@@ -1,41 +1,43 @@
 ## 项目简介
+
 - 本项目由 lowcode 生成工具 Gadmin2 生成：Admin page(CRUD) + Dashboard，包括前端和后端。
 - 前端的 Admin page(CRUD) 代码由配置（`config/ui/{ModelName}.ts`）驱动生成，后端的数据模型和 CRUD 代码由 prisma schema（`config/prisma/{module}.prisma`）驱动生成。
+- 项目使用的 ai coding context（`.agent/*`、`.codebuddy/*`）相关文件需要使用 `gadmin2 update --coding-context` 来安装和更新。
 
 ## 常用命令
 
 ```bash
-# 改了 config/prisma/*.prisma —— 迁移数据库 + 生成前后端代码
-gadmin2 g prisma:dev
-
-# 只改了 config/ui/*.ts —— 只生成代码，不碰数据库
-gadmin2 g prisma
-
 cd server && yarn start:dev   # 后端，端口 8000（优先读 server/.env.local）
-cd web && yarn dev            # 前端，端口 3000（注意web/ 用 yarn，不用 npm）
-cd server && yarn seed # 执行 seed（页面/资源/权限声明）
+cd web && yarn dev            # 前端，端口 3000（优先读 web/.env.local）
+cd server && yarn seed        # 执行 seed（页面/资源/权限声明）
 ```
 
-> gadmin2 命令需要在项目根目录执行
+## 架构概览
 
-## Architecture Overview
+### 前端技术栈
 
-### Frontend Tech Stack
 React 18, TypeScript, Vite, Ant Design v5, Refinedev, ECharts, i18next
 
 ```
 web/src/
-├── routes/         #页面模块：user/、role/ 等
-├── components/     # 共享 UI 组件（PageHeader、RowActions、SearchBar 等）
-├── hooks/          # 自定义 hooks（useECharts、useDynamicResources、useListPageState 等）
-├── providers/      # auth / data / access control provider
-├── config/         # routeRegistry.tsx（路由注册）、http.ts
-├── constants/# layout.ts（页面布局共享常量）
-├── enums/          # 共享枚举
-└── helpers/        # 工具函数（http.ts的 customRequest 等）
+├── routes/             # 页面模块：user/、role/ 等
+├── locales/            # i18n 文案：en/、zh_CN/
+├── components/         # 共享 UI 组件（PageHeader、RowActions、SearchBar 等）
+├── hooks/              # 自定义 hooks（useECharts、useDynamicResources、useListPageState 等）
+├── config/             # routeRegistry.tsx（路由注册）、http.ts
+├── constants/          # layout.ts（页面布局共享常量）
+├── enums/              # 共享枚举
+├── helpers/            # 工具函数（http.ts 的 customRequest 等）
+├── utilities/          # 通用工具（lazy-with-reload.ts）
+├── generated/          # 生成产物（禁止直接修改）
+├── dev-shell/          # 本地开发悬浮面板（仅 dev）
+├── plugins/            # Vite 插件（devShellPlugin.ts）
+├── authProvider.ts     # auth provider（扁平文件，非目录）
+└── auditLogProvider.ts # audit log provider
 ```
 
-### Backend Tech Stack
+### 后端技术栈
+
 NestJS v10, Prisma v6, TypeScript, nest-access-control, Winston logger
 
 ```
@@ -43,28 +45,115 @@ server/src/
 ├── modules/        # 业务模块，每个含 Module → Controller → Service
 ├── generated/      # Prisma 自动生成（禁止直接修改）
 ├── lib/            # 核心：auth.guard.ts、roles.guard.ts、taihu.ts、woaAuth.ts、logger.ts
-├── enums/          # 共享枚举
-└── utils/          # 工具函数
+├── config/         # index.ts（端口/日志/prisma/swagger 等运行时配置）
+└── app.module.ts   # 根模块（跨切面，改动需确认）
 ```
 
-### Permission Model (RBAC)
-参考 `.agent/references/permission-model.md`
+`server/seed/` 存放页面/资源/权限声明的 seed 脚本。
 
-### 数据库迁移、dev/prod 模式差异、认证绕过等本地开发
-细节见 `.agent/references/local-dev.md`。
+> **RBAC 授权数据在数据库**，由 `RoleService.getBuilder()` 构建成 RolesBuilder 注入 `AccessControlModule`，`RolesRefresherService` 定时刷新。**不要在代码里硬编码角色授权表。**
 
-### playwright 无头浏览器访问项目页面
-用 `server/scripts/gen-jwt.ts` 生成临时 token。
+## 参考文档
+
+- 权限模型（RBAC）：`.agent/references/permission-model.md`
+- 本地开发、dev/prod 模式差异、认证绕过等本地开发细节：`.agent/references/local-dev.md`
+- playwright 无头浏览器访问页面：用 `server/scripts/gen-jwt.ts` 生成临时 token
 
 ## 开发原则（必须遵守）
+
 - 使用 TypeScript 严格模式
 - 严格遵循前、后端既有技术栈，如无必要不要引入新库
 - 不确定时询问，不要猜；存在歧义时不要默默选择；有更简单的方案要说出来
-- 修改 config/ui/ 或 config/prisma/ 配置后，必须在**项目根目录**执行生成命令 `gadmin2 g prisma` 或者 `gadmin2 g prisma:dev`。
-- 修改 config/prisma/ 后必须同步检查 server/seed/：raw SQL 引用的列/表、seed 数据的必填字段与字段名要与新 schema 一致，改完需要提醒开发者 yarn seed 验证。
-- **优先使用 skill 解决问题** skill 的决策逻辑（配置优先、DB 先于页面等）见 `.agent/references/decision-map.md`
-- **默认业务代码范围：** 前端修改限定在 `web/src/routes/`，后端修改限定在 `server/src/modules/`、`server/seed/`。
-- **配置驱动源码：** `config/prisma/`、`config/ui/` 可按生成流程修改；标准 CRUD 优先改配置，不要绕过配置直接改生成物。
-- **跨切面窄白名单：** `web/src/config/routeRegistry.tsx` 仅可用于注册自定义路由。
-- skill 中列出的目标文件不会自动扩大修改权限。除上述范围外，修改 `web/src/components/`、`web/src/hooks/`、`web/src/constants/`、`web/src/providers/`、全局认证文件，以及 `server/src/lib/`、`server/src/app.module.ts`、`server/src/main.ts` 等跨切面文件，必须由用户明确要求或确认具体实施计划，并限定为最小必要改动。
-- **生成目录禁止直接修改：** `web/src/generated/`、`server/src/generated/` 只能由生成命令更新。
+- 修改 `config/ui/` 或 `config/prisma/` 后，必须在**项目根目录**执行生成命令：
+  - 改 prisma 文件 → 执行 `gadmin2 g prisma:dev`
+  - 只改 ui 配置文件 → 执行 `gadmin2 g prisma`
+- 修改 `config/prisma/` 后必须同步检查 `server/seed/`：
+  - raw SQL 引用的列/表、seed 数据的必填字段与字段名要与新 schema 一致
+  - 改完需要提醒开发者 `yarn seed` 验证
+- **优先使用 skill 解决问题**，具体走哪条路径见下方「项目改动路径决策」
+
+### 代码修改范围
+
+| 类别 | 路径 |
+|------|------|
+| 默认可改 | `web/src/routes/`、`web/src/locales/`、`server/src/modules/`、`server/seed/` |
+| 配置驱动源码（按生成流程改） | `config/prisma/`、`config/ui/` |
+| 窄白名单 | `web/src/config/routeRegistry.tsx`（仅用于注册自定义路由） |
+| 禁止直接修改 | `web/src/generated/`、`server/src/generated/`（只能由生成命令更新） |
+
+> ⚠️ **以上范围之外的任何文件**，**必须由用户明确要求或确认具体实施计划**，并限定为最小必要改动。包括但不限于：
+>
+> - 前端：`web/src/components/`、`hooks/`、`constants/`、`utilities/`、`authProvider.ts`、`App.tsx`、`i18n.ts`
+> - 后端：`server/src/lib/`、`server/src/config/`、`app.module.ts`、`main.ts` 等跨切面文件
+>
+> skill 与参考文档中列出的目标文件**不会自动扩大修改权限**；若 skill 需要改动上表之外的文件，先向用户确认。
+
+## 项目改动路径决策
+
+本节只回答一个问题：**这次改动该走哪条路径**（配置驱动 / 手写代码 / 数据库先行）。
+
+具体操作由 skill 承载——skill 靠自身 `description` 匹配任务，这里只做分流、不复制 skill 的操作步骤。
+
+### 一、三条核心原则
+
+1. **配置优先**
+   - 配置能表达的前端改动一律走 `ui-config-update` skill（无需再问用户），不要手写页面代码、不要绕过配置直接改生成物。
+   - 配置无法满足才手写，手写页面统一走 `page-management` skill。
+   - 涉及数据库表和字段的变更走 `prisma-schema-management` skill。
+   - 后端任何代码改动走 `backend-module` skill。
+
+2. **DB 先于页面**
+   - 页面要用的字段在数据库里不存在时，先改 schema + 迁移，再改 UI 配置。
+   - 顺序颠倒会生成引用不存在字段的代码。
+
+3. **不凭记忆自己写**
+   - 局部定制类需求（列渲染、搜索过滤、批量操作、表单联动、导入导出、i18n、菜单、权限…）都有对应 skill，按需求描述直接触发。
+
+### 二、先定页面类型，再定能否用配置表达
+
+**「gadmin2 标准的数据管理页面」的判定标准：** 页面 URL 以 `/admin/data-mngt/` 开头。
+
+- 该前缀下的页面全部由生成器产出（`routeRegistry.tsx` 的 `buildDataMngtChildren` 扫描 `generated/resources.tsx` 自动注册）。
+- 与 `config/ui/{ModelName}.ts` 一一对应。
+
+> ⚠️ 注意：**CRUD 外形 ≠ gadmin2 标准的数据管理页面。**
+>
+> - `/admin/permission/user`、`/admin/audit-log-list`、`/admin/workflow/node-instances` 等是手写 CRUD，改动走 `page-management`，不要试图改 config/ui。
+> - 新建页面没有 URL 可判时，看需求是否为「业务模型的标准 CRUD」——是则走 prisma 生成路径（生成后自动落在 `/admin/data-mngt/` 下）。
+
+```
+这个页面是什么类型？
+│
+├── gadmin2 标准的数据管理页面（CRUD：列表 / 创建 / 编辑 / 详情）
+│   └── 需求能否用 config/ui 表达？
+│       ├── 能 → [ui-config-update] → 根目录 gadmin2 g prisma
+│       └── 不能 → [page-management]（手动修改已经生成的 CRUD 页面，样例见其 examples/）
+│
+└── 自定义页面（统计、设置、非 CRUD 交互）→ [page-management]
+```
+
+**判断「能否用 config/ui 表达」的分界线：**
+
+- ✅ 配置能力范围内：字段增删、字段顺序、排序、精确匹配搜索、批量操作开关、工具栏按钮增删、表单默认值与联动、详情页字段
+- ✍️ 才需要手写：自定义 Hook、非标准布局、复杂交互、Tree 选择器等
+
+### 三、新建 / 删除页面的联动清单
+
+新建页面和删除页面都会牵涉多处，容易漏。四个环节各有归属 skill，**按环节分流、不要凭记忆自己拼**：
+
+| 环节 | 去哪个 skill |
+|------|-------------|
+| 页面代码 | 配置能表达 → `ui-config-update`；需手写 → `page-management` |
+| 路由注册 | `route-registration` |
+| 菜单 | `menu-management` |
+| 角色权限 | `permission-management` |
+
+- **新建**：按上表**自上而下**推进 —— 页面代码 → 路由注册 → 菜单 → 授权。
+- **删除**：按**自下而上**回收 —— 回收授权 → 删 `t_page` 行 → 删路由注册 → 删页面代码。
+
+> ⚠️ 顺序反了会卡住——`revoke` 要求页面仍存在。只删页面代码会留下菜单残留和权限脏数据，完整的按序清理清单见 `menu-management`。
+
+**两个最常踩的联动漏项：**
+
+1. 只建了 `t_page` 没授权 → 菜单**完全不出现**（`t_role_pages` 无行）
+2. 只有 `t_role_pages` 没有 `t_role_resource` → 菜单能看见但**所有 API 403**；且 `t_role_resource` 不会被定时任务自动补出来，详见 `permission-management`

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

@@ -40,6 +40,17 @@ enum WorkflowEventDeliveryStatus {
   FAILED
 }
 
+enum WorkflowLifecycleEventType {
+  FAILED
+}
+
+enum WorkflowLifecycleOutboxStatus {
+  PENDING
+  PROCESSING
+  COMPLETED
+  FAILED
+}
+
 enum WorkflowNodeCategory {
   TRIGGER
   ACTION
@@ -164,6 +175,7 @@ model WorkflowInstance {
   nodeExecutions       WorkflowNodeExecution[]
   externalInteractions ExternalInteraction[]
   eventDelivery       WorkflowEventDelivery?
+  lifecycleOutboxes   WorkflowLifecycleOutbox[]
 
   @@unique([workflowId, idempotencyKey], map: "uk_wi_workflow_idempotency") // NULL 不参与唯一性，未提供幂等键的内部执行不受影响
   @@unique([workflowId, sourceOutboxId], map: "uk_wi_workflow_outbox") // 一个 outbox 事件对一个 workflow 至多一条 instance（NULL 不参与唯一性，正常 execute / cron / webhook 不受影响）
@@ -452,6 +464,36 @@ model WorkflowEventDelivery {
   @@map("t_workflow_event_delivery")
 }
 
+/// Workflow 终态向业务系统的可靠通知。当前只投递事件触发实例的 FAILED 事件。
+/// @IgnoreNestCode
+/// @IgnoreReactCode
+/// @IgnoreAutoField
+model WorkflowLifecycleOutbox {
+  id                 BigInt                        @id @default(autoincrement())
+  eventKey           String                        @unique @map("event_key") @db.VarChar(128)
+  workflowInstanceId BigInt                        @map("workflow_instance_id")
+  eventType          WorkflowLifecycleEventType    @map("event_type")
+  workflowCode       String                        @map("workflow_code") @db.VarChar(21)
+  businessReference  Json                          @map("business_reference")
+  connectionRef      String                        @map("connection_ref") @db.VarChar(64)
+  callbackPath       String                        @map("callback_path") @db.VarChar(1024)
+  failedAt           DateTime                      @map("failed_at") @db.Timestamptz(3)
+  status             WorkflowLifecycleOutboxStatus @default(PENDING)
+  retryCount         Int                           @default(0) @map("retry_count")
+  nextAttemptAt      DateTime                      @default(now()) @map("next_attempt_at")
+  lockedAt           DateTime?                     @map("locked_at") @db.Timestamptz(3)
+  lockedBy           String?                       @map("locked_by") @db.VarChar(128)
+  processedAt        DateTime?                     @map("processed_at") @db.Timestamptz(3)
+  lastError          String?                       @map("last_error") @db.Text
+  createdAt          DateTime                      @default(now()) @map("created_at")
+  updatedAt          DateTime                      @updatedAt @default(now()) @map("updated_at")
+
+  workflowInstance WorkflowInstance @relation(fields: [workflowInstanceId], references: [id], onDelete: Cascade)
+
+  @@index([status, nextAttemptAt], map: "idx_wlo_status_next_attempt_at")
+  @@map("t_workflow_lifecycle_outbox")
+}
+
 /// @IgnoreReactCode
 /// @IgnoreAutoField
 model TemporalTenantConfig {

package/dist/lib/application/files/gadmin2-game-angle-demo/gitignore

@@ -6,6 +6,7 @@ generated/
 build/
 server/prisma/dbml
 server/prisma/schema.prisma
+server/.seed-timestamp
 upload/
 # Logs
 logs/
@@ -60,3 +61,4 @@ agent-eval/runs/
 agent-eval/baseline/
 tmp/
 CODEBUDDY.local.md
+.scratch/

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

@@ -12,6 +12,7 @@
     "prepare": "cd .. && husky install || true",
     "start": "dotenv -e .env.local -e .env  -- nest start -c gadmin-cli.json",
     "start:dev": "dotenv -e .env.local -e .env  -- nest start -c gadmin-cli.json --watch",
+    "prestart:dev": "node scripts/check-dev-env.js prestart",
     "start:dev:lite": "dotenv -e .env.local -e .env -- sh -c 'nest build -cgadmin-cli.json && concurrently -k -n build,run \"nodemon --config nodemon.lite.json\" \"node --enable-source-maps --watch dist/src/main\"'",
     "start:debug": "dotenv -e .env.local -e .env  -- nest start -c gadmin-cli.json --debug --watch",
     "start:prod": "/bin/sh start-prod.sh",
@@ -32,6 +33,7 @@
     "postgadminGenerate": "node scripts/notify-dev-servers.js",
     "push:db": "dotenv -e .env.local -e .env  -- prisma db push --skip-generate",
     "seed": "dotenv -e .env.local -e .env  -- ts-node seed/index.ts",
+    "postseed": "node scripts/check-dev-env.js mark-seed",
     "prisma:studio": "dotenv -e .env.local -e .env  -- prisma studio",
     "gen:jwt": "dotenv -e .env.local -e .env  -- ts-node scripts/gen-jwt.ts"
   },

package/dist/lib/application/files/gadmin2-game-angle-demo/server/scripts/check-dev-env.js

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+/**
+ * 开发环境同步检测：schema / UI 配置 / 迁移 / seed 落后时给出提示（或自动应用迁移）。
+ *
+ * 两种触发入口共用本脚本，保证提示文案与判断逻辑只有一份：
+ *
+ *   node check-dev-env.js hook <prevSha>
+ *     git hook 模式（.husky/post-merge、post-rewrite 调用）：
+ *     按 git diff 的文件变更检测，拉取后立即提示。只提示不执行。
+ *
+ *   node check-dev-env.js prestart
+ *     server prestart:dev 模式（yarn start:dev 前自动运行）：
+ *     按本地状态检测（mtime 对比 + prisma migrate status），
+ *     兜底覆盖 VS Code 等 GUI 拉代码看不到 hook 输出的场景。
+ *     未应用的迁移会自动执行 yarn migrate:deploy（非交互、幂等），其余只提示。
+ *
+ *   node check-dev-env.js mark-seed
+ *     yarn seed 的 postseed 钩子调用，记录 seed 时间戳供 prestart 对比。
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync, spawnSync } = require('child_process');
+
+const SERVER_DIR = path.join(__dirname, '..');
+const ROOT_DIR = path.join(SERVER_DIR, '..');
+const SEED_TS_FILE = path.join(SERVER_DIR, '.seed-timestamp');
+
+// ---------- 提示文案（两种模式共用） ----------
+
+function warnPrisma(files) {
+  console.log('');
+  console.log('⚠  检测到 Prisma schema 变更未同步到本地：');
+  (files || []).forEach((f) => console.log(`     ${f}`));
+  console.log('');
+  console.log('   请在项目根目录运行以下命令，同步本地代码与数据库：');
+  console.log('     → gadmin2 g prisma:dev');
+  console.log('   （应用新迁移到本地库 + 重新生成后端 CRUD 代码）');
+  console.log('');
+}
+
+function warnUi(files) {
+  console.log('');
+  console.log('⚠  检测到 UI 配置变更未同步到本地：');
+  (files || []).forEach((f) => console.log(`     ${f}`));
+  console.log('');
+  console.log('   请在项目根目录运行以下命令，重新生成前端页面代码：');
+  console.log('     → gadmin2 g prisma');
+  console.log('');
+}
+
+function warnSeed(files) {
+  console.log('');
+  console.log('⚠  检测到 seed 文件变更未同步到本地：');
+  (files || []).forEach((f) => console.log(`     ${f}`));
+  console.log('');
+  console.log('   请在 server 目录运行以下命令，同步本地 seed 数据（页面/资源/权限声明）：');
+  console.log('     → cd server && yarn seed');
+  console.log('');
+}
+
+// ---------- 工具 ----------
+
+/** 目录/ glob 内文件的最新 mtime（毫秒），不存在返回 0 */
+function newestMtime(target) {
+  let stat;
+  try {
+    stat = fs.statSync(target);
+  } catch {
+    return 0;
+  }
+  if (stat.isFile()) return stat.mtimeMs;
+  let newest = 0;
+  for (const entry of fs.readdirSync(target)) {
+    newest = Math.max(newest, newestMtime(path.join(target, entry)));
+  }
+  return newest;
+}
+
+function globMtime(dir, ext) {
+  let newest = 0;
+  let files = [];
+  try {
+    files = fs.readdirSync(dir).filter((f) => f.endsWith(ext));
+  } catch {
+    return 0;
+  }
+  for (const f of files) {
+    newest = Math.max(newest, fs.statSync(path.join(dir, f)).mtimeMs);
+  }
+  return newest;
+}
+
+// ---------- hook 模式：按 git diff 文件变更检测 ----------
+
+function runHook(prevSha) {
+  if (!prevSha) return;
+  let changed;
+  try {
+    changed = execSync(`git diff --name-only ${prevSha} HEAD`, {
+      cwd: ROOT_DIR,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+  } catch {
+    return;
+  }
+  if (!changed) return;
+  const files = changed.split('\n');
+
+  const prismaChanged = files.filter((f) => /^config\/prisma\/.*\.prisma$/.test(f));
+  const uiChanged = files.filter((f) => /^config\/ui\/.*\.ts$/.test(f));
+  const seedChanged = files.filter((f) => f.startsWith('server/seed/'));
+  const migrationsChanged = files.filter((f) => f.startsWith('server/prisma/migrations/'));
+
+  if (prismaChanged.length) warnPrisma(prismaChanged);
+  else if (uiChanged.length) warnUi(uiChanged);
+  if (seedChanged.length) warnSeed(seedChanged);
+  // gadmin2 g prisma:dev 已包含应用迁移，schema 变更时不重复提示。
+  if (migrationsChanged.length && !prismaChanged.length) {
+    console.log('');
+    console.log('⚠  检测到本次拉取包含新的数据库迁移：');
+    migrationsChanged.forEach((f) => console.log(`     ${f}`));
+    console.log('');
+    console.log('   请在 server 目录运行以下命令，将新迁移应用到本地数据库：');
+    console.log('     → cd server && yarn migrate:deploy');
+    console.log('');
+  }
+}
+
+// ---------- prestart 模式：按本地状态检测 ----------
+
+function isPrismaStale() {
+  const configMtime = globMtime(path.join(ROOT_DIR, 'config/prisma'), '.prisma');
+  if (!configMtime) return false;
+  const schemaMtime = newestMtime(path.join(SERVER_DIR, 'prisma/schema.prisma'));
+  return configMtime > schemaMtime;
+}
+
+function isUiStale() {
+  const configMtime = globMtime(path.join(ROOT_DIR, 'config/ui'), '.ts');
+  if (!configMtime) return false;
+  const generatedMtime = newestMtime(path.join(ROOT_DIR, 'web/src/generated'));
+  return !generatedMtime || configMtime > generatedMtime;
+}
+
+function isSeedStale() {
+  const seedMtime = newestMtime(path.join(SERVER_DIR, 'seed'));
+  if (!seedMtime) return false;
+  const tsMtime = newestMtime(SEED_TS_FILE);
+  return !tsMtime || seedMtime > tsMtime;
+}
+
+/** 有未应用的迁移返回 true；DB 不可达等异常返回 null（跳过检测） */
+function hasPendingMigrations() {
+  const res = spawnSync('yarn', ['--silent', 'migrate:status'], {
+    cwd: SERVER_DIR,
+    encoding: 'utf8',
+    timeout: 60000,
+  });
+  if (res.error || res.status === null) return null;
+  const out = (res.stdout || '') + (res.stderr || '');
+  if (/not yet been applied/i.test(out)) return true;
+  if (/Have not been applied|following migration/i.test(out)) return true;
+  // 无法连库等场景静默跳过
+  if (/Can't reach database|ECONNREFUSED|P1001/i.test(out)) return null;
+  return false;
+}
+
+function applyMigrations() {
+  console.log('');
+  console.log('⚠  检测到有数据库迁移尚未应用到本地库，自动执行 yarn migrate:deploy ...');
+  const res = spawnSync('yarn', ['--silent', 'migrate:deploy'], {
+    cwd: SERVER_DIR,
+    stdio: 'inherit',
+  });
+  if (res.status !== 0) {
+    console.log('');
+    console.log('✗  migrate:deploy 执行失败（本地库可能有 drift）。请手动到 server 目录排查：');
+    console.log('     → cd server && yarn migrate:status');
+    console.log('');
+  } else {
+    console.log('✓  迁移已应用到本地库。');
+    console.log('');
+  }
+}
+
+function runPrestart() {
+  // schema 过期时 gadmin2 g prisma:dev 会一并应用迁移，跳过 migrate 检测避免重复。
+  if (isPrismaStale()) {
+    warnPrisma();
+  } else if (hasPendingMigrations()) {
+    applyMigrations();
+  }
+  if (isUiStale()) warnUi();
+  if (isSeedStale()) warnSeed();
+}
+
+// ---------- mark-seed ----------
+
+function markSeed() {
+  fs.writeFileSync(SEED_TS_FILE, new Date().toISOString() + '\n');
+}
+
+// ---------- 入口 ----------
+
+const [mode, arg] = process.argv.slice(2);
+try {
+  if (mode === 'hook') runHook(arg);
+  else if (mode === 'prestart') runPrestart();
+  else if (mode === 'mark-seed') markSeed();
+  else {
+    console.error('usage: check-dev-env.js <hook <prevSha> | prestart | mark-seed>');
+    process.exit(1);
+  }
+} catch {
+  // 检测脚本永不阻断主流程
+}

package/dist/lib/application/files/gadmin2-game-angle-demo/server/scripts/page-manage.ts

@@ -20,7 +20,8 @@
  *     --zhName      "新名称"         (optional)
  *     --enName      "New Name"      (optional)
  *     --sortOrder   1090            (optional)
- *     --parentPageCode  game        (optional)
+ *     --parentPageCode  game        (optional — 会校验不形成环)
+ *     --isVirtual                   (optional — 从侧边栏隐藏；--isVirtual false 取消隐藏)
  *
  *   ── 删除页面 ──────────────────────────────────────────────────────────────────
  *   ts-node scripts/page-manage.ts delete \
@@ -85,6 +86,50 @@ async function requirePage(pageCode: string) {
   return page;
 }
 
+/**
+ * 校验把 pageId 挂到 newParentId 下不会形成环。
+ *
+ * 环不会报错，但会静默破坏菜单：useDynamicResources 从 root 做深度优先遍历
+ * (addPageWithChildren)，环里的页面遍历不到，最终落进 orphan 兜底被 append
+ * 到菜单末尾 —— 症状是「菜单项莫名跑到最底部」，极难排查。
+ */
+async function assertNoCycle(
+  pageId: number,
+  pageCode: string,
+  newParentId: number,
+): Promise<void> {
+  if (pageId === newParentId) {
+    console.error(`[page-manage] "${pageCode}" 不能把自己设为父节点。`);
+    process.exit(1);
+  }
+
+  const all = await prisma.page.findMany({
+    select: { id: true, code: true, parentId: true },
+  });
+  const byId = new Map(all.map((p) => [p.id, p]));
+
+  // seen 兼容库里已经存在的环，避免死循环
+  const seen = new Set<number>();
+  const trail: string[] = [];
+  let cursor: number | null = newParentId;
+
+  while (cursor != null && !seen.has(cursor)) {
+    const node = byId.get(cursor);
+    if (!node) break;
+    trail.push(node.code);
+    if (cursor === pageId) {
+      // trail 是从新父节点往 root 走的，反过来才是自上而下的环路径
+      const cyclePath = [...trail].reverse().join(' → ');
+      console.error(
+        `[page-manage] 该父节点是 "${pageCode}" 的后代，会形成环：${cyclePath} → ${pageCode}`,
+      );
+      process.exit(1);
+    }
+    seen.add(cursor);
+    cursor = node.parentId;
+  }
+}
+
 // ─── Actions ──────────────────────────────────────────────────────────────────
 
 async function actionCreate(flags: Record<string, string>) {
@@ -101,11 +146,19 @@ async function actionCreate(flags: Record<string, string>) {
     console.error('[page-manage] --pageCode is required.');
     process.exit(1);
   }
+  if (parentPageCode && parentPageCode === pageCode) {
+    console.error(`[page-manage] "${pageCode}" 不能把自己设为父节点。`);
+    process.exit(1);
+  }
 
   const parentId = parentPageCode
     ? await resolveParent(parentPageCode)
     : undefined;
 
+  // create 走 upsertPage，其 update 为 {} —— 页面已存在时不会改任何字段。
+  // 先查一次拿到准确的存在性（不要用 createdAt/updatedAt 的时间差去猜）。
+  const existing = await prisma.page.findUnique({ where: { code: pageCode } });
+
   const page = await upsertPage(prisma, {
     code: pageCode,
     name: pageName || pageCode,
@@ -115,14 +168,15 @@ async function actionCreate(flags: Record<string, string>) {
     parentId,
   });
 
-  const wasCreated =
-    Math.abs(page.createdAt.getTime() - page.updatedAt.getTime()) < 1000;
-  if (wasCreated) {
-    console.log(`[page-manage] ✚ Created page: ${pageCode} (id=${page.id})`);
-  } else {
+  if (existing) {
+    console.log(
+      `[page-manage] · Page already exists: ${pageCode} (id=${page.id}) — 未改动任何字段。`,
+    );
     console.log(
-      `[page-manage] · Page already exists: ${pageCode} (id=${page.id}) — skipped`,
+      `[page-manage]   要修改请用: page-manage.ts update --pageCode ${pageCode} ...`,
     );
+  } else {
+    console.log(`[page-manage] ✚ Created page: ${pageCode} (id=${page.id})`);
   }
 
   if (resources) {
@@ -145,8 +199,15 @@ async function actionCreate(flags: Record<string, string>) {
 }
 
 async function actionUpdate(flags: Record<string, string>) {
-  const { pageCode, pageName, zhName, enName, parentPageCode, sortOrder } =
-    flags;
+  const {
+    pageCode,
+    pageName,
+    zhName,
+    enName,
+    parentPageCode,
+    sortOrder,
+    isVirtual,
+  } = flags;
   if (!pageCode) {
     console.error('[page-manage] --pageCode is required.');
     process.exit(1);
@@ -159,12 +220,17 @@ async function actionUpdate(flags: Record<string, string>) {
   if (zhName !== undefined) data.zhName = zhName;
   if (enName !== undefined) data.enName = enName;
   if (sortOrder !== undefined) data.sortOrder = parseInt(sortOrder, 10);
-  if (parentPageCode !== undefined)
-    data.parentId = await resolveParent(parentPageCode);
+  // 裸 --isVirtual 被 parseArgs 解析成 'true'；仅 --isVirtual false 取消隐藏
+  if (isVirtual !== undefined) data.isVirtual = isVirtual !== 'false';
+  if (parentPageCode !== undefined) {
+    const newParentId = await resolveParent(parentPageCode);
+    await assertNoCycle(page.id, page.code, newParentId);
+    data.parentId = newParentId;
+  }
 
   if (Object.keys(data).length === 0) {
     console.log(
-      '[page-manage] No fields to update. Pass at least one of: --pageName --zhName --enName --sortOrder --parentPageCode',
+      '[page-manage] No fields to update. Pass at least one of: --pageName --zhName --enName --sortOrder --parentPageCode --isVirtual',
     );
     process.exit(0);
   }