@yss123/cage-cli 0.1.0 → 0.3.0

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

@@ -0,0 +1,192 @@
+// 采购单声明集中列出状态、范围、不变量、命令和事件。
+// handler 只读声明的依赖；数据库写入、版本检查、审计由内核完成。
+import {
+  aggregate,
+  ceiling,
+  command,
+  emit,
+  event,
+  fail,
+  files,
+  id,
+  int,
+  list,
+  money,
+  ref,
+  scope,
+  sod,
+  states,
+  text,
+} from '@yss123/cage-kernel';
+import { z } from 'zod';
+import { Inventory } from '../inventory/index.js';
+
+/**
+ * 采购单生命周期：草稿提交后等待审批，通过后等待外部收货；退回修改重新进入草稿。
+ * received/rejected/cancelled 是流程终点，终点标记供图谱检查；记录迟到 ERP 回执仍由专门命令显式允许。
+ */
+export const POStatus = states('draft', 'pending_approval', 'approved', 'received', 'rejected', 'cancelled', {
+  terminal: ['received', 'rejected', 'cancelled'],
+});
+
+/**
+ * 采购主对象保存申请材料、流程状态和外部回执；不在此聚合直接维护库存占用记录。
+ * 所有写入都要求正金额和非空明细；部门字段提供范围依据，实际可见部门由当前角色授权决定。
+ * 金额和附件在数据库提交前由字段原语校验，用户不能通过修改前端界面绕过约束。
+ */
+export const PurchaseOrder = aggregate('PurchaseOrder', {
+  fields: {
+    /** 归属部门；创建输入省略时使用操作者部门，也是审批选人与部门子树范围的依据。 */
+    deptId: ref('Dept'),
+    /** 创建人由内核设置，用于本人范围与审批职责分离，客户端不提供该身份。 */
+    createdBy: ref('User'),
+    /** 可缺省的供应商电话；普通读侧按 phone 策略掩码，明文读取需要单独授权和审计。 */
+    supplierPhone: text(32).sensitive('phone').optional(),
+    /** 采购总额，以十进制金额字符串传输，最多两位小数；范例按元解释，不存整数分。 */
+    amount: money(),
+    /** 可为空的用途说明；创建可先存草稿，AI 预审会判断是否足以支撑审批。 */
+    reason: text(2000).optional(),
+    /** 申请明细快照：sku 为物料编码，qty 为整数件数；输入额外要求每行数量为正。 */
+    items: list({ sku: text(64), qty: int() }),
+    /** ERP 成功响应后回填的外部单号，尚未同步时为空；不作为采购单生命周期状态。 */
+    erpNo: text(64).optional(),
+    /** 最多十个私有文件 ID；每个上限 2 GiB，命令提交时才把 ready 上传与本单事务绑定。 */
+    attachments: files({ maxCount: 10, maxBytes: 2 * 1024 ** 3, accept: ['application/pdf', 'image/jpeg', 'image/png', 'text/plain'] }),
+  },
+  states: POStatus,
+  scope: scope.deptSubtree('deptId'),
+  invariants: {
+    amountPositive: (o) => Number(o.amount) > 0,
+    hasItems: (o) => o.items.length > 0,
+  },
+});
+
+/** 提交快照供审批启动：orderId 关联主对象，金额和部门供声明过的路由条件使用。 */
+export const OrderSubmitted = event('OrderSubmitted', { orderId: id(), amount: money(), deptId: id() });
+/** 审批通过时固定需要占用/推送的物料明细，同一份事件驱动同事务建锁和异步 ERP 推送。 */
+export const OrderApproved = event('OrderApproved', {
+  orderId: id(),
+  items: list({ sku: text(64), qty: int() }),
+});
+/** 取消记录原状态，使释放反应只处理此前已经批准、实际持锁的采购单。 */
+export const OrderCancelled = event('OrderCancelled', { orderId: id(), previousStatus: text() });
+/** 外部收货确认后发出，后台据此释放采购占用；不携带可直接写库的库存指令。 */
+export const OrderReceived = event('OrderReceived', { orderId: id() });
+
+/** 命令输入比持久化 int 原语更具体：至少一行且每行数量为正，避免零数量申请进入审批。 */
+const itemsInput = z.array(z.object({ sku: z.string(), qty: z.number().int().positive() })).min(1);
+
+/**
+ * 保存草稿；金额格式、字段长度和不变量由内核随后统一校验，handler 无额外副作用。
+ * deptId 可指定但仍须满足创建范围；attachments 为已完成上传 ID，省略时初始化为空集合。
+ * 此处不提交审批、不调用 ERP，便于用户先完成材料整理。
+ */
+export const create = command(PurchaseOrder, {
+  from: 'new',
+  to: 'draft',
+  input: z.object({
+    amount: z.string(),
+    items: itemsInput,
+    supplierPhone: z.string().optional(),
+    reason: z.string().max(2000).optional(),
+    deptId: z.string().uuid().optional(),
+    attachments: z.array(z.string().uuid()).max(10).optional(),
+  }),
+  handler: (o) => o,
+});
+
+// 退回后的说明只在草稿状态修改，保留提交时的版本校验和原始审计。
+/** 只更新用途并保留 draft 状态；trim 后至少一个字符，修改结果与版本递增、审计一起提交。 */
+export const explainPurpose = command(PurchaseOrder, {
+  from: 'draft', to: null,
+  description: '补充采购用途与必要性，保存后可以重新提交审核',
+  input: z.object({ id: z.string().uuid(), reason: z.string().trim().min(1).max(2000) }),
+  handler: (_draft, input) => ({ reason: input.reason }),
+});
+
+/** 审批流程将材料不足的单据退回草稿；process 专用，浏览器不能绕过待办直接调用。 */
+export const returnForChanges = command(PurchaseOrder, {
+  from: 'pending_approval', to: 'draft', invokedBy: 'process',
+  description: '审核材料不足时退回修改，重提后重新进行 AI 和人工审核',
+  handler: (draft) => draft,
+});
+
+// 附件变更与其他业务写入一样受状态、版本、范围和审计约束；审批后不能替换原始材料。
+/** 替换完整附件 ID 集合，空数组表示移除全部；上传归属检查、绑定和解绑由同一命令事务落实。 */
+export const setAttachments = command(PurchaseOrder, {
+  from: 'draft', to: null,
+  input: z.object({ id: z.string().uuid(), attachments: z.array(z.string().uuid()).max(10) }),
+  handler: (_draft, input) => ({ attachments: input.attachments }),
+});
+
+/** 提交只改变状态并记录 OrderSubmitted；审批实例由事件消费启动，HTTP 成功不代表审批已完成。 */
+export const submit = command(PurchaseOrder, {
+  from: 'draft',
+  to: 'pending_approval',
+  emits: [OrderSubmitted],
+  handler: (o) => (o.items.length === 0 ? fail('NO_ITEMS') : o),
+});
+
+/**
+ * 审批终结命令必须同时满足创建人与审批人分离、当前角色额度，以及声明的库存只读检查。
+ * stock 是 reads 绑定的受范围约束仓储；找不到 SKU 或登记数量不足时返回 STOCK_SHORT 并回滚。
+ * 该检查不扣减 available；真正占用由 OrderApproved 的同事务反应创建 InventoryLock。
+ * 范例展示资源配对，不实现多订单累计扣减、仓库出入库或价格核算。
+ */
+export const approve = command(PurchaseOrder, {
+  from: 'pending_approval',
+  to: 'approved',
+  invokedBy: 'process',
+  constraints: [sod.notSameAs('createdBy'), ceiling('amount')],
+  reads: { stock: Inventory },
+  emits: [OrderApproved],
+  handler: async (o, _input, { stock }) => {
+    const short = [];
+    for (const i of o.items) {
+      const s = await stock.findOne({ sku: i.sku });
+      if (!s || s.available < i.qty) short.push(i.sku);
+    }
+    return short.length ? fail('STOCK_SHORT', short) : o;
+  },
+});
+
+/** 人工审批拒绝后进入终态；此时尚未批准建锁，因此不需要发出库存释放事件。 */
+export const reject = command(PurchaseOrder, {
+  from: 'pending_approval',
+  to: 'rejected',
+  invokedBy: 'process',
+  handler: (o) => o,
+});
+
+/**
+ * 草稿、待审批和已批准单据均可取消；显式事件映射使用提交前快照保留 previousStatus。
+ * 待审批取消会关闭对应审批，已批准取消会异步释放锁；两者都由订阅声明处理。
+ */
+export const cancel = command(PurchaseOrder, {
+  from: ['draft', 'pending_approval', 'approved'],
+  to: 'cancelled',
+  emits: [emit(OrderCancelled, (o, _i, prev) => ({ orderId: o.id, previousStatus: prev.status }))],
+  handler: (o) => o,
+});
+
+// 仅连接器能回写 ERP 单号和收货结论，浏览器无法直接调用这两个命令。
+/** 接受可能迟到的 ERP 回执，只补单号并递增版本；to:null 明确保留 approved/received/cancelled 原状态。 */
+export const recordErpNo = command(PurchaseOrder, {
+  // ERP 推送可能早于取消发出、晚于取消返回；收货回调也可能先于推送应答到达。
+  // 这里只记录外部回执，保留当前生命周期，保证 outbox 后续的解锁事件能够继续投递。
+  from: ['approved', 'received', 'cancelled'],
+  to: null,
+  invokedBy: 'external',
+  input: z.object({ id: z.string().uuid(), erpNo: z.string() }),
+  handler: (_o, input) => ({ erpNo: input.erpNo }),
+});
+
+/** 只允许已批准单据确认收货；验签后的 external 调用触发事件，库存释放需等待 worker 消费。 */
+export const markReceived = command(PurchaseOrder, {
+  from: 'approved',
+  to: 'received',
+  invokedBy: 'external',
+  input: z.object({ id: z.string().uuid() }),
+  emits: [OrderReceived],
+  handler: (o) => o,
+});

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

@@ -3,6 +3,11 @@ import { query } from '@yss123/cage-kernel';
 import { z } from 'zod';
 import { PurchaseOrder } from './purchase-order.js';
 
+/**
+ * 按指定状态统计当前调用者可见采购单的部门分布，结果为 dept_id 与整数 n。
+ * reads 声明触发 PurchaseOrder.read 检查；safe.purchase_order 继续执行租户和数据范围过滤。
+ * :status 由内核绑定为参数，结果不代表跨权限的全公司统计；本声明没有业务写入副作用。
+ */
 export const poByStatus = query('poByStatus', {
   reads: [PurchaseOrder],
   input: z.object({ status: z.string() }),

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

@@ -1,9 +1,13 @@
 // 跨聚合资源配对：审批时同事务建锁，取消/收货时通过 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';
 
+/**
+ * 审批与建锁共用一笔数据库事务，任一命令失败则二者回滚；不会出现批准成功但没有锁的中间提交。
+ * acquires 仅供图规则配对，实际写入来自 acquireLock，映射只传当前批准事件的固定快照。
+ */
 export const lockOnApprove = reaction(OrderApproved, {
   command: acquireLock,
   tx: 'same',
@@ -11,12 +15,14 @@ export const lockOnApprove = reaction(OrderApproved, {
   map: (e) => ({ id: e.orderId, orderId: e.orderId, items: e.items }),
 });
 
+/** 草稿/待审批取消从未建锁，返回 null 跳过；已批准取消进入 outbox，等待 worker 按单据顺序释放。 */
 export const releaseOnCancel = reaction(OrderCancelled, {
   command: releaseLock,
   releases: 'inventory.lock',
   map: (e) => (e.previousStatus === 'approved' ? { id: e.orderId } : null),
 });
 
+/** 收货事件保证来自已批准单据，因此按订单 ID 释放；默认异步失败由 worker 重试/死信处理。 */
 export const releaseOnReceive = reaction(OrderReceived, {
   command: releaseLock,
   releases: 'inventory.lock',

package/templates/app/packages/domain/src/workflows/purchase-process.ts

@@ -0,0 +1,42 @@
+// 阅读规格引用真实命令与审批；人工收货通知与自动锁库存分别表达。
+import { businessProcess } from '@yss123/cage-kernel';
+import { PurchaseOrder, create, submit, approve, reject, cancel, markReceived, poApproval, returnForChanges, explainPurpose } from '../modules/purchase/index.js';
+import { InventoryLock, acquireLock, releaseLock } from '../modules/inventory/index.js';
+
+/**
+ * 面向人和 agent 的流程阅读规格，引用真实命令、审批和资源对象，供本体图展示及一致性检查。
+ * stages/transitions 说明人工、自动和等待关系，本声明本身不调度命令，也不新增权限或运行时副作用。
+ * 自动动作的真实事务和异步边界分别以 approval、reaction、connector 声明为准。
+ */
+export const purchaseLifecycle = businessProcess('purchase-lifecycle', {
+  title: '采购全流程', description: '从填写申请、提交审批到确认收货，查看库存占用与释放。',
+  area: { id: 'purchase', title: '采购管理', description: '采购申请、审批、收货与库存协作。' },
+  subject: PurchaseOrder, entry: 'create',
+  stages: {
+    create: { title: '填写采购申请', description: '录入采购金额和明细，保存采购草稿。', actor: '申请人', action: create },
+    submit: { title: '提交申请', description: '检查明细并提交采购审批。', actor: '申请人', action: submit },
+    approval: { title: '采购审批', description: 'AI 先核查材料；通过后部门经理审批，金额超过五万元时增加财务审批。疑难材料由本步骤转人工。', actor: 'AI、部门经理、财务', kind: 'decision', action: poApproval },
+    returned: { title: '退回修改', description: '材料不足退回草稿，保留本轮审核理由。', actor: '审批流程', action: returnForChanges },
+    revise: { title: '补充采购用途', description: '依据建议补充用途，再次提交后从 AI 预审开始。', actor: '申请人', action: explainPurpose },
+    approved: { title: '批准并锁定库存', description: '审批结论通过权限、额度和库存校验后，同事务锁定所需库存。', actor: '审批流程与系统', action: approve,
+      related: [{ object: InventoryLock, label: '同事务锁库存', via: acquireLock }] },
+    received: { title: '确认收货', description: '接收外部收货通知并更新采购单，异步释放库存锁。', actor: '外部系统与系统', kind: 'end', action: markReceived,
+      related: [{ object: InventoryLock, label: '收货后释放占用', via: releaseLock }] },
+    rejected: { title: '审批驳回', description: '驳回结论通过领域命令落到采购单，本范例此轮采购结束。', actor: '审批流程', kind: 'end', action: reject },
+    cancelled: { title: '取消采购', description: '申请人取消采购；若已批准则按实际映射释放库存占用。', actor: '申请人', kind: 'end', action: cancel,
+      related: [{ object: InventoryLock, label: '按原状态释放占用', via: releaseLock }] },
+  },
+  transitions: [
+    { from: 'create', to: 'submit', mode: 'manual', label: '填写完成后提交' },
+    { from: 'submit', to: 'approval', mode: 'automatic', label: '提交成功后启动审批' },
+    { from: 'approval', to: 'approved', mode: 'automatic', label: '审批通过' },
+    { from: 'approval', to: 'rejected', mode: 'automatic', label: '审批驳回' },
+    { from: 'approval', to: 'returned', mode: 'automatic', label: '材料不足' },
+    { from: 'returned', to: 'revise', mode: 'manual', label: '补充材料' },
+    { from: 'revise', to: 'submit', mode: 'manual', label: '重新提交' },
+    { from: 'approved', to: 'received', mode: 'wait', label: '等待外部收货通知' },
+    { from: 'create', to: 'cancelled', mode: 'manual', label: '取消草稿', branch: true },
+    { from: 'submit', to: 'cancelled', mode: 'manual', label: '取消审批中的采购', branch: true },
+    { from: 'approved', to: 'cancelled', mode: 'manual', label: '取消已批准采购', branch: true },
+  ],
+});

package/templates/blank/.dockerignore

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

package/templates/blank/.env.example

@@ -0,0 +1,71 @@
+# 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=
+
+# 生产 NODE_ENV=production 时必须提供合格随机密钥；固定开发值会被拒绝。
+# 组织在审查执行 migrate 后，显式 cage bootstrap --credentials-file <新的受限文件>。
+# API 日常启动不会初始化组织或向日志输出管理员密码。
+# 可信代理在 apps/api/src/main.ts 显式配置地址/网段；默认 trustProxy: false。
+# /healthz 表示存活，/readyz 检查数据库和授权监听；API 与 worker 使用同版本部署。
+
+# [可选，开发默认 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
+
+# 私有上传目录，不能通过 Nginx/静态服务公开；生产挂载持久卷并与数据库配套备份。
+# 默认是项目根目录 .cage-files；改变目录前必须迁移已有文件。
+CAGE_FILES_DIR=.cage-files
+
+# [可选，范例默认 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,136 @@
+# 本项目的业务开发说明
+
+这是 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.3.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`。资料相对该学习目录，项目说明可指定源码仓库中的规范资料位置。
+
+### 详细中文注释（每次开发必须遵守）
+
+所有新增和维护的手写源码都必须写详细中文注释，先读学习目录中的 `commenting.md`（独立项目为 `docs/ai/commenting.md`）。注释是交付内容，不能以“代码自解释”或“保持简洁”为由省略。
+
+- 每个文件开头说明模块职责、谁调用它、主要调用链和责任边界；纯导出入口也说明如何组合模块。
+- 导出函数、类、组件、hooks、接口和业务声明使用 JSDoc，写清用途、参数含义、返回结果、主要步骤、前置条件、失败行为和副作用；复杂内部函数同样说明。参数类型已表达的语法无需重复，业务单位、空值、默认行为与约束必须解释。
+- 领域代码说明字段和状态的业务意义、命令调用身份与权限/范围、reads 依赖、事件用途、事务与异步边界、幂等/重试及资源释放；只写实际声明和实现已有的保证。
+- 页面说明 URL/查询参数、数据来源、临时状态、加载/空态/失败/无权限、提交后的刷新、会话与订阅清理；复杂分支、计算、顺序、并发和缓存规则在附近解释原因与过程。
+- 测试说明场景、前置条件、动作、断言和所防止的回归；脚本说明输入、读写路径、执行顺序、外部副作用与退出条件。注释不含密钥、凭据或个人数据。
+- 注释同时回答“做什么、为什么、如何完成、有哪些边界”，不能只有一句标题，也不能机械逐行翻译、凑字数或批量粘贴空泛模板。代码变更时同步更新注释，交付前逐文件核对。
+- 生成契约的注释由生成器维护，不手改生成物；已执行/已发布迁移不能改写。仅补注释时不得顺便重构或改变逻辑、接口、配置值和运行文案。
+
+### 原生 AI 能力入口
+
+遇到以下需求，先读 `docs/ai/intelligence.md`，用 `pnpm exec cage capabilities "关键词" --format json` 核对当前安装版本的公开 API，再检查本项目 domain 导出和页面接入。关键词可直接使用下表需求名称；未命中时缩短关键词或查公开符号，不能据此断言能力不存在。
+
+| 需求 | 框架入口与应用职责 |
+| --- | --- |
+| AI审批 / 智能审批 | 现有 `step` 使用 `kind: 'ai'`，支持 pass 通过、return 退回修改、manual 转人工；应用声明策略、结论命令、自动执行角色及接管人 |
+| 业务助理 / 本体助理 | 导出 `ai({ models, assistant })`；框架提供执行循环、按领域声明生成的工具、会话、偏好记忆和 HTTP；应用配置授权及界面 |
+| 页面上下文 / 随页助理 | `useAssistant(client.ai, page)` 配合 `useAiPageContext` / `AiPageContext`；应用上报页面、对象、选中项和草稿，服务端重读并校验业务事实 |
+| 模型管理 / Responses | `managedModel` 接入 Admin 动态配置，支持 Chat Completions / Responses；应用配置部署加密密钥并显式授权管理者 |
+| 性格 / 流式输出 | Admin 管理性格，SDK 提供选择、增量文字与执行进度；应用实现悬浮窗、Markdown 和确认卡片 |
+| 上下文预算 | `ai({ context: ... })` 的配置形状见 `AiContextOptions`；框架按预算选择完整工具或发现模式，历史和本体按需读取 |
+
+前端只使用客户端、协议与契约；后端循环、通用工具和记忆使用框架实现。页面快照和性格不授予权限。分别核对**框架支持**（公开导出）、**项目已启用**（domain 导出、迁移、模型、权限、worker、SDK）和**实际验证通过**（真实角色与模型联调）；空白模板的参考代码不表示已启用。具体接入顺序和验收步骤见该指南，不必将整份指南塞入每次任务上下文。
+
+### 业务代码放在哪里
+
+| 位置 | 职责 |
+| --- | --- |
+| `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` | 会话、URL 路由、布局、模块组合；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 snapshot save before-change` 保存不可覆盖的命名基线；或使用真实 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 --snapshot before-change`，补中文图谱名。
+5. 页面使用生成方法并处理 code/domainCode；列表、详情等多页面注册到 React Router，Link/NavLink 导航，筛选/分页进入 URL。组件状态用于弹窗和表单等临时交互。新增能力由管理员授权。数据库结构变化审查后显式 `pnpm migrate`，dev 不代办迁移。
+6. 按 `commenting.md` 逐文件检查详细中文注释与实现一致，再按改动运行必要验证；交付时说明体验步骤、授权配置、迁移、注释覆盖，以及通过/跳过/未执行项。
+
+### 必守边界
+
+- 聚合定义对象字段、状态、范围字段与不变量；命令是业务写入口。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、内核或数据库包。
+- 多页面业务必须有独立 URL，不用 useState/tab 模拟整页导航；详情从 URL 取 ID 并独立加载。前端路由集中在 app，页面从模块公开入口接入 Outlet。登录后保留原路径/query/hash，401 回登录，403 展示权限提示；/admin/ 使用普通链接进入独立系统管理。前端路由不替代后端授权。实现、SPA 部署回退和浏览器配方见 docs/ai/routing.md。
+- 跨聚合写入通过 reaction 调用命令。`tx: 'same'` 共同提交/回滚，默认 outbox 异步执行。资源 acquires/releases 是图规则标签，实际占用/释放仍由命令完成；离开持有状态要检查每条释放路径。
+- 批量调用同一命令使用 reactionEach，声明 maxItems、唯一排序字段 orderBy、items 和 map；稳定键排序后串行执行。步骤依赖用 order，同事件同事务分组不得混用有序/无序或重复顺序。保持同事务回滚边界，见 docs/ai/primitives.md。
+- 审批通过 approval + route 配置，结论是 process 命令；选中审批人不等于已具备能力、范围和额度。第三方 IO 通过连接器，回调验签后调用 external 命令。
+- job 的读取与调用必须列入 reads/calls。业务导入/导出放在需要的业务页面调用通用任务接口，202 只代表任务已接受；worker 必须运行。
+- 已部署事件只做兼容扩展；新增字段设为 optional，不兼容含义用新事件。已执行/已发布迁移不能改写，结构更新新增迁移。
+- 不手改生成物，不关闭门禁掩盖错误，不因方便自动授予生产角色新能力。unsafe 必须写明 reason/owner，不能替代普通业务声明。
+- 按前述详细中文注释规范完成文件、API、业务声明和关键流程说明；避免无业务价值的防御分支和静默兜底。维护脚本用 TypeScript，不新增 .mjs。
+
+### 最小命令形状
+
+```ts
+// 片段：Order 为已导出的聚合，OrderSubmitted 为事件，业务校验按需求添加。
+/**
+ * 将草稿订单提交审批：只有 draft 可进入 pending_approval。
+ * 入口使用 Order.submit 能力，真实授权、范围、状态和版本由内核检查；声明本身不自动授予权限。
+ * handler 返回草稿供后续校验和持久化，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 exec cage bootstrap --credentials-file .cage/admin-credentials.json` 显式初始化组织，最后 `pnpm dev`。已有配置不能覆盖，凭据文件必须是新受限文件且父目录存在。
+
+init 只准备账号/schema/授权并填写三个连接，不创建数据库；APP/READ/MIGRATE 指向同一个库。已有集群账号复用原密码，日常启动不用管理员。普通项目不新增 Docker 生命周期命令。
+
+API 日常启动不初始化组织、不输出管理员密码；生产缺少合格 Cookie 密钥会拒绝启动。bootstrap 不自动授予业务能力。`/healthz` 只表示存活，`/readyz` 检查必要依赖。首阶段 API 与 worker 同版本部署，查看实际注册指纹和消费者心跳。
+
+- `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 的逆向遍历不表示执行方向。报告中的测试/前端文件是候选，须核对；context 与图谱查询不覆盖当前图或命名快照。
+- `pnpm exec cage capabilities 关键词 --format json`：查当前安装版本公开签名；`cage doctor`：区分注册、生成、构建、迁移、授权与实际进程证据，unknown 不能当作通过。`cage timeline/explain` 关联实际异步证据与解释授权，参数和权限见 docs/ai/diagnostics.md。
+- 生成方法支持 signal/timeoutMs/idempotencyKey 请求选项。底层 CageResult 与 mutation 行为有区别：useCageCommand 失败抛 CageCommandError，成功才返回业务数据。订阅 client.subscribe 在退出、401、切换账号时取消查询并清除应用缓存。
+- `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` 表示不完整门禁；派生测试跳过不能当作通过。测试连接只用独立测试集群。
+- 重要业务改动验证成功路径及有风险的反例；文档或可逆的小改动不反复跑全量数据库测试。
+- 修改页面/导航后实际验收深链接、刷新、前进后退、登录回跳、无权限和 404；生产再查 SPA 回退。check/verify 不自动完成浏览器验收，未执行要明确报告。见 docs/ai/routing.md。
+- 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,40 @@
+# 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 exec cage bootstrap --credentials-file .cage/admin-credentials.json` 显式初始化组织；凭证只写到新的受限文件，交付后移除。业务能力需管理员配置。
+6. 执行 `pnpm dev`，在浏览器打开终端打印的 Web 地址。日常 API 启动不初始化组织或输出密码。
+
+登录后可从“系统管理”配置用户、部门、角色与权限，再按业务需求添加模块。页面不会显示虚构业务数据。`.env` 中三个账号连接同一个数据库；日常运行不需要管理员账号。首次迁移应在为本项目准备的库中执行，接管历史业务表需要额外映射和迁移审查。
+
+前端已配置 React Router：`/login` 登录、`/workspace` 工作台、`/directory/users` 成员列表、`/directory/users/:id` 成员详情，以及应用 404。成员页面只读取已有组织模型，需要 User.read，未增加演示业务或数据。详情可直达、刷新，登录后返回原地址。新增业务与生产 SPA 回退按[路由和浏览器验收指南](docs/ai/routing.md)执行；反向代理示例见 [deploy/nginx.conf](deploy/nginx.conf)。
+
+## 添加第一个业务模块
+
+先读[工程目录与代码组织](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,9 @@
+node_modules/
+dist/
+.cage/
+.cage-files/
+generated/
+.env
+.env.*
+!.env.example
+*.log