@yss123/cage-cli 0.0.0-stage → 0.1.0

package/templates/app/packages/contracts/src/purchase-order.ts

@@ -0,0 +1,72 @@
+// 生成物：由 cage gen 从 domain 声明生成，不要手改。
+/* eslint-disable */
+
+import { z } from 'zod';
+import { client, useCageList, useCageQuery } 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：需要 PurchaseOrder.export 能力 */
+  export: (params: PurchaseOrderListParams = {}) => client.post<string, never>('/api/purchase-order/export', params),
+  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/app/packages/contracts/src/queries.ts

@@ -0,0 +1,17 @@
+// 生成物：由 cage gen 从 domain 声明生成，不要手改。
+/* eslint-disable */
+
+import { z } from 'zod';
+import { client, useCageQuery } from '@yss123/cage-client';
+
+/** 查询输入 */
+export const QueryInputs = {
+  poByStatus: z.object({ status: z.string() }),
+};
+
+export const queries = {
+  /** poByStatus（需要 PurchaseOrder.read） */
+  poByStatus: (input: z.input<typeof QueryInputs.poByStatus> = {} as any) => client.get<Record<string, unknown>[]>('/api/queries/po-by-status', input as Record<string, unknown>),
+};
+
+export const usePoByStatus = (input: z.input<typeof QueryInputs.poByStatus> = {} as any) => useCageQuery<Record<string, unknown>[]>(['query', 'poByStatus'], '/api/queries/po-by-status', undefined, { query: input as Record<string, unknown> });

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

@@ -0,0 +1,85 @@
+// 生成物：由 cage gen 从 domain 声明生成，不要手改。
+/* eslint-disable */
+
+import { z } from 'zod';
+import { client, useCageList, useCageQuery } 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：需要 Role.export 能力 */
+  export: (params: RoleListParams = {}) => client.post<string, never>('/api/role/export', params),
+  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/app/packages/contracts/src/user.ts

@@ -0,0 +1,89 @@
+// 生成物：由 cage gen 从 domain 声明生成，不要手改。
+/* eslint-disable */
+
+import { z } from 'zod';
+import { client, useCageList, useCageQuery } 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：需要 User.export 能力 */
+  export: (params: UserListParams = {}) => client.post<string, never>('/api/user/export', params),
+  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/app/packages/contracts/tsconfig.json

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

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

@@ -0,0 +1,23 @@
+{
+  "name": "@app/domain",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "development": "./src/index.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@yss123/cage-kernel": "0.1.0",
+    "@yss123/cage-admin": "0.1.0",
+    "@yss123/cage-approval": "0.1.0",
+    "@yss123/cage-connectors": "0.1.0",
+    "zod": "^4.1.5"
+  }
+}

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

@@ -0,0 +1,18 @@
+// 路由只决定由谁审批；最终结论仍调用领域命令，执行职责分离和额度约束。
+import { approval } from '@yss123/cage-kernel';
+import { approver, gt, route, step, when } from '@yss123/cage-approval';
+import { PurchaseOrder, OrderSubmitted, OrderCancelled, approve, reject } from './purchase-order.js';
+
+export const poApproval = approval(PurchaseOrder, {
+  process: 'po-approval',
+  start: OrderSubmitted,
+  cancelOn: [OrderCancelled],
+  routable: ['amount', 'deptId'],
+  onApproved: approve,
+  onRejected: reject,
+});
+
+export const poRoute = route('po-approval', [
+  step('部门经理审批', approver.deptLeader('deptId')),
+  when(gt('amount', 50000), step('财务审批', approver.role('finance'), { mode: 'any' })),
+]);

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

@@ -0,0 +1,36 @@
+// ERP 的两个边界：出站只发送声明允许的字段，入站回调必须通过 HMAC 验签。
+// 本地由 worker 注册 fake；这里始终只写声明，不发送请求或读取环境变量。
+import { z } from 'zod';
+import { connector, hmacSha256, inbound, op, outbound } from '@yss123/cage-connectors';
+import { OrderApproved, recordErpNo, markReceived } from './purchase-order.js';
+
+export const erp = connector('erp', {
+  hosts: { test: 'erp-sandbox.example.com', prod: 'erp.example.com' },
+  secret: 'ERP_API_TOKEN',
+  timeoutMs: 5000,
+  operations: {
+    pushOrder: op({
+      effect: 'retryableWrite',
+      method: 'POST',
+      path: '/api/purchase-orders',
+      request: z.object({
+        externalId: z.string(),
+        lines: z.array(z.object({ sku: z.string(), qty: z.number() })),
+      }),
+      response: z.object({ erpNo: z.string() }),
+    }),
+  },
+});
+
+export const pushToErp = outbound(OrderApproved, erp.operations.pushOrder, {
+  idempotencyKey: (e) => `po-${e.orderId}`,
+  map: (e) => ({ externalId: e.orderId, lines: e.items.map((i) => ({ sku: i.sku, qty: i.qty })) }),
+  onSuccess: { command: recordErpNo, map: (res, e) => ({ id: e.orderId, erpNo: res.erpNo }) },
+});
+
+export const erpReceived = inbound(erp, 'goodsReceived', {
+  verify: hmacSha256('ERP_WEBHOOK_SECRET'),
+  payload: z.object({ externalId: z.string().uuid() }),
+  command: markReceived,
+  map: (p) => ({ id: p.externalId }),
+});

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

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

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

@@ -0,0 +1,43 @@
+// 最简聚合示例：Inventory 维护物料台账，InventoryLock 记录订单的资源占用。
+// 此范例验证锁的生命周期；available 是登记数量，不包含仓库出入库核算。
+import { aggregate, command, id, int, list, scope, states, text } from '@yss123/cage-kernel';
+import { z } from 'zod';
+
+export const Inventory = aggregate('Inventory', {
+  fields: { sku: text(64).unique(), available: int() },
+  scope: scope.none(),
+});
+
+export const createInventory = command(Inventory, {
+  name: 'create',
+  from: 'new',
+  to: 'active',
+  input: z.object({ sku: z.string(), available: z.number().int() }),
+  handler: (o) => o,
+});
+
+export const InventoryLock = aggregate('InventoryLock', {
+  fields: { orderId: id(), items: list({ sku: text(64), qty: int() }) },
+  states: states('held', 'released', { terminal: ['released'] }),
+  scope: scope.none(),
+});
+
+// 锁以订单 id 为主键，同一事务反应确保审批和建锁一起成功或回滚。
+const itemsInput = z.array(z.object({ sku: z.string(), qty: z.number().int().positive() })).min(1);
+
+export const acquireLock = command(InventoryLock, {
+  name: 'acquire',
+  from: 'new',
+  to: 'held',
+  invokedBy: 'process',
+  input: z.object({ id: z.string().uuid(), orderId: z.string().uuid(), items: itemsInput }),
+  handler: (o) => o,
+});
+
+export const releaseLock = command(InventoryLock, {
+  name: 'release',
+  from: 'held',
+  to: 'released',
+  invokedBy: 'process',
+  handler: (o) => o,
+});

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

@@ -0,0 +1,13 @@
+// 定时任务只调用显式列出的命令；取消操作和用户操作共用内核及审计。
+import { daysAgo, job } from '@yss123/cage-kernel';
+import { PurchaseOrder, cancel } from './purchase-order.js';
+
+export const expireStaleOrders = job('expireStaleOrders', {
+  cron: '0 2 * * *',
+  reads: [PurchaseOrder],
+  calls: [cancel],
+  run: async ({ query, call }) => {
+    const stale = await query.list(PurchaseOrder, { status: 'draft', createdBefore: daysAgo(30) });
+    for (const po of stale) await call(cancel, { id: po.id });
+  },
+});

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

@@ -0,0 +1,137 @@
+// 定向业务测试补足通用造数无法准备的库存、审批人和角色参数。
+// 使用真实 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;
+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());
+
+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);
+});
+
+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',
+  );
+});
+
+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);
+});