@yss123/cage-cli 0.2.0 → 0.3.1

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

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

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

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

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

@@ -6,13 +6,36 @@
   "graph": {
     "title": "采购业务图谱",
     "labels": {
+      "module:purchase": "采购管理",
+      "module:inventory": "库存管理",
       "aggregate:PurchaseOrder": "采购单",
+      "aggregate:ApprovalMember": "采购审批协作名录",
       "aggregate:Inventory": "库存台账",
       "aggregate:InventoryLock": "库存锁",
       "aggregate:Dept": "部门",
       "aggregate:User": "用户",
       "aggregate:Role": "角色",
       "command:PurchaseOrder.create": "新建采购单",
+      "command:PurchaseOrder.explainPurpose": "补充采购用途",
+      "command:PurchaseOrder.setReviewers": "设置专业复核人员",
+      "command:PurchaseOrder.returnForChanges": "退回修改",
+      "field:PurchaseOrder.reason": "采购用途",
+      "field:PurchaseOrder.needsSpecialistReview": "需要专业复核",
+      "field:PurchaseOrder.reviewerIds": "专业复核人员",
+      "command:ApprovalMember.create": "登记采购协作人",
+      "command:ApprovalMember.update": "修改协作人公开资料",
+      "command:ApprovalMember.retire": "退役采购协作人",
+      "field:ApprovalMember.userId": "协作账号",
+      "field:ApprovalMember.displayName": "公开业务姓名",
+      "field:ApprovalMember.specialty": "专业领域",
+      "state:ApprovalMember.active": "可选协作人",
+      "state:ApprovalMember.retired": "已退役协作人",
+      "capability:ApprovalMember.read": "查看采购协作名录",
+      "capability:ApprovalMember.export": "导出采购协作名录",
+      "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": "驳回审批",

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

@@ -0,0 +1,70 @@
+// 生成物：由 cage gen 从 domain 声明生成，不要手改。
+/* eslint-disable */
+
+import { z } from 'zod';
+import { client, useCageList, useCageQuery, type TransferTask, type RequestOptions } from '@yss123/cage-client';
+
+/** 采购审批协作名录：读侧快照（敏感字段是按权限掩码后的值） */
+export const ApprovalMemberSchema = z.object({
+  id: z.string().uuid(),
+  userId: z.string().uuid(),
+  displayName: z.string(),
+  specialty: z.string(),
+  status: z.enum(["active", "retired"]),
+  version: z.number().int(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+export type ApprovalMember = z.infer<typeof ApprovalMemberSchema>;
+export type ApprovalMemberStatus = ApprovalMember['status'];
+export const ApprovalMemberStates = ['active', 'retired'] as const;
+
+/** 命令输入：和后端命令的输入校验完全一致 */
+export const ApprovalMemberInputs = {
+  create: z.object({ userId: 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)$")), displayName: z.unknown(), specialty: z.unknown() }),
+  retire: 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)$")) }),
+  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)$")), displayName: z.unknown(), specialty: z.unknown() }),
+};
+
+/** ApprovalMember.create 可能返回的错误码 */
+export type ApprovalMemberCreateError = 'CONFLICT' | 'CONSTRAINT_VIOLATED' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT';
+/** ApprovalMember.retire 可能返回的错误码 */
+export type ApprovalMemberRetireError = 'CONFLICT' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
+/** ApprovalMember.update 可能返回的错误码 */
+export type ApprovalMemberUpdateError = 'CONFLICT' | 'DOMAIN_ERROR' | 'FORBIDDEN' | 'INVALID_INPUT' | 'INVALID_TRANSITION' | 'NOT_FOUND';
+
+export type ApprovalMemberSortKey = 'createdAt' | 'updatedAt' | 'userId' | 'displayName' | 'specialty';
+export interface ApprovalMemberListParams {
+  page?: number;
+  pageSize?: number;
+  /** 排序：字段名，前面加 - 表示倒序 */
+  sort?: ApprovalMemberSortKey | `-${ApprovalMemberSortKey}`;
+  /** 可以逗号分隔多个状态 */
+  status?: string;
+  createdAfter?: string;
+  createdBefore?: string;
+  userId?: string | number | boolean;
+  displayName?: string | number | boolean;
+  specialty?: string | number | boolean;
+}
+
+/** 调用方法：每个命令一个；client 自动生成并附带幂等键和 CSRF 令牌 */
+export const approvalMember = {
+  /** 登记采购审批协作人 */
+  create: (input: z.input<typeof ApprovalMemberInputs.create>, options: RequestOptions = {}) => client.post<ApprovalMember, ApprovalMemberCreateError>('/api/approval-member/create', input, options),
+  /** 停用采购审批协作名录成员 */
+  retire: (id: string, expectedVersion?: number, options: RequestOptions = {}) => client.post<ApprovalMember, ApprovalMemberRetireError>(`/api/approval-member/${encodeURIComponent(id)}/retire`, { expectedVersion }, options),
+  /** 修改采购协作人的公开资料 */
+  update: (id: string, input: Omit<z.input<typeof ApprovalMemberInputs.update>, 'id'>, expectedVersion?: number, options: RequestOptions = {}) => client.post<ApprovalMember, ApprovalMemberUpdateError>(`/api/approval-member/${encodeURIComponent(id)}/update`, { ...input, expectedVersion }, options),
+  /** 异步导出 CSV：返回任务，使用 client.transfer(id) 查状态，完成后下载。需要 ApprovalMember.export 能力。 */
+  export: (params: ApprovalMemberListParams = {}, options: RequestOptions = {}) => client.post<TransferTask, 'CONFLICT'>('/api/approval-member/export', params, options),
+  get: (id: string, options: RequestOptions = {}) => client.get<ApprovalMember>(`/api/approval-member/${encodeURIComponent(id)}`, undefined, options),
+  list: (params: ApprovalMemberListParams = {}, options: RequestOptions = {}) => client.get<{ items: ApprovalMember[]; total: number; page: number; pageSize: number }>('/api/approval-member', params as Record<string, unknown>, options),
+};
+
+/** 详情查询 hook：响应也用 schema 校验；范围外返回 NOT_FOUND */
+export const useApprovalMember = (id: string) => useCageQuery(['approval-member', id], `/api/approval-member/${encodeURIComponent(id)}`, ApprovalMemberSchema, { enabled: !!id });
+/** 列表查询 hook：走读侧账号与安全视图 */
+export const useApprovalMemberList = (params: ApprovalMemberListParams = {}) => useCageList(['approval-member'], '/api/approval-member', params as Record<string, unknown>, ApprovalMemberSchema);
+/** 查询缓存键前缀：命令成功后让它失效 */
+export const approvalMemberKeys = { all: ['approval-member'] as const, one: (id: string) => ['approval-member', id] as const };

package/templates/blank/docs/examples/purchase-admin/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/docs/examples/purchase-admin/packages/contracts/src/aggregates/inventory/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';
 
 /** Inventory：读侧快照（敏感字段是按权限掩码后的值） */
 export const InventorySchema = z.object({
@@ -42,11 +42,11 @@ export interface InventoryListParams {
 
 /** 调用方法：每个命令一个；client 自动生成并附带幂等键和 CSRF 令牌 */
 export const inventory = {
-  create: (input: z.input<typeof InventoryInputs.create>) => client.post<Inventory, InventoryCreateError>('/api/inventory/create', input),
+  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: { 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>),
+  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 */

package/templates/blank/docs/examples/purchase-admin/packages/contracts/src/aggregates/inventory-lock/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';
 
 /** InventoryLock：读侧快照（敏感字段是按权限掩码后的值） */
 export const InventoryLockSchema = z.object({
@@ -39,9 +39,9 @@ export interface InventoryLockListParams {
 /** 调用方法：每个命令一个；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>),
+  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 */

package/templates/blank/docs/examples/purchase-admin/packages/contracts/src/aggregates/purchase-order/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';
 
 /** PurchaseOrder：读侧快照（敏感字段是按权限掩码后的值） */
 export const PurchaseOrderSchema = z.object({
@@ -11,8 +11,12 @@ export const PurchaseOrderSchema = z.object({
   createdBy: z.string().uuid(),
   supplierPhone: z.string().nullable().optional(),
   amount: z.string(),
+  reason: z.string().nullable().optional(),
+  needsSpecialistReview: z.boolean().nullable().optional(),
+  reviewerIds: z.array(z.string().uuid()).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(),
@@ -21,23 +25,34 @@ export const PurchaseOrderSchema = z.object({
 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() }),
-  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() }),
+  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(), needsSpecialistReview: z.boolean().optional(), reviewerIds: 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(5).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) }),
+  setReviewers: 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)$")), needsSpecialistReview: z.boolean(), reviewerIds: 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(5) }),
+  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';
+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.setReviewers 可能返回的错误码 */
+export type PurchaseOrderSetReviewersError = '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' | 'erpNo';
+export type PurchaseOrderSortKey = 'createdAt' | 'updatedAt' | 'deptId' | 'createdBy' | 'supplierPhone' | 'amount' | 'reason' | 'needsSpecialistReview' | 'erpNo';
 export interface PurchaseOrderListParams {
   page?: number;
   pageSize?: number;
@@ -50,18 +65,25 @@ export interface PurchaseOrderListParams {
   deptId?: string | number | boolean;
   createdBy?: string | number | boolean;
   amount?: string | number | boolean;
+  reason?: string | number | boolean;
+  needsSpecialistReview?: 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 }),
+  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),
+  /** 设置采购单专业复核需求和人员 */
+  setReviewers: (id: string, input: Omit<z.input<typeof PurchaseOrderInputs.setReviewers>, 'id'>, expectedVersion?: number, options: RequestOptions = {}) => client.post<PurchaseOrder, PurchaseOrderSetReviewersError>(`/api/purchase-order/${encodeURIComponent(id)}/set-reviewers`, { ...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: { 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>),
+  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 */

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