@yss123/cage-cli 0.1.0 → 0.3.0

package/templates/blank/docs/examples/purchase-admin/apps/web/src/shared/ui/notice.tsx

@@ -0,0 +1,20 @@
+/**
+ * 业务操作结果的可关闭提示，内容和关闭状态由页面或 useCommand 持有。
+ */
+import type { ReactNode } from 'react';
+
+/** 通用提示容器只负责呈现；提示文案和关闭后的业务行为由调用页面决定。 */
+/**
+ * 呈现 children 消息并在关闭按钮点击时调用 onClose。
+ * 仅关闭提示，不回滚已经提交的命令，也不取消正在运行的任务。
+ */
+export function Notice({ children, onClose }: { children: ReactNode; onClose: () => void }) {
+  return (
+    <div role="status" className="notice">
+      {children}
+      <button onClick={onClose} aria-label="关闭提示">
+        ×
+      </button>
+    </div>
+  );
+}

package/templates/blank/docs/examples/purchase-admin/apps/web/src/shared/ui/page-heading.tsx

@@ -0,0 +1,35 @@
+/**
+ * 业务页公共标题区，统一标题、说明与右侧操作的布局，不包含查询和权限逻辑。
+ */
+import type { ReactNode } from 'react';
+
+/** 统一页面标题的排版；不读取路由或业务状态，避免共享 UI 反向依赖某项业务。 */
+/**
+ * 展示 eyebrow 分类文字、title 主标题、description 说明和 children 操作区。
+ * 操作按钮及其 can 检查由使用页面提供；此组件不会替调用方判断权限。
+ */
+export function PageHeading({
+  eyebrow,
+  title,
+  description,
+  children,
+}: {
+  eyebrow: string;
+  title: string;
+  description: string;
+  children?: ReactNode;
+}) {
+  return (
+    <div className="page-title">
+      <div>
+        <span className="eyebrow">{eyebrow}</span>
+        <h1>
+          {title}
+          <span className="title-dot">.</span>
+        </h1>
+        <p className="muted">{description}</p>
+      </div>
+      {children}
+    </div>
+  );
+}

package/templates/blank/docs/examples/purchase-admin/apps/web/src/shared/ui/page-state.css

@@ -0,0 +1,47 @@
+/**
+ * 共享页面状态卡与返回链接的样式，采购和空白模板均由同步流程取得同一版本。
+ * 颜色变量由应用主题提供；这里只排版标题、说明和操作，具体错误分类由 PageState/QueryFailure 决定。
+ */
+/* 与两套工作台共享的纸面状态卡；状态清楚可读，链接保持可聚焦和可复制。 */
+.route-state {
+  margin: 32px 0;
+  padding: 68px 36px;
+  border: 1px solid var(--line);
+  border-radius: 7px;
+  background: #fdfefb;
+  text-align: center;
+}
+.route-state-mark {
+  display: block;
+  margin-bottom: 20px;
+  color: #7d9866;
+  font:
+    italic 42px Georgia,
+    serif;
+}
+.route-state h1 {
+  font-size: 26px;
+  letter-spacing: -0.5px;
+}
+.route-state p {
+  margin: 16px 0 26px;
+  color: var(--muted);
+  font-size: 13px;
+  line-height: 1.9;
+}
+.route-link {
+  display: inline-flex;
+  align-items: center;
+  padding: 10px 16px;
+  border: 1px solid var(--line);
+  border-radius: 4px;
+  background: #f1f5eb;
+  color: var(--green);
+  font-size: 12px;
+}
+.route-link:hover {
+  background: #e4ecd9;
+}
+.route-state > button {
+  margin-left: 12px;
+}

package/templates/blank/docs/examples/purchase-admin/apps/web/src/shared/ui/page-state.tsx

@@ -0,0 +1,76 @@
+/**
+ * 供列表、详情和路由守卫复用的页面级状态组件。
+ * 将服务端可确认的错误与可恢复操作对应，保留返回链接；不泄露范围外记录是否真实存在。
+ */
+import type { ReactNode } from 'react';
+import { Link } from 'react-router-dom';
+import { CageQueryError } from '@app/contracts';
+import './page-state.css';
+
+/** 页面级状态保留导航入口，详情直达失败时也能回到列表，而不是出现空白页。 */
+/**
+ * 渲染标题、说明、返回链接和可选附加操作。
+ * props.title/description 为调用方提供的当前状态；to 是业务返回地址，label 缺省为返回列表。
+ * children 可放重试按钮；组件只呈现内容，不自行读取数据或推断错误。
+ */
+export function PageState({
+  title,
+  description,
+  to,
+  label = '返回列表',
+  children,
+}: {
+  title: string;
+  description: string;
+  to: string;
+  label?: string;
+  children?: ReactNode;
+}) {
+  return (
+    <section className="route-state" aria-labelledby="route-state-title">
+      <span className="route-state-mark" aria-hidden="true">
+        ↗
+      </span>
+      <h1 id="route-state-title">{title}</h1>
+      <p>{description}</p>
+      <Link className="route-link" to={to}>
+        {label}
+      </Link>
+      {children}
+    </section>
+  );
+}
+
+/** 按服务端错误区分权限、范围/不存在和服务故障；不从 URL 推断记录是否存在。 */
+/**
+ * 将查询异常映射为页面状态。CageQueryError 的 FORBIDDEN 与 NOT_FOUND 不展示重试按钮，其他错误允许调用 retry。
+ * props.error 为实际查询异常；to/label 决定退出路径，retry 由页面绑定 refetch。
+ * NOT_FOUND 同时涵盖记录不存在与不在可访问范围，不能据此向用户确认数据库中有无此记录。
+ */
+export function QueryFailure({
+  error,
+  to,
+  label,
+  retry,
+}: {
+  error: Error;
+  to: string;
+  label?: string;
+  retry: () => void;
+}) {
+  const code = error instanceof CageQueryError ? error.result.code : undefined;
+  const title = code === 'FORBIDDEN' ? '暂无访问权限' : code === 'NOT_FOUND' ? '记录不可用' : '暂时无法读取';
+  const description =
+    code === 'FORBIDDEN'
+      ? '当前账号没有访问此页面所需的权限，请联系管理员。'
+      : code === 'NOT_FOUND'
+        ? '记录不存在，或不在你当前可访问的数据范围内。'
+        : code === 'UNAUTHENTICATED'
+          ? '登录已过期，请重新登录后继续。'
+          : '请检查网络或稍后重新尝试。';
+  return (
+    <PageState title={title} description={description} to={to} label={label}>
+      {code !== 'FORBIDDEN' && code !== 'NOT_FOUND' && <button onClick={retry}>重新读取</button>}
+    </PageState>
+  );
+}

package/templates/blank/docs/examples/purchase-admin/apps/web/src/shared/ui/require-capability.tsx

@@ -0,0 +1,34 @@
+/**
+ * 业务路由的界面能力守卫，根据当前 SDK 能力快照决定渲染页面还是无权限提示。
+ * 服务端对请求独立授权；缓存中的能力只影响界面入口，不增加数据可见范围。
+ */
+import type { ReactNode } from 'react';
+import { useCan } from '@app/contracts';
+import { PageState } from './page-state';
+
+/** 直接输入 URL 也给出权限提示；真正的授权和数据范围仍由后端接口强制执行。 */
+/**
+ * 检查 capability 对应的页面入口权限，允许时渲染 children，否则提供回到 home 的链接。
+ * 需放在已恢复会话的路由内，避免把尚未加载的能力列表当作最终账号权限。
+ */
+export function RequireCapability({
+  capability,
+  children,
+  home,
+}: {
+  capability: Parameters<typeof useCan>[0];
+  children: ReactNode;
+  home: string;
+}) {
+  const allowed = useCan(capability);
+  return allowed ? (
+    children
+  ) : (
+    <PageState
+      title="暂无访问权限"
+      description="当前账号没有访问此页面所需的权限，请联系管理员。"
+      to={home}
+      label="返回工作台"
+    />
+  );
+}

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

@@ -0,0 +1,123 @@
+{
+  "domain": "packages/domain/src/index.ts",
+  "contracts": "packages/contracts/src",
+  "structure": "modular",
+  "typecheck": ["packages/domain", "packages/contracts", "apps/api", "apps/web"],
+  "graph": {
+    "title": "采购业务图谱",
+    "labels": {
+      "module:purchase": "采购管理",
+      "module:inventory": "库存管理",
+      "aggregate:PurchaseOrder": "采购单",
+      "aggregate:Inventory": "库存台账",
+      "aggregate:InventoryLock": "库存锁",
+      "aggregate:Dept": "部门",
+      "aggregate:User": "用户",
+      "aggregate:Role": "角色",
+      "command:PurchaseOrder.create": "新建采购单",
+      "command:PurchaseOrder.explainPurpose": "补充采购用途",
+      "command:PurchaseOrder.returnForChanges": "退回修改",
+      "field:PurchaseOrder.reason": "采购用途",
+      "capability:Sys.ai.use": "使用智能助理",
+      "capability:Sys.ai.models.manage": "管理 AI 模型",
+      "command:PurchaseOrder.setAttachments": "修改采购附件",
+      "field:PurchaseOrder.attachments": "采购附件",
+      "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, type RequestOptions } from '@yss123/cage-client';
+
+/** 部门：读侧快照（敏感字段是按权限掩码后的值） */
+export const DeptSchema = z.object({
+  id: z.string().uuid(),
+  name: z.string(),
+  code: z.string().nullable().optional(),
+  parentId: z.string().uuid().nullable().optional(),
+  ancestors: z.string(),
+  leaderId: z.string().uuid().nullable().optional(),
+  status: z.enum(["active", "archived"]),
+  version: z.number().int(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+export type Dept = z.infer<typeof DeptSchema>;
+export type DeptStatus = Dept['status'];
+export const DeptStates = ['active', 'archived'] as const;
+
+/** 命令输入：和后端命令的输入校验完全一致 */
+export const DeptInputs = {
+  archive: z.object({ id: z.string().uuid().regex(new RegExp("^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$")) }),
+  create: z.object({ name: z.string().min(1).max(100), code: z.string().max(64).optional(), parentId: z.string().uuid().regex(new RegExp("^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$")).nullable().optional(), leaderId: z.string().uuid().regex(new RegExp("^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$")).nullable().optional() }),
+  update: z.object({ id: z.string().uuid().regex(new RegExp("^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$")), name: z.string().min(1).max(100).optional(), code: z.string().max(64).nullable().optional(), leaderId: z.string().uuid().regex(new RegExp("^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$")).nullable().optional() }),
+};
+
+/** Dept.archive 可能返回的错误码 */
+export type DeptArchiveError = 'CONFLICT' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
+/** Dept.create 可能返回的错误码 */
+export type DeptCreateError = 'CONFLICT' | 'CONSTRAINT_VIOLATED' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT';
+/** Dept.update 可能返回的错误码 */
+export type DeptUpdateError = 'CONFLICT' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
+
+export type DeptSortKey = 'createdAt' | 'updatedAt' | 'name' | 'code' | 'parentId' | 'ancestors' | 'leaderId';
+export interface DeptListParams {
+  page?: number;
+  pageSize?: number;
+  /** 排序：字段名，前面加 - 表示倒序 */
+  sort?: DeptSortKey | `-${DeptSortKey}`;
+  /** 可以逗号分隔多个状态 */
+  status?: string;
+  createdAfter?: string;
+  createdBefore?: string;
+  name?: string | number | boolean;
+  code?: string | number | boolean;
+  parentId?: string | number | boolean;
+  ancestors?: string | number | boolean;
+  leaderId?: string | number | boolean;
+}
+
+/** 调用方法：每个命令一个；client 自动生成并附带幂等键和 CSRF 令牌 */
+export const dept = {
+  /** 停用部门（没有在职用户和下级部门时） */
+  archive: (id: string, expectedVersion?: number, options: RequestOptions = {}) => client.post<Dept, DeptArchiveError>(`/api/dept/${encodeURIComponent(id)}/archive`, { expectedVersion }, options),
+  /** 新建部门 */
+  create: (input: z.input<typeof DeptInputs.create>, options: RequestOptions = {}) => client.post<Dept, DeptCreateError>('/api/dept/create', input, options),
+  /** 修改部门名称、编码、负责人 */
+  update: (id: string, input: Omit<z.input<typeof DeptInputs.update>, 'id'>, expectedVersion?: number, options: RequestOptions = {}) => client.post<Dept, DeptUpdateError>(`/api/dept/${encodeURIComponent(id)}/update`, { ...input, expectedVersion }, options),
+  /** 异步导出 CSV：返回任务，使用 client.transfer(id) 查状态，完成后下载。需要 Dept.export 能力。 */
+  export: (params: DeptListParams = {}, options: RequestOptions = {}) => client.post<TransferTask, 'CONFLICT'>('/api/dept/export', params, options),
+  get: (id: string, options: RequestOptions = {}) => client.get<Dept>(`/api/dept/${encodeURIComponent(id)}`, undefined, options),
+  list: (params: DeptListParams = {}, options: RequestOptions = {}) => client.get<{ items: Dept[]; total: number; page: number; pageSize: number }>('/api/dept', params as Record<string, unknown>, options),
+};
+
+/** 详情查询 hook：响应也用 schema 校验；范围外返回 NOT_FOUND */
+export const useDept = (id: string) => useCageQuery(['dept', id], `/api/dept/${encodeURIComponent(id)}`, DeptSchema, { enabled: !!id });
+/** 列表查询 hook：走读侧账号与安全视图 */
+export const useDeptList = (params: DeptListParams = {}) => useCageList(['dept'], '/api/dept', params as Record<string, unknown>, DeptSchema);
+/** 查询缓存键前缀：命令成功后让它失效 */
+export const deptKeys = { all: ['dept'] as const, one: (id: string) => ['dept', id] as const };

package/templates/blank/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, type RequestOptions } 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>, options: RequestOptions = {}) => client.post<Inventory, InventoryCreateError>('/api/inventory/create', input, options),
+  /** 异步导出 CSV：返回任务，使用 client.transfer(id) 查状态，完成后下载。需要 Inventory.export 能力。 */
+  export: (params: InventoryListParams = {}, options: RequestOptions = {}) => client.post<TransferTask, 'CONFLICT'>('/api/inventory/export', params, options),
+  get: (id: string, options: RequestOptions = {}) => client.get<Inventory>(`/api/inventory/${encodeURIComponent(id)}`, undefined, options),
+  list: (params: InventoryListParams = {}, options: RequestOptions = {}) => client.get<{ items: Inventory[]; total: number; page: number; pageSize: number }>('/api/inventory', params as Record<string, unknown>, options),
+};
+
+/** 详情查询 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, type RequestOptions } 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: RequestOptions = {}) => client.post<TransferTask, 'CONFLICT'>('/api/inventory-lock/export', params, options),
+  get: (id: string, options: RequestOptions = {}) => client.get<InventoryLock>(`/api/inventory-lock/${encodeURIComponent(id)}`, undefined, options),
+  list: (params: InventoryLockListParams = {}, options: RequestOptions = {}) => client.get<{ items: InventoryLock[]; total: number; page: number; pageSize: number }>('/api/inventory-lock', params as Record<string, unknown>, options),
+};
+
+/** 详情查询 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,86 @@
+// 生成物：由 cage gen 从 domain 声明生成，不要手改。
+/* eslint-disable */
+
+import { z } from 'zod';
+import { client, useCageList, useCageQuery, type TransferTask, type RequestOptions } 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(),
+  reason: z.string().nullable().optional(),
+  items: z.array(z.object({ sku: z.string(), qty: z.number().int() })),
+  erpNo: z.string().nullable().optional(),
+  attachments: z.array(z.string().uuid()).max(10),
+  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 PurchaseOrderFileFields = {"attachments":{"maxBytes":2147483648,"accept":["application/pdf","image/jpeg","image/png","text/plain"],"maxCount":10,"multiple":true}} as const;
+
+/** 命令输入：和后端命令的输入校验完全一致 */
+export const PurchaseOrderInputs = {
+  cancel: 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({ 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(), reason: z.string().max(2000).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(), attachments: 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(10).optional() }),
+  explainPurpose: 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)$")), reason: z.unknown() }),
+  setAttachments: 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)$")), attachments: 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(10) }),
+  submit: 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)$")) }),
+};
+
+/** 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' | 'NOT_FOUND';
+/** PurchaseOrder.explainPurpose 可能返回的错误码 */
+export type PurchaseOrderExplainPurposeError = 'CONFLICT' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'INVARIANT_VIOLATED' | 'NOT_FOUND';
+/** PurchaseOrder.setAttachments 可能返回的错误码 */
+export type PurchaseOrderSetAttachmentsError = 'CONFLICT' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'INVARIANT_VIOLATED' | 'NOT_FOUND';
+/** 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' | 'reason' | '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;
+  reason?: string | number | boolean;
+  erpNo?: string | number | boolean;
+}
+
+/** 调用方法：每个命令一个；client 自动生成并附带幂等键和 CSRF 令牌 */
+export const purchaseOrder = {
+  cancel: (id: string, expectedVersion?: number, options: RequestOptions = {}) => client.post<PurchaseOrder, PurchaseOrderCancelError>(`/api/purchase-order/${encodeURIComponent(id)}/cancel`, { expectedVersion }, options),
+  create: (input: z.input<typeof PurchaseOrderInputs.create>, options: RequestOptions = {}) => client.post<PurchaseOrder, PurchaseOrderCreateError>('/api/purchase-order/create', input, options),
+  /** 补充采购用途与必要性，保存后可以重新提交审核 */
+  explainPurpose: (id: string, input: Omit<z.input<typeof PurchaseOrderInputs.explainPurpose>, 'id'>, expectedVersion?: number, options: RequestOptions = {}) => client.post<PurchaseOrder, PurchaseOrderExplainPurposeError>(`/api/purchase-order/${encodeURIComponent(id)}/explain-purpose`, { ...input, expectedVersion }, options),
+  setAttachments: (id: string, input: Omit<z.input<typeof PurchaseOrderInputs.setAttachments>, 'id'>, expectedVersion?: number, options: RequestOptions = {}) => client.post<PurchaseOrder, PurchaseOrderSetAttachmentsError>(`/api/purchase-order/${encodeURIComponent(id)}/set-attachments`, { ...input, expectedVersion }, options),
+  submit: (id: string, expectedVersion?: number, options: RequestOptions = {}) => client.post<PurchaseOrder, PurchaseOrderSubmitError>(`/api/purchase-order/${encodeURIComponent(id)}/submit`, { expectedVersion }, options),
+  /** 异步导出 CSV：返回任务，使用 client.transfer(id) 查状态，完成后下载。需要 PurchaseOrder.export 能力。 */
+  export: (params: PurchaseOrderListParams = {}, options: RequestOptions = {}) => client.post<TransferTask, 'CONFLICT'>('/api/purchase-order/export', params, options),
+  get: (id: string, options: RequestOptions = {}) => client.get<PurchaseOrder>(`/api/purchase-order/${encodeURIComponent(id)}`, undefined, options),
+  list: (params: PurchaseOrderListParams = {}, options: RequestOptions = {}) => client.get<{ items: PurchaseOrder[]; total: number; page: number; pageSize: number }>('/api/purchase-order', params as Record<string, unknown>, options),
+};
+
+/** 详情查询 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 };