@yss123/cage-cli 0.2.0 → 0.3.1

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

@@ -2,6 +2,11 @@
 import { daysAgo, job } from '@yss123/cage-kernel';
 import { PurchaseOrder, cancel } from './purchase-order.js';
 
+/**
+ * 每日 02:00 候选周期清理创建超过三十天且仍为 draft 的单据，时间解释沿用 worker 调度器环境。
+ * reads/calls 是实际运行白名单；查询默认批次上限为 1000，逐条取消各自经过独立命令事务。
+ * 已成功取消的单据不会再次匹配 draft；中途失败保留已提交进度，不能把本轮任务视为整体回滚。
+ */
 export const expireStaleOrders = job('expireStaleOrders', {
   cron: '0 2 * * *',
   reads: [PurchaseOrder],

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

@@ -10,6 +10,10 @@ import * as domain from '../../index.js';
 let env: TestEnv;
 let buyer: TestUser;
 let manager: TestUser;
+/**
+ * 夹具通过真实命令建立部门负责人和库存，不绕过领域规则直接造业务行。
+ * 申请人和经理能力分开，经理额度限定为 50000，确保后续断言真的经过职责分离与额度分支。
+ */
 beforeAll(async () => {
   env = await createTestEnv({
     domain,
@@ -27,6 +31,7 @@ beforeAll(async () => {
 });
 afterAll(() => env?.close());
 
+/** 创建并提交一张 1200 元、两件 A-01 的采购单；只推进领域状态，不在此助手中消费 outbox。 */
 async function submitted() {
   const ctx = await buyer.ctx();
   const order = await env.kernel.execute(
@@ -37,6 +42,7 @@ async function submitted() {
   return env.kernel.execute('PurchaseOrder.submit', { id: order.id }, ctx);
 }
 
+/** 同时验证同步提交边界、异步释放与审计条数，避免把命令成功返回当作后台已完成。 */
 it('审批成功同事务建锁；取消后 worker 释放锁，且每步都有审计', async () => {
   const order = await submitted();
   const process = env.kernel.processCtx({
@@ -62,6 +68,7 @@ it('审批成功同事务建锁；取消后 worker 释放锁，且每步都有
   ).toHaveLength(1);
 });
 
+/** process 只是调用来源，onBehalfOf 仍保留实际操作者；流程身份不得消除创建人分离约束。 */
 it('提单人不能借流程身份审批自己的采购单', async () => {
   const order = await submitted();
   const process = env.kernel.processCtx({
@@ -75,6 +82,7 @@ it('提单人不能借流程身份审批自己的采购单', async () => {
   );
 });
 
+/** 通过控制事件消费顺序模拟 ERP 响应迟到，覆盖取消和收货两条终态路径及后续锁释放。 */
 it.each(['cancelled', 'received'] as const)(
   '采购单进入 %s 后，延迟的 ERP 回写保留终态且不会阻塞解锁',
   async (status) => {
@@ -118,6 +126,7 @@ it.each(['cancelled', 'received'] as const)(
   },
 );
 
+/** 低额度反例检查硬约束阻止批准，且同事务反应没有留下半成功的占用记录。 */
 it('审批额度不够时保留待审批状态，不创建库存锁', async () => {
   const order = await submitted();
   const lowLimit = await env.user({

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

@@ -1,12 +1,17 @@
-// 采购单声明集中列出状态、范围、不变量、命令和事件。
-// handler 只读声明的依赖；数据库写入、版本检查、审计由内核完成。
+/**
+ * 采购单声明集中列出申请材料、专业复核名单、状态、范围、命令和事件，由 API、worker 和生成器统一消费。
+ * 草稿可编辑专业复核名单，提交重新核对协作名录；handler 仅读取声明依赖，数据库写入、版本与审计由内核完成。
+ * 审批结论仍以 process 命令执行职责分离、额度和库存检查；选入名录或路由不授予权限。
+ */
 import {
   aggregate,
+  bool,
   ceiling,
   command,
   emit,
   event,
   fail,
+  files,
   id,
   int,
   list,
@@ -16,22 +21,47 @@ import {
   sod,
   states,
   text,
+  type ReadRepo,
 } from '@yss123/cage-kernel';
 import { z } from 'zod';
 import { Inventory } from '../inventory/index.js';
+import { ApprovalMember } from './approval-members.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(),
+    /** 是否增加专业会签；旧记录 null/缺省按 false，不改变已经启动的审批实例。 */
+    needsSpecialistReview: bool().optional(),
+    /** 提交快照的专业复核用户 UUID；旧记录可为空，启用复核时必须为 1–5 个不同且非创建人的有效名录用户。 */
+    reviewerIds: list(id()).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'),
@@ -41,16 +71,42 @@ export const PurchaseOrder = aggregate('PurchaseOrder', {
   },
 });
 
+/** 提交快照供审批启动：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);
 
+/**
+ * 在设置和提交时核对专业复核名单，防止界面被绕过、名录退役或重复账号减少会签人数。
+ * disabled/范围/批准能力仍由审批运行时处理；此处只按当前命令声明的名录读依赖判断业务成员 active。
+ * 关闭专业复核必须传空名单；旧记录 null 等价 false/[]。最多五人使逐人查询有明确上限。
+ */
+async function validateReviewers(needsReview: boolean | null | undefined, ids: string[] | null | undefined, creator: string, members: ReadRepo<typeof ApprovalMember>) {
+  const selected = ids ?? [];
+  if (!needsReview) return selected.length ? fail('REVIEWERS_NOT_REQUIRED', '未启用专业复核时请清空复核人员') : undefined;
+  if (selected.length < 1 || selected.length > 5) return fail('REVIEWERS_REQUIRED', '专业复核需选择 1–5 位协作人');
+  if (new Set(selected).size !== selected.length) return fail('DUPLICATE_REVIEWERS', '同一人不能重复承担专业会签');
+  if (selected.includes(creator)) return fail('REVIEWER_IS_APPLICANT', '提单人不能担任本单专业复核人');
+  for (const userId of selected) {
+    if (!await members.findOne({ userId, status: 'active' })) return fail('REVIEWER_UNAVAILABLE', '所选专业复核人不在有效协作名录中');
+  }
+}
+
+/**
+ * 保存草稿；金额格式、字段长度和不变量由内核随后统一校验，handler 无额外副作用。
+ * deptId 可指定但仍须满足创建范围；attachments 为已完成上传 ID，省略时初始化为空集合。
+ * 此处不提交审批、不调用 ERP，便于用户先完成材料整理。
+ */
 export const create = command(PurchaseOrder, {
   from: 'new',
   to: 'draft',
@@ -58,18 +114,76 @@ export const create = command(PurchaseOrder, {
     amount: z.string(),
     items: itemsInput,
     supplierPhone: z.string().optional(),
+    reason: z.string().max(2000).optional(),
+    needsSpecialistReview: z.boolean().optional(),
+    reviewerIds: z.array(z.string().uuid()).max(5).optional(),
     deptId: z.string().uuid().optional(),
+    attachments: z.array(z.string().uuid()).max(10).optional(),
   }),
-  handler: (o) => o,
+  // 草稿允许先保存未选完的复核需求；提交才要求完整名单，新记录统一 false/[]，旧记录兼容 null。
+  handler: (o) => ({ ...o, needsSpecialistReview: o.needsSpecialistReview ?? false, reviewerIds: o.reviewerIds ?? [] }),
+});
+
+/**
+ * 在 draft 中调整本单专业复核需求和名单；需要 PurchaseOrder.setReviewers，不能直接修改待审批快照。
+ * 输入保存前核对 1–5 位不同且非提单人的 active 名录成员；关闭时用 false/[]，失败整次回滚。
+ * 提交还会重新查询名录，以拒绝保存后退役的成员；名录不授予对单据的读取、批准能力或额度。
+ */
+export const setReviewers = command(PurchaseOrder, {
+  name: 'setReviewers', description: '设置采购单专业复核需求和人员', from: 'draft', to: null,
+  input: z.object({ id: z.string().uuid(), needsSpecialistReview: z.boolean(), reviewerIds: z.array(z.string().uuid()).max(5) }),
+  reads: { members: ApprovalMember },
+  handler: async (draft, input, { members }) => {
+    const invalid = await validateReviewers(input.needsSpecialistReview, input.reviewerIds, draft.createdBy, members);
+    return invalid ?? { needsSpecialistReview: input.needsSpecialistReview, reviewerIds: input.reviewerIds };
+  },
+});
+
+// 退回后的说明只在草稿状态修改，保留提交时的版本校验和原始审计。
+/** 只更新用途并保留 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，实例由 worker 消费后创建；HTTP 成功不表示审批完成。
+ */
 export const submit = command(PurchaseOrder, {
   from: 'draft',
   to: 'pending_approval',
   emits: [OrderSubmitted],
-  handler: (o) => (o.items.length === 0 ? fail('NO_ITEMS') : o),
+  reads: { members: ApprovalMember },
+  handler: async (o, _input, { members }) => {
+    if (o.items.length === 0) return fail('NO_ITEMS');
+    return await validateReviewers(o.needsSpecialistReview, o.reviewerIds, o.createdBy, members) ?? o;
+  },
 });
 
+/**
+ * 审批终结命令必须同时满足创建人与审批人分离、当前角色额度，以及声明的库存只读检查。
+ * stock 是 reads 绑定的受范围约束仓储；找不到 SKU 或登记数量不足时返回 STOCK_SHORT 并回滚。
+ * 该检查不扣减 available；真正占用由 OrderApproved 的同事务反应创建 InventoryLock。
+ * 范例展示资源配对，不实现多订单累计扣减、仓库出入库或价格核算。
+ */
 export const approve = command(PurchaseOrder, {
   from: 'pending_approval',
   to: 'approved',
@@ -87,6 +201,7 @@ export const approve = command(PurchaseOrder, {
   },
 });
 
+/** 人工审批拒绝后进入终态；此时尚未批准建锁，因此不需要发出库存释放事件。 */
 export const reject = command(PurchaseOrder, {
   from: 'pending_approval',
   to: 'rejected',
@@ -94,6 +209,10 @@ export const reject = command(PurchaseOrder, {
   handler: (o) => o,
 });
 
+/**
+ * 草稿、待审批和已批准单据均可取消；显式事件映射使用提交前快照保留 previousStatus。
+ * 待审批取消会关闭对应审批，已批准取消会异步释放锁；两者都由订阅声明处理。
+ */
 export const cancel = command(PurchaseOrder, {
   from: ['draft', 'pending_approval', 'approved'],
   to: 'cancelled',
@@ -102,6 +221,7 @@ export const cancel = command(PurchaseOrder, {
 });
 
 // 仅连接器能回写 ERP 单号和收货结论，浏览器无法直接调用这两个命令。
+/** 接受可能迟到的 ERP 回执，只补单号并递增版本；to:null 明确保留 approved/received/cancelled 原状态。 */
 export const recordErpNo = command(PurchaseOrder, {
   // ERP 推送可能早于取消发出、晚于取消返回；收货回调也可能先于推送应答到达。
   // 这里只记录外部回执，保留当前生命周期，保证 outbox 后续的解锁事件能够继续投递。
@@ -112,6 +232,7 @@ export const recordErpNo = command(PurchaseOrder, {
   handler: (_o, input) => ({ erpNo: input.erpNo }),
 });
 
+/** 只允许已批准单据确认收货；验签后的 external 调用触发事件，库存释放需等待 worker 消费。 */
 export const markReceived = command(PurchaseOrder, {
   from: 'approved',
   to: 'received',

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

@@ -4,6 +4,10 @@ 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',
@@ -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/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

@@ -11,9 +11,9 @@
     "build:app": "pnpm --filter @app/domain build && pnpm --filter @app/api build && pnpm --filter @app/web build"
   },
   "devDependencies": {
-    "@yss123/cage-cli": "0.2.0",
-    "@yss123/cage-testkit": "0.2.0",
-    "@yss123/cage-lint": "0.2.0",
+    "@yss123/cage-cli": "0.3.1",
+    "@yss123/cage-testkit": "0.3.1",
+    "@yss123/cage-lint": "0.3.1",
     "@types/node": "^24.3.0",
     "typescript": "~5.9.3",
     "vitest": "^4.1.12",

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

@@ -10,7 +10,7 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@yss123/cage-client": "0.2.0",
+    "@yss123/cage-client": "0.3.1",
     "zod": "^4.1.5"
   }
 }

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

@@ -2,7 +2,7 @@
 /* eslint-disable */
 
 import { z } from 'zod';
-import { client, useCageList, useCageQuery, type TransferTask } from '@yss123/cage-client';
+import { client, useCageList, useCageQuery, type TransferTask, type RequestOptions } from '@yss123/cage-client';
 
 /** 部门：读侧快照（敏感字段是按权限掩码后的值） */
 export const DeptSchema = z.object({
@@ -23,9 +23,9 @@ export const DeptStates = ['active', 'archived'] as const;
 
 /** 命令输入：和后端命令的输入校验完全一致 */
 export const DeptInputs = {
-  archive: z.object({ id: z.string().uuid() }),
-  create: z.object({ name: z.string().min(1).max(100), code: z.string().max(64).optional(), parentId: z.string().uuid().nullable().optional(), leaderId: z.string().uuid().nullable().optional() }),
-  update: z.object({ id: z.string().uuid(), name: z.string().min(1).max(100).optional(), code: z.string().max(64).nullable().optional(), leaderId: z.string().uuid().nullable().optional() }),
+  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 可能返回的错误码 */
@@ -55,15 +55,15 @@ export interface DeptListParams {
 /** 调用方法：每个命令一个；client 自动生成并附带幂等键和 CSRF 令牌 */
 export const dept = {
   /** 停用部门（没有在职用户和下级部门时） */
-  archive: (id: string, expectedVersion?: number) => client.post<Dept, DeptArchiveError>(`/api/dept/${encodeURIComponent(id)}/archive`, { expectedVersion }),
+  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>) => client.post<Dept, DeptCreateError>('/api/dept/create', input),
+  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) => client.post<Dept, DeptUpdateError>(`/api/dept/${encodeURIComponent(id)}/update`, { ...input, expectedVersion }),
+  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: { 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>),
+  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 */

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

@@ -2,7 +2,7 @@
 /* eslint-disable */
 
 import { z } from 'zod';
-import { client, useCageList, useCageQuery, type TransferTask } from '@yss123/cage-client';
+import { client, useCageList, useCageQuery, type TransferTask, type RequestOptions } from '@yss123/cage-client';
 
 /** 角色：读侧快照（敏感字段是按权限掩码后的值） */
 export const RoleSchema = z.object({
@@ -22,12 +22,12 @@ export const RoleStates = ['active', 'archived'] as const;
 
 /** 命令输入：和后端命令的输入校验完全一致 */
 export const RoleInputs = {
-  archive: z.object({ id: z.string().uuid() }),
+  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(), capability: z.string().min(1).max(200), params: z.record(z.string(), z.unknown()).optional() }),
-  rename: z.object({ id: z.string().uuid(), name: z.string().min(1).max(100) }),
-  revokeCapability: z.object({ id: z.string().uuid(), capability: z.string().min(1).max(200) }),
-  setScope: z.object({ id: z.string().uuid(), aggregate: z.string().min(1).max(100), combinator: z.enum(["all", "self", "dept", "deptSubtree", "deptSet"]).nullable(), deptIds: z.array(z.string().uuid()).optional() }),
+  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 可能返回的错误码 */
@@ -60,21 +60,21 @@ export interface RoleListParams {
 /** 调用方法：每个命令一个；client 自动生成并附带幂等键和 CSRF 令牌 */
 export const role = {
   /** 停用角色 */
-  archive: (id: string, expectedVersion?: number) => client.post<Role, RoleArchiveError>(`/api/role/${encodeURIComponent(id)}/archive`, { expectedVersion }),
+  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>) => client.post<Role, RoleCreateError>('/api/role/create', input),
+  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) => client.post<Role, RoleGrantCapabilityError>(`/api/role/${encodeURIComponent(id)}/grant-capability`, { ...input, expectedVersion }),
+  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) => client.post<Role, RoleRenameError>(`/api/role/${encodeURIComponent(id)}/rename`, { ...input, expectedVersion }),
+  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) => client.post<Role, RoleRevokeCapabilityError>(`/api/role/${encodeURIComponent(id)}/revoke-capability`, { ...input, expectedVersion }),
+  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) => client.post<Role, RoleSetScopeError>(`/api/role/${encodeURIComponent(id)}/set-scope`, { ...input, expectedVersion }),
+  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: { 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>),
+  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 */

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

@@ -2,7 +2,7 @@
 /* eslint-disable */
 
 import { z } from 'zod';
-import { client, useCageList, useCageQuery, type TransferTask } from '@yss123/cage-client';
+import { client, useCageList, useCageQuery, type TransferTask, type RequestOptions } from '@yss123/cage-client';
 
 /** 用户：读侧快照（敏感字段是按权限掩码后的值） */
 export const UserSchema = z.object({
@@ -25,12 +25,12 @@ export const UserStates = ['active', 'disabled'] as const;
 
 /** 命令输入：和后端命令的输入校验完全一致 */
 export const UserInputs = {
-  assignRoles: z.object({ id: z.string().uuid(), roleIds: z.array(z.string().uuid()).max(50) }),
-  create: z.object({ username: z.string().min(2).max(64).regex(new RegExp("^[A-Za-z0-9_.@-]+$")), name: z.string().min(1).max(100), deptId: z.string().uuid(), phone: z.string().max(32).nullable().optional(), email: z.string().email().max(200).nullable().optional(), ssoSubject: z.string().max(200).nullable().optional() }),
-  disable: z.object({ id: z.string().uuid() }),
-  enable: z.object({ id: z.string().uuid() }),
-  setPassword: z.object({ id: z.string().uuid(), password: z.string().min(8).max(200) }),
-  update: z.object({ id: z.string().uuid(), name: z.string().min(1).max(100).optional(), deptId: z.string().uuid().optional(), phone: z.string().max(32).nullable().optional(), email: z.string().email().max(200).nullable().optional() }),
+  assignRoles: 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)$")), roleIds: 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)$"))).max(50) }),
+  create: z.object({ username: z.string().min(2).max(64).regex(new RegExp("^[A-Za-z0-9_.@-]+$")), name: z.string().min(1).max(100), deptId: 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)$")), phone: z.string().max(32).nullable().optional(), email: z.string().email().max(200).nullable().optional(), ssoSubject: z.string().max(200).nullable().optional() }),
+  disable: 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)$")) }),
+  enable: 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)$")) }),
+  setPassword: 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)$")), password: z.string().min(8).max(200) }),
+  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(), deptId: 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(), phone: z.string().max(32).nullable().optional(), email: z.string().email().max(200).nullable().optional() }),
 };
 
 /** User.assignRoles 可能返回的错误码 */
@@ -64,21 +64,21 @@ export interface UserListParams {
 /** 调用方法：每个命令一个；client 自动生成并附带幂等键和 CSRF 令牌 */
 export const user = {
   /** 设置用户的角色（不能分配包含自己没有的能力的角色） */
-  assignRoles: (id: string, input: Omit<z.input<typeof UserInputs.assignRoles>, 'id'>, expectedVersion?: number) => client.post<User, UserAssignRolesError>(`/api/user/${encodeURIComponent(id)}/assign-roles`, { ...input, expectedVersion }),
+  assignRoles: (id: string, input: Omit<z.input<typeof UserInputs.assignRoles>, 'id'>, expectedVersion?: number, options: RequestOptions = {}) => client.post<User, UserAssignRolesError>(`/api/user/${encodeURIComponent(id)}/assign-roles`, { ...input, expectedVersion }, options),
   /** 新建用户（默认没有任何角色） */
-  create: (input: z.input<typeof UserInputs.create>) => client.post<User, UserCreateError>('/api/user/create', input),
+  create: (input: z.input<typeof UserInputs.create>, options: RequestOptions = {}) => client.post<User, UserCreateError>('/api/user/create', input, options),
   /** 停用用户 */
-  disable: (id: string, expectedVersion?: number) => client.post<User, UserDisableError>(`/api/user/${encodeURIComponent(id)}/disable`, { expectedVersion }),
+  disable: (id: string, expectedVersion?: number, options: RequestOptions = {}) => client.post<User, UserDisableError>(`/api/user/${encodeURIComponent(id)}/disable`, { expectedVersion }, options),
   /** 启用用户 */
-  enable: (id: string, expectedVersion?: number) => client.post<User, UserEnableError>(`/api/user/${encodeURIComponent(id)}/enable`, { expectedVersion }),
+  enable: (id: string, expectedVersion?: number, options: RequestOptions = {}) => client.post<User, UserEnableError>(`/api/user/${encodeURIComponent(id)}/enable`, { expectedVersion }, options),
   /** 重置密码 */
-  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 }),
+  setPassword: (id: string, input: Omit<z.input<typeof UserInputs.setPassword>, 'id'>, expectedVersion?: number, options: RequestOptions = {}) => client.post<User, UserSetPasswordError>(`/api/user/${encodeURIComponent(id)}/set-password`, { ...input, expectedVersion }, options),
   /** 修改用户信息 */
-  update: (id: string, input: Omit<z.input<typeof UserInputs.update>, 'id'>, expectedVersion?: number) => client.post<User, UserUpdateError>(`/api/user/${encodeURIComponent(id)}/update`, { ...input, expectedVersion }),
+  update: (id: string, input: Omit<z.input<typeof UserInputs.update>, 'id'>, expectedVersion?: number, options: RequestOptions = {}) => client.post<User, UserUpdateError>(`/api/user/${encodeURIComponent(id)}/update`, { ...input, expectedVersion }, options),
   /** 异步导出 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>),
+  export: (params: UserListParams = {}, options: RequestOptions = {}) => client.post<TransferTask, 'CONFLICT'>('/api/user/export', params, options),
+  get: (id: string, options: RequestOptions = {}) => client.get<User>(`/api/user/${encodeURIComponent(id)}`, undefined, options),
+  list: (params: UserListParams = {}, options: RequestOptions = {}) => client.get<{ items: User[]; total: number; page: number; pageSize: number }>('/api/user', params as Record<string, unknown>, options),
 };
 
 /** 详情查询 hook：响应也用 schema 校验；范围外返回 NOT_FOUND */

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

@@ -9,7 +9,7 @@ import { can as baseCan, useCan as baseUseCan } from '@yss123/cage-client';
 import { DeptInputs } from './aggregates/dept';
 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 { client, configureClient, loadMe, currentUser, CageQueryError, CageCommandError, useTransfer, useFileUpload, FileUploadError, type FileUploadTask, type FileUploadSnapshot, type UploadSession, type FileInfo, type RequestOptions, type CageResult, type CommonError, type TransferTask, type ImportReport } from '@yss123/cage-client';
 
 /** 能力目录（由代码派生）：写错能力点名会编译失败 */
 export const capabilities = [

package/templates/blank/packages/contracts/src/queries/index.ts

@@ -2,7 +2,7 @@
 /* eslint-disable */
 
 import { z } from 'zod';
-import { client, useCageQuery } from '@yss123/cage-client';
+import { client, useCageQuery, type RequestOptions } from '@yss123/cage-client';
 
 /** 查询输入 */
 export const QueryInputs = {

package/templates/blank/packages/domain/package.json

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

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

@@ -1,4 +1,5 @@
 // CLI、API 与 worker 共用这个领域入口。空白项目只注册组织基础模型，
-// 不注册采购示例；新增业务写在同目录的 .ts 文件，再从这里统一导出。
+// 不注册采购示例；新增业务写在 modules/<业务>，跨模块流程和外部集成分别放 workflows、integrations，再统一导出。
 // 完整采购代码保存在 docs/examples/purchase-admin，仅作离线参考。
+// 未导出的声明不参与注册、生成或事件消费；本入口只组合声明，不做数据库初始化与网络访问。
 export * from '@yss123/cage-admin/domain';