@yss123/cage-cli 0.3.0 → 0.3.1

package/templates/blank/docs/examples/purchase-admin/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');
+});

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

@@ -1,7 +1,11 @@
-// 采购单声明集中列出状态、范围、不变量、命令和事件。
-// handler 只读声明的依赖；数据库写入、版本检查、审计由内核完成。
+/**
+ * 采购单声明集中列出申请材料、专业复核名单、状态、范围、命令和事件，由 API、worker 和生成器统一消费。
+ * 草稿可编辑专业复核名单，提交重新核对协作名录；handler 仅读取声明依赖，数据库写入、版本与审计由内核完成。
+ * 审批结论仍以 process 命令执行职责分离、额度和库存检查；选入名录或路由不授予权限。
+ */
 import {
   aggregate,
+  bool,
   ceiling,
   command,
   emit,
@@ -17,9 +21,11 @@ import {
   sod,
   states,
   text,
+  type ReadRepo,
 } from '@yss123/cage-kernel';
 import { z } from 'zod';
 import { Inventory } from '../inventory/index.js';
+import { ApprovalMember } from './approval-members.js';
 
 /**
  * 采购单生命周期：草稿提交后等待审批，通过后等待外部收货；退回修改重新进入草稿。
@@ -46,6 +52,10 @@ export const PurchaseOrder = aggregate('PurchaseOrder', {
     amount: money(),
     /** 可为空的用途说明；创建可先存草稿，AI 预审会判断是否足以支撑审批。 */
     reason: text(2000).optional(),
+    /** 是否增加专业会签；旧记录 null/缺省按 false，不改变已经启动的审批实例。 */
+    needsSpecialistReview: bool().optional(),
+    /** 提交快照的专业复核用户 UUID；旧记录可为空，启用复核时必须为 1–5 个不同且非创建人的有效名录用户。 */
+    reviewerIds: list(id()).optional(),
     /** 申请明细快照：sku 为物料编码，qty 为整数件数；输入额外要求每行数量为正。 */
     items: list({ sku: text(64), qty: int() }),
     /** ERP 成功响应后回填的外部单号，尚未同步时为空；不作为采购单生命周期状态。 */
@@ -76,6 +86,22 @@ export const OrderReceived = event('OrderReceived', { orderId: id() });
 /** 命令输入比持久化 int 原语更具体：至少一行且每行数量为正，避免零数量申请进入审批。 */
 const itemsInput = z.array(z.object({ sku: z.string(), qty: z.number().int().positive() })).min(1);
 
+/**
+ * 在设置和提交时核对专业复核名单，防止界面被绕过、名录退役或重复账号减少会签人数。
+ * disabled/范围/批准能力仍由审批运行时处理；此处只按当前命令声明的名录读依赖判断业务成员 active。
+ * 关闭专业复核必须传空名单；旧记录 null 等价 false/[]。最多五人使逐人查询有明确上限。
+ */
+async function validateReviewers(needsReview: boolean | null | undefined, ids: string[] | null | undefined, creator: string, members: ReadRepo<typeof ApprovalMember>) {
+  const selected = ids ?? [];
+  if (!needsReview) return selected.length ? fail('REVIEWERS_NOT_REQUIRED', '未启用专业复核时请清空复核人员') : undefined;
+  if (selected.length < 1 || selected.length > 5) return fail('REVIEWERS_REQUIRED', '专业复核需选择 1–5 位协作人');
+  if (new Set(selected).size !== selected.length) return fail('DUPLICATE_REVIEWERS', '同一人不能重复承担专业会签');
+  if (selected.includes(creator)) return fail('REVIEWER_IS_APPLICANT', '提单人不能担任本单专业复核人');
+  for (const userId of selected) {
+    if (!await members.findOne({ userId, status: 'active' })) return fail('REVIEWER_UNAVAILABLE', '所选专业复核人不在有效协作名录中');
+  }
+}
+
 /**
  * 保存草稿；金额格式、字段长度和不变量由内核随后统一校验，handler 无额外副作用。
  * deptId 可指定但仍须满足创建范围；attachments 为已完成上传 ID，省略时初始化为空集合。
@@ -89,10 +115,28 @@ export const create = command(PurchaseOrder, {
     items: itemsInput,
     supplierPhone: z.string().optional(),
     reason: z.string().max(2000).optional(),
+    needsSpecialistReview: z.boolean().optional(),
+    reviewerIds: z.array(z.string().uuid()).max(5).optional(),
     deptId: z.string().uuid().optional(),
     attachments: z.array(z.string().uuid()).max(10).optional(),
   }),
-  handler: (o) => o,
+  // 草稿允许先保存未选完的复核需求；提交才要求完整名单，新记录统一 false/[]，旧记录兼容 null。
+  handler: (o) => ({ ...o, needsSpecialistReview: o.needsSpecialistReview ?? false, reviewerIds: o.reviewerIds ?? [] }),
+});
+
+/**
+ * 在 draft 中调整本单专业复核需求和名单；需要 PurchaseOrder.setReviewers，不能直接修改待审批快照。
+ * 输入保存前核对 1–5 位不同且非提单人的 active 名录成员；关闭时用 false/[]，失败整次回滚。
+ * 提交还会重新查询名录，以拒绝保存后退役的成员；名录不授予对单据的读取、批准能力或额度。
+ */
+export const setReviewers = command(PurchaseOrder, {
+  name: 'setReviewers', description: '设置采购单专业复核需求和人员', from: 'draft', to: null,
+  input: z.object({ id: z.string().uuid(), needsSpecialistReview: z.boolean(), reviewerIds: z.array(z.string().uuid()).max(5) }),
+  reads: { members: ApprovalMember },
+  handler: async (draft, input, { members }) => {
+    const invalid = await validateReviewers(input.needsSpecialistReview, input.reviewerIds, draft.createdBy, members);
+    return invalid ?? { needsSpecialistReview: input.needsSpecialistReview, reviewerIds: input.reviewerIds };
+  },
 });
 
 // 退回后的说明只在草稿状态修改，保留提交时的版本校验和原始审计。
@@ -119,12 +163,19 @@ export const setAttachments = command(PurchaseOrder, {
   handler: (_draft, input) => ({ attachments: input.attachments }),
 });
 
-/** 提交只改变状态并记录 OrderSubmitted；审批实例由事件消费启动，HTTP 成功不代表审批已完成。 */
+/**
+ * 提交前重查专业复核名单，避免草稿保存后退役的成员进入新流程；缺省旧字段按无需复核处理。
+ * 成功只改变状态并记录 OrderSubmitted，实例由 worker 消费后创建；HTTP 成功不表示审批完成。
+ */
 export const submit = command(PurchaseOrder, {
   from: 'draft',
   to: 'pending_approval',
   emits: [OrderSubmitted],
-  handler: (o) => (o.items.length === 0 ? fail('NO_ITEMS') : o),
+  reads: { members: ApprovalMember },
+  handler: async (o, _input, { members }) => {
+    if (o.items.length === 0) return fail('NO_ITEMS');
+    return await validateReviewers(o.needsSpecialistReview, o.reviewerIds, o.createdBy, members) ?? o;
+  },
 });
 
 /**

package/templates/blank/package.json

@@ -11,9 +11,9 @@
     "build:app": "pnpm --filter @app/domain build && pnpm --filter @app/api build && pnpm --filter @app/web build"
   },
   "devDependencies": {
-    "@yss123/cage-cli": "0.3.0",
-    "@yss123/cage-testkit": "0.3.0",
-    "@yss123/cage-lint": "0.3.0",
+    "@yss123/cage-cli": "0.3.1",
+    "@yss123/cage-testkit": "0.3.1",
+    "@yss123/cage-lint": "0.3.1",
     "@types/node": "^24.3.0",
     "typescript": "~5.9.3",
     "vitest": "^4.1.12",

package/templates/blank/packages/contracts/package.json

@@ -10,7 +10,7 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@yss123/cage-client": "0.3.0",
+    "@yss123/cage-client": "0.3.1",
     "zod": "^4.1.5"
   }
 }

package/templates/blank/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"
   }
 }