@yss123/cage-cli 0.2.0 → 0.3.1

package/templates/blank/docs/examples/purchase-admin/apps/web/src/modules/approval/pages/approval-tasks-page.tsx

@@ -1,53 +1,104 @@
-// 审批待办独立成页；结论调用框架审批接口，领域约束仍在后端执行。
+/**
+ * 审批收件箱使用 URL 的 view 切换本人、可领取和等待加签任务，刷新/前进后退保留视图。
+ * 通过 app 注入详情链接，界面调用客户端完成领取、释放、人员流转与决定；候选身份和版本仍由服务端校验。
+ * 原因是行内临时草稿，动作成功后由 useCommand 失效查询并重读；waiting 仅供查看，不显示决定入口。
+ */
+import { useState } from 'react';
 import { client } from '@app/contracts';
-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';
 
-export function ApprovalTasksPage() {
-  const tasks = useApprovalTasks();
+/** 三种任务视图进入查询参数；只有 pending 会计入原有导航待办数。 */
+const views = { pending: '待我处理', candidates: '可领取', waiting: '等待加签' } as const;
+
+/**
+ * 为一项任务展示顺序、意见和合法阶段入口。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 [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 (
     <>
-      <PageHeading eyebrow="APPROVAL INBOX" title="审批待办" description="处理分配给你的审批任务。" />
+      <AssistantPage context={{ page: { id: 'approval-inbox', title: '审批待办', kind: 'list', route: '/approvals' },
+        visibleContent: [{ id: 'visible-tasks', text: tasks.data ? `${views[view]}当前显示 ${tasks.data.length} 项，以重新查询为准。` : '审批任务正在读取或暂时不可用。' }],
+      }} suggestions={['查看当前待我处理的审批', '通过、驳回和退回修改有什么区别？']} />
+      <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">
-              <button
-                disabled={busy}
-                onClick={() => run(() => client.post(`/api/approval/tasks/${task.id}/reject`), '已驳回')}
-              >
-                驳回
-              </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/blank/docs/examples/purchase-admin/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/blank/docs/examples/purchase-admin/apps/web/src/modules/auth/index.ts

@@ -1 +1,5 @@
+/**
+ * auth 模块的公开入口，对 app 暴露登录页。
+ * 外部组合通过本入口导入，页面、组件与内部 helper 的组织由模块自行维护。
+ */
 export { LoginPage } from './pages/login-page';

package/templates/blank/docs/examples/purchase-admin/apps/web/src/modules/auth/pages/login-page.tsx

@@ -1,11 +1,23 @@
+/**
+ * 采购应用认证页面，收集账号密码并调用契约客户端登录。
+ * 会话协议和当前能力同步由 SDK 负责；成功后的安全回跳交给 app 路由层。
+ */
 // 登录页属于认证模块；表单反馈留在模块内，会话切换由 app 处理。
 import { useState, type FormEvent } from 'react';
 import { client } from '@app/contracts';
 import { errorMessage } from '../../../shared/lib/error-message';
 
+/**
+ * 维护提交中与失败提示，成功调用 onLogin 通知路由切换。
+ * 不在组件内持久化密码，不自行跳转未校验的 returnTo。
+ */
 export function LoginPage({ onLogin }: { onLogin: () => void }) {
   const [error, setError] = useState('');
   const [busy, setBusy] = useState(false);
+  /**
+   * 阻止浏览器原生表单跳转，读取本次输入并等待 client.login。
+   * 成功后由 app 进入已登录路由；错误通过统一映射显示，输入与凭证不写入日志。
+   */
   async function submit(event: FormEvent<HTMLFormElement>) {
     event.preventDefault();
     setBusy(true);

package/templates/blank/docs/examples/purchase-admin/apps/web/src/modules/inventory/index.ts

@@ -1 +1,5 @@
+/**
+ * inventory 模块的公开入口，对 app 暴露库存页。
+ * 外部组合通过本入口导入，页面、组件与内部 helper 的组织由模块自行维护。
+ */
 export { InventoryPage } from './pages/inventory-page';

package/templates/blank/docs/examples/purchase-admin/apps/web/src/modules/inventory/pages/inventory-page.tsx

@@ -1,14 +1,43 @@
+/**
+ * 库存示例页，读取库存安全列表并通过生成命令创建库存记录。
+ * 这只是采购范例中的库存展示与输入入口，资源占用和释放仍通过领域流程落实。
+ */
 // 库存模块只管理台账页面，登记物料通过生成的 Inventory.create 命令。
 import { can, inventory, useInventoryList } from '@app/contracts';
 import { useCommand } from '../../../shared/hooks/use-command';
 import { Notice } from '../../../shared/ui/notice';
 import { PageHeading } from '../../../shared/ui/page-heading';
+import { QueryFailure } from '../../../shared/ui/page-state';
+import { AssistantPage } from '../../../shared/ui/assistant-scope';
 
+/**
+ * 读取最多前一百条库存并展示查询失败、加载和空结果；列表不代表系统全部库存。
+ * 创建成功后重置表单并刷新查询，失败保留输入。助理上下文只列当前可见记录 ID，服务端仍核验读取范围。
+ */
 export function InventoryPage() {
   const stock = useInventoryList({ pageSize: 100 });
   const { run, busy, message, clearMessage } = useCommand();
+  if (stock.isPending)
+    return (
+      <p className="empty" role="status">
+        正在读取库存台账…
+      </p>
+    );
+  // 页面已打开后权限仍可能变化，必须处理安全接口的拒绝，不能把失败展示成空台账。
+  if (stock.isError)
+    return (
+      <QueryFailure
+        error={stock.error}
+        to="/workspace"
+        label="返回工作台"
+        retry={() => void stock.refetch()}
+      />
+    );
   return (
     <>
+      <AssistantPage context={{ page: { id: 'inventory', title: '库存台账', kind: 'list', route: '/inventory' },
+        view: { aggregate: 'Inventory', input: { pageSize: 100 }, visibleIds: stock.data.items.map(item => item.id) },
+      }} suggestions={['汇总当前可见的物料库存', '查询库存时有哪些权限限制？']} />
       <PageHeading eyebrow="INVENTORY" title="库存台账" description="查看物料与当前登记数量。" />
       {message && <Notice onClose={clearMessage}>{message}</Notice>}
       <section className="panel">
@@ -48,7 +77,6 @@ export function InventoryPage() {
             </button>
           </form>
         )}
-        {stock.isError && <p className="error">{stock.error.message}</p>}
         <table>
           <thead>
             <tr>

package/templates/blank/docs/examples/purchase-admin/apps/web/src/modules/purchase/components/approval-history.tsx

@@ -0,0 +1,67 @@
+/**
+ * 采购单审批轨迹展示，按单据与版本读取服务端整理后的轮次和步骤。
+ * AI 与人工状态使用同一记录来源；并行节点按服务端分支路径展示，序号仅定位节点、不代表串行先后。
+ * 受限详情不显示理由，不能根据缺少细节推断未执行；该组件只消费框架历史，不实现审批调度。
+ */
+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: '并行加签' };
+
+/**
+ * 运行、步骤与人工待办状态的展示映射，未知状态仍由页面按实际值处理。
+ */
+const status: Record<string, string> = { queued: '待执行', running: '处理中', passed: '已通过', approved: '已通过', returned: '已退回修改', rejected: '已拒绝', manual: '待人工接管', waiting_manual: '待人工接管', waiting: '待人工审批', cancelled: '已取消', failed: '执行失败', pending: '待处理', skipped: '未执行' };
+/**
+ * id 为采购单标识，version 使业务变更后查询重新取数，pending 决定是否每 1500ms 刷新。
+ * 只显示历史，不执行审批；detailRestricted 分支尊重服务端裁剪，人工接管也不等于通过。
+ */
+export function ApprovalHistory({ id, version, pending }: { id: string; version: number; pending: boolean }) {
+  const history = useQuery({ queryKey: ['approval-history', id, version], queryFn: async () => {
+    const result = await client.approvalHistory('PurchaseOrder', id);
+    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">提交后按已配置流程审批，实际环节和并行分支将在此显示。</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.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/blank/docs/examples/purchase-admin/apps/web/src/modules/purchase/components/order-attachments.tsx

@@ -0,0 +1,29 @@
+/**
+ * 采购详情的附件展示与草稿编辑区，将上传准备和领域关联保存明确分开。
+ * 读取到新版本后重新采用服务端附件列表并收起编辑，避免旧草稿覆盖已变化记录。
+ */
+import { useEffect, useState } from 'react';
+import { can, purchaseOrder, PurchaseOrderFileFields, type PurchaseOrder } from '@app/contracts';
+import { AttachmentUpload, FileLink } from '../../../shared/ui/attachment-upload';
+import { useCommand } from '../../../shared/hooks/use-command';
+
+/**
+ * order 为已读取的采购记录，包含版本、状态和已绑定附件 ID。
+ * 仅草稿且具有 setAttachments 能力时显示编辑入口；保存传入 id 与 version，服务端重新校验。
+ * value 是临时选择列表，移除或上传不会自动修改单据；成功后的缓存刷新带回正式结果。
+ */
+export function OrderAttachments({ order }: { order: PurchaseOrder }) {
+  const [editing, setEditing] = useState(false);
+  const [value, setValue] = useState(order.attachments);
+  const [uploading, setUploading] = useState(false);
+  const { run, busy, message } = useCommand();
+  useEffect(() => { setValue(order.attachments); setEditing(false); }, [order.version, order.attachments]);
+  return <section aria-label="采购附件">
+    <div className="section-head"><h2>采购附件</h2>{order.status === 'draft' && can('PurchaseOrder.setAttachments') && <button type="button" onClick={() => setEditing(!editing)}>{editing ? '收起编辑' : '编辑附件'}</button>}</div>
+    {editing ? <>
+      <AttachmentUpload command="PurchaseOrder.setAttachments" field="attachments" targetId={order.id} policy={PurchaseOrderFileFields.attachments} value={value} onChange={setValue} onBusyChange={setUploading} />
+      <button type="button" disabled={uploading || busy} onClick={() => run(() => purchaseOrder.setAttachments(order.id, { attachments: value }, order.version), '附件已保存')}>保存附件</button>
+      {message && <p role="status">{message}</p>}
+    </> : order.attachments.length ? <ul>{order.attachments.map(id => <li key={id}><FileLink id={id} /></li>)}</ul> : <p className="muted">暂无附件</p>}
+  </section>;
+}

package/templates/blank/docs/examples/purchase-admin/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/blank/docs/examples/purchase-admin/apps/web/src/modules/purchase/components/purchase-assistant-context.tsx

@@ -0,0 +1,17 @@
+/**
+ * 采购模块与公共助理之间的语义适配层，提供采购字段、命令的中文展示名称。
+ * 页面通过 context 显式传入当前所见，不导入领域运行时或自行获取越权数据。
+ */
+import type { PageContextInput } from '@yss123/cage-client';
+import { AssistantPage } from '../../../shared/ui/assistant-scope';
+
+// 页面只补充业务文案与上下文，工具发现、授权及命令执行全部使用框架 SDK。
+/**
+ * 将页面快照与建议问题注册到最近的 AssistantScope，不再创建第二个面板。
+ * context 中的记录/草稿来源由页面负责；标签仅用于确认展示，工具与授权仍来自框架。
+ */
+export function PurchaseAssistantContext({ context, suggestions }: { context: PageContextInput; suggestions: string[] }) {
+  return <AssistantPage context={context} suggestions={suggestions}
+    fieldLabels={{ reason: '采购用途', amount: '金额', items: '物料', key: '偏好名称', value: '偏好内容', comment: '审批意见', outcome: '审批结果' }}
+    commandLabels={{ 'PurchaseOrder.submit': '提交采购审批', 'PurchaseOrder.explainPurpose': '保存采购用途', 'PurchaseOrder.cancel': '取消采购单', 'PurchaseOrder.create': '新建采购单' }} />;
+}

package/templates/blank/docs/examples/purchase-admin/apps/web/src/modules/purchase/components/purchase-order-form.css

@@ -0,0 +1,6 @@
+/**
+ * 采购创建弹窗的高度与滚动约束。附件任务和恢复列表可能增高表单，使用动态视口高度保留边距。
+ * 滚动在弹窗内完成，限制滚动传播，确保保存按钮在窄屏仍可滚动到达。
+ */
+/* 附件与恢复任务会增加表单高度；滚动留在弹窗内，保证窄屏仍可完成保存。 */
+.purchase-order-dialog { max-height: calc(100dvh - 48px); overflow-y: auto; overscroll-behavior: contain; }

package/templates/blank/docs/examples/purchase-admin/apps/web/src/modules/purchase/components/purchase-order-form.tsx

@@ -1,12 +1,33 @@
+/**
+ * 采购草稿创建表单，收集物料、数量、元金额字符串、用途、电话和已上传附件。
+ * 创建人、部门和初始状态由领域及内核确定；浏览器表单限制只承担输入体验。
+ */
 // 只处理采购草稿输入；状态迁移、创建人和权限仍由领域命令决定。
 import { useState, type FormEvent } from 'react';
-import { purchaseOrder } 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';
 
+/**
+ * 在弹窗中维护附件列表、上传状态和提交状态。
+ * close 由列表控制弹窗关闭；run 使用 useCommand 协议返回成功布尔值，失败保留输入。
+ * 上传中的文件不能随表单提交，上传完成仍需 create 命令正式绑定。
+ */
 export function PurchaseOrderForm({ close, run }: { close: () => void; run: RunCommand }) {
   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 返回结果，不额外捕获任意抛出异常。
+   */
   async function submit(event: FormEvent<HTMLFormElement>) {
     event.preventDefault();
+    if (uploading || busy) return;
     setBusy(true);
     const data = new FormData(event.currentTarget);
     const ok = await run(
@@ -14,7 +35,10 @@ export function PurchaseOrderForm({ close, run }: { close: () => void; run: RunC
         purchaseOrder.create({
           amount: String(data.get('amount')),
           supplierPhone: String(data.get('phone')) || undefined,
+          reason: String(data.get('reason')) || undefined,
           items: [{ sku: String(data.get('sku')), qty: Number(data.get('qty')) }],
+          attachments,
+          needsSpecialistReview, reviewerIds: needsSpecialistReview ? reviewerIds : [],
         }),
       '采购单已保存为草稿',
     );
@@ -23,7 +47,7 @@ export function PurchaseOrderForm({ close, run }: { close: () => void; run: RunC
   }
   return (
     <div className="modal-backdrop">
-      <section role="dialog" aria-modal="true" aria-labelledby="new-order-title" className="modal">
+      <section role="dialog" aria-modal="true" aria-labelledby="new-order-title" className="modal purchase-order-dialog">
         <div className="section-head">
           <h2 id="new-order-title">新建采购单</h2>
           <button onClick={close} aria-label="关闭">
@@ -50,7 +74,12 @@ export function PurchaseOrderForm({ close, run }: { close: () => void; run: RunC
             <input name="phone" type="tel" maxLength={32} />
           </label>
           <p className="muted">保存后可在列表提交审批，创建人和部门会自动填写。</p>
-          <button className="primary" disabled={busy}>
+          <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 || (needsSpecialistReview && reviewerIds.length === 0)}>
             {busy ? '保存中…' : '保存草稿'}
           </button>
         </form>

package/templates/blank/docs/examples/purchase-admin/apps/web/src/modules/purchase/index.ts

@@ -1,2 +1,7 @@
+/**
+ * purchase 模块的公开入口，对 app 暴露采购列表和独立详情页。
+ * 外部组合通过本入口导入，页面、组件与内部 helper 的组织由模块自行维护。
+ */
 // 模块公开入口：应用壳只需要页面，不依赖内部表单与本地状态。
 export { PurchaseOrdersPage } from './pages/purchase-orders-page';
+export { PurchaseOrderDetailPage } from './pages/purchase-order-detail-page';

package/templates/blank/docs/examples/purchase-admin/apps/web/src/modules/purchase/lib/presentation.ts

@@ -0,0 +1,20 @@
+/**
+ * 采购页面共享的展示映射与金额格式；不承载状态迁移、权限或精确金额计算。
+ */
+// 同一业务的列表与详情共用展示口径；不把采购状态塞入全局 shared。
+/**
+ * 采购记录状态到中文名称的界面映射，状态合法性与迁移规则仍以领域声明为准。
+ */
+export const statusLabels: Record<string, string> = {
+  draft: '草稿',
+  pending_approval: '待审批',
+  approved: '已通过',
+  received: '已收货',
+  rejected: '已驳回',
+  cancelled: '已取消',
+};
+/**
+ * 把以元表示的金额字符串转为人民币格式显示；Number 转换只用于展示，不能用于账务计算。
+ */
+export const currency = (value: string) =>
+  new Intl.NumberFormat('zh-CN', { style: 'currency', currency: 'CNY' }).format(Number(value));

package/templates/blank/docs/examples/purchase-admin/apps/web/src/modules/purchase/pages/purchase-intelligence.css

@@ -0,0 +1,17 @@
+/**
+ * 采购详情的用途编辑区和审批轮次轨迹样式；实际审批状态来自 ApprovalHistory 的接口结果。
+ * 纵向步骤线表示展示层次，颜色不产生通过/退回判断；文本框允许用户按内容调整高度。
+ */
+.purchase-detail-content { min-width: 0; }
+.purchase-detail-content .panel { margin-bottom: 22px; }
+.purpose-editor { border-top: 1px solid var(--line, #e4e8df); padding: 20px 0; }
+.purpose-editor > label { display: block; font-weight: 600; margin-bottom: 12px; }
+.purpose-editor textarea { width: 100%; box-sizing: border-box; padding: 12px; border: 1px solid #d9e0d8; border-radius: 8px; font: inherit; resize: vertical; }
+.purpose-editor .actions { margin-top: 12px; justify-content: space-between; }
+.review-round { margin-top: 20px; }
+.review-round h3 { font-size: 14px; color: #36594d; }
+.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; }