@yss123/cage-cli 0.3.0 → 0.3.2

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.2",
+    "@yss123/cage-testkit": "0.3.2",
+    "@yss123/cage-lint": "0.3.2",
     "@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.2",
     "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.2",
+    "@yss123/cage-admin": "0.3.2",
+    "@yss123/cage-approval": "0.3.2",
+    "@yss123/cage-connectors": "0.3.2",
+    "@yss123/cage-ai": "0.3.2",
     "zod": "^4.1.5"
   }
 }

package/templates/app/docs/ai/README.md

@@ -1,98 +0,0 @@
-# 业务开发指南（给 Codex 等编程工具）
-
-这是 `create-cage-app` 产物自带的业务开发资料。目标是让 Codex 等编程工具只读当前项目，就能增加业务对象、操作、审批、报表和页面。先读根目录 `AGENTS.md`，再按任务定位本页资料；无需另行克隆 Cage 框架仓库。
-
-## 先认识当前应用
-
-| 目录 | 开发业务时放什么 |
-| --- | --- |
-| `packages/domain/src/modules/<业务>` | 按业务集中聚合、命令、事件、审批、查询与任务；跨模块反应放 workflows，外部协议放 integrations |
-| `packages/contracts/src/aggregates`、`queries` | 按聚合目录生成 API 与类型；通过根 @app/contracts 使用，通过 gen 更新 |
-| `apps/api/src` | API 与 worker 的薄启动入口；普通业务不在这里写路由 |
-| `apps/web/src/app`、`modules`、`shared` | 应用组合 / 业务页面与交互 / 无具体业务归属的共用代码 |
-| `db/migrations` | 生成后审查的迁移；更新已有数据库中的表 |
-| `.env` / `.env.example` | 本机配置 / 不含真实凭证的配置说明 |
-| `docs/ai`、`docs/errors` | 业务开发方法与错误排查 |
-
-下文路径均相对**应用根目录**，即生成项目的 `package.json` 所在目录。框架包使用 `@yss123/cage-*`，作为依赖安装；当前项目不应复制或重新实现这些包。框架维护者在源码仓库读本页时，应用根目录为 `examples/purchase-admin`。
-
-创建时可选 `blank`（空白业务项目）或 `purchase`（采购示例项目）。空白项目只有组织基础模型，新增客户业务写入根目录的 `packages/domain/src`；采购参考源码放在 `docs/examples/purchase-admin`，不参与注册、编译或建表。阅读本指南中的采购路径时，空白项目在该参考目录下查找，采购项目直接在应用根目录查找。先读本项目 AGENTS.md 的模板说明，不能把参考代码误当成已运行的业务。
-
-## 推荐阅读顺序
-
-| 顺序 | 资料 | 读完应能回答 |
-| --- | --- | --- |
-| 1 | [架构与执行模型](architecture.md) | 聚合是什么？为什么写入必须走命令？数据库由谁连接？ |
-| 2 | [工程目录与代码组织](project-structure.md) | 新业务放哪里？页面如何拆分？哪些依赖会被门禁阻止？ |
-| 3 | [原语与最小业务](primitives.md) | 如何新增字段、CRUD 命令、读依赖、事件和查询？ |
-| 编码必读 | [详细中文注释规范](commenting.md) | 如何说明文件职责、API、字段、关键流程、权限/事务与失败边界，并同步维护注释？ |
-| 开发前 | [本体查询与 AI 上下文](ontology-context.md) | 按需求查哪些代码？为什么关联？候选、证据与子图边界怎么判断？ |
-| 开发与排错 | [能力发现与状态诊断](diagnostics.md) | 公开 API 有什么？注册/契约/进程哪里过期？如何查执行时间线和授权拒绝？ |
-| 按需 | [对象关系](relations.md) | 如何在 fields 中声明一对一、一对多、多对多，修改关联并分页读取？ |
-| 前端必读 | [业务路由与浏览器验收](routing.md) | 列表/详情如何获得独立 URL？登录回跳、404、/admin 和部署回退怎样验收？ |
-| 原生 AI | [智能助理与 AI 审批](intelligence.md) | 如何启用后端、配置三态审核、生成工具、传入页面快照和接入 SDK？ |
-| 4 | [标准采购范例导读](purchase-example.md) | 一次提交如何进入审批、锁库存、推 ERP、释放资源？ |
-| 5 | [开发步骤](workflow.md) | 改哪个文件？运行哪些命令？检查结果在哪里？ |
-| 6 | [业务任务配方](recipes.md) | 如何从采购演示换成自己的业务？常见需求如何交给 AI？ |
-| 7 | [业务页导入导出](transfers.md) | 如何提交任务、准备 CSV、查询状态、下载和展示报告？ |
-| 8 | [排错方法](troubleshooting.md)、[错误码册](../errors/README.md) | 如何区分配置、权限、业务失败和异步死信？ |
-| 按需 | [文件字段与断点续传](files.md) | 私有上传、分片恢复、命令绑定、下载授权和存储部署 |
-
-第一次先读架构、目录规范和原语，再沿范例读代码。接到业务需求后先运行 `pnpm exec cage context "需求关键词"`，确认候选入口，再按源码位置阅读对应实现。
-
-框架源码与脚手架应用都要求详细中文注释。新建或修改代码时按[注释规范](commenting.md)同步说明文件职责与调用链、导出 API/类型字段、组件/hooks 和关键流程的“做什么、为什么、怎么做、边界”；修改既有行为时连同相关上下游说明一起更新。注释属于交付内容，不能用“代码自解释”免除，也不能以逐行翻译或注释字数代替质量。
-
-不确定框架支持什么时先用 `pnpm exec cage capabilities 关键词 --format json` 查看当前版本公开签名；功能未生效时用 `pnpm exec cage doctor` 区分注册、生成、构建、迁移、授权和实际进程。未检查项为 `unknown`，不能作为验证通过。
-
-遇到 AI 审批、业务助理、随页助理、模型管理、性格或 Responses 需求，先读[原生智能化指南](intelligence.md)。这些是框架可选能力：后端循环、工具、会话与偏好记忆、HTTP 和 SDK 由框架提供；应用配置声明、策略、授权、页面快照及界面。入口不要求每次加载整份本体或全部指南，按本次任务读取相关章节即可。
-
-## 按任务找入口
-
-| 用户需求 | 优先修改 | 需要一起考虑 |
-| --- | --- | --- |
-| 增加业务对象、字段 | `packages/domain/src/modules/<业务>` | 模块公开入口、范围字段、不变量、契约、迁移、角色授权、图谱中文名 |
-| 增加对象关联 | `fields` 的 ref / hasMany / manyToMany；见[关系指南](relations.md) | 归属命令、双侧权限与范围、目标分页、迁移；纯关联不手写中间表聚合 |
-| 增加操作按钮 | 领域命令 + `apps/web/src/modules/<业务>` | 状态迁移、调用身份、错误展示、提交幂等键 |
-| 增加列表、详情或新页面 | 模块 pages + app 路由表 | URL、查询条件、深链接、刷新、前进后退、登录回跳；见[路由指南](routing.md) |
-| 增加报表 | 所属领域模块 `queries.ts` | `reads`、`safe.*`、参数化、调用人 read 权限 |
-| 修改审批顺序/条件/选人 | 所属领域模块 `approvals.ts` | `routable`、角色/负责人数据、结论命令约束 |
-| AI 预审、退回修改、转人工 | 现有 `step` 的 `kind: 'ai'` + `approval` 绑定 | 策略、取证字段/查询、`automatedBy` 角色、结论命令及 `handoff`；见[智能化指南](intelligence.md) |
-| 业务助理、随页悬浮窗 | domain 导出 `ai()`；页面接 `useAssistant` 与 `useAiPageContext` | 业务权限、页面快照、流式 Markdown、写入确认；界面由应用实现 |
-| 模型动态配置、Responses、性格 | `managedModel` 与框架 Admin 页面 | 部署加密密钥、管理权限、实际网关能力、性格仅影响表达 |
-| 取消后释放占用 | `workflows/<相关业务>.ts` + 领域事件/命令 | 所有离开持有状态的路径、同事务/异步选择 |
-| 接 ERP 或其他系统 | `integrations/<系统名>.ts` | schema、密钥名、白名单、幂等、回调验签、重试 |
-| 业务页导入/导出 | 业务前端调用已有接口 | 任务状态、worker、权限、导入目标命令；不固定到系统管理页 |
-| 文件上传/业务附件 | file/files 字段 + 用户命令 + 客户端上传任务 | 断点续传、当前权限、命令绑定、私有存储及清理；见[文件指南](files.md) |
-| 新业务没出现在图或 API | domain 统一入口 | 顶层 `export const`、导出名唯一、入口 re-export |
-| 框架无法表达业务 | 先核对公开导出与范例 | 说明能力缺口；不要编造 API 或把业务分支塞进内核 |
-
-## 三份协作材料各管什么
-
-- **AGENTS.md** 是工作入口：必守边界、目录、顺序和验证要求。`<!-- cage:begin ... -->` 到 `<!-- cage:end -->` 为框架托管区，`cage sync` 更新它；项目自己的规则放在外面。
-- **标准范例** 是可运行证据：采购模板包含完整运行链路，空白模板保留离线参考源码。按需学习其中模式，客户业务仍写在本项目自己的 domain 和页面中。
-- **错误码册** 是诊断索引：按真实错误码查位置、触发原因、修复步骤和正反例；不要靠放开权限或关闭门禁“修好”报错。
-
-`docs/ai` 与 `docs/errors` 已放入分发模板，创建项目时一起复制，可离线阅读。框架仓库中的标准范例使用根目录的规范文档，资料位置由应用 AGENTS.md 指明。
-
-## 当前实现边界
-
-以下区分可避免 agent 把方案中的愿景写成不存在的功能。
-
-| 已有能力 | 使用边界 |
-| --- | --- |
-| 真实 PostgreSQL 连接、分账号、表结构迁移 | 连接已有数据库；`init` 不建库；不会自动识别并接管任意历史表 |
-| 聚合/命令、能力与范围、掩码、审计、outbox、worker | handler 不做数据库/网络 IO；生产角色不会自动拿到新能力 |
-| fields 中的 ref / hasMany / manyToMany | hasMany 为只读反查；manyToMany 自动中间表并随主对象事务写入，公开读取独立分页；双向集合不会自动互为镜像 |
-| 本体抽取、中文检索/节点/路径/AI 上下文、图规则、图谱、生成、影响分析与门禁 | 上下文注明证据、源码和覆盖边界；名称与测试匹配是候选线索，不能证明任意 JS 正确；跳过用例仍需补足 |
-| 有界集合 reactionEach、显式步骤 order | 稳定唯一键排序后串行调用目标命令；同事务整体回滚，异步链按 outbox 恢复；不是并行写表接口 |
-| capabilities、doctor、timeline、explain、snapshot | 实际运行诊断需要受控会话与权限；未取得的证据为 unknown，授权解释不执行 handler |
-| 代码审批路由与适配接口 | 顺序步骤、条件步骤、步骤内任一/全部审批；没有通用可视化流程设计器、任意 JS 选人、转签/加签 API |
-| 原生 AI 审批与领域助理 | 现有 `step` 支持 `kind: 'ai'`；三态审核、自动工具、会话及偏好记忆可复用；需显式启用、授权并做模型质量验收 |
-| Admin 模型与性格、助理 SDK | 动态模型连接和性格管理；Chat Completions / Responses 兼容性以实际服务为准；SDK 提供流式状态与页面快照，悬浮窗和 Markdown 由应用实现 |
-| 连接器 fake、出站、入站验签、同步记录 | fake 不等于真实 ERP 联调，也不等于完整请求录制/回放平台 |
-| 异步 CSV 导入/导出接口与客户端任务查询 | 界面由业务项目决定；导出结果不是可直接回导的命令输入模板 |
-| 私有文件字段、流式分片上传、暂停与续传、范围下载 | 默认本地存储，提供对象存储适配接口；尚无内置 S3/OSS、签名直传、病毒扫描及文件共享 |
-| 组织模型、系统管理界面 | 暂无移动部门（改上级）的完整支持、菜单配置页 |
-| 库存锁采购范例 | 演示资源生命周期；不是仓库级并发库存扣减、退货或 ERP 撤销补偿系统 |
-
-文档与实现冲突时，以当前代码和检查结果为依据，指出冲突并修正文档；不要默默扩展公开 API。规划、代码存在、构建通过、真实联调通过是不同状态，交付时分别说明。

package/templates/blank/docs/ai/README.md

@@ -1,98 +0,0 @@
-# 业务开发指南（给 Codex 等编程工具）
-
-这是 `create-cage-app` 产物自带的业务开发资料。目标是让 Codex 等编程工具只读当前项目，就能增加业务对象、操作、审批、报表和页面。先读根目录 `AGENTS.md`，再按任务定位本页资料；无需另行克隆 Cage 框架仓库。
-
-## 先认识当前应用
-
-| 目录 | 开发业务时放什么 |
-| --- | --- |
-| `packages/domain/src/modules/<业务>` | 按业务集中聚合、命令、事件、审批、查询与任务；跨模块反应放 workflows，外部协议放 integrations |
-| `packages/contracts/src/aggregates`、`queries` | 按聚合目录生成 API 与类型；通过根 @app/contracts 使用，通过 gen 更新 |
-| `apps/api/src` | API 与 worker 的薄启动入口；普通业务不在这里写路由 |
-| `apps/web/src/app`、`modules`、`shared` | 应用组合 / 业务页面与交互 / 无具体业务归属的共用代码 |
-| `db/migrations` | 生成后审查的迁移；更新已有数据库中的表 |
-| `.env` / `.env.example` | 本机配置 / 不含真实凭证的配置说明 |
-| `docs/ai`、`docs/errors` | 业务开发方法与错误排查 |
-
-下文路径均相对**应用根目录**，即生成项目的 `package.json` 所在目录。框架包使用 `@yss123/cage-*`，作为依赖安装；当前项目不应复制或重新实现这些包。框架维护者在源码仓库读本页时，应用根目录为 `examples/purchase-admin`。
-
-创建时可选 `blank`（空白业务项目）或 `purchase`（采购示例项目）。空白项目只有组织基础模型，新增客户业务写入根目录的 `packages/domain/src`；采购参考源码放在 `docs/examples/purchase-admin`，不参与注册、编译或建表。阅读本指南中的采购路径时，空白项目在该参考目录下查找，采购项目直接在应用根目录查找。先读本项目 AGENTS.md 的模板说明，不能把参考代码误当成已运行的业务。
-
-## 推荐阅读顺序
-
-| 顺序 | 资料 | 读完应能回答 |
-| --- | --- | --- |
-| 1 | [架构与执行模型](architecture.md) | 聚合是什么？为什么写入必须走命令？数据库由谁连接？ |
-| 2 | [工程目录与代码组织](project-structure.md) | 新业务放哪里？页面如何拆分？哪些依赖会被门禁阻止？ |
-| 3 | [原语与最小业务](primitives.md) | 如何新增字段、CRUD 命令、读依赖、事件和查询？ |
-| 编码必读 | [详细中文注释规范](commenting.md) | 如何说明文件职责、API、字段、关键流程、权限/事务与失败边界，并同步维护注释？ |
-| 开发前 | [本体查询与 AI 上下文](ontology-context.md) | 按需求查哪些代码？为什么关联？候选、证据与子图边界怎么判断？ |
-| 开发与排错 | [能力发现与状态诊断](diagnostics.md) | 公开 API 有什么？注册/契约/进程哪里过期？如何查执行时间线和授权拒绝？ |
-| 按需 | [对象关系](relations.md) | 如何在 fields 中声明一对一、一对多、多对多，修改关联并分页读取？ |
-| 前端必读 | [业务路由与浏览器验收](routing.md) | 列表/详情如何获得独立 URL？登录回跳、404、/admin 和部署回退怎样验收？ |
-| 原生 AI | [智能助理与 AI 审批](intelligence.md) | 如何启用后端、配置三态审核、生成工具、传入页面快照和接入 SDK？ |
-| 4 | [标准采购范例导读](purchase-example.md) | 一次提交如何进入审批、锁库存、推 ERP、释放资源？ |
-| 5 | [开发步骤](workflow.md) | 改哪个文件？运行哪些命令？检查结果在哪里？ |
-| 6 | [业务任务配方](recipes.md) | 如何从采购演示换成自己的业务？常见需求如何交给 AI？ |
-| 7 | [业务页导入导出](transfers.md) | 如何提交任务、准备 CSV、查询状态、下载和展示报告？ |
-| 8 | [排错方法](troubleshooting.md)、[错误码册](../errors/README.md) | 如何区分配置、权限、业务失败和异步死信？ |
-| 按需 | [文件字段与断点续传](files.md) | 私有上传、分片恢复、命令绑定、下载授权和存储部署 |
-
-第一次先读架构、目录规范和原语，再沿范例读代码。接到业务需求后先运行 `pnpm exec cage context "需求关键词"`，确认候选入口，再按源码位置阅读对应实现。
-
-框架源码与脚手架应用都要求详细中文注释。新建或修改代码时按[注释规范](commenting.md)同步说明文件职责与调用链、导出 API/类型字段、组件/hooks 和关键流程的“做什么、为什么、怎么做、边界”；修改既有行为时连同相关上下游说明一起更新。注释属于交付内容，不能用“代码自解释”免除，也不能以逐行翻译或注释字数代替质量。
-
-不确定框架支持什么时先用 `pnpm exec cage capabilities 关键词 --format json` 查看当前版本公开签名；功能未生效时用 `pnpm exec cage doctor` 区分注册、生成、构建、迁移、授权和实际进程。未检查项为 `unknown`，不能作为验证通过。
-
-遇到 AI 审批、业务助理、随页助理、模型管理、性格或 Responses 需求，先读[原生智能化指南](intelligence.md)。这些是框架可选能力：后端循环、工具、会话与偏好记忆、HTTP 和 SDK 由框架提供；应用配置声明、策略、授权、页面快照及界面。入口不要求每次加载整份本体或全部指南，按本次任务读取相关章节即可。
-
-## 按任务找入口
-
-| 用户需求 | 优先修改 | 需要一起考虑 |
-| --- | --- | --- |
-| 增加业务对象、字段 | `packages/domain/src/modules/<业务>` | 模块公开入口、范围字段、不变量、契约、迁移、角色授权、图谱中文名 |
-| 增加对象关联 | `fields` 的 ref / hasMany / manyToMany；见[关系指南](relations.md) | 归属命令、双侧权限与范围、目标分页、迁移；纯关联不手写中间表聚合 |
-| 增加操作按钮 | 领域命令 + `apps/web/src/modules/<业务>` | 状态迁移、调用身份、错误展示、提交幂等键 |
-| 增加列表、详情或新页面 | 模块 pages + app 路由表 | URL、查询条件、深链接、刷新、前进后退、登录回跳；见[路由指南](routing.md) |
-| 增加报表 | 所属领域模块 `queries.ts` | `reads`、`safe.*`、参数化、调用人 read 权限 |
-| 修改审批顺序/条件/选人 | 所属领域模块 `approvals.ts` | `routable`、角色/负责人数据、结论命令约束 |
-| AI 预审、退回修改、转人工 | 现有 `step` 的 `kind: 'ai'` + `approval` 绑定 | 策略、取证字段/查询、`automatedBy` 角色、结论命令及 `handoff`；见[智能化指南](intelligence.md) |
-| 业务助理、随页悬浮窗 | domain 导出 `ai()`；页面接 `useAssistant` 与 `useAiPageContext` | 业务权限、页面快照、流式 Markdown、写入确认；界面由应用实现 |
-| 模型动态配置、Responses、性格 | `managedModel` 与框架 Admin 页面 | 部署加密密钥、管理权限、实际网关能力、性格仅影响表达 |
-| 取消后释放占用 | `workflows/<相关业务>.ts` + 领域事件/命令 | 所有离开持有状态的路径、同事务/异步选择 |
-| 接 ERP 或其他系统 | `integrations/<系统名>.ts` | schema、密钥名、白名单、幂等、回调验签、重试 |
-| 业务页导入/导出 | 业务前端调用已有接口 | 任务状态、worker、权限、导入目标命令；不固定到系统管理页 |
-| 文件上传/业务附件 | file/files 字段 + 用户命令 + 客户端上传任务 | 断点续传、当前权限、命令绑定、私有存储及清理；见[文件指南](files.md) |
-| 新业务没出现在图或 API | domain 统一入口 | 顶层 `export const`、导出名唯一、入口 re-export |
-| 框架无法表达业务 | 先核对公开导出与范例 | 说明能力缺口；不要编造 API 或把业务分支塞进内核 |
-
-## 三份协作材料各管什么
-
-- **AGENTS.md** 是工作入口：必守边界、目录、顺序和验证要求。`<!-- cage:begin ... -->` 到 `<!-- cage:end -->` 为框架托管区，`cage sync` 更新它；项目自己的规则放在外面。
-- **标准范例** 是可运行证据：采购模板包含完整运行链路，空白模板保留离线参考源码。按需学习其中模式，客户业务仍写在本项目自己的 domain 和页面中。
-- **错误码册** 是诊断索引：按真实错误码查位置、触发原因、修复步骤和正反例；不要靠放开权限或关闭门禁“修好”报错。
-
-`docs/ai` 与 `docs/errors` 已放入分发模板，创建项目时一起复制，可离线阅读。框架仓库中的标准范例使用根目录的规范文档，资料位置由应用 AGENTS.md 指明。
-
-## 当前实现边界
-
-以下区分可避免 agent 把方案中的愿景写成不存在的功能。
-
-| 已有能力 | 使用边界 |
-| --- | --- |
-| 真实 PostgreSQL 连接、分账号、表结构迁移 | 连接已有数据库；`init` 不建库；不会自动识别并接管任意历史表 |
-| 聚合/命令、能力与范围、掩码、审计、outbox、worker | handler 不做数据库/网络 IO；生产角色不会自动拿到新能力 |
-| fields 中的 ref / hasMany / manyToMany | hasMany 为只读反查；manyToMany 自动中间表并随主对象事务写入，公开读取独立分页；双向集合不会自动互为镜像 |
-| 本体抽取、中文检索/节点/路径/AI 上下文、图规则、图谱、生成、影响分析与门禁 | 上下文注明证据、源码和覆盖边界；名称与测试匹配是候选线索，不能证明任意 JS 正确；跳过用例仍需补足 |
-| 有界集合 reactionEach、显式步骤 order | 稳定唯一键排序后串行调用目标命令；同事务整体回滚，异步链按 outbox 恢复；不是并行写表接口 |
-| capabilities、doctor、timeline、explain、snapshot | 实际运行诊断需要受控会话与权限；未取得的证据为 unknown，授权解释不执行 handler |
-| 代码审批路由与适配接口 | 顺序步骤、条件步骤、步骤内任一/全部审批；没有通用可视化流程设计器、任意 JS 选人、转签/加签 API |
-| 原生 AI 审批与领域助理 | 现有 `step` 支持 `kind: 'ai'`；三态审核、自动工具、会话及偏好记忆可复用；需显式启用、授权并做模型质量验收 |
-| Admin 模型与性格、助理 SDK | 动态模型连接和性格管理；Chat Completions / Responses 兼容性以实际服务为准；SDK 提供流式状态与页面快照，悬浮窗和 Markdown 由应用实现 |
-| 连接器 fake、出站、入站验签、同步记录 | fake 不等于真实 ERP 联调，也不等于完整请求录制/回放平台 |
-| 异步 CSV 导入/导出接口与客户端任务查询 | 界面由业务项目决定；导出结果不是可直接回导的命令输入模板 |
-| 私有文件字段、流式分片上传、暂停与续传、范围下载 | 默认本地存储，提供对象存储适配接口；尚无内置 S3/OSS、签名直传、病毒扫描及文件共享 |
-| 组织模型、系统管理界面 | 暂无移动部门（改上级）的完整支持、菜单配置页 |
-| 库存锁采购范例 | 演示资源生命周期；不是仓库级并发库存扣减、退货或 ERP 撤销补偿系统 |
-
-文档与实现冲突时，以当前代码和检查结果为依据，指出冲突并修正文档；不要默默扩展公开 API。规划、代码存在、构建通过、真实联调通过是不同状态，交付时分别说明。