@yss123/cage-cli 0.0.0-stage → 0.2.0

package/templates/blank/docs/examples/purchase-admin/cage.config.json

@@ -0,0 +1,114 @@
+{
+  "domain": "packages/domain/src/index.ts",
+  "contracts": "packages/contracts/src",
+  "structure": "modular",
+  "typecheck": ["packages/domain", "packages/contracts", "apps/api", "apps/web"],
+  "graph": {
+    "title": "采购业务图谱",
+    "labels": {
+      "aggregate:PurchaseOrder": "采购单",
+      "aggregate:Inventory": "库存台账",
+      "aggregate:InventoryLock": "库存锁",
+      "aggregate:Dept": "部门",
+      "aggregate:User": "用户",
+      "aggregate:Role": "角色",
+      "command:PurchaseOrder.create": "新建采购单",
+      "command:PurchaseOrder.submit": "提交审批",
+      "command:PurchaseOrder.approve": "通过审批",
+      "command:PurchaseOrder.reject": "驳回审批",
+      "command:PurchaseOrder.cancel": "取消采购单",
+      "command:PurchaseOrder.markReceived": "确认收货",
+      "command:PurchaseOrder.recordErpNo": "回写外部单号",
+      "command:Inventory.create": "登记库存",
+      "command:InventoryLock.acquire": "锁定库存",
+      "command:InventoryLock.release": "释放库存锁",
+      "event:OrderSubmitted": "采购单已提交",
+      "event:OrderApproved": "采购单已批准",
+      "event:OrderCancelled": "采购单已取消",
+      "event:OrderReceived": "采购单已收货",
+      "reaction:lockOnApprove": "审批通过后锁库存",
+      "reaction:releaseOnCancel": "取消后释放库存锁",
+      "reaction:releaseOnReceive": "收货后释放库存锁",
+      "approval:poApproval": "采购审批流程",
+      "route:route:po-approval": "采购审批分支",
+      "query:poByStatus": "按状态汇总采购单",
+      "job:expireStaleOrders": "清理过期采购草稿",
+      "connector:connector:erp": "企业资源系统",
+      "outbound:pushToErp": "推送采购单至外部",
+      "inbound:erpReceived": "接收外部收货通知",
+      "state:PurchaseOrder.draft": "草稿",
+      "state:PurchaseOrder.pending_approval": "待审批",
+      "state:PurchaseOrder.approved": "已批准",
+      "state:PurchaseOrder.received": "已收货",
+      "state:PurchaseOrder.rejected": "已驳回",
+      "state:PurchaseOrder.cancelled": "已取消",
+      "state:Inventory.active": "有效库存",
+      "state:Inventory.deleted": "已删除",
+      "state:InventoryLock.held": "锁定中",
+      "state:InventoryLock.released": "已释放",
+      "field:PurchaseOrder.amount": "采购金额",
+      "field:PurchaseOrder.deptId": "所属部门",
+      "field:PurchaseOrder.createdBy": "提单人",
+      "field:PurchaseOrder.supplierPhone": "供应商电话",
+      "field:PurchaseOrder.items": "采购明细",
+      "field:PurchaseOrder.erpNo": "外部系统单号",
+      "field:Inventory.sku": "物料编码",
+      "field:Inventory.available": "台账数量",
+      "field:InventoryLock.orderId": "采购单编号",
+      "field:InventoryLock.items": "锁定明细",
+      "capability:PurchaseOrder.read": "查看采购单",
+      "capability:PurchaseOrder.export": "导出采购单",
+      "capability:Inventory.read": "查看库存台账",
+      "capability:Inventory.export": "导出库存台账",
+      "capability:InventoryLock.read": "查看库存锁",
+      "capability:InventoryLock.export": "导出库存锁",
+      "command:Dept.create": "新建部门",
+      "command:Dept.update": "修改部门信息",
+      "command:Dept.archive": "停用部门",
+      "state:Dept.active": "启用中",
+      "state:Dept.archived": "已停用",
+      "field:Dept.name": "部门名称",
+      "field:Dept.code": "部门编码",
+      "field:Dept.parentId": "上级部门",
+      "field:Dept.ancestors": "部门层级路径",
+      "field:Dept.leaderId": "部门负责人",
+      "capability:Dept.read": "查看部门",
+      "capability:Dept.export": "导出部门",
+      "command:User.create": "新建用户",
+      "command:User.update": "修改用户信息",
+      "command:User.assignRoles": "分配角色",
+      "command:User.disable": "停用用户",
+      "command:User.enable": "启用用户",
+      "command:User.setPassword": "设置密码",
+      "state:User.active": "启用中",
+      "state:User.disabled": "已停用",
+      "field:User.username": "登录账号",
+      "field:User.name": "用户姓名",
+      "field:User.deptId": "所属部门",
+      "field:User.roleIds": "拥有的角色",
+      "field:User.phone": "手机号码",
+      "field:User.email": "电子邮箱",
+      "field:User.ssoSubject": "单点登录标识",
+      "field:User.passwordHash": "密码摘要",
+      "capability:User.read": "查看用户",
+      "capability:User.export": "导出用户",
+      "command:Role.create": "新建角色",
+      "command:Role.rename": "修改角色名称",
+      "command:Role.archive": "停用角色",
+      "command:Role.grantCapability": "授予能力",
+      "command:Role.revokeCapability": "收回能力",
+      "command:Role.setScope": "设置数据范围",
+      "state:Role.active": "启用中",
+      "state:Role.archived": "已停用",
+      "field:Role.code": "角色编码",
+      "field:Role.name": "角色名称",
+      "field:Role.capabilities": "能力点与额度",
+      "field:Role.scopes": "数据访问范围",
+      "capability:Role.read": "查看角色",
+      "capability:Role.export": "导出角色",
+      "resource:inventory.lock": "库存锁",
+      "operation:pushOrder": "推送采购单",
+      "event:goodsReceived": "外部收货通知"
+    }
+  }
+}

package/templates/blank/docs/examples/purchase-admin/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 } 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() }),
+  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() }),
+};
+
+/** 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) => client.post<Dept, DeptArchiveError>(`/api/dept/${encodeURIComponent(id)}/archive`, { expectedVersion }),
+  /** 新建部门 */
+  create: (input: z.input<typeof DeptInputs.create>) => client.post<Dept, DeptCreateError>('/api/dept/create', input),
+  /** 修改部门名称、编码、负责人 */
+  update: (id: string, input: Omit<z.input<typeof DeptInputs.update>, 'id'>, expectedVersion?: number) => client.post<Dept, DeptUpdateError>(`/api/dept/${encodeURIComponent(id)}/update`, { ...input, expectedVersion }),
+  /** 异步导出 CSV：返回任务，使用 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>),
+};
+
+/** 详情查询 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/docs/examples/purchase-admin/packages/contracts/src/aggregates/inventory/index.ts

@@ -0,0 +1,57 @@
+// 生成物：由 cage gen 从 domain 声明生成，不要手改。
+/* eslint-disable */
+
+import { z } from 'zod';
+import { client, useCageList, useCageQuery, type TransferTask } from '@yss123/cage-client';
+
+/** Inventory：读侧快照（敏感字段是按权限掩码后的值） */
+export const InventorySchema = z.object({
+  id: z.string().uuid(),
+  sku: z.string(),
+  available: z.number().int(),
+  status: z.enum(["active", "deleted"]),
+  version: z.number().int(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+export type Inventory = z.infer<typeof InventorySchema>;
+export type InventoryStatus = Inventory['status'];
+export const InventoryStates = ['active', 'deleted'] as const;
+
+/** 命令输入：和后端命令的输入校验完全一致 */
+export const InventoryInputs = {
+  create: z.object({ sku: z.string(), available: z.number().int().min(-9007199254740991).max(9007199254740991) }),
+};
+
+/** Inventory.create 可能返回的错误码 */
+export type InventoryCreateError = 'CONFLICT' | 'CONSTRAINT_VIOLATED' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT';
+
+export type InventorySortKey = 'createdAt' | 'updatedAt' | 'sku' | 'available';
+export interface InventoryListParams {
+  page?: number;
+  pageSize?: number;
+  /** 排序：字段名，前面加 - 表示倒序 */
+  sort?: InventorySortKey | `-${InventorySortKey}`;
+  /** 可以逗号分隔多个状态 */
+  status?: string;
+  createdAfter?: string;
+  createdBefore?: string;
+  sku?: string | number | boolean;
+  available?: string | number | boolean;
+}
+
+/** 调用方法：每个命令一个；client 自动生成并附带幂等键和 CSRF 令牌 */
+export const inventory = {
+  create: (input: z.input<typeof InventoryInputs.create>) => client.post<Inventory, InventoryCreateError>('/api/inventory/create', input),
+  /** 异步导出 CSV：返回任务，使用 client.transfer(id) 查状态，完成后下载。需要 Inventory.export 能力。 */
+  export: (params: InventoryListParams = {}, options: { idempotencyKey?: string } = {}) => client.post<TransferTask, 'CONFLICT'>('/api/inventory/export', params, options),
+  get: (id: string) => client.get<Inventory>(`/api/inventory/${encodeURIComponent(id)}`),
+  list: (params: InventoryListParams = {}) => client.get<{ items: Inventory[]; total: number; page: number; pageSize: number }>('/api/inventory', params as Record<string, unknown>),
+};
+
+/** 详情查询 hook：响应也用 schema 校验；范围外返回 NOT_FOUND */
+export const useInventory = (id: string) => useCageQuery(['inventory', id], `/api/inventory/${encodeURIComponent(id)}`, InventorySchema, { enabled: !!id });
+/** 列表查询 hook：走读侧账号与安全视图 */
+export const useInventoryList = (params: InventoryListParams = {}) => useCageList(['inventory'], '/api/inventory', params as Record<string, unknown>, InventorySchema);
+/** 查询缓存键前缀：命令成功后让它失效 */
+export const inventoryKeys = { all: ['inventory'] as const, one: (id: string) => ['inventory', id] as const };

package/templates/blank/docs/examples/purchase-admin/packages/contracts/src/aggregates/inventory-lock/index.ts

@@ -0,0 +1,52 @@
+// 生成物：由 cage gen 从 domain 声明生成，不要手改。
+/* eslint-disable */
+
+import { z } from 'zod';
+import { client, useCageList, useCageQuery, type TransferTask } from '@yss123/cage-client';
+
+/** InventoryLock：读侧快照（敏感字段是按权限掩码后的值） */
+export const InventoryLockSchema = z.object({
+  id: z.string().uuid(),
+  orderId: z.string().uuid(),
+  items: z.array(z.object({ sku: z.string(), qty: z.number().int() })),
+  status: z.enum(["held", "released"]),
+  version: z.number().int(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+export type InventoryLock = z.infer<typeof InventoryLockSchema>;
+export type InventoryLockStatus = InventoryLock['status'];
+export const InventoryLockStates = ['held', 'released'] as const;
+
+/** 命令输入：和后端命令的输入校验完全一致 */
+export const InventoryLockInputs = {
+};
+
+
+export type InventoryLockSortKey = 'createdAt' | 'updatedAt' | 'orderId';
+export interface InventoryLockListParams {
+  page?: number;
+  pageSize?: number;
+  /** 排序：字段名，前面加 - 表示倒序 */
+  sort?: InventoryLockSortKey | `-${InventoryLockSortKey}`;
+  /** 可以逗号分隔多个状态 */
+  status?: string;
+  createdAfter?: string;
+  createdBefore?: string;
+  orderId?: string | number | boolean;
+}
+
+/** 调用方法：每个命令一个；client 自动生成并附带幂等键和 CSRF 令牌 */
+export const inventoryLock = {
+  /** 异步导出 CSV：返回任务，使用 client.transfer(id) 查状态，完成后下载。需要 InventoryLock.export 能力。 */
+  export: (params: InventoryLockListParams = {}, options: { idempotencyKey?: string } = {}) => client.post<TransferTask, 'CONFLICT'>('/api/inventory-lock/export', params, options),
+  get: (id: string) => client.get<InventoryLock>(`/api/inventory-lock/${encodeURIComponent(id)}`),
+  list: (params: InventoryLockListParams = {}) => client.get<{ items: InventoryLock[]; total: number; page: number; pageSize: number }>('/api/inventory-lock', params as Record<string, unknown>),
+};
+
+/** 详情查询 hook：响应也用 schema 校验；范围外返回 NOT_FOUND */
+export const useInventoryLock = (id: string) => useCageQuery(['inventory-lock', id], `/api/inventory-lock/${encodeURIComponent(id)}`, InventoryLockSchema, { enabled: !!id });
+/** 列表查询 hook：走读侧账号与安全视图 */
+export const useInventoryLockList = (params: InventoryLockListParams = {}) => useCageList(['inventory-lock'], '/api/inventory-lock', params as Record<string, unknown>, InventoryLockSchema);
+/** 查询缓存键前缀：命令成功后让它失效 */
+export const inventoryLockKeys = { all: ['inventory-lock'] as const, one: (id: string) => ['inventory-lock', id] as const };

package/templates/blank/docs/examples/purchase-admin/packages/contracts/src/aggregates/purchase-order/index.ts

@@ -0,0 +1,72 @@
+// 生成物：由 cage gen 从 domain 声明生成，不要手改。
+/* eslint-disable */
+
+import { z } from 'zod';
+import { client, useCageList, useCageQuery, type TransferTask } from '@yss123/cage-client';
+
+/** PurchaseOrder：读侧快照（敏感字段是按权限掩码后的值） */
+export const PurchaseOrderSchema = z.object({
+  id: z.string().uuid(),
+  deptId: z.string().uuid(),
+  createdBy: z.string().uuid(),
+  supplierPhone: z.string().nullable().optional(),
+  amount: z.string(),
+  items: z.array(z.object({ sku: z.string(), qty: z.number().int() })),
+  erpNo: z.string().nullable().optional(),
+  status: z.enum(["draft", "pending_approval", "approved", "received", "rejected", "cancelled"]),
+  version: z.number().int(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+export type PurchaseOrder = z.infer<typeof PurchaseOrderSchema>;
+export type PurchaseOrderStatus = PurchaseOrder['status'];
+export const PurchaseOrderStates = ['draft', 'pending_approval', 'approved', 'received', 'rejected', 'cancelled'] as const;
+
+/** 命令输入：和后端命令的输入校验完全一致 */
+export const PurchaseOrderInputs = {
+  cancel: z.object({ id: z.string().uuid() }),
+  create: z.object({ amount: z.string(), items: z.array(z.object({ sku: z.string(), qty: z.number().int().max(9007199254740991).gt(0) })).min(1), supplierPhone: z.string().optional(), deptId: z.string().uuid().optional() }),
+  submit: z.object({ id: z.string().uuid() }),
+};
+
+/** PurchaseOrder.cancel 可能返回的错误码 */
+export type PurchaseOrderCancelError = 'CONFLICT' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'INVARIANT_VIOLATED' | 'NOT_FOUND';
+/** PurchaseOrder.create 可能返回的错误码 */
+export type PurchaseOrderCreateError = 'CONFLICT' | 'CONSTRAINT_VIOLATED' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVARIANT_VIOLATED';
+/** PurchaseOrder.submit 可能返回的错误码；业务码（domainCode）：NO_ITEMS */
+export type PurchaseOrderSubmitError = 'CONFLICT' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'INVARIANT_VIOLATED' | 'NOT_FOUND';
+export type PurchaseOrderSubmitDomainCode = 'NO_ITEMS';
+
+export type PurchaseOrderSortKey = 'createdAt' | 'updatedAt' | 'deptId' | 'createdBy' | 'supplierPhone' | 'amount' | 'erpNo';
+export interface PurchaseOrderListParams {
+  page?: number;
+  pageSize?: number;
+  /** 排序：字段名，前面加 - 表示倒序 */
+  sort?: PurchaseOrderSortKey | `-${PurchaseOrderSortKey}`;
+  /** 可以逗号分隔多个状态 */
+  status?: string;
+  createdAfter?: string;
+  createdBefore?: string;
+  deptId?: string | number | boolean;
+  createdBy?: string | number | boolean;
+  amount?: string | number | boolean;
+  erpNo?: string | number | boolean;
+}
+
+/** 调用方法：每个命令一个；client 自动生成并附带幂等键和 CSRF 令牌 */
+export const purchaseOrder = {
+  cancel: (id: string, expectedVersion?: number) => client.post<PurchaseOrder, PurchaseOrderCancelError>(`/api/purchase-order/${encodeURIComponent(id)}/cancel`, { expectedVersion }),
+  create: (input: z.input<typeof PurchaseOrderInputs.create>) => client.post<PurchaseOrder, PurchaseOrderCreateError>('/api/purchase-order/create', input),
+  submit: (id: string, expectedVersion?: number) => client.post<PurchaseOrder, PurchaseOrderSubmitError>(`/api/purchase-order/${encodeURIComponent(id)}/submit`, { expectedVersion }),
+  /** 异步导出 CSV：返回任务，使用 client.transfer(id) 查状态，完成后下载。需要 PurchaseOrder.export 能力。 */
+  export: (params: PurchaseOrderListParams = {}, options: { idempotencyKey?: string } = {}) => client.post<TransferTask, 'CONFLICT'>('/api/purchase-order/export', params, options),
+  get: (id: string) => client.get<PurchaseOrder>(`/api/purchase-order/${encodeURIComponent(id)}`),
+  list: (params: PurchaseOrderListParams = {}) => client.get<{ items: PurchaseOrder[]; total: number; page: number; pageSize: number }>('/api/purchase-order', params as Record<string, unknown>),
+};
+
+/** 详情查询 hook：响应也用 schema 校验；范围外返回 NOT_FOUND */
+export const usePurchaseOrder = (id: string) => useCageQuery(['purchase-order', id], `/api/purchase-order/${encodeURIComponent(id)}`, PurchaseOrderSchema, { enabled: !!id });
+/** 列表查询 hook：走读侧账号与安全视图 */
+export const usePurchaseOrderList = (params: PurchaseOrderListParams = {}) => useCageList(['purchase-order'], '/api/purchase-order', params as Record<string, unknown>, PurchaseOrderSchema);
+/** 查询缓存键前缀：命令成功后让它失效 */
+export const purchaseOrderKeys = { all: ['purchase-order'] as const, one: (id: string) => ['purchase-order', id] as const };

package/templates/blank/docs/examples/purchase-admin/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 } 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() }),
+  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() }),
+};
+
+/** 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) => client.post<Role, RoleArchiveError>(`/api/role/${encodeURIComponent(id)}/archive`, { expectedVersion }),
+  /** 新建角色（默认没有任何能力） */
+  create: (input: z.input<typeof RoleInputs.create>) => client.post<Role, RoleCreateError>('/api/role/create', input),
+  /** 给角色授予能力点（不能授出自己没有的能力点） */
+  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 }),
+  /** 修改角色名称 */
+  rename: (id: string, input: Omit<z.input<typeof RoleInputs.rename>, 'id'>, expectedVersion?: number) => client.post<Role, RoleRenameError>(`/api/role/${encodeURIComponent(id)}/rename`, { ...input, expectedVersion }),
+  /** 收回角色的能力点 */
+  revokeCapability: (id: string, input: Omit<z.input<typeof RoleInputs.revokeCapability>, 'id'>, expectedVersion?: number) => client.post<Role, RoleRevokeCapabilityError>(`/api/role/${encodeURIComponent(id)}/revoke-capability`, { ...input, expectedVersion }),
+  /** 设置角色在某个聚合上的数据范围（不能授出比自己更宽的范围） */
+  setScope: (id: string, input: Omit<z.input<typeof RoleInputs.setScope>, 'id'>, expectedVersion?: number) => client.post<Role, RoleSetScopeError>(`/api/role/${encodeURIComponent(id)}/set-scope`, { ...input, expectedVersion }),
+  /** 异步导出 CSV：返回任务，使用 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>),
+};
+
+/** 详情查询 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 };

package/templates/blank/docs/examples/purchase-admin/packages/contracts/src/aggregates/user/index.ts

@@ -0,0 +1,89 @@
+// 生成物：由 cage gen 从 domain 声明生成，不要手改。
+/* eslint-disable */
+
+import { z } from 'zod';
+import { client, useCageList, useCageQuery, type TransferTask } from '@yss123/cage-client';
+
+/** 用户：读侧快照（敏感字段是按权限掩码后的值） */
+export const UserSchema = z.object({
+  id: z.string().uuid(),
+  username: z.string(),
+  name: z.string(),
+  deptId: z.string().uuid(),
+  roleIds: z.array(z.string().uuid()),
+  phone: z.string().nullable().optional(),
+  email: z.string().nullable().optional(),
+  ssoSubject: z.string().nullable().optional(),
+  status: z.enum(["active", "disabled"]),
+  version: z.number().int(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+export type User = z.infer<typeof UserSchema>;
+export type UserStatus = User['status'];
+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() }),
+};
+
+/** User.assignRoles 可能返回的错误码 */
+export type UserAssignRolesError = 'CONFLICT' | 'CONSTRAINT_VIOLATED' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
+/** User.create 可能返回的错误码 */
+export type UserCreateError = 'CONFLICT' | 'CONSTRAINT_VIOLATED' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT';
+/** User.disable 可能返回的错误码 */
+export type UserDisableError = 'CONFLICT' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
+/** User.enable 可能返回的错误码 */
+export type UserEnableError = 'CONFLICT' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
+/** User.setPassword 可能返回的错误码 */
+export type UserSetPasswordError = 'CONFLICT' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
+/** User.update 可能返回的错误码 */
+export type UserUpdateError = 'CONFLICT' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
+
+export type UserSortKey = 'createdAt' | 'updatedAt' | 'username' | 'name' | 'deptId' | 'phone' | 'email' | 'ssoSubject';
+export interface UserListParams {
+  page?: number;
+  pageSize?: number;
+  /** 排序：字段名，前面加 - 表示倒序 */
+  sort?: UserSortKey | `-${UserSortKey}`;
+  /** 可以逗号分隔多个状态 */
+  status?: string;
+  createdAfter?: string;
+  createdBefore?: string;
+  username?: string | number | boolean;
+  deptId?: string | number | boolean;
+  ssoSubject?: string | number | boolean;
+}
+
+/** 调用方法：每个命令一个；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 }),
+  /** 新建用户（默认没有任何角色） */
+  create: (input: z.input<typeof UserInputs.create>) => client.post<User, UserCreateError>('/api/user/create', input),
+  /** 停用用户 */
+  disable: (id: string, expectedVersion?: number) => client.post<User, UserDisableError>(`/api/user/${encodeURIComponent(id)}/disable`, { expectedVersion }),
+  /** 启用用户 */
+  enable: (id: string, expectedVersion?: number) => client.post<User, UserEnableError>(`/api/user/${encodeURIComponent(id)}/enable`, { expectedVersion }),
+  /** 重置密码 */
+  setPassword: (id: string, input: Omit<z.input<typeof UserInputs.setPassword>, 'id'>, expectedVersion?: number) => client.post<User, UserSetPasswordError>(`/api/user/${encodeURIComponent(id)}/set-password`, { ...input, expectedVersion }),
+  /** 修改用户信息 */
+  update: (id: string, input: Omit<z.input<typeof UserInputs.update>, 'id'>, expectedVersion?: number) => client.post<User, UserUpdateError>(`/api/user/${encodeURIComponent(id)}/update`, { ...input, expectedVersion }),
+  /** 异步导出 CSV：返回任务，使用 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>),
+};
+
+/** 详情查询 hook：响应也用 schema 校验；范围外返回 NOT_FOUND */
+export const useUser = (id: string) => useCageQuery(['user', id], `/api/user/${encodeURIComponent(id)}`, UserSchema, { enabled: !!id });
+/** 列表查询 hook：走读侧账号与安全视图 */
+export const useUserList = (params: UserListParams = {}) => useCageList(['user'], '/api/user', params as Record<string, unknown>, UserSchema);
+/** 查询缓存键前缀：命令成功后让它失效 */
+export const userKeys = { all: ['user'] as const, one: (id: string) => ['user', id] as const };

package/templates/blank/docs/examples/purchase-admin/packages/contracts/src/index.ts

@@ -0,0 +1,81 @@
+// 生成物：由 cage gen 从 domain 声明生成，不要手改。
+/* eslint-disable */
+
+export * from './aggregates/dept';
+export * from './aggregates/inventory';
+export * from './aggregates/inventory-lock';
+export * from './aggregates/purchase-order';
+export * from './aggregates/role';
+export * from './aggregates/user';
+export * from './queries';
+import { can as baseCan, useCan as baseUseCan } from '@yss123/cage-client';
+import { DeptInputs } from './aggregates/dept';
+import { InventoryInputs } from './aggregates/inventory';
+import { InventoryLockInputs } from './aggregates/inventory-lock';
+import { PurchaseOrderInputs } from './aggregates/purchase-order';
+import { RoleInputs } from './aggregates/role';
+import { UserInputs } from './aggregates/user';
+export { client, configureClient, loadMe, currentUser, CageQueryError, useTransfer, type CageResult, type CommonError, type TransferTask, type ImportReport } from '@yss123/cage-client';
+
+/** 能力目录（由代码派生）：写错能力点名会编译失败 */
+export const capabilities = [
+  'Dept.archive',
+  'Dept.create',
+  'Dept.export',
+  'Dept.read',
+  'Dept.update',
+  'Inventory.create',
+  'Inventory.export',
+  'Inventory.read',
+  'InventoryLock.acquire',
+  'InventoryLock.export',
+  'InventoryLock.read',
+  'InventoryLock.release',
+  'PurchaseOrder.approve',
+  'PurchaseOrder.cancel',
+  'PurchaseOrder.create',
+  'PurchaseOrder.export',
+  'PurchaseOrder.markReceived',
+  'PurchaseOrder.read',
+  'PurchaseOrder.recordErpNo',
+  'PurchaseOrder.reject',
+  'PurchaseOrder.submit',
+  'PurchaseOrder.unmask.phone',
+  'Role.archive',
+  'Role.create',
+  'Role.export',
+  'Role.grantCapability',
+  'Role.read',
+  'Role.rename',
+  'Role.revokeCapability',
+  'Role.setScope',
+  'Sys.audit.read',
+  'Sys.ops.manage',
+  'Sys.ops.read',
+  'User.assignRoles',
+  'User.create',
+  'User.disable',
+  'User.enable',
+  'User.export',
+  'User.read',
+  'User.setPassword',
+  'User.unmask.email',
+  'User.unmask.name',
+  'User.unmask.phone',
+  'User.update',
+] as const;
+export type Capability = (typeof capabilities)[number];
+
+/** 当前用户有没有某个能力点。只影响界面显示：绕过前端直接调接口，内核一样会拒绝 */
+export const can = (capability: Capability): boolean => baseCan(capability);
+export const useCan = (capability: Capability): boolean => baseUseCan(capability);
+
+/** 各聚合的命令输入 schema：按聚合名、命令名访问，可直接供表单库校验 */
+export const schemas = {
+  Dept: DeptInputs,
+  Inventory: InventoryInputs,
+  InventoryLock: InventoryLockInputs,
+  PurchaseOrder: PurchaseOrderInputs,
+  Role: RoleInputs,
+  User: UserInputs,
+};