@yss123/cage-cli 0.3.0 → 0.3.1

package/templates/app/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/app/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/app/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/app/packages/domain/package.json

@@ -14,11 +14,11 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@yss123/cage-kernel": "0.3.0",
-    "@yss123/cage-admin": "0.3.0",
-    "@yss123/cage-approval": "0.3.0",
-    "@yss123/cage-connectors": "0.3.0",
-    "@yss123/cage-ai": "0.3.0",
+    "@yss123/cage-kernel": "0.3.1",
+    "@yss123/cage-admin": "0.3.1",
+    "@yss123/cage-approval": "0.3.1",
+    "@yss123/cage-connectors": "0.3.1",
+    "@yss123/cage-ai": "0.3.1",
     "zod": "^4.1.5"
   }
 }

package/templates/app/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/app/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/app/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';

package/templates/app/packages/domain/src/modules/purchase/intelligence.test.ts

@@ -1,4 +1,8 @@
-// 模型决策用固定脚本，回归实际采购声明如何消费框架 AI 节点、命令和审批引擎。
+/**
+ * 以实际采购声明、应用迁移、真实 PostgreSQL 和 worker 回归 AI 预审到人工 OA 的完整业务链。
+ * 只把模型生成器换为固定工具裁决，采购路由、协作名录、结论命令及库存反应仍使用应用实现。
+ * 断言任务等待、会签完成和最终库存占用的区别；不连接应用数据库，也不把测试成功当作浏览器验收。
+ */
 import { beforeAll, afterAll, expect, it } from 'vitest';
 import { randomUUID } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
@@ -12,27 +16,64 @@ let decision: 'pass' | 'return' | 'manual' = 'return';
 /** 保留真实工具调用协议，只替换模型生成器；领域声明、审批引擎、数据库和 worker 仍使用实际实现。 */
 const intelligence = ai({ models: { main: { spec: { kind: 'test-only' }, generate: async (): Promise<ModelResult> => ({ text: '', calls: [{ id: randomUUID(), name: 'review_decide',
   arguments: { decision, reason: '按当前用途审查', suggestions: decision === 'return' ? ['补充具体使用场景'] : [], evidence: [{ source: 'subject', detail: 'reason 字段' }] } }] }) } } });
-let env: TestEnv, buyer: TestUser, reviewer: TestUser;
+let env: TestEnv, buyer: TestUser, reviewer: TestUser, specialistA: TestUser, specialistB: TestUser, financeA: TestUser, financeB: TestUser;
 /**
  * 显式建立人工负责人和自动审查角色，证明声明本身不授予 AI 执行权限。
  * 自动角色只获 read/returnForChanges，不授 approve；通过 AI 节点后必须继续走人工经理结论。
  */
 beforeAll(async () => {
   env = await createTestEnv({ domain: { ...purchase, intelligence }, migrations: readMigrations(fileURLToPath(new URL('../../../../../db/migrations/', import.meta.url))) });
-  buyer = await env.user({ caps: ['PurchaseOrder.read', 'PurchaseOrder.create', 'PurchaseOrder.explainPurpose', 'PurchaseOrder.submit'] });
+  buyer = await env.user({ caps: ['PurchaseOrder.read', 'PurchaseOrder.create', 'PurchaseOrder.explainPurpose', 'PurchaseOrder.submit', 'PurchaseOrder.setReviewers', 'ApprovalMember.read'],
+    scopes: { ApprovalMember: 'all' } });
   reviewer = await env.user({ caps: ['PurchaseOrder.read', 'PurchaseOrder.approve', 'PurchaseOrder.returnForChanges'], scopes: { PurchaseOrder: 'dept' }, params: { 'PurchaseOrder.approve': { ceiling: 50000 } } });
   await env.kernel.execute('Dept.update', { id: env.rootDeptId, leaderId: reviewer.id }, env.system());
   await env.kernel.execute('Inventory.create', { sku: 'AI-01', available: 100 }, env.system());
   const role = await env.kernel.execute('Role.create', { code: 'purchase_ai_reviewer', name: '材料预审角色' }, env.system());
   for (const capability of ['PurchaseOrder.read', 'PurchaseOrder.returnForChanges']) await env.kernel.execute('Role.grantCapability', { id: role.id, capability }, env.system());
   await env.kernel.execute('Role.setScope', { id: role.id, aggregate: 'PurchaseOrder', combinator: 'all' }, env.system());
+  specialistA = await collaborator('设备技术复核'); specialistB = await collaborator('采购合规复核');
+  financeA = await collaborator('财务共享受理甲'); financeB = await collaborator('财务共享受理乙');
+  const financeRole = await env.kernel.execute('Role.create', { code: 'finance', name: '采购财务候选人员' }, env.system());
+  for (const user of [financeA, financeB]) await env.kernel.execute('User.assignRoles', { id: user.id, roleIds: [user.roleId, financeRole.id] }, env.system());
 });
 afterAll(() => env?.close());
-/** 创建材料不足的固定单据并消费当前事件，让每个测试从真实 AI 节点的处理结果开始。 */
-async function submit() {
-  const order = await env.kernel.execute('PurchaseOrder.create', { amount: '1200.00', reason: '用途待补充', items: [{ sku: 'AI-01', qty: 2 }] }, await buyer.ctx());
+
+/**
+ * 通过组织和业务命令登记同部门协作人；10 万元额度只供本隔离库验证大额流程，名录本身不授予能力。
+ * 专业和财务共享这些真实审批能力，财务候选身份由额外的 finance 角色单独赋予。
+ */
+async function collaborator(specialty: string) {
+  const user = await env.user({ caps: ['PurchaseOrder.read', 'PurchaseOrder.approve', 'PurchaseOrder.reject', 'PurchaseOrder.returnForChanges'],
+    scopes: { PurchaseOrder: 'dept' }, params: { 'PurchaseOrder.approve': { ceiling: 100000 } } });
+  await env.kernel.execute('ApprovalMember.create', { userId: user.id, displayName: specialty, specialty }, env.system());
+  return user;
+}
+
+/** 创建固定物料草稿；金额按元传输，专业名单仍交真实 create/submit 命令校验。 */
+async function draft(options: { amount?: string; needsSpecialistReview?: boolean; reviewerIds?: string[] } = {}) {
+  return env.kernel.execute('PurchaseOrder.create', { amount: '1200.00', reason: '用途待补充', items: [{ sku: 'AI-01', qty: 2 }], ...options }, await buyer.ctx());
+}
+
+/** 提交真实采购单并消费当前事件；固定模型输出使每例从明确 AI 结果开始，不替换人工审批路由。 */
+async function submit(options: { amount?: string; needsSpecialistReview?: boolean; reviewerIds?: string[] } = {}) {
+  const order = await draft(options);
   await env.kernel.execute('PurchaseOrder.submit', { id: order.id }, await buyer.ctx()); await env.drain(); return order;
 }
+
+/** 从操作者本人待办重新取得当前 revision，避免复用动作发生前的旧页面版本。 */
+async function taskOf(user: TestUser, orderId: string, status = 'pending') {
+  const task = (await purchase.poRoute.engine(env.kernel).tasksOf(user.id, env.tenantId, status)).find(item => item.businessKey === orderId);
+  expect(task).toBeDefined(); return task!;
+}
+
+/** 通过真实待办批准当前节点，最终节点才会执行采购领域命令和同事务库存占用。 */
+async function approveBy(user: TestUser, orderId: string) {
+  const task = await taskOf(user, orderId);
+  await purchase.poRoute.engine(env.kernel).decide(task.id, user.id, env.tenantId, 'approved', undefined, task.revision);
+}
+
+/** 以采购员安全读侧核对业务状态，不从任务通过的局部结果推断整张单据已经批准。 */
+async function orderStatus(orderId: string) { return (await env.kernel.read.get(purchase.PurchaseOrder, orderId, await buyer.ctx())).status; }
 /** 退回不覆盖旧审批证据；重新提交产生新轮次，历史保留上次建议且最新轮次继续经理待办。 */
 it('AI 退回修改后保存用途并重新提交，形成新轮次且先重新经过 AI 节点', async () => {
   decision = 'return'; const order = await submit();
@@ -49,7 +90,7 @@ it('AI 通过只推进到经理节点，经理通过后才执行批准命令及
   decision = 'pass'; const order = await submit(), engine = purchase.poRoute.engine(env.kernel);
   expect((await env.kernel.read.get(purchase.PurchaseOrder, order.id, await buyer.ctx())).status).toBe('pending_approval');
   const task = (await engine.tasksOf(reviewer.id, env.tenantId)).find(t => t.businessKey === order.id)!;
-  await engine.decide(task.id, reviewer.id, env.tenantId, 'approved');
+  await engine.decide(task.id, reviewer.id, env.tenantId, 'approved', undefined, task.revision);
   expect((await env.kernel.read.get(purchase.PurchaseOrder, order.id, await buyer.ctx())).status).toBe('approved');
   expect((await env.query('select status from core.inventory_lock where id = $1', [order.id]))[0].status).toBe('held');
 });
@@ -60,3 +101,124 @@ it('AI 转人工保留在本节点，人工可退回修改', async () => {
   await engine.decide(task.id, reviewer.id, env.tenantId, 'returned', '请补充审批材料');
   expect((await env.kernel.read.get(purchase.PurchaseOrder, order.id, await buyer.ctx())).status).toBe('draft');
 });
+
+/** 草稿允许暂存，但编辑和提交都拒绝不完整、自审、重复或未登记名单，失败不产生审批实例。 */
+it.each(['无人', '重复', '本人', '未登记', '关闭仍有名单'] as const)('专业复核名单%s时，设置和提交均拒绝且保留草稿', async boundary => {
+  const reviewerIds = boundary === '无人' ? [] : boundary === '重复' ? [specialistA.id, specialistA.id]
+    : boundary === '本人' ? [buyer.id] : boundary === '未登记' ? [randomUUID()] : [specialistA.id];
+  const needsSpecialistReview = boundary !== '关闭仍有名单';
+  const domainCode = { 无人: 'REVIEWERS_REQUIRED', 重复: 'DUPLICATE_REVIEWERS', 本人: 'REVIEWER_IS_APPLICANT', 未登记: 'REVIEWER_UNAVAILABLE', 关闭仍有名单: 'REVIEWERS_NOT_REQUIRED' }[boundary];
+  const order = await draft({ needsSpecialistReview, reviewerIds });
+  expect(await env.callAs(await buyer.ctx(), 'PurchaseOrder.setReviewers', { id: order.id, needsSpecialistReview, reviewerIds })).toMatchObject({ ok: false, domainCode });
+  expect(await env.callAs(await buyer.ctx(), 'PurchaseOrder.submit', { id: order.id })).toMatchObject({ ok: false, domainCode });
+  expect(await orderStatus(order.id)).toBe('draft');
+  expect(await env.query('select id from flow.approval_instance where business_key=$1', [order.id])).toHaveLength(0);
+});
+
+/** 名录通过业务 read 开放，用户无需 User.read；提交会重查设置后退役的成员，防止旧草稿带入新流程。 */
+it('采购员无需系统用户读权限即可配置协作人，但提交拒绝已退役名单', async () => {
+  const person = await env.user({ caps: [] });
+  const member = await env.kernel.execute('ApprovalMember.create', { userId: person.id, displayName: '临时合同复核', specialty: '合同条款' }, env.system());
+  expect((await env.kernel.read.get(purchase.ApprovalMember, member.id, await buyer.ctx())).displayName).toBe('临时合同复核');
+  const order = await draft();
+  await env.kernel.execute('PurchaseOrder.setReviewers', { id: order.id, needsSpecialistReview: true, reviewerIds: [person.id] }, await buyer.ctx());
+  await env.kernel.execute('ApprovalMember.retire', { id: member.id }, env.system());
+  expect(await env.callAs(await buyer.ctx(), 'PurchaseOrder.submit', { id: order.id })).toMatchObject({ ok: false, domainCode: 'REVIEWER_UNAVAILABLE' });
+  expect(await orderStatus(order.id)).toBe('draft');
+});
+
+/** 两位字段选人均须完成；第一票不能提前触发批准命令和库存锁，最终签署者仍走真实领域约束。 */
+it('经理后开启所选专业人员 all 会签，全部通过才批准并锁库存', async () => {
+  decision = 'pass'; const order = await submit({ needsSpecialistReview: true, reviewerIds: [specialistA.id, specialistB.id] });
+  await approveBy(reviewer, order.id);
+  const a = await taskOf(specialistA, order.id), b = await taskOf(specialistB, order.id);
+  expect(a.step).toBe(2); expect(b.step).toBe(2); expect(a.id).not.toBe(b.id);
+  expect(a.actions).toEqual({ transfer: true, delegate: true, addSign: true });
+  // 历史标题来自当前实例的步骤快照，帮助详情区分部门审核与专业会签；不读取或展示 AI 策略全文。
+  const history = await purchase.poRoute.engine(env.kernel).history('PurchaseOrder', order.id, await buyer.ctx());
+  expect(history[0].steps.map(step => step.title)).toEqual(['AI 材料预审', '部门经理审批', '专业人员会签']);
+  await approveBy(specialistA, order.id);
+  expect(await orderStatus(order.id)).toBe('pending_approval');
+  expect(await env.query('select id from core.inventory_lock where id=$1', [order.id])).toHaveLength(0);
+  await approveBy(specialistB, order.id);
+  expect(await orderStatus(order.id)).toBe('approved');
+  expect((await env.query('select status from core.inventory_lock where id=$1', [order.id]))[0].status).toBe('held');
+});
+
+/** gt 阈值必须保持严格大于；恰好 5 万元时经理的同额 ceiling 足够，不创建财务候选任务。 */
+it('恰好 50000 元经理通过后直接批准，不产生财务候选待办', async () => {
+  decision = 'pass'; const order = await submit({ amount: '50000.00' });
+  await approveBy(reviewer, order.id);
+  expect(await orderStatus(order.id)).toBe('approved');
+  expect((await purchase.poRoute.engine(env.kernel).candidateTasks(financeA.id, env.tenantId)).some(task => task.businessKey === order.id)).toBe(false);
+});
+
+/** 同一大额采购仅建一个候选任务，领取/释放保留 revision，另一财务领取并批准后才产生库存锁。 */
+it('超过 50000 元进入财务共享候选池，释放后另一人领取并完成真实采购审批', async () => {
+  decision = 'pass'; const order = await submit({ amount: '50000.01' }), engine = purchase.poRoute.engine(env.kernel);
+  await approveBy(reviewer, order.id);
+  const a = (await engine.candidateTasks(financeA.id, env.tenantId)).find(task => task.businessKey === order.id)!;
+  const b = (await engine.candidateTasks(financeB.id, env.tenantId)).find(task => task.businessKey === order.id)!;
+  expect(a.id).toBe(b.id); expect(a.assignment).toBe('candidate'); expect(a.assigneeId).toBeNull();
+  await expect(engine.decide(a.id, financeA.id, env.tenantId, 'approved', undefined, a.revision)).rejects.toMatchObject({ code: 'NOT_FOUND' });
+  await engine.act(a.id, financeA.id, env.tenantId, { action: 'claim', expectedRevision: a.revision, reason: '财务甲领取大额采购' });
+  const claimed = await taskOf(financeA, order.id);
+  await engine.act(a.id, financeA.id, env.tenantId, { action: 'unclaim', expectedRevision: claimed.revision, reason: '转回共享池由在岗财务受理' });
+  await expect(engine.act(b.id, financeB.id, env.tenantId, { action: 'claim', expectedRevision: b.revision, reason: '旧列表尝试领取' })).rejects.toMatchObject({ code: 'CONFLICT' });
+  const available = (await engine.candidateTasks(financeB.id, env.tenantId)).find(task => task.businessKey === order.id)!;
+  await engine.act(available.id, financeB.id, env.tenantId, { action: 'claim', expectedRevision: available.revision, reason: '财务乙刷新后领取' });
+  expect(await orderStatus(order.id)).toBe('pending_approval');
+  await approveBy(financeB, order.id);
+  expect(await orderStatus(order.id)).toBe('approved');
+  expect((await env.query('select status from core.inventory_lock where id=$1', [order.id]))[0].status).toBe('held');
+  const history = await engine.taskHistory('PurchaseOrder', order.id, await buyer.ctx(), { limit: 100 });
+  expect(history.items.map(entry => entry.action)).toEqual(['approved', 'claim', 'unclaim', 'claim', 'approved']);
+});
+
+/** 转办在本例经理节点真实开放，原人不能用旧待办决定；最终采购命令使用接手人的身份。 */
+it('经理将采购审核转办给协作人，由接手人完成批准并留下转办和决定记录', async () => {
+  decision = 'pass'; const order = await submit(), engine = purchase.poRoute.engine(env.kernel), task = await taskOf(reviewer, order.id);
+  await engine.act(task.id, reviewer.id, env.tenantId, { action: 'transfer', targetUserId: specialistA.id, expectedRevision: task.revision, reason: '设备细节交专业人员审核' });
+  await expect(engine.decide(task.id, reviewer.id, env.tenantId, 'approved', undefined, task.revision)).rejects.toMatchObject({ code: 'NOT_FOUND' });
+  await approveBy(specialistA, order.id);
+  expect(await orderStatus(order.id)).toBe('approved');
+  const history = await engine.taskHistory('PurchaseOrder', order.id, await buyer.ctx());
+  expect(history.items.map(entry => entry.action)).toEqual(['transfer', 'approved']);
+  expect(await env.audit({ aggregateId: order.id, command: 'PurchaseOrder.approve', kind: 'write' })).toMatchObject([{ on_behalf_of: specialistA.id }]);
+});
+
+/** 委派用于协助核验，接手人只能完成归还；原经理作最终决定，避免把委派误作转办。 */
+it('经理委派采购材料核查，协作人归还后仍由经理正式批准', async () => {
+  decision = 'pass'; const order = await submit(), engine = purchase.poRoute.engine(env.kernel), task = await taskOf(reviewer, order.id);
+  await engine.act(task.id, reviewer.id, env.tenantId, { action: 'delegate', targetUserId: specialistA.id, expectedRevision: task.revision, reason: '请核对设备技术材料' });
+  const delegated = await taskOf(specialistA, order.id);
+  expect(delegated).toMatchObject({ ownerId: reviewer.id, delegation: 'pending' });
+  await expect(engine.decide(delegated.id, specialistA.id, env.tenantId, 'approved', undefined, delegated.revision)).rejects.toMatchObject({ code: 'INVALID_TRANSITION' });
+  await engine.act(delegated.id, specialistA.id, env.tenantId, { action: 'resolve', expectedRevision: delegated.revision, reason: '已核对技术材料并归还' });
+  expect(await orderStatus(order.id)).toBe('pending_approval');
+  await approveBy(reviewer, order.id);
+  expect(await orderStatus(order.id)).toBe('approved');
+  const history = await engine.taskHistory('PurchaseOrder', order.id, await buyer.ctx());
+  expect(history.items.map(entry => entry.action)).toEqual(['delegate', 'resolve', 'approved']);
+});
+
+/** 三种加签共用真实采购单：首票后都不能建锁，前/后置的等待状态必须按指定签序开放。 */
+it.each(['before', 'parallel', 'after'] as const)('经理节点 %s 加签要求原审批与附加意见都完成才批准采购', async placement => {
+  decision = 'pass'; const order = await submit(), engine = purchase.poRoute.engine(env.kernel), task = await taskOf(reviewer, order.id);
+  await engine.act(task.id, reviewer.id, env.tenantId, { action: 'addSign', userIds: [specialistA.id], placement, expectedRevision: task.revision, reason: '采购设备补充专业意见' });
+  if (placement === 'before') {
+    expect((await taskOf(reviewer, order.id, 'waiting')).id).toBe(task.id);
+    await approveBy(specialistA, order.id);
+  } else {
+    if (placement === 'after') {
+      const waiting = await taskOf(specialistA, order.id, 'waiting');
+      await expect(engine.decide(waiting.id, specialistA.id, env.tenantId, 'approved', undefined, waiting.revision)).rejects.toMatchObject({ code: 'INVALID_TRANSITION' });
+    }
+    await approveBy(reviewer, order.id);
+  }
+  expect(await orderStatus(order.id)).toBe('pending_approval');
+  expect(await env.query('select id from core.inventory_lock where id=$1', [order.id])).toHaveLength(0);
+  await approveBy(placement === 'before' ? reviewer : specialistA, order.id);
+  expect(await orderStatus(order.id)).toBe('approved');
+  expect((await env.query('select status from core.inventory_lock where id=$1', [order.id]))[0].status).toBe('held');
+});