@yss123/cage-cli 0.3.0 → 0.3.1

package/templates/app/apps/web/src/modules/approval/pages/approval-tasks-page.tsx

@@ -1,72 +1,104 @@
 /**
- * 个人审批待办页，展示服务端分配的任务并调用标准审批接口提交结论。
- * 通过 app 注入业务详情链接，避免审批模块直接依赖采购页面文件。
+ * 审批收件箱使用 URL 的 view 切换本人、可领取和等待加签任务，刷新/前进后退保留视图。
+ * 通过 app 注入详情链接，界面调用客户端完成领取、释放、人员流转与决定；候选身份和版本仍由服务端校验。
+ * 原因是行内临时草稿，动作成功后由 useCommand 失效查询并重读；waiting 仅供查看，不显示决定入口。
  */
-// 审批待办独立成页；结论调用框架审批接口，领域约束仍在后端执行。
+import { useState } from 'react';
 import { client } from '@app/contracts';
-import { Link } from 'react-router-dom';
-import { useCommand } from '../../../shared/hooks/use-command';
+import type { ApprovalTask } from '@yss123/cage-client';
+import { Link, useSearchParams } from 'react-router-dom';
+import { useCommand, type RunCommand } from '../../../shared/hooks/use-command';
 import { Notice } from '../../../shared/ui/notice';
 import { PageHeading } from '../../../shared/ui/page-heading';
 import { useApprovalTasks } from '../hooks/use-approval-tasks';
 import { AssistantPage } from '../../../shared/ui/assistant-scope';
+import './approval-tasks.css';
+import { TaskOperationDialog, type PersonnelOperation } from '../components/task-operation-dialog';
+
+/** 三种任务视图进入查询参数；只有 pending 会计入原有导航待办数。 */
+const views = { pending: '待我处理', candidates: '可领取', waiting: '等待加签' } as const;
 
 /**
- * 查询待办并区分加载、失败与已清空状态；按钮使用 useCommand 共享忙碌及消息反馈。
- * @param orderUrl 由 app 将 businessKey 转为采购详情 URL 的函数。
- * 通过/驳回/退回对应不同后端流程，页面不直接更新单据状态；成功后刷新查询取得真实任务变化。
+ * 为一项任务展示顺序、意见和合法阶段入口。busy 来自整页，提交时防止同页重复操作。
+ * 领取/释放/委派归还必须人工填写原因；决定意见可选。每次都提交当前 revision，失败保留草稿供核对。
+ * @param task 服务端安全摘要；assigneeId 为空表示尚未领取，不可直接批准。
+ * @param orderUrl app 组合的详情 URL 生成器，不访问其他业务模块内部。
+ * @param run 统一结果/缓存处理；此组件不乐观修改任务或赋予权限。
+ */
+function TaskRow({ task, orderUrl, busy, run }: { task: ApprovalTask; orderUrl: (id: string) => string; busy: boolean; run: RunCommand }) {
+  const [reason, setReason] = useState('');
+  const [operation, setOperation] = useState<PersonnelOperation | null>(null);
+  const waiting = task.status === 'waiting';
+  const candidate = task.assigneeId === null;
+  const delegated = task.delegation === 'pending';
+  const manage = (action: 'claim' | 'unclaim' | 'resolve', success: string) => run(
+    () => client.approvalTaskAction(task.id, { action, expectedRevision: task.revision, reason }), success);
+  const position = task.signPosition === 'before' ? '前签' : task.signPosition === 'after' ? '后签' : task.taskKind === 'additional' ? '并行加签' : null;
+  return (
+    <div className="task">
+      <div className="approval-task-summary">
+        <h3>{task.title}{position && <small className="muted"> · {position}</small>}</h3>
+        {!!task.branchPath?.length && <p className="muted">{task.branchPath.map(part => `${part.parallel} · ${part.branch}`).join(' / ')}</p>}
+        <p className="mono muted">PO-{task.businessKey.slice(0, 8).toUpperCase()}</p>
+        <p className="muted">金额 ¥{String(task.vars.amount ?? '—')}{task.vars.needsSpecialistReview === true ? ' · 含专业会签' : ''}</p>
+        <p className="muted">{waiting ? '前置签署完成后恢复处理' : candidate ? '领取后由你负责处理' : delegated ? '受托处理中，请先归还原审批人' : '请核对单据后提交意见'}</p>
+      </div>
+      <div className="approval-task-controls">
+        <div className="actions">
+          <Link className="route-link" to={orderUrl(task.businessKey)}>查看采购单 ↗</Link>
+          {!waiting && <input aria-label={`${task.title}处理意见`} placeholder={candidate || delegated ? '填写操作原因（必填）' : '审批意见；释放任务时必填'}
+            maxLength={1000} value={reason} disabled={busy} onChange={event => setReason(event.target.value)} />}
+        </div>
+        {!waiting && <div className="actions">
+          {candidate ? <button className="primary" disabled={busy || !reason.trim()} onClick={() => void manage('claim', '已领取，请在待我处理中继续')}>领取任务</button>
+            : delegated ? <button disabled={busy || !reason.trim()} onClick={() => void manage('resolve', '已归还原审批人')}>归还审批人</button>
+            : <>
+              {task.assignment === 'candidate' && <button disabled={busy || !reason.trim()} onClick={() => void manage('unclaim', '已释放到候选池')}>释放任务</button>}
+              <button disabled={busy} onClick={() => void run(() => client.decideApprovalTask(task.id, 'reject', { expectedRevision: task.revision, comment: reason }), '已驳回')}>驳回</button>
+              <button disabled={busy} onClick={() => void run(() => client.decideApprovalTask(task.id, 'return', { expectedRevision: task.revision, comment: reason }), '已退回修改')}>退回修改</button>
+              <button disabled={busy} className="primary" onClick={() => void run(() => client.decideApprovalTask(task.id, 'approve', { expectedRevision: task.revision, comment: reason }), '已通过审批')}>通过审批</button>
+              {task.actions.transfer && <button disabled={busy} onClick={() => setOperation('transfer')}>转办</button>}
+              {task.actions.delegate && <button disabled={busy} onClick={() => setOperation('delegate')}>委派</button>}
+              {task.actions.addSign && task.taskKind === 'original' && task.signPositions.map(position => <button key={position} disabled={busy}
+                onClick={() => setOperation(position)}>{position === 'before' ? '前加签' : position === 'after' ? '后加签' : '并行加签'}</button>)}
+            </>}
+        </div>}
+      </div>
+      {operation && <TaskOperationDialog task={task} operation={operation} close={() => setOperation(null)} />}
+    </div>
+  );
+}
+
+/**
+ * 读取当前视图并区分加载、错误与空结果；URL 中未知 view 按默认待办读取，不制造无效请求。
+ * @param orderUrl 由 app 将业务主键转为采购详情地址；组件只改变 view 参数，保留其他 URL 参数。
+ * 人员操作使用业务协作名录，不读取完整组织用户；动作政策与签序来自实例快照，不按最新声明猜测在途权限。
  */
 export function ApprovalTasksPage({ orderUrl }: { orderUrl: (id: string) => string }) {
-  const tasks = useApprovalTasks();
+  const [params, setParams] = useSearchParams();
+  const selected = params.get('view');
+  const view = selected === 'candidates' || selected === 'waiting' ? selected : 'pending';
+  const tasks = useApprovalTasks(view);
   const { run, busy, message, clearMessage } = useCommand();
   return (
     <>
       <AssistantPage context={{ page: { id: 'approval-inbox', title: '审批待办', kind: 'list', route: '/approvals' },
-        visibleContent: [{ id: 'pending-tasks', text: tasks.data ? `当前待处理审批 ${tasks.data.length} 项，以重新查询的待办为准。` : '审批待办正在读取或暂时不可用。' }],
+        visibleContent: [{ id: 'visible-tasks', text: tasks.data ? `${views[view]}当前显示 ${tasks.data.length} 项，以重新查询为准。` : '审批任务正在读取或暂时不可用。' }],
       }} suggestions={['查看当前待我处理的审批', '通过、驳回和退回修改有什么区别？']} />
-      <PageHeading eyebrow="APPROVAL INBOX" title="审批待办" description="处理分配给你的审批任务。" />
+      <PageHeading eyebrow="APPROVAL INBOX" title="审批待办" description="领取、处理和跟进你的审批任务。" />
       {message && <Notice onClose={clearMessage}>{message}</Notice>}
-      <section className="panel">
+      <section className="panel approval-inbox">
         <div className="section-head">
-          <h2>待你处理</h2>
-          <button onClick={() => void tasks.refetch()}>刷新</button>
+          <div className="actions" aria-label="审批任务视图">
+            {Object.entries(views).map(([key, label]) => <button key={key} disabled={busy} aria-pressed={key === view} className={key === view ? 'primary' : ''}
+              onClick={() => setParams(previous => { const next = new URLSearchParams(previous); if (key === 'pending') next.delete('view'); else next.set('view', key); return next; })}>{label}</button>)}
+          </div>
+          <button disabled={busy || tasks.isFetching} onClick={() => void tasks.refetch()}>刷新</button>
         </div>
         {tasks.isError && <p className="error">{tasks.error.message}</p>}
-        {tasks.isPending && <p className="empty">正在读取待办…</p>}
-        {tasks.data?.map((task) => (
-          <div className="task" key={task.id}>
-            <div>
-              <h3>{task.title}</h3>
-              <p className="mono muted">PO-{task.businessKey.slice(0, 8).toUpperCase()}</p>
-            </div>
-            <div className="actions">
-              {/* 单据的页面地址由 app 组合层提供，审批模块不依赖采购页面内部文件。 */}
-              <Link className="route-link" to={orderUrl(task.businessKey)}>
-                查看采购单 ↗
-              </Link>
-              <button
-                disabled={busy}
-                onClick={() => run(() => client.post(`/api/approval/tasks/${task.id}/reject`), '已驳回')}
-              >
-                驳回
-              </button>
-              <button disabled={busy} onClick={() => run(() => client.post(`/api/approval/tasks/${task.id}/return`), '已退回修改')}>退回修改</button>
-              <button
-                disabled={busy}
-                className="primary"
-                onClick={() => run(() => client.post(`/api/approval/tasks/${task.id}/approve`), '已通过审批')}
-              >
-                通过审批
-              </button>
-            </div>
-          </div>
-        ))}
-        {tasks.data?.length === 0 && (
-          <div className="empty">
-            <h3>待办已清空</h3>
-            <p>新任务分配给你后会显示在这里。</p>
-          </div>
-        )}
+        {tasks.isPending && <p className="empty">正在读取任务…</p>}
+        {tasks.data?.map(task => <TaskRow key={`${task.id}:${task.revision}`} task={task} orderUrl={orderUrl} busy={busy} run={run} />)}
+        {tasks.data?.length === 0 && <div className="empty"><h3>当前没有{views[view]}的任务</h3><p>任务分配或签署顺序变化后，可刷新查看。</p></div>}
       </section>
     </>
   );

package/templates/app/apps/web/src/modules/approval/pages/approval-tasks.css

@@ -0,0 +1,18 @@
+/**
+ * 审批收件箱局部布局，沿用工作台配色与按钮；将意见、详情及提交分行，避免窄屏压缩链接。
+ * 只作用于审批模块，桌面保留事项/操作两栏，空间不足自动换行；等待阶段由组件省略操作控件。
+ */
+.approval-inbox .task { flex-wrap: wrap; gap: 20px; }
+.approval-task-summary { flex: 1 1 240px; }
+.approval-task-controls { display: grid; gap: 12px; flex: 0 1 420px; }
+.approval-task-controls .actions { align-items: center; flex-wrap: wrap; }
+.approval-task-controls .route-link { white-space: nowrap; }
+.approval-task-controls input { min-width: 180px; flex: 1; }
+.approval-operation-dialog { width: min(760px, calc(100vw - 32px)); max-height: calc(100vh - 48px); overflow-y: auto; }
+.approval-operation-dialog form { padding: 24px; }
+.approval-operation-dialog textarea { width: 100%; }
+.approval-inbox .section-head { gap: 16px; flex-wrap: wrap; }
+@media (max-width: 660px) {
+  .approval-task-controls { flex-basis: 100%; }
+  .approval-inbox .task { padding: 20px; }
+}

package/templates/app/apps/web/src/modules/purchase/components/approval-history.tsx

@@ -1,9 +1,15 @@
 /**
  * 采购单审批轨迹展示，按单据与版本读取服务端整理后的轮次和步骤。
- * AI 与人工状态使用同一记录来源；受限详情不显示理由，不能根据缺少细节推断未执行。
+ * AI 与人工状态使用同一记录来源；并行节点按服务端分支路径展示，序号仅定位节点、不代表串行先后。
+ * 受限详情不显示理由，不能根据缺少细节推断未执行；该组件只消费框架历史，不实现审批调度。
  */
-import { useQuery } from '@tanstack/react-query';
+import { useInfiniteQuery, useQuery } from '@tanstack/react-query';
 import { client } from '@yss123/cage-client';
+import { useApprovalMembers } from '../../../shared/ui/approval-member-picker';
+
+/** 人工操作与引擎自动激活都来自已提交历史；未知动作保留原值，不能伪装成通过。 */
+const actionLabels: Record<string, string> = { transfer: '转办', delegate: '委派协助', resolve: '归还审批人', addSign: '增加签署人', claim: '领取任务', unclaim: '释放任务', approved: '通过审批', rejected: '驳回', returned: '退回修改', cancelled: '取消流程', activated: '激活等待任务', skipped: '结束其余待办', advanced: '推进审批分支', urged: '申请人催办', reminded: '流程时限提醒' };
+const positionLabels: Record<string, string> = { before: '前加签', after: '后加签', parallel: '并行加签' };
 
 /**
  * 运行、步骤与人工待办状态的展示映射，未知状态仍由页面按实际值处理。
@@ -19,14 +25,43 @@ export function ApprovalHistory({ id, version, pending }: { id: string; version:
     if (!result.ok) throw new Error(`审批记录读取失败：${result.code}`);
     return result.data;
   }, refetchInterval: pending ? 1500 : false });
+  const members = useApprovalMembers(1, true);
+  // 跨轮次动作按服务端游标递增分页；轮询重读已经打开的页，避免只更新首屏或丢失后续意见。
+  const actions = useInfiniteQuery({ queryKey: ['approval-task-history', id], initialPageParam: undefined as string | undefined,
+    queryFn: async ({ pageParam }) => {
+      const result = await client.approvalTaskHistory('po-approval', 'PurchaseOrder', id, { after: pageParam, limit: 50 });
+      if (!result.ok) throw new Error(`操作记录读取失败：${result.code}`);
+      return result.data;
+    }, getNextPageParam: last => last.nextCursor ?? undefined, refetchInterval: pending ? 1500 : false });
+  const person = (userId: string | null) => userId ? members.data?.items.find(member => member.userId === userId)?.displayName ?? userId.slice(0, 8) : '系统';
   return <section className="panel approval-history"><div className="section-head"><h2>审批记录</h2><span className="muted">退回后重新提交，从第一步重新审核</span></div>
     {history.isPending && <p className="muted">正在读取审核记录…</p>}
     {history.isError && <p role="alert">{history.error.message}</p>}
-    {history.data?.length === 0 && <p className="muted">提交后先进入 AI 材料预审，再按流程交由人工审批。</p>}
+    {history.data?.length === 0 && <p className="muted">提交后按已配置流程审批，实际环节和并行分支将在此显示。</p>}
     {history.data?.map((round, index) => <div className="review-round" key={round.id}><h3>第 {history.data.length - index} 轮 · {status[round.status] ?? round.status}</h3>
-      {round.steps.map(step => <div className="review-step" key={step.index}><strong>{step.index + 1}. {step.kind === 'ai' ? 'AI 材料预审' : '人工审批'} · {status[step.status] ?? step.status}</strong>
+      {(round.currentSteps?.length ?? 0) > 1 && <p className="muted">当前有 {round.currentSteps!.length} 个审批环节并行办理，全部完成后才继续。</p>}
+      {round.steps.map(step => <div className="review-step" key={step.index}><strong>{step.index + 1}. {step.title ?? (step.kind === 'ai' ? 'AI 材料预审' : '人工审批')} · {status[step.status] ?? step.status}</strong>
+        {!!step.branchPath?.length && <p className="muted">{step.branchPath.map(part => `${part.parallel} · ${part.branch}`).join(' / ')}</p>}
         {step.detailRestricted ? <p>当前权限无法查看审核解释。</p> : <>{step.decision && <p>{step.decision.reason}</p>}{step.decision?.suggestions.map((text, i) => <p className="review-suggestion" key={i}>{text}</p>)}</>}
       </div>)}
     </div>)}
+    <div className="review-actions"><h3>人员流转与处理意见</h3>
+      {actions.isPending && <p role="status">正在读取操作记录…</p>}
+      {actions.isError && <p role="alert">{actions.error.message} <button onClick={() => void actions.refetch()}>重试</button></p>}
+      {actions.data?.pages.flatMap(page => page.items).map(item => {
+        const placement = typeof item.details.placement === 'string' ? positionLabels[item.details.placement] : undefined;
+        const targets = Array.isArray(item.details.userIds) ? item.details.userIds.filter((value): value is string => typeof value === 'string') : [];
+        const to = typeof item.details.to === 'string' ? item.details.to : null;
+        const roundIndex = history.data?.findIndex(round => round.id === item.instanceId) ?? -1;
+        return <article className="review-step" key={item.id}>
+          <strong>{person(item.actorId)} · {placement ?? actionLabels[item.action] ?? item.action}</strong>
+          <small className="muted">{roundIndex >= 0 ? `第 ${history.data!.length - roundIndex} 轮 · ` : ''}{new Date(item.createdAt).toLocaleString('zh-CN')}</small>
+          {targets.length > 0 ? <p>签署人：{targets.map(person).join('、')}</p> : to && ['transfer', 'delegate', 'resolve'].includes(item.action) ? <p>交给：{person(to)}</p> : null}
+          {item.reason && <p>{item.reason}</p>}
+        </article>;
+      })}
+      {actions.data?.pages[0].items.length === 0 && <p className="muted">尚无人工操作记录。</p>}
+      {actions.hasNextPage && <button disabled={actions.isFetchingNextPage} onClick={() => void actions.fetchNextPage()}>加载后续记录</button>}
+    </div>
   </section>;
 }

package/templates/app/apps/web/src/modules/purchase/components/order-reviewers.tsx

@@ -0,0 +1,38 @@
+/**
+ * 采购详情中的专业复核配置，申请人在草稿或退回后选择实际会签人。
+ * 配置通过 setReviewers 命令保存，提交后只读；页面不能更改已经生成的审批实例快照。
+ * 名录只用于展示与选人，服务端重查有效名录、提单人隔离、状态、版本及命令权限。
+ */
+import { useState } from 'react';
+import { can, purchaseOrder, type PurchaseOrder } from '@app/contracts';
+import { useCommand } from '../../../shared/hooks/use-command';
+import { ApprovalMemberPicker, useApprovalMembers } from '../../../shared/ui/approval-member-picker';
+import { Notice } from '../../../shared/ui/notice';
+
+/**
+ * order 为安全读取的最新单据；null 草稿表示未编辑，避免后台刷新覆盖用户尚未保存的选人。
+ * 保存携带当前业务版本，成功清空本地草稿并刷新缓存；失败保留选择和提示，不重试写入。
+ * 名录首页外或已不可读人员保留 UUID，不能把查不到名称解释为已删除或无需签署。
+ */
+export function OrderReviewers({ order }: { order: PurchaseOrder }) {
+  const [draft, setDraft] = useState<{ enabled: boolean; ids: string[] } | null>(null);
+  const members = useApprovalMembers(1, true);
+  const { run, busy, message, clearMessage } = useCommand();
+  const editable = order.status === 'draft' && can('PurchaseOrder.setReviewers');
+  const selection = draft ?? { enabled: order.needsSpecialistReview ?? false, ids: order.reviewerIds ?? [] };
+  const names = (order.reviewerIds ?? []).map(id => members.data?.items.find(member => member.userId === id)?.displayName ?? id);
+  return <section className="purpose-editor">
+    <h2>审批安排{draft && editable && <small className="muted"> · 尚未保存</small>}</h2>
+    <p className="muted">{selection.enabled ? '需要所选专业人员全部签署。' : '本单不要求专业人员会签。'}具体流转与其他审批环节以提交后的流程记录为准。</p>
+    {message && <Notice onClose={clearMessage}>{message}</Notice>}
+    {editable ? <>
+      <label className="review-checkbox"><input type="checkbox" checked={selection.enabled} disabled={busy}
+        onChange={event => setDraft({ ...selection, enabled: event.target.checked })} />需要专业会签（技术、质量等）</label>
+      {selection.enabled && <ApprovalMemberPicker value={selection.ids} onChange={ids => setDraft({ ...selection, ids })} exclude={[order.createdBy]} disabled={busy} />}
+      <div className="actions"><span className="muted">退回后可重新安排，重提将开启新一轮审批。</span>
+        <button disabled={busy || draft === null || (selection.enabled && !selection.ids.length)} onClick={async () => {
+          if (await run(() => purchaseOrder.setReviewers(order.id, { needsSpecialistReview: selection.enabled, reviewerIds: selection.enabled ? selection.ids : [] }, order.version), '审批安排已保存')) setDraft(null);
+        }}>保存审批安排</button></div>
+    </> : <p>{order.needsSpecialistReview ? `专业会签：${names.join('、')}` : '无需专业会签'}</p>}
+  </section>;
+}

package/templates/app/apps/web/src/modules/purchase/components/purchase-order-form.tsx

@@ -4,10 +4,11 @@
  */
 // 只处理采购草稿输入；状态迁移、创建人和权限仍由领域命令决定。
 import { useState, type FormEvent } from 'react';
-import { purchaseOrder, PurchaseOrderFileFields } from '@app/contracts';
+import { purchaseOrder, PurchaseOrderFileFields, currentUser } from '@app/contracts';
 import type { RunCommand } from '../../../shared/hooks/use-command';
 import { AttachmentUpload } from '../../../shared/ui/attachment-upload';
 import './purchase-order-form.css';
+import { ApprovalMemberPicker } from '../../../shared/ui/approval-member-picker';
 
 /**
  * 在弹窗中维护附件列表、上传状态和提交状态。
@@ -18,6 +19,8 @@ export function PurchaseOrderForm({ close, run }: { close: () => void; run: RunC
   const [busy, setBusy] = useState(false);
   const [attachments, setAttachments] = useState<string[]>([]);
   const [uploading, setUploading] = useState(false);
+  const [needsSpecialistReview, setNeedsSpecialistReview] = useState(false);
+  const [reviewerIds, setReviewerIds] = useState<string[]>([]);
   /**
    * 读取 FormData 并构造创建输入：金额保留字符串，数量转数值，可选空文本转 undefined。
    * 等待 run 返回后解除提交态，只有成功才关闭；依赖 run 返回结果，不额外捕获任意抛出异常。
@@ -35,6 +38,7 @@ export function PurchaseOrderForm({ close, run }: { close: () => void; run: RunC
           reason: String(data.get('reason')) || undefined,
           items: [{ sku: String(data.get('sku')), qty: Number(data.get('qty')) }],
           attachments,
+          needsSpecialistReview, reviewerIds: needsSpecialistReview ? reviewerIds : [],
         }),
       '采购单已保存为草稿',
     );
@@ -71,8 +75,11 @@ export function PurchaseOrderForm({ close, run }: { close: () => void; run: RunC
           </label>
           <p className="muted">保存后可在列表提交审批，创建人和部门会自动填写。</p>
           <label>采购用途与必要性<textarea name="reason" rows={3} maxLength={2000} placeholder="说明具体用途；提交后先进行 AI 材料预审" /></label>
+          <label className="review-checkbox"><input type="checkbox" checked={needsSpecialistReview} onChange={event => setNeedsSpecialistReview(event.target.checked)} />需要专业会签（技术、质量等）</label>
+          {needsSpecialistReview && <ApprovalMemberPicker value={reviewerIds} onChange={setReviewerIds} exclude={currentUser() ? [currentUser()!.id] : []} disabled={busy} />}
+          <p className="muted">{needsSpecialistReview ? '所选专业人员需要全部签署。' : '本次不要求专业会签。'}提交后可在审批记录查看实际环节和办理进度。</p>
           <AttachmentUpload command="PurchaseOrder.create" field="attachments" policy={PurchaseOrderFileFields.attachments} value={attachments} onChange={setAttachments} onBusyChange={setUploading} />
-          <button className="primary" disabled={busy || uploading}>
+          <button className="primary" disabled={busy || uploading || (needsSpecialistReview && reviewerIds.length === 0)}>
             {busy ? '保存中…' : '保存草稿'}
           </button>
         </form>

package/templates/app/apps/web/src/modules/purchase/pages/purchase-intelligence.css

@@ -13,3 +13,5 @@
 .review-step { margin: 14px 0; border-left: 2px solid #bbd0bd; padding: 4px 0 4px 18px; font-size: 13px; line-height: 1.8; }
 .review-step p { margin: 6px 0; }
 .review-suggestion { color: #956128; }
+.review-actions { margin-top: 24px; border-top: 1px solid var(--line, #e4e8df); padding-top: 12px; }
+.review-actions small { display: block; }

package/templates/app/apps/web/src/modules/purchase/pages/purchase-order-detail-page.tsx

@@ -14,6 +14,7 @@ import { currency, statusLabels } from '../lib/presentation';
 import { OrderAttachments } from '../components/order-attachments';
 import { PurchaseAssistantContext } from '../components/purchase-assistant-context';
 import { ApprovalHistory } from '../components/approval-history';
+import { OrderReviewers } from '../components/order-reviewers';
 import './purchase-intelligence.css';
 
 const list = '/procurement/orders';
@@ -122,6 +123,7 @@ function OrderDetail({ id }: { id: string }) {
             }}>保存用途</button></div>
           </> : <p>{order.reason || '尚未填写用途'}</p>}
         </div>
+        <OrderReviewers order={order} />
         <OrderAttachments order={order} />
         <div className="section-head">
           <h2>采购物料</h2>

package/templates/app/apps/web/src/modules/purchase/pages/purchase-orders-page.tsx

@@ -170,6 +170,8 @@ export function PurchaseOrdersPage({ pendingTasks }: { pendingTasks?: number })
                         >
                           PO-{order.id.slice(0, 8).toUpperCase()}
                         </Link>
+                        {/* 用途摘要帮助采购员辨认单据；完整材料仍在详情页按安全读权限展示。 */}
+                        {order.reason && <small title={order.reason}>{order.reason.length > 48 ? `${order.reason.slice(0, 48)}…` : order.reason}</small>}
                         <small>{new Date(order.createdAt).toLocaleString('zh-CN')}</small>
                       </td>
                       <td>{order.items.map((i) => `${i.sku} × ${i.qty}`).join('、')}</td>

package/templates/app/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/app/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/app/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/app/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/app/db/migrations/0004_draft.sql

@@ -0,0 +1,27 @@
+-- 迁移草稿：由 cage gen 生成，人审后提交；已发布的迁移不要修改
+-- 破坏性变更按「先扩展再收缩」分多次发布
+
+-- 新表：来自聚合 ApprovalMember
+CREATE TABLE IF NOT EXISTS "core"."approval_member" (
+  "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  "tenant_id" uuid NOT NULL,
+  "user_id" uuid NOT NULL REFERENCES "sys"."user"(id),
+  "display_name" text NOT NULL,
+  "specialty" text NOT NULL,
+  "status" text NOT NULL,
+  "version" integer NOT NULL DEFAULT 1,
+  "created_at" timestamptz NOT NULL DEFAULT now(),
+  "updated_at" timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT "approval_member_status_check" CHECK (status IN ('active', 'retired'))
+);
+CREATE UNIQUE INDEX IF NOT EXISTS "approval_member_user_id_uq" ON "core"."approval_member" (tenant_id, "user_id");
+CREATE INDEX IF NOT EXISTS "approval_member_status_idx" ON "core"."approval_member" ("tenant_id", "status");
+CREATE INDEX IF NOT EXISTS "approval_member_user_id_idx" ON "core"."approval_member" ("user_id");
+
+ALTER TABLE "core"."purchase_order" ADD COLUMN IF NOT EXISTS "needs_specialist_review" boolean;
+
+ALTER TABLE "core"."purchase_order" ADD COLUMN IF NOT EXISTS "reviewer_ids" jsonb;
+
+/* cage:schema
+{"version":1,"tables":[{"schema":"sys","name":"dept","aggregate":"Dept","columns":[{"name":"id","type":"uuid","notNull":true},{"name":"tenant_id","type":"uuid","notNull":true},{"name":"name","type":"text","notNull":true},{"name":"code","type":"text","notNull":false},{"name":"parent_id","type":"uuid","notNull":false,"references":"sys.dept"},{"name":"ancestors","type":"text","notNull":true},{"name":"leader_id","type":"uuid","notNull":false},{"name":"status","type":"text","notNull":true},{"name":"version","type":"integer","notNull":true},{"name":"created_at","type":"timestamptz","notNull":true},{"name":"updated_at","type":"timestamptz","notNull":true}],"statusValues":["active","archived"],"indexes":[{"name":"dept_status_idx","columns":["tenant_id","status"]},{"name":"dept_parent_id_idx","columns":["parent_id"]}]},{"schema":"sys","name":"user","aggregate":"User","columns":[{"name":"id","type":"uuid","notNull":true},{"name":"tenant_id","type":"uuid","notNull":true},{"name":"username","type":"text","notNull":true,"unique":true},{"name":"name","type":"text","notNull":true},{"name":"dept_id","type":"uuid","notNull":true,"references":"sys.dept"},{"name":"role_ids","type":"jsonb","notNull":true},{"name":"phone","type":"text","notNull":false},{"name":"email","type":"text","notNull":false},{"name":"sso_subject","type":"text","notNull":false},{"name":"password_hash","type":"text","notNull":false},{"name":"status","type":"text","notNull":true},{"name":"version","type":"integer","notNull":true},{"name":"created_at","type":"timestamptz","notNull":true},{"name":"updated_at","type":"timestamptz","notNull":true}],"statusValues":["active","disabled"],"indexes":[{"name":"user_tenant_dept_id_idx","columns":["tenant_id","dept_id"]},{"name":"user_status_idx","columns":["tenant_id","status"]}]},{"schema":"core","name":"approval_member","aggregate":"ApprovalMember","columns":[{"name":"id","type":"uuid","notNull":true},{"name":"tenant_id","type":"uuid","notNull":true},{"name":"user_id","type":"uuid","notNull":true,"references":"sys.user","unique":true},{"name":"display_name","type":"text","notNull":true},{"name":"specialty","type":"text","notNull":true},{"name":"status","type":"text","notNull":true},{"name":"version","type":"integer","notNull":true},{"name":"created_at","type":"timestamptz","notNull":true},{"name":"updated_at","type":"timestamptz","notNull":true}],"statusValues":["active","retired"],"indexes":[{"name":"approval_member_status_idx","columns":["tenant_id","status"]},{"name":"approval_member_user_id_idx","columns":["user_id"]}]},{"schema":"core","name":"inventory","aggregate":"Inventory","columns":[{"name":"id","type":"uuid","notNull":true},{"name":"tenant_id","type":"uuid","notNull":true},{"name":"sku","type":"text","notNull":true,"unique":true},{"name":"available","type":"integer","notNull":true},{"name":"status","type":"text","notNull":true},{"name":"version","type":"integer","notNull":true},{"name":"created_at","type":"timestamptz","notNull":true},{"name":"updated_at","type":"timestamptz","notNull":true}],"statusValues":["active","deleted"],"indexes":[{"name":"inventory_status_idx","columns":["tenant_id","status"]}]},{"schema":"core","name":"inventory_lock","aggregate":"InventoryLock","columns":[{"name":"id","type":"uuid","notNull":true},{"name":"tenant_id","type":"uuid","notNull":true},{"name":"order_id","type":"uuid","notNull":true},{"name":"items","type":"jsonb","notNull":true},{"name":"status","type":"text","notNull":true},{"name":"version","type":"integer","notNull":true},{"name":"created_at","type":"timestamptz","notNull":true},{"name":"updated_at","type":"timestamptz","notNull":true}],"statusValues":["held","released"],"indexes":[{"name":"inventory_lock_status_idx","columns":["tenant_id","status"]}]},{"schema":"core","name":"purchase_order","aggregate":"PurchaseOrder","columns":[{"name":"id","type":"uuid","notNull":true},{"name":"tenant_id","type":"uuid","notNull":true},{"name":"dept_id","type":"uuid","notNull":true,"references":"sys.dept"},{"name":"created_by","type":"uuid","notNull":true,"references":"sys.user"},{"name":"supplier_phone","type":"text","notNull":false},{"name":"amount","type":"numeric(18,2)","notNull":true},{"name":"reason","type":"text","notNull":false},{"name":"needs_specialist_review","type":"boolean","notNull":false},{"name":"reviewer_ids","type":"jsonb","notNull":false},{"name":"items","type":"jsonb","notNull":true},{"name":"erp_no","type":"text","notNull":false},{"name":"attachments","type":"jsonb","notNull":true},{"name":"status","type":"text","notNull":true},{"name":"version","type":"integer","notNull":true},{"name":"created_at","type":"timestamptz","notNull":true},{"name":"updated_at","type":"timestamptz","notNull":true}],"statusValues":["draft","pending_approval","approved","received","rejected","cancelled"],"indexes":[{"name":"purchase_order_tenant_dept_id_idx","columns":["tenant_id","dept_id"]},{"name":"purchase_order_tenant_created_by_idx","columns":["tenant_id","created_by"]},{"name":"purchase_order_status_idx","columns":["tenant_id","status"]}]},{"schema":"sys","name":"role","aggregate":"Role","columns":[{"name":"id","type":"uuid","notNull":true},{"name":"tenant_id","type":"uuid","notNull":true},{"name":"code","type":"text","notNull":true,"unique":true},{"name":"name","type":"text","notNull":true},{"name":"capabilities","type":"jsonb","notNull":true},{"name":"scopes","type":"jsonb","notNull":true},{"name":"status","type":"text","notNull":true},{"name":"version","type":"integer","notNull":true},{"name":"created_at","type":"timestamptz","notNull":true},{"name":"updated_at","type":"timestamptz","notNull":true}],"statusValues":["active","archived"],"indexes":[{"name":"role_status_idx","columns":["tenant_id","status"]}]}]}
+*/

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

@@ -29,6 +29,7 @@
 | 开发前 | [本体查询与 AI 上下文](ontology-context.md) | 按需求查哪些代码？为什么关联？候选、证据与子图边界怎么判断？ |
 | 开发与排错 | [能力发现与状态诊断](diagnostics.md) | 公开 API 有什么？注册/契约/进程哪里过期？如何查执行时间线和授权拒绝？ |
 | 按需 | [对象关系](relations.md) | 如何在 fields 中声明一对一、一对多、多对多，修改关联并分页读取？ |
+| 复杂审批 | [审批流转、并行与流程时效](approvals.md) | 如何声明 AND 并行与汇合，按字段选人、候选领取、转办/委派/加签，并使用框架节点时限、站内提醒、催办和已读？ |
 | 前端必读 | [业务路由与浏览器验收](routing.md) | 列表/详情如何获得独立 URL？登录回跳、404、/admin 和部署回退怎样验收？ |
 | 原生 AI | [智能助理与 AI 审批](intelligence.md) | 如何启用后端、配置三态审核、生成工具、传入页面快照和接入 SDK？ |
 | 4 | [标准采购范例导读](purchase-example.md) | 一次提交如何进入审批、锁库存、推 ERP、释放资源？ |
@@ -55,7 +56,9 @@
 | 增加操作按钮 | 领域命令 + `apps/web/src/modules/<业务>` | 状态迁移、调用身份、错误展示、提交幂等键 |
 | 增加列表、详情或新页面 | 模块 pages + app 路由表 | URL、查询条件、深链接、刷新、前进后退、登录回跳；见[路由指南](routing.md) |
 | 增加报表 | 所属领域模块 `queries.ts` | `reads`、`safe.*`、参数化、调用人 read 权限 |
-| 修改审批顺序/条件/选人 | 所属领域模块 `approvals.ts` | `routable`、角色/负责人数据、结论命令约束 |
+| 修改审批顺序/条件/并行/选人 | 所属领域模块 `approvals.ts` | `parallel/branch` 的 AND 汇合与完整 currentSteps、`routable`、`approver.field` 的 UUID/数组、角色/负责人数据、同租户 active 用户及结论命令约束；见[任务流转](approvals.md) |
+| 候选领取、转办、委派和前后加签 | 人工 `step` 的 `assignment/actions` + 客户端任务接口 | 候选规则与权限实时检查、waiting 依赖、任务 revision、旧实例快照、系统迁移；Admin/采购已有领取、释放、归还，采购还提供协作名录选人、转办/委派/三种加签及分页人工历史 |
+| 节点时限、流程提醒与申请人催办 | `step.sla`、`route.reminders` + 导出的 `approvalOperations()` | 自然分钟、逐节点开启计时、同实例共享催办冷却；并行催办携带 expectedSteps；沿用框架 Admin 申请/提醒页或 SDK，见[流程时效](approvals.md) |
 | AI 预审、退回修改、转人工 | 现有 `step` 的 `kind: 'ai'` + `approval` 绑定 | 策略、取证字段/查询、`automatedBy` 角色、结论命令及 `handoff`；见[智能化指南](intelligence.md) |
 | 业务助理、随页悬浮窗 | domain 导出 `ai()`；页面接 `useAssistant` 与 `useAiPageContext` | 业务权限、页面快照、流式 Markdown、写入确认；界面由应用实现 |
 | 模型动态配置、Responses、性格 | `managedModel` 与框架 Admin 页面 | 部署加密密钥、管理权限、实际网关能力、性格仅影响表达 |
@@ -86,7 +89,9 @@
 | 本体抽取、中文检索/节点/路径/AI 上下文、图规则、图谱、生成、影响分析与门禁 | 上下文注明证据、源码和覆盖边界；名称与测试匹配是候选线索，不能证明任意 JS 正确；跳过用例仍需补足 |
 | 有界集合 reactionEach、显式步骤 order | 稳定唯一键排序后串行调用目标命令；同事务整体回滚，异步链按 outbox 恢复；不是并行写表接口 |
 | capabilities、doctor、timeline、explain、snapshot | 实际运行诊断需要受控会话与权限；未取得的证据为 unknown，授权解释不执行 handler |
-| 代码审批路由与适配接口 | 顺序步骤、条件步骤、步骤内任一/全部审批；没有通用可视化流程设计器、任意 JS 选人、转签/加签 API |
+| 代码审批路由与任务流转 | 顺序/条件、`parallel/branch` 结构化 AND 分支与汇合、any/all、字段选人、候选领取/释放、转办、单层委派归还、前后/并行必签和动作历史；候选池仅支持 any，追加票全部必签。条件和依赖随提交冻结，currentStep 仅为最小活动索引；尚无任意连线/循环/OR 网关、岗位/代理规则、通用恢复、任意 JS 选人或在途迁移，见[任务流转](approvals.md) |
+| 审批时限、站内提醒与催办 | 人工节点按实际开启时间计算自然分钟 SLA，worker 持久投递临期/超时提醒；申请人可按完整活动集合催办，同实例共享冷却，接收人可标已读。旧快照不自动获得政策；尚无工作日历、自动升级、抄送或邮件/短信通知 |
+| 审批界面与 SDK | Admin/采购待办可领取、释放、归还受托任务并查看等待加签；采购另有协作名录选人器、转办/委派/三种加签及分页人工历史，view 查询参数保留视图。启用运营后通用 Admin 提供我的申请、催办和流程提醒；页面仍需应用启用、真实授权与浏览器验收。AI 助理目前只查询本人待办及提交决定，无人员管理写工具 |
 | 原生 AI 审批与领域助理 | 现有 `step` 支持 `kind: 'ai'`；三态审核、自动工具、会话及偏好记忆可复用；需显式启用、授权并做模型质量验收 |
 | Admin 模型与性格、助理 SDK | 动态模型连接和性格管理；Chat Completions / Responses 兼容性以实际服务为准；SDK 提供流式状态与页面快照，悬浮窗和 Markdown 由应用实现 |
 | 连接器 fake、出站、入站验签、同步记录 | fake 不等于真实 ERP 联调，也不等于完整请求录制/回放平台 |