@yss123/cage-cli 0.1.0 → 0.3.0

package/templates/blank/docs/examples/purchase-admin/packages/domain/src/modules/purchase/purchase-order.test.ts

@@ -0,0 +1,146 @@
+// 定向业务测试补足通用造数无法准备的库存、审批人和角色参数。
+// 使用真实 PostgreSQL 及示例迁移，确保示例不是仅能通过抽取的静态声明。
+import { afterAll, beforeAll, expect, it } from 'vitest';
+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';
+
+let env: TestEnv;
+let buyer: TestUser;
+let manager: TestUser;
+/**
+ * 夹具通过真实命令建立部门负责人和库存，不绕过领域规则直接造业务行。
+ * 申请人和经理能力分开，经理额度限定为 50000，确保后续断言真的经过职责分离与额度分支。
+ */
+beforeAll(async () => {
+  env = await createTestEnv({
+    domain,
+    migrations: readMigrations(fileURLToPath(new URL('../../../../../db/migrations/', import.meta.url))),
+  });
+  buyer = await env.user({
+    caps: ['PurchaseOrder.create', 'PurchaseOrder.submit', 'PurchaseOrder.cancel', 'PurchaseOrder.read'],
+  });
+  manager = await env.user({
+    caps: ['PurchaseOrder.approve'],
+    params: { 'PurchaseOrder.approve': { ceiling: 50000 } },
+  });
+  await env.kernel.execute('Dept.update', { id: env.rootDeptId, leaderId: manager.id }, env.system());
+  await env.kernel.execute('Inventory.create', { sku: 'A-01', available: 100 }, env.system());
+});
+afterAll(() => env?.close());
+
+/** 创建并提交一张 1200 元、两件 A-01 的采购单；只推进领域状态，不在此助手中消费 outbox。 */
+async function submitted() {
+  const ctx = await buyer.ctx();
+  const order = await env.kernel.execute(
+    'PurchaseOrder.create',
+    { amount: '1200.00', items: [{ sku: 'A-01', qty: 2 }] },
+    ctx,
+  );
+  return env.kernel.execute('PurchaseOrder.submit', { id: order.id }, ctx);
+}
+
+/** 同时验证同步提交边界、异步释放与审计条数，避免把命令成功返回当作后台已完成。 */
+it('审批成功同事务建锁；取消后 worker 释放锁，且每步都有审计', async () => {
+  const order = await submitted();
+  const process = env.kernel.processCtx({
+    process: 'po-approval',
+    tenantId: env.tenantId,
+    onBehalfOf: manager.id,
+    capabilities: ['PurchaseOrder.approve'],
+  });
+  await env.kernel.execute('PurchaseOrder.approve', { id: order.id }, process);
+  expect(
+    (await env.query('select status from core.inventory_lock where id = $1', [order.id]))[0].status,
+  ).toBe('held');
+  // 先完成审批事件及 ERP 回写，再验证后续取消的资源释放。
+  // 同一单据的 outbox 严格按顺序执行，不能越过尚未成功的前序事件。
+  await env.drain();
+  await env.kernel.execute('PurchaseOrder.cancel', { id: order.id }, await buyer.ctx());
+  await env.drain();
+  expect(
+    (await env.query('select status from core.inventory_lock where id = $1', [order.id]))[0].status,
+  ).toBe('released');
+  expect(
+    await env.audit({ aggregateId: order.id, command: 'PurchaseOrder.approve', kind: 'write' }),
+  ).toHaveLength(1);
+});
+
+/** process 只是调用来源，onBehalfOf 仍保留实际操作者；流程身份不得消除创建人分离约束。 */
+it('提单人不能借流程身份审批自己的采购单', async () => {
+  const order = await submitted();
+  const process = env.kernel.processCtx({
+    process: 'po-approval',
+    tenantId: env.tenantId,
+    onBehalfOf: buyer.id,
+    capabilities: ['PurchaseOrder.approve'],
+  });
+  expect((await env.callAs(process, 'PurchaseOrder.approve', { id: order.id })).code).toBe(
+    'CONSTRAINT_VIOLATED',
+  );
+});
+
+/** 通过控制事件消费顺序模拟 ERP 响应迟到，覆盖取消和收货两条终态路径及后续锁释放。 */
+it.each(['cancelled', 'received'] as const)(
+  '采购单进入 %s 后，延迟的 ERP 回写保留终态且不会阻塞解锁',
+  async (status) => {
+    const order = await submitted();
+    const process = env.kernel.processCtx({
+      process: 'po-approval',
+      tenantId: env.tenantId,
+      onBehalfOf: manager.id,
+      capabilities: ['PurchaseOrder.approve'],
+    });
+    await env.kernel.execute('PurchaseOrder.approve', { id: order.id }, process);
+    // 有意在处理 outbox 之前取消：数据库命令与第三方响应之间没有完成顺序保证。
+    // 断言最终业务状态和资源状态，避免仅验证命令返回成功而漏掉死信阻塞。
+    if (status === 'cancelled') {
+      await env.kernel.execute('PurchaseOrder.cancel', { id: order.id }, await buyer.ctx());
+    } else {
+      const external = systemCtx({
+        kind: 'external',
+        name: 'erp',
+        tenantId: env.tenantId,
+        capabilities: ['PurchaseOrder.markReceived'],
+      });
+      await env.kernel.execute('PurchaseOrder.markReceived', { id: order.id }, external);
+    }
+    await env.drain();
+    const saved = (
+      await env.query('select status, erp_no, version from core.purchase_order where id = $1', [order.id])
+    )[0];
+    expect(saved.status).toBe(status);
+    expect(saved.erp_no).toBeTruthy();
+    expect(saved.version).toBe(5);
+    expect(
+      (await env.query('select status from core.inventory_lock where id = $1', [order.id]))[0].status,
+    ).toBe('released');
+    expect(
+      await env.query('select id from sys.dead_letter where aggregate_id = $1', [order.id]),
+    ).toHaveLength(0);
+    expect(
+      await env.audit({ aggregateId: order.id, command: 'PurchaseOrder.recordErpNo', kind: 'write' }),
+    ).toHaveLength(1);
+  },
+);
+
+/** 低额度反例检查硬约束阻止批准，且同事务反应没有留下半成功的占用记录。 */
+it('审批额度不够时保留待审批状态，不创建库存锁', async () => {
+  const order = await submitted();
+  const lowLimit = await env.user({
+    caps: ['PurchaseOrder.approve'],
+    params: { 'PurchaseOrder.approve': { ceiling: 500 } },
+  });
+  const process = env.kernel.processCtx({
+    process: 'po-approval',
+    tenantId: env.tenantId,
+    onBehalfOf: lowLimit.id,
+    capabilities: ['PurchaseOrder.approve'],
+  });
+  expect((await env.callAs(process, 'PurchaseOrder.approve', { id: order.id })).code).toBe(
+    'CONSTRAINT_VIOLATED',
+  );
+  expect(await env.query('select id from core.inventory_lock where id = $1', [order.id])).toHaveLength(0);
+});

package/templates/blank/docs/examples/purchase-admin/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/blank/docs/examples/purchase-admin/packages/domain/src/modules/purchase/queries.ts

@@ -0,0 +1,15 @@
+// 查询只能读取安全视图；命名参数由运行时绑定，不拼接用户输入。
+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() }),
+  sql: `select dept_id, count(*)::int as n from safe.purchase_order where status = :status group by dept_id`,
+});

package/templates/blank/docs/examples/purchase-admin/packages/domain/src/workflows/purchase-inventory.ts

@@ -0,0 +1,30 @@
+// 跨聚合资源配对：审批时同事务建锁，取消/收货时通过 outbox 释放。
+// acquires/releases 供图规则检查；map 返回 null 表示该次事件没有需要释放的资源。
+import { reaction } from '@yss123/cage-kernel';
+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',
+  acquires: 'inventory.lock',
+  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',
+  map: (e) => ({ id: e.orderId }),
+});

package/templates/blank/docs/examples/purchase-admin/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/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@app/business-app",
+  "private": true,
+  "type": "module",
+  "packageManager": "pnpm@10.14.0",
+  "scripts": {
+    "dev": "cage dev",
+    "migrate": "cage migrate",
+    "verify": "cage verify",
+    "gen": "cage gen",
+    "build:app": "pnpm --filter @app/domain build && pnpm --filter @app/api build && pnpm --filter @app/web build"
+  },
+  "devDependencies": {
+    "@yss123/cage-cli": "0.3.0",
+    "@yss123/cage-testkit": "0.3.0",
+    "@yss123/cage-lint": "0.3.0",
+    "@types/node": "^24.3.0",
+    "typescript": "~5.9.3",
+    "vitest": "^4.1.12",
+    "tsx": "^4.20.5"
+  }
+}

package/templates/blank/packages/contracts/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@app/contracts",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@yss123/cage-client": "0.3.0",
+    "zod": "^4.1.5"
+  }
+}

package/templates/blank/packages/contracts/src/aggregates/dept/index.ts

@@ -0,0 +1,74 @@
+// 生成物：由 cage gen 从 domain 声明生成，不要手改。
+/* eslint-disable */
+
+import { z } from 'zod';
+import { client, useCageList, useCageQuery, type TransferTask, type RequestOptions } from '@yss123/cage-client';
+
+/** 部门：读侧快照（敏感字段是按权限掩码后的值） */
+export const DeptSchema = z.object({
+  id: z.string().uuid(),
+  name: z.string(),
+  code: z.string().nullable().optional(),
+  parentId: z.string().uuid().nullable().optional(),
+  ancestors: z.string(),
+  leaderId: z.string().uuid().nullable().optional(),
+  status: z.enum(["active", "archived"]),
+  version: z.number().int(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+export type Dept = z.infer<typeof DeptSchema>;
+export type DeptStatus = Dept['status'];
+export const DeptStates = ['active', 'archived'] as const;
+
+/** 命令输入：和后端命令的输入校验完全一致 */
+export const DeptInputs = {
+  archive: z.object({ id: z.string().uuid().regex(new RegExp("^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$")) }),
+  create: z.object({ name: z.string().min(1).max(100), code: z.string().max(64).optional(), parentId: z.string().uuid().regex(new RegExp("^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$")).nullable().optional(), leaderId: z.string().uuid().regex(new RegExp("^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$")).nullable().optional() }),
+  update: z.object({ id: z.string().uuid().regex(new RegExp("^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$")), name: z.string().min(1).max(100).optional(), code: z.string().max(64).nullable().optional(), leaderId: z.string().uuid().regex(new RegExp("^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$")).nullable().optional() }),
+};
+
+/** Dept.archive 可能返回的错误码 */
+export type DeptArchiveError = 'CONFLICT' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
+/** Dept.create 可能返回的错误码 */
+export type DeptCreateError = 'CONFLICT' | 'CONSTRAINT_VIOLATED' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT';
+/** Dept.update 可能返回的错误码 */
+export type DeptUpdateError = 'CONFLICT' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
+
+export type DeptSortKey = 'createdAt' | 'updatedAt' | 'name' | 'code' | 'parentId' | 'ancestors' | 'leaderId';
+export interface DeptListParams {
+  page?: number;
+  pageSize?: number;
+  /** 排序：字段名，前面加 - 表示倒序 */
+  sort?: DeptSortKey | `-${DeptSortKey}`;
+  /** 可以逗号分隔多个状态 */
+  status?: string;
+  createdAfter?: string;
+  createdBefore?: string;
+  name?: string | number | boolean;
+  code?: string | number | boolean;
+  parentId?: string | number | boolean;
+  ancestors?: string | number | boolean;
+  leaderId?: string | number | boolean;
+}
+
+/** 调用方法：每个命令一个；client 自动生成并附带幂等键和 CSRF 令牌 */
+export const dept = {
+  /** 停用部门（没有在职用户和下级部门时） */
+  archive: (id: string, expectedVersion?: number, options: RequestOptions = {}) => client.post<Dept, DeptArchiveError>(`/api/dept/${encodeURIComponent(id)}/archive`, { expectedVersion }, options),
+  /** 新建部门 */
+  create: (input: z.input<typeof DeptInputs.create>, options: RequestOptions = {}) => client.post<Dept, DeptCreateError>('/api/dept/create', input, options),
+  /** 修改部门名称、编码、负责人 */
+  update: (id: string, input: Omit<z.input<typeof DeptInputs.update>, 'id'>, expectedVersion?: number, options: RequestOptions = {}) => client.post<Dept, DeptUpdateError>(`/api/dept/${encodeURIComponent(id)}/update`, { ...input, expectedVersion }, options),
+  /** 异步导出 CSV：返回任务，使用 client.transfer(id) 查状态，完成后下载。需要 Dept.export 能力。 */
+  export: (params: DeptListParams = {}, options: RequestOptions = {}) => client.post<TransferTask, 'CONFLICT'>('/api/dept/export', params, options),
+  get: (id: string, options: RequestOptions = {}) => client.get<Dept>(`/api/dept/${encodeURIComponent(id)}`, undefined, options),
+  list: (params: DeptListParams = {}, options: RequestOptions = {}) => client.get<{ items: Dept[]; total: number; page: number; pageSize: number }>('/api/dept', params as Record<string, unknown>, options),
+};
+
+/** 详情查询 hook：响应也用 schema 校验；范围外返回 NOT_FOUND */
+export const useDept = (id: string) => useCageQuery(['dept', id], `/api/dept/${encodeURIComponent(id)}`, DeptSchema, { enabled: !!id });
+/** 列表查询 hook：走读侧账号与安全视图 */
+export const useDeptList = (params: DeptListParams = {}) => useCageList(['dept'], '/api/dept', params as Record<string, unknown>, DeptSchema);
+/** 查询缓存键前缀：命令成功后让它失效 */
+export const deptKeys = { all: ['dept'] as const, one: (id: string) => ['dept', id] as const };

package/templates/blank/packages/contracts/src/aggregates/role/index.ts

@@ -0,0 +1,85 @@
+// 生成物：由 cage gen 从 domain 声明生成，不要手改。
+/* eslint-disable */
+
+import { z } from 'zod';
+import { client, useCageList, useCageQuery, type TransferTask, type RequestOptions } from '@yss123/cage-client';
+
+/** 角色：读侧快照（敏感字段是按权限掩码后的值） */
+export const RoleSchema = z.object({
+  id: z.string().uuid(),
+  code: z.string(),
+  name: z.string(),
+  capabilities: z.array(z.object({ capability: z.string(), params: z.record(z.string(), z.unknown()).nullable().optional() })),
+  scopes: z.array(z.object({ aggregate: z.string(), combinator: z.enum(["all", "self", "dept", "deptSubtree", "deptSet"]), deptIds: z.array(z.string().uuid()).nullable().optional() })),
+  status: z.enum(["active", "archived"]),
+  version: z.number().int(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+export type Role = z.infer<typeof RoleSchema>;
+export type RoleStatus = Role['status'];
+export const RoleStates = ['active', 'archived'] as const;
+
+/** 命令输入：和后端命令的输入校验完全一致 */
+export const RoleInputs = {
+  archive: z.object({ id: z.string().uuid().regex(new RegExp("^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$")) }),
+  create: z.object({ code: z.string().min(1).max(64).regex(new RegExp("^[a-z][a-z0-9_]*$")), name: z.string().min(1).max(100) }),
+  grantCapability: z.object({ id: z.string().uuid().regex(new RegExp("^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$")), capability: z.string().min(1).max(200), params: z.record(z.string(), z.unknown()).optional() }),
+  rename: z.object({ id: z.string().uuid().regex(new RegExp("^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$")), name: z.string().min(1).max(100) }),
+  revokeCapability: z.object({ id: z.string().uuid().regex(new RegExp("^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$")), capability: z.string().min(1).max(200) }),
+  setScope: z.object({ id: z.string().uuid().regex(new RegExp("^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$")), aggregate: z.string().min(1).max(100), combinator: z.enum(["all", "self", "dept", "deptSubtree", "deptSet"]).nullable(), deptIds: z.array(z.string().uuid().regex(new RegExp("^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"))).optional() }),
+};
+
+/** Role.archive 可能返回的错误码 */
+export type RoleArchiveError = 'CONFLICT' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
+/** Role.create 可能返回的错误码 */
+export type RoleCreateError = 'CONFLICT' | 'CONSTRAINT_VIOLATED' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT';
+/** Role.grantCapability 可能返回的错误码 */
+export type RoleGrantCapabilityError = 'CONFLICT' | 'CONSTRAINT_VIOLATED' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
+/** Role.rename 可能返回的错误码 */
+export type RoleRenameError = 'CONFLICT' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
+/** Role.revokeCapability 可能返回的错误码 */
+export type RoleRevokeCapabilityError = 'CONFLICT' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
+/** Role.setScope 可能返回的错误码 */
+export type RoleSetScopeError = 'CONFLICT' | 'CONSTRAINT_VIOLATED' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
+
+export type RoleSortKey = 'createdAt' | 'updatedAt' | 'code' | 'name';
+export interface RoleListParams {
+  page?: number;
+  pageSize?: number;
+  /** 排序：字段名，前面加 - 表示倒序 */
+  sort?: RoleSortKey | `-${RoleSortKey}`;
+  /** 可以逗号分隔多个状态 */
+  status?: string;
+  createdAfter?: string;
+  createdBefore?: string;
+  code?: string | number | boolean;
+  name?: string | number | boolean;
+}
+
+/** 调用方法：每个命令一个；client 自动生成并附带幂等键和 CSRF 令牌 */
+export const role = {
+  /** 停用角色 */
+  archive: (id: string, expectedVersion?: number, options: RequestOptions = {}) => client.post<Role, RoleArchiveError>(`/api/role/${encodeURIComponent(id)}/archive`, { expectedVersion }, options),
+  /** 新建角色（默认没有任何能力） */
+  create: (input: z.input<typeof RoleInputs.create>, options: RequestOptions = {}) => client.post<Role, RoleCreateError>('/api/role/create', input, options),
+  /** 给角色授予能力点（不能授出自己没有的能力点） */
+  grantCapability: (id: string, input: Omit<z.input<typeof RoleInputs.grantCapability>, 'id'>, expectedVersion?: number, options: RequestOptions = {}) => client.post<Role, RoleGrantCapabilityError>(`/api/role/${encodeURIComponent(id)}/grant-capability`, { ...input, expectedVersion }, options),
+  /** 修改角色名称 */
+  rename: (id: string, input: Omit<z.input<typeof RoleInputs.rename>, 'id'>, expectedVersion?: number, options: RequestOptions = {}) => client.post<Role, RoleRenameError>(`/api/role/${encodeURIComponent(id)}/rename`, { ...input, expectedVersion }, options),
+  /** 收回角色的能力点 */
+  revokeCapability: (id: string, input: Omit<z.input<typeof RoleInputs.revokeCapability>, 'id'>, expectedVersion?: number, options: RequestOptions = {}) => client.post<Role, RoleRevokeCapabilityError>(`/api/role/${encodeURIComponent(id)}/revoke-capability`, { ...input, expectedVersion }, options),
+  /** 设置角色在某个聚合上的数据范围（不能授出比自己更宽的范围） */
+  setScope: (id: string, input: Omit<z.input<typeof RoleInputs.setScope>, 'id'>, expectedVersion?: number, options: RequestOptions = {}) => client.post<Role, RoleSetScopeError>(`/api/role/${encodeURIComponent(id)}/set-scope`, { ...input, expectedVersion }, options),
+  /** 异步导出 CSV：返回任务，使用 client.transfer(id) 查状态，完成后下载。需要 Role.export 能力。 */
+  export: (params: RoleListParams = {}, options: RequestOptions = {}) => client.post<TransferTask, 'CONFLICT'>('/api/role/export', params, options),
+  get: (id: string, options: RequestOptions = {}) => client.get<Role>(`/api/role/${encodeURIComponent(id)}`, undefined, options),
+  list: (params: RoleListParams = {}, options: RequestOptions = {}) => client.get<{ items: Role[]; total: number; page: number; pageSize: number }>('/api/role', params as Record<string, unknown>, options),
+};
+
+/** 详情查询 hook：响应也用 schema 校验；范围外返回 NOT_FOUND */
+export const useRole = (id: string) => useCageQuery(['role', id], `/api/role/${encodeURIComponent(id)}`, RoleSchema, { enabled: !!id });
+/** 列表查询 hook：走读侧账号与安全视图 */
+export const useRoleList = (params: RoleListParams = {}) => useCageList(['role'], '/api/role', params as Record<string, unknown>, RoleSchema);
+/** 查询缓存键前缀：命令成功后让它失效 */
+export const roleKeys = { all: ['role'] as const, one: (id: string) => ['role', id] as const };