@yss123/cage-cli 0.1.0 → 0.2.0

package/templates/app/packages/contracts/src/{dept.ts → aggregates/dept/index.ts}

@@ -2,7 +2,7 @@
 /* eslint-disable */
 
 import { z } from 'zod';
-import { client, useCageList, useCageQuery } from '@yss123/cage-client';
+import { client, useCageList, useCageQuery, type TransferTask } from '@yss123/cage-client';
 
 /** 部门：读侧快照（敏感字段是按权限掩码后的值） */
 export const DeptSchema = z.object({
@@ -60,8 +60,8 @@ export const dept = {
   create: (input: z.input<typeof DeptInputs.create>) => client.post<Dept, DeptCreateError>('/api/dept/create', input),
   /** 修改部门名称、编码、负责人 */
   update: (id: string, input: Omit<z.input<typeof DeptInputs.update>, 'id'>, expectedVersion?: number) => client.post<Dept, DeptUpdateError>(`/api/dept/${encodeURIComponent(id)}/update`, { ...input, expectedVersion }),
-  /** 导出 CSV：需要 Dept.export 能力 */
-  export: (params: DeptListParams = {}) => client.post<string, never>('/api/dept/export', params),
+  /** 异步导出 CSV：返回任务，使用 client.transfer(id) 查状态，完成后下载。需要 Dept.export 能力。 */
+  export: (params: DeptListParams = {}, options: { idempotencyKey?: string } = {}) => client.post<TransferTask, 'CONFLICT'>('/api/dept/export', params, options),
   get: (id: string) => client.get<Dept>(`/api/dept/${encodeURIComponent(id)}`),
   list: (params: DeptListParams = {}) => client.get<{ items: Dept[]; total: number; page: number; pageSize: number }>('/api/dept', params as Record<string, unknown>),
 };

package/templates/app/packages/contracts/src/{inventory.ts → aggregates/inventory/index.ts}

@@ -2,7 +2,7 @@
 /* eslint-disable */
 
 import { z } from 'zod';
-import { client, useCageList, useCageQuery } from '@yss123/cage-client';
+import { client, useCageList, useCageQuery, type TransferTask } from '@yss123/cage-client';
 
 /** Inventory：读侧快照（敏感字段是按权限掩码后的值） */
 export const InventorySchema = z.object({
@@ -43,8 +43,8 @@ export interface InventoryListParams {
 /** 调用方法：每个命令一个；client 自动生成并附带幂等键和 CSRF 令牌 */
 export const inventory = {
   create: (input: z.input<typeof InventoryInputs.create>) => client.post<Inventory, InventoryCreateError>('/api/inventory/create', input),
-  /** 导出 CSV：需要 Inventory.export 能力 */
-  export: (params: InventoryListParams = {}) => client.post<string, never>('/api/inventory/export', params),
+  /** 异步导出 CSV：返回任务，使用 client.transfer(id) 查状态，完成后下载。需要 Inventory.export 能力。 */
+  export: (params: InventoryListParams = {}, options: { idempotencyKey?: string } = {}) => client.post<TransferTask, 'CONFLICT'>('/api/inventory/export', params, options),
   get: (id: string) => client.get<Inventory>(`/api/inventory/${encodeURIComponent(id)}`),
   list: (params: InventoryListParams = {}) => client.get<{ items: Inventory[]; total: number; page: number; pageSize: number }>('/api/inventory', params as Record<string, unknown>),
 };

package/templates/app/packages/contracts/src/{inventory-lock.ts → aggregates/inventory-lock/index.ts}

@@ -2,7 +2,7 @@
 /* eslint-disable */
 
 import { z } from 'zod';
-import { client, useCageList, useCageQuery } from '@yss123/cage-client';
+import { client, useCageList, useCageQuery, type TransferTask } from '@yss123/cage-client';
 
 /** InventoryLock：读侧快照（敏感字段是按权限掩码后的值） */
 export const InventoryLockSchema = z.object({
@@ -38,8 +38,8 @@ export interface InventoryLockListParams {
 
 /** 调用方法：每个命令一个；client 自动生成并附带幂等键和 CSRF 令牌 */
 export const inventoryLock = {
-  /** 导出 CSV：需要 InventoryLock.export 能力 */
-  export: (params: InventoryLockListParams = {}) => client.post<string, never>('/api/inventory-lock/export', params),
+  /** 异步导出 CSV：返回任务，使用 client.transfer(id) 查状态，完成后下载。需要 InventoryLock.export 能力。 */
+  export: (params: InventoryLockListParams = {}, options: { idempotencyKey?: string } = {}) => client.post<TransferTask, 'CONFLICT'>('/api/inventory-lock/export', params, options),
   get: (id: string) => client.get<InventoryLock>(`/api/inventory-lock/${encodeURIComponent(id)}`),
   list: (params: InventoryLockListParams = {}) => client.get<{ items: InventoryLock[]; total: number; page: number; pageSize: number }>('/api/inventory-lock', params as Record<string, unknown>),
 };

package/templates/app/packages/contracts/src/{purchase-order.ts → aggregates/purchase-order/index.ts}

@@ -2,7 +2,7 @@
 /* eslint-disable */
 
 import { z } from 'zod';
-import { client, useCageList, useCageQuery } from '@yss123/cage-client';
+import { client, useCageList, useCageQuery, type TransferTask } from '@yss123/cage-client';
 
 /** PurchaseOrder：读侧快照（敏感字段是按权限掩码后的值） */
 export const PurchaseOrderSchema = z.object({
@@ -58,8 +58,8 @@ export const purchaseOrder = {
   cancel: (id: string, expectedVersion?: number) => client.post<PurchaseOrder, PurchaseOrderCancelError>(`/api/purchase-order/${encodeURIComponent(id)}/cancel`, { expectedVersion }),
   create: (input: z.input<typeof PurchaseOrderInputs.create>) => client.post<PurchaseOrder, PurchaseOrderCreateError>('/api/purchase-order/create', input),
   submit: (id: string, expectedVersion?: number) => client.post<PurchaseOrder, PurchaseOrderSubmitError>(`/api/purchase-order/${encodeURIComponent(id)}/submit`, { expectedVersion }),
-  /** 导出 CSV：需要 PurchaseOrder.export 能力 */
-  export: (params: PurchaseOrderListParams = {}) => client.post<string, never>('/api/purchase-order/export', params),
+  /** 异步导出 CSV：返回任务，使用 client.transfer(id) 查状态，完成后下载。需要 PurchaseOrder.export 能力。 */
+  export: (params: PurchaseOrderListParams = {}, options: { idempotencyKey?: string } = {}) => client.post<TransferTask, 'CONFLICT'>('/api/purchase-order/export', params, options),
   get: (id: string) => client.get<PurchaseOrder>(`/api/purchase-order/${encodeURIComponent(id)}`),
   list: (params: PurchaseOrderListParams = {}) => client.get<{ items: PurchaseOrder[]; total: number; page: number; pageSize: number }>('/api/purchase-order', params as Record<string, unknown>),
 };

package/templates/app/packages/contracts/src/{role.ts → aggregates/role/index.ts}

@@ -2,7 +2,7 @@
 /* eslint-disable */
 
 import { z } from 'zod';
-import { client, useCageList, useCageQuery } from '@yss123/cage-client';
+import { client, useCageList, useCageQuery, type TransferTask } from '@yss123/cage-client';
 
 /** 角色：读侧快照（敏感字段是按权限掩码后的值） */
 export const RoleSchema = z.object({
@@ -71,8 +71,8 @@ export const role = {
   revokeCapability: (id: string, input: Omit<z.input<typeof RoleInputs.revokeCapability>, 'id'>, expectedVersion?: number) => client.post<Role, RoleRevokeCapabilityError>(`/api/role/${encodeURIComponent(id)}/revoke-capability`, { ...input, expectedVersion }),
   /** 设置角色在某个聚合上的数据范围（不能授出比自己更宽的范围） */
   setScope: (id: string, input: Omit<z.input<typeof RoleInputs.setScope>, 'id'>, expectedVersion?: number) => client.post<Role, RoleSetScopeError>(`/api/role/${encodeURIComponent(id)}/set-scope`, { ...input, expectedVersion }),
-  /** 导出 CSV：需要 Role.export 能力 */
-  export: (params: RoleListParams = {}) => client.post<string, never>('/api/role/export', params),
+  /** 异步导出 CSV：返回任务，使用 client.transfer(id) 查状态，完成后下载。需要 Role.export 能力。 */
+  export: (params: RoleListParams = {}, options: { idempotencyKey?: string } = {}) => client.post<TransferTask, 'CONFLICT'>('/api/role/export', params, options),
   get: (id: string) => client.get<Role>(`/api/role/${encodeURIComponent(id)}`),
   list: (params: RoleListParams = {}) => client.get<{ items: Role[]; total: number; page: number; pageSize: number }>('/api/role', params as Record<string, unknown>),
 };

package/templates/app/packages/contracts/src/{user.ts → aggregates/user/index.ts}

@@ -2,7 +2,7 @@
 /* eslint-disable */
 
 import { z } from 'zod';
-import { client, useCageList, useCageQuery } from '@yss123/cage-client';
+import { client, useCageList, useCageQuery, type TransferTask } from '@yss123/cage-client';
 
 /** 用户：读侧快照（敏感字段是按权限掩码后的值） */
 export const UserSchema = z.object({
@@ -75,8 +75,8 @@ export const user = {
   setPassword: (id: string, input: Omit<z.input<typeof UserInputs.setPassword>, 'id'>, expectedVersion?: number) => client.post<User, UserSetPasswordError>(`/api/user/${encodeURIComponent(id)}/set-password`, { ...input, expectedVersion }),
   /** 修改用户信息 */
   update: (id: string, input: Omit<z.input<typeof UserInputs.update>, 'id'>, expectedVersion?: number) => client.post<User, UserUpdateError>(`/api/user/${encodeURIComponent(id)}/update`, { ...input, expectedVersion }),
-  /** 导出 CSV：需要 User.export 能力 */
-  export: (params: UserListParams = {}) => client.post<string, never>('/api/user/export', params),
+  /** 异步导出 CSV：返回任务，使用 client.transfer(id) 查状态，完成后下载。需要 User.export 能力。 */
+  export: (params: UserListParams = {}, options: { idempotencyKey?: string } = {}) => client.post<TransferTask, 'CONFLICT'>('/api/user/export', params, options),
   get: (id: string) => client.get<User>(`/api/user/${encodeURIComponent(id)}`),
   list: (params: UserListParams = {}) => client.get<{ items: User[]; total: number; page: number; pageSize: number }>('/api/user', params as Record<string, unknown>),
 };

package/templates/app/packages/contracts/src/index.ts

@@ -1,21 +1,21 @@
 // 生成物：由 cage gen 从 domain 声明生成，不要手改。
 /* eslint-disable */
 
-export * from './dept';
-export * from './inventory';
-export * from './inventory-lock';
-export * from './purchase-order';
-export * from './role';
-export * from './user';
+export * from './aggregates/dept';
+export * from './aggregates/inventory';
+export * from './aggregates/inventory-lock';
+export * from './aggregates/purchase-order';
+export * from './aggregates/role';
+export * from './aggregates/user';
 export * from './queries';
 import { can as baseCan, useCan as baseUseCan } from '@yss123/cage-client';
-import { DeptInputs } from './dept';
-import { InventoryInputs } from './inventory';
-import { InventoryLockInputs } from './inventory-lock';
-import { PurchaseOrderInputs } from './purchase-order';
-import { RoleInputs } from './role';
-import { UserInputs } from './user';
-export { client, configureClient, loadMe, currentUser, CageQueryError, type CageResult, type CommonError } from '@yss123/cage-client';
+import { DeptInputs } from './aggregates/dept';
+import { InventoryInputs } from './aggregates/inventory';
+import { InventoryLockInputs } from './aggregates/inventory-lock';
+import { PurchaseOrderInputs } from './aggregates/purchase-order';
+import { RoleInputs } from './aggregates/role';
+import { UserInputs } from './aggregates/user';
+export { client, configureClient, loadMe, currentUser, CageQueryError, useTransfer, type CageResult, type CommonError, type TransferTask, type ImportReport } from '@yss123/cage-client';
 
 /** 能力目录（由代码派生）：写错能力点名会编译失败 */
 export const capabilities = [
@@ -70,7 +70,7 @@ export type Capability = (typeof capabilities)[number];
 export const can = (capability: Capability): boolean => baseCan(capability);
 export const useCan = (capability: Capability): boolean => baseUseCan(capability);
 
-/** 各聚合的命令输入 schema：schemas.PurchaseOrder.create 可以直接给表单库做校验 */
+/** 各聚合的命令输入 schema：按聚合名、命令名访问，可直接供表单库校验 */
 export const schemas = {
   Dept: DeptInputs,
   Inventory: InventoryInputs,

package/templates/app/packages/domain/package.json

@@ -14,10 +14,10 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@yss123/cage-kernel": "0.1.0",
-    "@yss123/cage-admin": "0.1.0",
-    "@yss123/cage-approval": "0.1.0",
-    "@yss123/cage-connectors": "0.1.0",
+    "@yss123/cage-kernel": "0.2.0",
+    "@yss123/cage-admin": "0.2.0",
+    "@yss123/cage-approval": "0.2.0",
+    "@yss123/cage-connectors": "0.2.0",
     "zod": "^4.1.5"
   }
 }

package/templates/app/packages/domain/src/index.ts

@@ -1,9 +1,6 @@
 // 单一导出入口：CLI 抽取器、API 和 worker 都加载同一套声明。
 export * from '@yss123/cage-admin/domain';
-export * from './inventory.js';
-export * from './purchase-order.js';
-export * from './reactions.js';
-export * from './approvals.js';
-export * from './erp.js';
-export * from './queries.js';
-export * from './jobs.js';
+export * from './modules/inventory/index.js';
+export * from './modules/purchase/index.js';
+export * from './workflows/purchase-inventory.js';
+export * from './integrations/erp.js';

package/templates/app/packages/domain/src/{erp.ts → integrations/erp.ts}

@@ -2,7 +2,7 @@
 // 本地由 worker 注册 fake；这里始终只写声明，不发送请求或读取环境变量。
 import { z } from 'zod';
 import { connector, hmacSha256, inbound, op, outbound } from '@yss123/cage-connectors';
-import { OrderApproved, recordErpNo, markReceived } from './purchase-order.js';
+import { OrderApproved, recordErpNo, markReceived } from '../modules/purchase/index.js';
 
 export const erp = connector('erp', {
   hosts: { test: 'erp-sandbox.example.com', prod: 'erp.example.com' },

package/templates/app/packages/domain/src/modules/inventory/index.ts

@@ -0,0 +1,2 @@
+// 库存模块的公开声明：台账和占用记录共同属于库存业务。
+export * from './inventory.js';

package/templates/app/packages/domain/src/modules/purchase/index.ts

@@ -0,0 +1,6 @@
+// 采购模块的公开声明；其他模块通过本入口依赖它，不穿透内部文件。
+// index 只转导出，避免在组装入口里隐藏业务行为或产生初始化副作用。
+export * from './purchase-order.js';
+export * from './approvals.js';
+export * from './queries.js';
+export * from './jobs.js';

package/templates/app/packages/domain/src/{purchase-order.test.ts → modules/purchase/purchase-order.test.ts}

@@ -5,7 +5,7 @@ import { createTestEnv, type TestEnv, type TestUser } from '@yss123/cage-testkit
 import { readMigrations } from '@yss123/cage-kernel/db';
 import { systemCtx } from '@yss123/cage-kernel';
 import { fileURLToPath } from 'node:url';
-import * as domain from './index.js';
+import * as domain from '../../index.js';
 
 let env: TestEnv;
 let buyer: TestUser;
@@ -13,7 +13,7 @@ let manager: TestUser;
 beforeAll(async () => {
   env = await createTestEnv({
     domain,
-    migrations: readMigrations(fileURLToPath(new URL('../../../db/migrations/', import.meta.url))),
+    migrations: readMigrations(fileURLToPath(new URL('../../../../../db/migrations/', import.meta.url))),
   });
   buyer = await env.user({
     caps: ['PurchaseOrder.create', 'PurchaseOrder.submit', 'PurchaseOrder.cancel', 'PurchaseOrder.read'],

package/templates/app/packages/domain/src/{purchase-order.ts → modules/purchase/purchase-order.ts}

@@ -18,7 +18,7 @@ import {
   text,
 } from '@yss123/cage-kernel';
 import { z } from 'zod';
-import { Inventory } from './inventory.js';
+import { Inventory } from '../inventory/index.js';
 
 export const POStatus = states('draft', 'pending_approval', 'approved', 'received', 'rejected', 'cancelled', {
   terminal: ['received', 'rejected', 'cancelled'],

package/templates/app/packages/domain/src/{reactions.ts → workflows/purchase-inventory.ts}

@@ -1,8 +1,8 @@
 // 跨聚合资源配对：审批时同事务建锁，取消/收货时通过 outbox 释放。
 // acquires/releases 供图规则检查；map 返回 null 表示该次事件没有需要释放的资源。
 import { reaction } from '@yss123/cage-kernel';
-import { OrderApproved, OrderCancelled, OrderReceived } from './purchase-order.js';
-import { acquireLock, releaseLock } from './inventory.js';
+import { OrderApproved, OrderCancelled, OrderReceived } from '../modules/purchase/index.js';
+import { acquireLock, releaseLock } from '../modules/inventory/index.js';
 
 export const lockOnApprove = reaction(OrderApproved, {
   command: acquireLock,

package/templates/blank/.dockerignore

@@ -0,0 +1,10 @@
+node_modules
+**/node_modules
+**/dist
+.git
+.cage
+**/.cage
+generated
+.env
+.env.*
+*.log

package/templates/blank/.env.example

@@ -0,0 +1,61 @@
+# Cage 业务项目配置：复制此文件为同目录的 .env，首次只填写管理员数据库连接。
+# .env 位于业务项目根目录，与 package.json、cage.config.json 同级。
+# pnpm exec cage init / pnpm dev / pnpm migrate 自动读取它；同名外部环境变量优先。
+# 修改后重启 dev；migrate 在下次执行时读取新值。不要把 .env 提交到 Git。
+# 数据库需已经存在并能连接；框架不安装 PostgreSQL、不创建数据库、不管理 Docker。
+
+# ===== 第一步：提供已有数据库的管理员连接，执行 pnpm exec cage init =====
+# 格式：postgresql://用户名:密码@主机:端口/数据库名
+# 将 127.0.0.1、5432、business_db 换成实际地址、端口和已有数据库名。
+# 密码中的特殊字符必须 URL 编码，例如 @ 写成 %40、# 写成 %23、% 写成 %25。
+# [首次初始化必填] 管理员通常叫 postgres；若你的管理员叫 root，使用实际账号名。
+# 管理员需要创建角色、schema 和授权的权限。连接的数据库必须已经存在。
+# 将下面的管理员密码、主机、端口和库名改为实际值，再执行 pnpm exec cage init。
+# init 会创建框架账号、生成独立随机密码和 Cookie 密钥，并自动填好下面的配置。
+# 成功后管理员连接会从 .env 移除；日常开发不用再提供管理员密码。
+CAGE_ADMIN_DATABASE_URL=postgresql://postgres:REPLACE_WITH_ADMIN_PASSWORD@127.0.0.1:5432/business_db
+
+# ===== 第二步：以下配置由 init 自动填充，无需手动创建账号或编写授权 SQL =====
+# 三个连接使用同一个数据库，主机、端口、库名一致，账号权限不同。
+# 重复 init 会验证并复用已保存的账号，不重置密码。
+# 若集群已有 Cage 账号且本项目未保存连接，需复用原凭证，不能仅凭管理员重置其他项目的密码。
+
+# [必填] 业务写入账号 cage_app：API 和 worker 执行命令、审计和后台任务使用。
+# 它有业务所需读写权限，不应使用 postgres 超级用户替代。
+# CAGE_APP_DATABASE_URL=
+
+# [必填] 安全查询账号 cage_read：仅通过安全视图读取，经数据范围过滤和敏感字段掩码。
+# 不要与写入账号混用，否则会破坏读写权限隔离。
+# CAGE_READ_DATABASE_URL=
+
+# [执行迁移时必填] 迁移账号 cage_migrate：pnpm migrate 用它更新表、索引、视图和权限。
+# 它连接上述同一个数据库；迁移只在手动执行命令时发生，dev 不自动执行迁移。
+# 生产环境只给迁移任务配置此项，API / worker 无需获得此账号。
+# CAGE_MIGRATE_DATABASE_URL=
+
+# ===== 应用配置 =====
+# [init 自动生成] Cookie 签名密钥，不是数据库密码，也不是网页登录密码。
+# 自动生成 32 字节随机值；已有值保留。同一应用的多个实例使用同一值。
+# CAGE_COOKIE_SECRET=
+
+# [可选，开发默认 fake] 第三方连接器阶段：fake 使用模拟实现；test / prod 使用真实适配器。
+# 本项只影响第三方外部服务，fake 阶段仍连接真实 PostgreSQL。
+# test / prod 需另行配置业务连接器要求的地址与密钥，不是修改此值就完成对接。
+CAGE_STAGE=fake
+
+# [可选，Vite 默认 5173] 本地 Web 页面端口。这里选 15173，减少 Windows 保留端口冲突。
+# 多个应用同时运行时，各选一个空闲端口；它与数据库端口无关。
+CAGE_WEB_PORT=15173
+
+# [可选，默认 3000] API 服务端口；本地 Web 代理自动转发到这个端口。
+PORT=3000
+
+# [可选，范例默认 0.0.0.0] API 监听地址；这里使用 127.0.0.1，仅允许本机访问。
+# 需要容器内或局域网访问时改为 0.0.0.0，并按部署环境配置网络访问权限。
+HOST=127.0.0.1
+
+# ===== 仅执行数据库测试时使用；正常启动不需要 =====
+# [可选] 独立、可丢弃 PostgreSQL 测试集群的管理连接，需有建库和管理角色权限。
+# 测试会创建/删除临时库、初始化集群级角色；不能指向业务或生产数据库所在的集群。
+# 不填写时测试工具使用内嵌真实 PostgreSQL；这仅是测试行为，dev 不会自动启动数据库。
+# CAGE_TEST_DATABASE_URL=postgresql://test_admin:REPLACE_WITH_TEST_PASSWORD@127.0.0.1:5433/postgres

package/templates/blank/.github/workflows/cage.yml

@@ -0,0 +1,44 @@
+# 尚未配置框架发布地址时直接调用同一个 CLI 门禁。
+# 框架发布后可将此任务替换为远端 app-verify.yml 的 uses 引用。
+name: Cage application
+on: [push, pull_request]
+permissions:
+  contents: read
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:18
+        env: { POSTGRES_PASSWORD: cage_ci }
+        ports: ['5432:5432']
+        options: --health-cmd "pg_isready -U postgres" --health-interval 5s --health-timeout 5s --health-retries 10
+    env:
+      CAGE_TEST_DATABASE_URL: postgres://postgres:cage_ci@localhost:5432/postgres
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - uses: pnpm/action-setup@v4
+        with: { version: 10.14.0 }
+      - uses: actions/setup-node@v4
+        with: { node-version: 24 }
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm build:app
+      - run: pnpm cage verify
+      - name: Pull request impact
+        if: github.event_name == 'pull_request'
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+        run: |
+          pnpm cage impact --base "$BASE_SHA" --format md --out .cage/impact.md
+          cat .cage/impact.md >> "$GITHUB_STEP_SUMMARY"
+      - run: pnpm audit --prod --audit-level high
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: cage-report
+          include-hidden-files: true
+          path: |
+            .cage/verify.json
+            .cage/test-results.json
+            .cage/impact.md

package/templates/blank/AGENTS.md

@@ -0,0 +1,96 @@
+# 本项目的业务开发说明
+
+这是 create-cage-app 的空白业务项目。真实运行的 domain 仅包含用户、部门和角色组织模型；从 packages/domain/src 新建客户自己的业务，再从 index.ts 导出。框架通过 @yss123/cage-* 依赖提供。
+
+先读 [业务开发指南](docs/ai/README.md)、[任务配方](docs/ai/recipes.md) 和 [错误码册](docs/errors/README.md)。[采购范例参考源码](docs/examples/purchase-admin/README.md) 只用于学习，未注册到应用；导读中的采购路径在 docs/examples/purchase-admin 下查找。普通业务路径仍相对项目根目录。
+
+## 项目自己的业务约定
+
+客户术语、角色权限、状态规则、第三方协议和验收标准写在本节或链接到独立文档。按客户需求新增业务，不要为了让空白页面有内容而复制采购演示、演示数据或伪造统计。
+
+本节位于托管区之外，cage sync 会保留。下面的托管区提供框架工作方法。
+
+<!-- cage:begin v0.2.0 -->
+## Cage 业务开发约定（框架托管）
+
+### 先读，再按需求改业务
+
+本项目由 create-cage-app 创建。框架来自 `@yss123/cage-*` 依赖，业务写在本项目；不需要克隆框架仓库，也不要复制框架内部实现。
+
+先读项目说明指定的学习资料，默认入口为 `docs/ai/README.md`。第一次读 `architecture.md`、`project-structure.md` 和 `primitives.md`；具体任务读 `recipes.md`，采购全链路读 `purchase-example.md`，错误查 `docs/errors/README.md` 和 `docs/ai/troubleshooting.md`。资料相对该学习目录，项目说明可指定源码仓库中的规范资料位置。
+
+### 业务代码放在哪里
+
+| 位置 | 职责 |
+| --- | --- |
+| `packages/domain/src/modules/<业务>` | 同业务聚合、状态、命令、事件、审批、查询、任务；模块 index.ts 公开导出 |
+| `packages/domain/src/workflows`、`integrations` | 跨模块反应 / 第三方协议与映射；不堆到全局 reactions.ts、queries.ts |
+| `packages/domain/src/index.ts` | 统一导出全部业务及组织模型；没导出的声明不会注册 |
+| `packages/contracts/src/aggregates/<聚合>`、`queries` | 生成协议；根 index.ts 提供 @app/contracts 公共入口，只用 cage gen 更新 |
+| `apps/api/src` | API/worker 薄启动入口，普通业务不手写 HTTP 路由 |
+| `apps/web/src/app` | 会话、导航、布局、模块组合；main.tsx 只挂载和装配 Provider |
+| `apps/web/src/modules/<业务>` | 页面、表单、专用 hooks/API/样式；从模块 index.ts 暴露页面 |
+| `apps/web/src/shared` | 跨模块复用且不绑定业务的 UI、hooks、纯辅助函数 |
+| `db/migrations` | 审查过的结构迁移，作用于已配置的数据库 |
+| `cage.config.json` | 项目路径、检查配置、graph.labels 中文图谱名称 |
+| `.env` | 本机真实连接和密钥；不提交、不输出完整内容 |
+
+新增业务不得继续平铺在 src 根目录。前端模块只依赖自己和 shared，由 app 通过公开入口组合；shared 不反向依赖业务。领域模块间确有读取依赖时走目标模块 index.ts；跨模块反应写 workflows。小模块不创建空层级，已有独立职责再拆文件。完整命名、目录树和示例见 `docs/ai/project-structure.md`。新模板启用 `structure: modular`，check/verify 检查目录和导入边界，遇到 CAGE-STRUCT 错误按职责修正。
+
+### 实现一项需求的顺序
+
+1. 先运行 `pnpm exec cage context "需求关键词"`；按需 `graph search` 查候选、`graph inspect` 查完整节点、`graph path` 看关系路径。确认中文匹配入口后按源码位置阅读实现；候选和子图不是全部依赖，具体条件不能凭连线推断。完整用法见 `docs/ai/ontology-context.md`。从用户需求确定字段、状态/动作、角色/范围、约束与后续动作；能由业务声明表达的不改框架。
+2. 已有业务含义变化时，修改前保存本体图基线：`pnpm exec cage analyze` 后将 `.cage/ontology.json` 另存为独立文件；或使用真实 Git 基线。
+3. 先声明 aggregate/states/command/constraints/event，再写 handler、reaction/query/approval/connector，最后接业务页面。声明使用模块顶层 `export const`，从 domain 入口导出，跨文件导出名保持唯一。
+4. 运行 `pnpm exec cage check` 和 `pnpm gen`，审查 contracts 和迁移草稿。按需运行 `pnpm exec cage impact --base-file 旧图.json`，补中文图谱名。
+5. 页面使用生成方法并处理 code/domainCode；新增能力由管理员授权。数据库结构变化审查后显式 `pnpm migrate`，dev 不代办迁移。
+6. 按改动运行必要验证，交付时说明体验步骤、授权配置、迁移，以及通过/跳过/未执行项。
+
+### 必守边界
+
+- 聚合定义对象字段、状态、范围字段与不变量；命令是业务写入口。handler 只计算业务变化和读取 reads 中的依赖，不直接操作数据库、网络或文件。
+- 对象关系统一放在 fields：ref 为外键，hasMany 为只读反查，manyToMany 自动生成中间表并随所属对象命令提交。前端用生成的 related 方法分页读取；不手写纯中间表聚合，不把单页结果当完整集合替换。完整例子见 docs/ai/relations.md。
+- command 的 input 使用 Zod；已有记录输入必须含 id。from/to 表达状态迁移；`to: null` 只适用于已有记录并保留状态，不能靠 handler 改 status 绕过状态机。
+- 写入、审计、版本、幂等和事务交给内核；不要在业务项目重建 repository、连接池或权限流水线。
+- 自定义查询声明 reads，二选一使用 sql/build，只读 `safe.*`；值参数化。不得拼接 SQL、查询基表绕过范围或硬编码密钥。
+- scope 描述范围字段，角色数据决定实际范围；`scope.none()` 不代表所有人可访问。`can/useCan` 只控制按钮，后端负责授权。
+- 前端从 `@app/contracts` 导入生成 API/类型，按需使用 `@yss123/cage-client`；不导入 domain、内核或数据库包。
+- 跨聚合写入通过 reaction 调用命令。`tx: 'same'` 共同提交/回滚，默认 outbox 异步执行。资源 acquires/releases 是图规则标签，实际占用/释放仍由命令完成；离开持有状态要检查每条释放路径。
+- 审批通过 approval + route 配置，结论是 process 命令；选中审批人不等于已具备能力、范围和额度。第三方 IO 通过连接器，回调验签后调用 external 命令。
+- job 的读取与调用必须列入 reads/calls。业务导入/导出放在需要的业务页面调用通用任务接口，202 只代表任务已接受；worker 必须运行。
+- 已部署事件只做兼容扩展；新增字段设为 optional，不兼容含义用新事件。已执行/已发布迁移不能改写，结构更新新增迁移。
+- 不手改生成物，不关闭门禁掩盖错误，不因方便自动授予生产角色新能力。unsafe 必须写明 reason/owner，不能替代普通业务声明。
+- 代码注释说明职责、关键流程和设计原因；避免无业务价值的防御分支和静默兜底。维护脚本用 TypeScript，不新增 .mjs。
+
+### 最小命令形状
+
+```ts
+// 片段：Order 为已导出的聚合，OrderSubmitted 为事件，业务校验按需求添加。
+export const submitOrder = command(Order, {
+  name: 'submit',
+  from: 'draft',
+  to: 'pending_approval',
+  emits: [OrderSubmitted],
+  handler: (draft) => draft,
+});
+```
+
+完整可添加的普通管理对象见 `docs/ai/primitives.md` 的 Note；采购模板的审批、资源、第三方示例在 `packages/domain/src`，空白模板的参考源码在 `docs/examples/purchase-admin`。先读本项目 AGENTS.md 中的模板说明，区分运行代码与参考资料。API 以当前包公开导出和生成契约为准，不发明不存在的配置和方法。
+
+### 启动、验证与排错
+
+在项目根目录执行：首次 `pnpm install`，复制并编辑 .env.example，仅提供已有库管理员连接后 `pnpm exec cage init`；再 `pnpm build:app`、`pnpm gen`，审查后 `pnpm migrate`，最后 `pnpm dev`。已有配置不能覆盖。
+
+init 只准备账号/schema/授权并填写三个连接，不创建数据库；APP/READ/MIGRATE 指向同一个库。已有集群账号复用原密码，日常启动不用管理员。普通项目不新增 Docker 生命周期命令。
+
+- `pnpm exec cage graph`：浏览器图谱，默认端口 15418，以终端为准。
+- `pnpm exec cage context command:对象.命令 --format json --out .cage/context.json`：按完整 key 取精简上下文；默认 Markdown，可用 --depth/--limit 调整范围。CLI 每次重新抽取；Web“复制 AI 上下文”使用当前页面快照，改代码后先刷新图谱。
+- `graph inspect/path` 有歧义时复制候选完整 key；path 默认沿箭头，--direction both 的逆向遍历不表示执行方向。报告中的测试/前端文件是候选，须核对；查询也会覆盖当前 .cage/ontology.json，旧基线务必另存。
+- `pnpm exec cage gen --check`：生成一致性；`pnpm exec cage sync --check`：本托管区一致性。
+- `pnpm exec cage test --only project`：业务测试；`pnpm verify`：类型、依赖、lint、图规则、生成、托管区、预算和测试。
+- `pnpm exec cage verify --skip-tests` 表示不完整门禁；派生测试跳过不能当作通过。测试连接只用独立测试集群。
+- 重要业务改动验证成功路径及有风险的反例；文档或可逆的小改动不反复跑全量数据库测试。
+- CLI 报错先看 code/at/reason/fix，再查错误码册；HTTP 错误查 runtime.md。异步失败先看 worker、同步记录和死信，修复后重放，不能直接 SQL 改状态。
+
+框架托管区由 cage sync 更新；项目独有的业务规则写在标记之外，避免升级覆盖。
+<!-- cage:end -->

package/templates/blank/Dockerfile

@@ -0,0 +1,25 @@
+# 独立业务仓库使用已发布的 @yss123/cage-* 依赖；先提交 pnpm-lock.yaml。
+# --framework-path 创建的 link: 本地依赖只用于源码开发，不能拷贝进独立镜像。
+FROM node:24-bookworm-slim AS build
+RUN corepack enable && corepack prepare pnpm@10.14.0 --activate
+WORKDIR /app
+COPY . .
+RUN pnpm install --frozen-lockfile && pnpm build:app
+RUN pnpm --filter @app/api deploy --prod --legacy /out/api
+
+# 发布过程先单独运行此 target，迁移账号只注入迁移任务。
+FROM build AS migration
+CMD ["pnpm", "cage", "migrate"]
+
+# API 与 worker 共用运行时镜像，通过启动命令区分职责。
+FROM node:24-bookworm-slim AS runtime
+WORKDIR /app
+COPY --from=build --chown=node:node /out/api /app
+COPY --from=build --chown=node:node /app/apps/web/dist /app/web
+# 系统管理与图谱共享中文显示配置；运行时工作目录同样保持为 /app。
+COPY --from=build --chown=node:node /app/cage.config.json /app/cage.config.json
+ENV NODE_ENV=production PORT=3000 WEB_DIR=/app/web
+USER node
+EXPOSE 3000
+CMD ["node", "dist/main.js"]
+# worker 启动命令：node dist/worker.js

package/templates/blank/README.md

@@ -0,0 +1,37 @@
+# Cage 空白业务项目
+
+这是可直接开发业务的 TypeScript + React 项目，框架由 `@yss123/cage-*` npm 包提供。当前仅注册用户、部门、角色基础模型，保留登录、权限、系统管理、审计和异步任务；没有采购、库存、审批演示声明或演示业务表。
+
+先读 [AGENTS.md](AGENTS.md) 和 [业务开发指南](docs/ai/README.md)。给 Codex 等工具描述自己的业务需求，按 [任务配方](docs/ai/recipes.md) 开发即可。[采购范例导读](docs/ai/purchase-example.md) 对应 `docs/examples/purchase-admin` 中的参考源码；这些文件不参与编译、领域注册或迁移。
+
+## 首次启动
+
+需要 Node.js 24、pnpm 10，以及一个**已经存在**的 PostgreSQL 数据库。框架负责连接和表结构，不创建数据库，不管理 Docker。
+
+1. 在项目根目录执行 `pnpm install`。
+2. 复制 `.env.example` 为 `.env`。按其中注释，仅填写 `CAGE_ADMIN_DATABASE_URL`，指向已有数据库。密码含特殊字符时需 URL 编码。
+3. 执行 `pnpm exec cage init`。自动创建运行、只读、迁移账号和随机密码，填写 `.env` 并移除管理员连接；已有配置不会重置密码。
+4. 执行 `pnpm build:app`、`pnpm gen`。审查 `db/migrations` 后执行 `pnpm migrate`，创建本项目需要的组织与系统表。
+5. 执行 `pnpm dev`，在浏览器打开终端打印的 Web 地址。初始管理员凭证在 API 终端显示一次，请自行妥善保存。
+
+登录后可从“系统管理”配置用户、部门、角色与权限，再按业务需求添加模块。页面不会显示虚构业务数据。`.env` 中三个账号连接同一个数据库；日常运行不需要管理员账号。首次迁移应在为本项目准备的库中执行，接管历史业务表需要额外映射和迁移审查。
+
+## 添加第一个业务模块
+
+先读[工程目录与代码组织](docs/ai/project-structure.md)。在 `packages/domain/src/modules/<业务>` 新建声明，通过模块 index.ts 从领域总入口导出；运行 `pnpm exec cage check`、`pnpm gen`，审查生成契约和迁移。在 `apps/web/src/modules/<业务>` 使用 `@app/contracts` 实现页面和表单，通过模块公开入口接入 `app` 导航；共享 UI/工具放 `shared`。最后按需迁移，并由管理员分配新增能力。完整的 Note 对象示例见 [原语与最小业务](docs/ai/primitives.md)。
+
+`src/main.tsx` 只挂载 React 和全局 Provider，业务不平铺到 src 根目录。`cage.config.json` 已启用 `structure: modular`，check/verify 会检查目录和依赖边界；不要关闭检查或将所有业务移入 shared 来消除提示。
+
+## 常用命令
+
+| 命令 | 用途 |
+| --- | --- |
+| `pnpm dev` | 连接已配置的数据库，启动 API、worker 与 Web |
+| `pnpm build:app` | 构建领域、API 和 Web |
+| `pnpm gen` | 生成契约、SQL、图谱和迁移草稿 |
+| `pnpm migrate` | 在已配置库中执行审查后的迁移 |
+| `pnpm exec cage graph` | 查看本体图谱；勾选“包含系统组织模型”可看初始组织模型 |
+| `pnpm verify` | 完整门禁，数据库测试须使用独立测试集群 |
+| `pnpm exec cage verify --skip-tests` | 仅静态门禁，会明确标为不完整 |
+
+配置错误看 `.env.example`，业务错误查 [错误码册](docs/errors/README.md)。不要编辑生成契约或已执行迁移；新增业务需要生成新的迁移。

package/templates/blank/_gitignore

@@ -0,0 +1,8 @@
+node_modules/
+dist/
+.cage/
+generated/
+.env
+.env.*
+!.env.example
+*.log

package/templates/blank/apps/api/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@app/api",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "start": "node dist/main.js",
+    "worker": "node dist/worker.js"
+  },
+  "dependencies": {
+    "@app/domain": "workspace:*",
+    "@yss123/cage-http": "0.2.0"
+  }
+}

package/templates/blank/apps/api/src/main.ts

@@ -0,0 +1,11 @@
+// 业务声明决定接口。这个入口只装配框架，不需要另建连接池或手写 CRUD 路由。
+// 数据库连接由框架读取项目 .env；生产环境的 WEB_DIR 指向前端构建目录。
+import { createServer } from '@yss123/cage-http';
+import * as domain from '@app/domain';
+
+const server = createServer({ domain, webDir: process.env.WEB_DIR, title: 'Cage 业务工作台' });
+await server.listen();
+
+// 退出时释放连接池及数据库通知连接，便于部署时平滑替换进程。
+process.once('SIGINT', () => void server.close());
+process.once('SIGTERM', () => void server.close());

package/templates/blank/apps/api/src/worker.ts

@@ -0,0 +1,8 @@
+// worker 处理框架异步任务；增加事件反应、审批或数据导入导出后也沿用此入口。
+// 空白项目没有第三方演示连接器，真实外部服务按业务需求声明和配置。
+import { startWorker } from '@yss123/cage-http/worker';
+import * as domain from '@app/domain';
+
+const worker = await startWorker({ domain });
+process.once('SIGINT', () => void worker.stop());
+process.once('SIGTERM', () => void worker.stop());

package/templates/blank/apps/api/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": { "outDir": "dist", "rootDir": "src" },
+  "include": ["src"]
+}