@yss123/cage-cli 0.3.0 → 0.3.1

package/templates/blank/docs/examples/purchase-admin/apps/web/src/shared/lib/error-message.ts

@@ -14,10 +14,15 @@ export function errorMessage(r: Extract<CageResult<unknown, string>, { ok: false
   const labels: Record<string, string> = {
     FORBIDDEN: '你没有执行此操作的权限',
     INVALID_INPUT: '请检查填写内容',
-    CONFLICT: '单据已更新，请刷新后重试',
+    CONFLICT: '数据或任务已更新，请刷新后重试',
     UNAUTHENTICATED: '登录已过期',
     CONSTRAINT_VIOLATED: '未满足审批条件，请检查审批人或额度',
     STOCK_SHORT: '库存不足',
+    REVIEWERS_REQUIRED: '请为专业会签选择 1–5 位协作人',
+    REVIEWERS_NOT_REQUIRED: '取消专业会签时请清空复核人员',
+    DUPLICATE_REVIEWERS: '专业会签人员不能重复',
+    REVIEWER_IS_APPLICANT: '申请人不能担任本单专业会签人',
+    REVIEWER_UNAVAILABLE: '所选人员已不可用，请重新核对协作名录',
     NETWORK: '连接失败，请稍后重试',
   };
   return `${labels[r.domainCode ?? r.code] ?? r.domainCode ?? r.code}${r.requestId ? ` · 请求 ${r.requestId.slice(0, 8)}` : ''}`;

package/templates/blank/docs/examples/purchase-admin/apps/web/src/shared/ui/approval-member-picker.css

@@ -0,0 +1,10 @@
+/** 协作名录的复选行布局供采购和审批模块复用；不覆盖其他表单，窄屏单列保持可点击标签。 */
+.approval-member-picker { border: 1px solid #dbe3d9; border-radius: 8px; padding: 14px; margin: 14px 0; min-width: 0; }
+.approval-member-picker legend { font-size: 12px; padding: 0 6px; font-weight: 600; }
+.approval-member-options { display: grid; grid-template-columns: repeat(auto-fit, minmax(210px, 1fr)); gap: 8px; margin: 12px 0; max-height: 250px; overflow-y: auto; }
+.approval-member-options label { display: flex; align-items: center; gap: 10px; padding: 10px; border: 1px solid #e5e9e2; border-radius: 6px; cursor: pointer; }
+.approval-member-options input[type='checkbox'] { width: 16px; height: 16px; flex: 0 0 auto; }
+.approval-member-options small { display: block; margin-top: 3px; color: #647365; }
+/* 开关与选人复选框保留原生尺寸，避免通用表单的 width:100% 让标签错位。 */
+label.review-checkbox { display: flex; align-items: center; gap: 10px; }
+label.review-checkbox input { width: auto; flex: none; }

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

@@ -0,0 +1,51 @@
+/**
+ * 采购参与者共用的审批协作名录选择器，由采购表单和审批管理弹窗消费。
+ * 仅通过生成契约读取 ApprovalMember 安全视图，不读取完整 User 或凭账号名猜测权限。
+ * 目录是公开协作身份，不保证被选者对当前单据有审批权限；实际提交由服务端复核，空/失败不能伪装成可选名单。
+ */
+import { useState } from 'react';
+import { useQuery } from '@tanstack/react-query';
+import { approvalMember } from '@app/contracts';
+import { errorMessage } from '../lib/error-message';
+import './approval-member-picker.css';
+
+/**
+ * 在有名录读取权限的界面加载当前页，可按显示名/职责就地筛选；最多读取 200 项，不声称返回完整组织。
+ * page 进入查询缓存键，退出账号时由应用会话层清理；retired 默认不用于选人。
+ */
+export function useApprovalMembers(page = 1, includeRetired = false) {
+  return useQuery({ queryKey: ['approval-members', page, includeRetired], queryFn: async () => {
+    const result = await approvalMember.list({ page, pageSize: 200, ...(includeRetired ? {} : { status: 'active' }) });
+    if (!result.ok) throw new Error(errorMessage(result));
+    return result.data;
+  } });
+}
+
+/**
+ * 单选/多选均输出真实 userId，value 与 onChange 由父表单持有，exclude 只改善体验，不替代服务端重复票检查。
+ * max 限制本次选择数量，已选项始终可取消；翻页保留已选 ID，页面展示本次已选数量。
+ * disabled 用于在父级提交时冻结编辑；刷新与失败保留用户选择，不自动选择或发起写操作。
+ */
+export function ApprovalMemberPicker({ value, onChange, max = 5, exclude = [], disabled = false }: {
+  value: string[]; onChange: (ids: string[]) => void; max?: number; exclude?: string[]; disabled?: boolean;
+}) {
+  const [search, setSearch] = useState(''), [page, setPage] = useState(1);
+  const query = useApprovalMembers(page);
+  const entries = query.data?.items.filter(member => !exclude.includes(member.userId) &&
+    `${member.displayName} ${member.specialty}`.includes(search.trim())) ?? [];
+  return <fieldset className="approval-member-picker" disabled={disabled}>
+    <legend>选择协作人员 · 已选 {value.length}/{max}</legend>
+    <input aria-label="筛选协作人员" placeholder="按姓名或职责筛选当前页" value={search} onChange={event => setSearch(event.target.value)} />
+    {query.isPending && <p role="status">正在读取协作名录…</p>}
+    {query.isError && <p role="alert">{query.error.message} <button type="button" onClick={() => void query.refetch()}>重试</button></p>}
+    <div className="approval-member-options">{entries.map(member => <label key={member.id}>
+      <input type="checkbox" checked={value.includes(member.userId)} disabled={disabled || (!value.includes(member.userId) && value.length >= max && max !== 1)}
+        onChange={event => onChange(event.target.checked ? max === 1 ? [member.userId] : [...value, member.userId] : value.filter(id => id !== member.userId))} />
+      <span><strong>{member.displayName}</strong><small>{member.specialty}</small></span>
+    </label>)}</div>
+    {query.data && entries.length === 0 && <p className="muted">当前页没有匹配人员，请调整筛选或联系名录维护人。</p>}
+    {(query.data?.total ?? 0) > 200 && <div className="actions"><button type="button" disabled={page === 1} onClick={() => setPage(page - 1)}>上一页</button>
+      <span>第 {page} 页</span><button type="button" disabled={page * 200 >= query.data!.total} onClick={() => setPage(page + 1)}>下一页</button></div>}
+    <small className="muted">名录只提供选人信息，处理权限、数据范围和最终额度仍以服务端校验为准。</small>
+  </fieldset>;
+}

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

@@ -9,6 +9,7 @@
       "module:purchase": "采购管理",
       "module:inventory": "库存管理",
       "aggregate:PurchaseOrder": "采购单",
+      "aggregate:ApprovalMember": "采购审批协作名录",
       "aggregate:Inventory": "库存台账",
       "aggregate:InventoryLock": "库存锁",
       "aggregate:Dept": "部门",
@@ -16,8 +17,21 @@
       "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": "修改采购附件",

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/purchase-order/index.ts

@@ -12,6 +12,8 @@ export const PurchaseOrderSchema = z.object({
   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),
@@ -29,9 +31,10 @@ export const PurchaseOrderFileFields = {"attachments":{"maxBytes":2147483648,"ac
 /** 命令输入：和后端命令的输入校验完全一致 */
 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() }),
+  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)$")) }),
 };
 
@@ -43,11 +46,13 @@ export type PurchaseOrderCreateError = 'CONFLICT' | 'CONSTRAINT_VIOLATED' | 'DOM
 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' | 'reason' | 'erpNo';
+export type PurchaseOrderSortKey = 'createdAt' | 'updatedAt' | 'deptId' | 'createdBy' | 'supplierPhone' | 'amount' | 'reason' | 'needsSpecialistReview' | 'erpNo';
 export interface PurchaseOrderListParams {
   page?: number;
   pageSize?: number;
@@ -61,6 +66,7 @@ export interface PurchaseOrderListParams {
   createdBy?: string | number | boolean;
   amount?: string | number | boolean;
   reason?: string | number | boolean;
+  needsSpecialistReview?: string | number | boolean;
   erpNo?: string | number | boolean;
 }
 
@@ -71,6 +77,8 @@ export const purchaseOrder = {
   /** 补充采购用途与必要性，保存后可以重新提交审核 */
   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: RequestOptions = {}) => client.post<TransferTask, 'CONFLICT'>('/api/purchase-order/export', params, options),

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

@@ -1,6 +1,7 @@
 // 生成物：由 cage gen 从 domain 声明生成，不要手改。
 /* eslint-disable */
 
+export * from './aggregates/approval-member';
 export * from './aggregates/dept';
 export * from './aggregates/inventory';
 export * from './aggregates/inventory-lock';
@@ -9,6 +10,7 @@ export * from './aggregates/role';
 export * from './aggregates/user';
 export * from './queries';
 import { can as baseCan, useCan as baseUseCan } from '@yss123/cage-client';
+import { ApprovalMemberInputs } from './aggregates/approval-member';
 import { DeptInputs } from './aggregates/dept';
 import { InventoryInputs } from './aggregates/inventory';
 import { InventoryLockInputs } from './aggregates/inventory-lock';
@@ -19,6 +21,11 @@ export { client, configureClient, loadMe, currentUser, CageQueryError, CageComma
 
 /** 能力目录（由代码派生）：写错能力点名会编译失败 */
 export const capabilities = [
+  'ApprovalMember.create',
+  'ApprovalMember.export',
+  'ApprovalMember.read',
+  'ApprovalMember.retire',
+  'ApprovalMember.update',
   'Dept.archive',
   'Dept.create',
   'Dept.export',
@@ -42,6 +49,7 @@ export const capabilities = [
   'PurchaseOrder.reject',
   'PurchaseOrder.returnForChanges',
   'PurchaseOrder.setAttachments',
+  'PurchaseOrder.setReviewers',
   'PurchaseOrder.submit',
   'PurchaseOrder.unmask.phone',
   'Role.archive',
@@ -78,6 +86,7 @@ export const useCan = (capability: Capability): boolean => baseUseCan(capability
 
 /** 各聚合的命令输入 schema：按聚合名、命令名访问，可直接供表单库校验 */
 export const schemas = {
+  ApprovalMember: ApprovalMemberInputs,
   Dept: DeptInputs,
   Inventory: InventoryInputs,
   InventoryLock: InventoryLockInputs,

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

@@ -0,0 +1,54 @@
+/**
+ * 采购协作名录：由业务管理员登记可参与采购复核的账号、公开业务姓名和专业领域，供草稿选人及任务操作使用。
+ * 聚合通过标准命令维护，浏览器读取 safe.approval_member；名录与 sys.user 的私密资料、角色授权分离。
+ * 名录在同租户内向具 ApprovalMember.read 且显式获 all 范围的采购参与者公开；加入名录不授予审批权限、范围或额度。
+ */
+import { aggregate, command, ref, scope, states, text } from '@yss123/cage-kernel';
+import { z } from 'zod';
+
+/**
+ * 一位账号对应一个采购协作身份，显示姓名是管理员明确登记的业务公开值，不读取 User.name 明文。
+ * active 可供新申请选择，retired 保留旧单据的人员证据；退役不取消已经承担的审批责任或撤销真实角色。
+ */
+export const ApprovalMember = aggregate('ApprovalMember', {
+  description: '采购审批协作名录',
+  fields: {
+    /** 当前租户的真实用户引用；租户内唯一，禁止用多条名录为同一账号制造多个会签名额。 */
+    userId: ref('User').unique(),
+    /** 对采购协作者公开的展示姓名；与登录姓名独立维护，不包含电话、邮箱或其他个人资料。 */
+    displayName: text(80),
+    /** 供选人判断的专业领域或岗位说明，例如设备技术、合同审查；不是角色编码或权限表达式。 */
+    specialty: text(120),
+  },
+  states: states('active', 'retired', { terminal: ['retired'] }),
+  // 名录没有部门或创建人字段，因此采购参与者必须由管理员显式授予 ApprovalMember 的 all 范围。
+  scope: scope.none(),
+});
+
+/**
+ * 登记采购协作人，要求 ApprovalMember.create；真实账号引用和租户约束由内核处理。
+ * 只保存公开业务名录，不改 User 的角色或密码，不代表所选用户可以批准任何采购单。
+ */
+export const createApprovalMember = command(ApprovalMember, {
+  name: 'create', description: '登记采购审批协作人', from: 'new', to: 'active',
+  input: z.object({ userId: z.string().uuid(), displayName: z.string().trim().min(1).max(80), specialty: z.string().trim().min(1).max(120) }),
+  handler: draft => draft,
+});
+
+/**
+ * 仅更新有效成员的展示姓名与专业说明，版本、范围和审计由内核维护。
+ * 不接受 userId，避免已被采购单引用的协作身份悄悄换人；需要另一个账号时登记新成员。
+ */
+export const updateApprovalMember = command(ApprovalMember, {
+  name: 'update', description: '修改采购协作人的公开资料', from: 'active', to: null,
+  input: z.object({ id: z.string().uuid(), displayName: z.string().trim().min(1).max(80), specialty: z.string().trim().min(1).max(120) }),
+  handler: (_draft, input) => ({ displayName: input.displayName, specialty: input.specialty }),
+});
+
+/**
+ * 退役成员使后续设置/提交专业复核名单拒绝此人，保留记录供历史展示。
+ * 此动作不停用登录账号、不收回角色，也不修改在途流程快照；在途处理仍按当前真实权限核验。
+ */
+export const retireApprovalMember = command(ApprovalMember, {
+  name: 'retire', description: '停用采购审批协作名录成员', from: 'active', to: 'retired', handler: draft => draft,
+});

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

@@ -1,10 +1,14 @@
-// 路由只决定由谁审批；最终结论仍调用领域命令，执行职责分离和额度约束。
+/**
+ * 采购实际审批路由：AI 预审、部门审核、可选专业会签和大额财务候选受理，共用一个采购流程实例。
+ * 人工节点显式开放转办、委派和前后/并行加签；步骤/政策随提交保存，旧实例保持自己的快照。
+ * 路由只决定任务分配与签序，最终结论仍执行领域命令的职责分离、额度与库存约束。
+ */
 import { approval } from '@yss123/cage-kernel';
-import { approver, gt, route, step, when } from '@yss123/cage-approval';
+import { approver, eq, gt, route, step, when } from '@yss123/cage-approval';
 import { PurchaseOrder, OrderSubmitted, OrderCancelled, approve, reject, returnForChanges } from './purchase-order.js';
 
 /**
- * 把提交/取消事件与审批生命周期关联；routable 仅开放金额和部门给流程路由使用。
+ * 把提交/取消事件与审批生命周期关联；routable 仅开放金额、部门和专业复核需求/名单。
  * 通过、驳回、退回分别调用已有 process 命令，领域状态与最终审批结论由引擎在事务内落实。
  * automatedBy 是自动结论执行角色代码，必须由部署管理员显式配置能力和范围，声明不自动授予权限。
  */
@@ -12,7 +16,7 @@ export const poApproval = approval(PurchaseOrder, {
   process: 'po-approval',
   start: OrderSubmitted,
   cancelOn: [OrderCancelled],
-  routable: ['amount', 'deptId'],
+  routable: ['amount', 'deptId', 'needsSpecialistReview', 'reviewerIds'],
   onApproved: approve,
   onRejected: reject,
   onReturned: returnForChanges,
@@ -20,10 +24,12 @@ export const poApproval = approval(PurchaseOrder, {
 });
 
 /**
- * 顺序为 AI 材料预审、部门经理、条件财务审批；金额严格大于 50000 元才增加财务节点。
+ * 顺序为 AI 材料预审、部门经理、按单据指定人员的专业会签、条件财务候选受理。
+ * needsSpecialistReview=true 才增加专业会签，名单来自提交快照且全部人必须通过；金额严格大于 50000 元才增加财务节点。
  * AI 只读取 reason/amount/items，pass 仅推进到经理，return 回到草稿，manual 在当前节点交部门负责人。
  * 模型失败同样转人工，最多四轮/五次工具调用/120 秒；不以失败兜底为自动批准。
- * 财务 any 表示候选财务人员中一人处理即可；所有人工处理仍需真实命令能力、范围、额度和职责分离。
+ * 财务共享一项未分配任务，finance 当前成员须先领取；所有人工动作仍需真实命令能力、范围、额度和职责分离。
+ * AI 人工接管保持原节点规则；经理、专业和财务才开放三项管理动作，新实例自动保存允许的加签位置。
  */
 export const poRoute = route('po-approval', [
   step('AI 材料预审', {
@@ -34,6 +40,11 @@ export const poRoute = route('po-approval', [
     limits: { maxSteps: 4, maxToolCalls: 5, timeoutMs: 120_000 },
     onFailure: 'manual',
   }),
-  step('部门经理审批', approver.deptLeader('deptId')),
-  when(gt('amount', 50000), step('财务审批', approver.role('finance'), { mode: 'any' })),
+  step('部门经理审批', approver.deptLeader('deptId'), { actions: { transfer: true, delegate: true, addSign: true } }),
+  when(eq('needsSpecialistReview', true), step('专业人员会签', approver.field('reviewerIds'), {
+    mode: 'all', actions: { transfer: true, delegate: true, addSign: true },
+  })),
+  when(gt('amount', 50000), step('财务候选受理', approver.role('finance'), {
+    assignment: 'candidate', mode: 'any', actions: { transfer: true, delegate: true, addSign: true },
+  })),
 ]);

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

@@ -1,7 +1,8 @@
 // 采购模块的公开声明；其他模块通过本入口依赖它，不穿透内部文件。
 // index 只转导出，避免在组装入口里隐藏业务行为或产生初始化副作用。
-// 主对象、审批、只读统计和定时任务统一由此公开；测试文件不导出，运行时不注册测试夹具。
+// 主对象、协作名录、审批、只读统计和定时任务统一由此公开；测试文件不导出，运行时不注册测试夹具。
 export * from './purchase-order.js';
+export * from './approval-members.js';
 export * from './approvals.js';
 export * from './queries.js';
 export * from './jobs.js';