@yss123/cage-cli 0.2.0 → 0.3.0

package/templates/app/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/app/apps/web/src/modules/inventory/index.ts

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

package/templates/app/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/app/apps/web/src/modules/purchase/components/approval-history.tsx

@@ -0,0 +1,32 @@
+/**
+ * 采购单审批轨迹展示，按单据与版本读取服务端整理后的轮次和步骤。
+ * AI 与人工状态使用同一记录来源；受限详情不显示理由，不能根据缺少细节推断未执行。
+ */
+import { useQuery } from '@tanstack/react-query';
+import { client } from '@yss123/cage-client';
+
+/**
+ * 运行、步骤与人工待办状态的展示映射，未知状态仍由页面按实际值处理。
+ */
+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 });
+  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?.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>
+        {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>)}
+  </section>;
+}

package/templates/app/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/app/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/app/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/app/apps/web/src/modules/purchase/components/purchase-order-form.tsx

@@ -1,12 +1,30 @@
+/**
+ * 采购草稿创建表单，收集物料、数量、元金额字符串、用途、电话和已上传附件。
+ * 创建人、部门和初始状态由领域及内核确定；浏览器表单限制只承担输入体验。
+ */
 // 只处理采购草稿输入；状态迁移、创建人和权限仍由领域命令决定。
 import { useState, type FormEvent } from 'react';
-import { purchaseOrder } from '@app/contracts';
+import { purchaseOrder, PurchaseOrderFileFields } from '@app/contracts';
 import type { RunCommand } from '../../../shared/hooks/use-command';
+import { AttachmentUpload } from '../../../shared/ui/attachment-upload';
+import './purchase-order-form.css';
 
+/**
+ * 在弹窗中维护附件列表、上传状态和提交状态。
+ * 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);
+  /**
+   * 读取 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 +32,9 @@ 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,
         }),
       '采购单已保存为草稿',
     );
@@ -23,7 +43,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 +70,9 @@ 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>
+          <AttachmentUpload command="PurchaseOrder.create" field="attachments" policy={PurchaseOrderFileFields.attachments} value={attachments} onChange={setAttachments} onBusyChange={setUploading} />
+          <button className="primary" disabled={busy || uploading}>
             {busy ? '保存中…' : '保存草稿'}
           </button>
         </form>

package/templates/app/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/app/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/app/apps/web/src/modules/purchase/pages/purchase-intelligence.css

@@ -0,0 +1,15 @@
+/**
+ * 采购详情的用途编辑区和审批轮次轨迹样式；实际审批状态来自 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; }

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

@@ -0,0 +1,154 @@
+/**
+ * 采购详情路由，直接从地址栏校验单据 ID 并独立读取，支持刷新与深链接。
+ * 详情由真实契约数据构建，附件、审批轨迹和助理上下文通过同模块组件组合。
+ */
+// 详情通过 URL 中的记录 ID 重新读取安全接口；刷新或新标签页不依赖列表的内存状态。
+import { Link, useParams } from 'react-router-dom';
+import { useEffect, useState } from 'react';
+import { can, PurchaseOrderSchema, purchaseOrder, usePurchaseOrder } from '@app/contracts';
+import { useCommand } from '../../../shared/hooks/use-command';
+import { PageState, QueryFailure } from '../../../shared/ui/page-state';
+import { PageHeading } from '../../../shared/ui/page-heading';
+import { Notice } from '../../../shared/ui/notice';
+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 './purchase-intelligence.css';
+
+const list = '/procurement/orders';
+
+/**
+ * 从 URL 参数获取 id，使用生成 schema 校验；无效地址给返回列表入口。
+ * 有效 ID 作为 OrderDetail 的 key，使切换记录时重置本地未保存用途草稿。
+ */
+export function PurchaseOrderDetailPage() {
+  const { id } = useParams();
+  const parsed = PurchaseOrderSchema.shape.id.safeParse(id);
+  if (!parsed.success)
+    return <PageState title="单据地址无效" description="请从采购单列表选择有效单据。" to={list} />;
+  return <OrderDetail key={parsed.data} id={parsed.data} />;
+}
+
+/**
+ * 按 id 读取单据；待审批期间定时刷新，错误不作为空记录处理。
+ * 用途草稿用 null 区分尚未编辑与主动清空；保存成功后回到服务端数据，命令使用当前 version。
+ * 助理收到明确区分的已保存 record 与未保存 draft；审批历史及附件仍各自按权限读取。
+ */
+function OrderDetail({ id }: { id: string }) {
+  const query = usePurchaseOrder(id);
+  const [draftReason, setDraftReason] = useState<string | null>(null);
+  useEffect(() => {
+    if (query.data?.status !== 'pending_approval') return;
+    const timer = setInterval(() => void query.refetch(), 1500);
+    return () => clearInterval(timer);
+  }, [query.data?.status, query.refetch]);
+  const { run, busy, message, clearMessage } = useCommand();
+  if (query.isPending)
+    return (
+      <p className="empty" role="status">
+        正在读取采购单…
+      </p>
+    );
+  if (query.isError) return <QueryFailure error={query.error} to={list} retry={() => void query.refetch()} />;
+  const order = query.data;
+  return (
+    <>
+      <PageHeading
+        eyebrow={`PO-${order.id.slice(0, 8).toUpperCase()}`}
+        title="采购单详情"
+        description="单据内容与最新状态，以服务端记录为准。"
+      >
+        <Link className="route-link" to={list}>
+          ← 返回采购单
+        </Link>
+      </PageHeading>
+      {message && <Notice onClose={clearMessage}>{message}</Notice>}
+      <div className="purchase-detail-content"><section className="panel">
+        <div className="section-head">
+          <span className={`badge ${order.status}`}>{statusLabels[order.status]}</span>
+          <div className="actions">
+            {order.status === 'draft' && can('PurchaseOrder.submit') && (
+              <button
+                className="primary"
+                disabled={busy}
+                onClick={() => run(() => purchaseOrder.submit(id, order.version), '已提交审批')}
+              >
+                提交审批
+              </button>
+            )}
+            {['draft', 'pending_approval', 'approved'].includes(order.status) &&
+              can('PurchaseOrder.cancel') && (
+                <button
+                  disabled={busy}
+                  onClick={() => run(() => purchaseOrder.cancel(id, order.version), '采购单已取消')}
+                >
+                  取消采购单
+                </button>
+              )}
+          </div>
+        </div>
+        <dl className="record-facts">
+          <div>
+            <dt>采购金额</dt>
+            <dd className="amount">{currency(order.amount)}</dd>
+          </div>
+          <div>
+            <dt>ERP 单号</dt>
+            <dd>{order.erpNo ?? '尚未同步'}</dd>
+          </div>
+          <div>
+            <dt>供应商电话</dt>
+            <dd>{order.supplierPhone ?? '未填写'}</dd>
+          </div>
+          <div>
+            <dt>创建时间</dt>
+            <dd>{new Date(order.createdAt).toLocaleString('zh-CN')}</dd>
+          </div>
+          <div>
+            <dt>单据 ID</dt>
+            <dd className="mono">{order.id}</dd>
+          </div>
+          <div>
+            <dt>当前版本</dt>
+            <dd>{order.version}</dd>
+          </div>
+        </dl>
+        <div className="purpose-editor"><label htmlFor="purchase-purpose">采购用途与必要性</label>
+          {order.status === 'draft' && can('PurchaseOrder.explainPurpose') ? <>
+            <textarea id="purchase-purpose" rows={4} maxLength={2000} value={draftReason ?? order.reason ?? ''} onChange={e => setDraftReason(e.target.value)} placeholder="说明用于什么工作、需要哪些物料以及采购原因" />
+            <div className="actions"><small className="muted">助理可检查此处尚未保存的内容。</small><button disabled={busy || draftReason === null || !draftReason.trim()} onClick={async () => {
+              if (await run(() => purchaseOrder.explainPurpose(id, { reason: draftReason! }, order.version), '采购用途已保存')) setDraftReason(null);
+            }}>保存用途</button></div>
+          </> : <p>{order.reason || '尚未填写用途'}</p>}
+        </div>
+        <OrderAttachments order={order} />
+        <div className="section-head">
+          <h2>采购物料</h2>
+          <span className="muted">{order.items.length} 项</span>
+        </div>
+        <table>
+          <thead>
+            <tr>
+              <th>物料编码</th>
+              <th>采购数量</th>
+            </tr>
+          </thead>
+          <tbody>
+            {order.items.map((item, index) => (
+              <tr key={`${item.sku}-${index}`}>
+                <td className="mono">{item.sku}</td>
+                <td>{item.qty}</td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </section>
+      <ApprovalHistory id={id} version={order.version} pending={order.status === 'pending_approval'} /></div>
+      <PurchaseAssistantContext context={{ page: { id: 'purchase-order-detail', title: '采购单详情', kind: 'detail', route: `/procurement/orders/${id}` },
+        subject: { aggregate: 'PurchaseOrder', id, observedVersion: order.version },
+        ...(draftReason !== null && order.status === 'draft' ? { draft: { command: 'PurchaseOrder.explainPurpose', values: { reason: draftReason }, baseVersion: order.version } } : {}),
+      }} suggestions={['检查当前采购用途是否符合审核要求', '这张采购单现在到哪一步了？', '帮我提交当前采购单']} />
+    </>
+  );
+}

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

@@ -1,26 +1,40 @@
+/**
+ * 采购列表页：从 URL 恢复状态筛选与页码，查询真实单据，提供创建、提交、取消和后台导出入口。
+ * 通过采购模块入口进入路由；审批待办统计由 app 注入，查询和写入均消费生成契约。
+ */
 // 采购页面拥有筛选、分页、新建和导出状态；其他模块不用了解这些实现细节。
 import { useState } from 'react';
+import { Link, useSearchParams } from 'react-router-dom';
 import { can, client, purchaseOrder, usePurchaseOrderList, useTransfer } from '@app/contracts';
 import { useCommand } from '../../../shared/hooks/use-command';
 import { errorMessage } from '../../../shared/lib/error-message';
 import { Notice } from '../../../shared/ui/notice';
 import { PageHeading } from '../../../shared/ui/page-heading';
+import { QueryFailure } from '../../../shared/ui/page-state';
 import { PurchaseOrderForm } from '../components/purchase-order-form';
+import { currency, statusLabels } from '../lib/presentation';
+import { PurchaseAssistantContext } from '../components/purchase-assistant-context';
 
-const statusLabels: Record<string, string> = {
-  draft: '草稿',
-  pending_approval: '待审批',
-  approved: '已通过',
-  received: '已收货',
-  rejected: '已驳回',
-  cancelled: '已取消',
-};
-const currency = (value: string) =>
-  new Intl.NumberFormat('zh-CN', { style: 'currency', currency: 'CNY' }).format(Number(value));
-
+/**
+ * 按状态及每页十条读取服务端列表，加载、失败和空结果分别呈现。
+ * pendingTasks 可省略，表示待办数量尚不可用；创建弹窗和导出任务 ID 只保存在当前页面状态。
+ * 提交/取消携带读取到的 version，服务端负责并发、状态及授权检查；导出完成后才显示下载入口。
+ */
 export function PurchaseOrdersPage({ pendingTasks }: { pendingTasks?: number }) {
-  const [status, setStatus] = useState('');
-  const [page, setPage] = useState(1);
+  // 可分享、刷新恢复的列表条件进入 URL；弹窗和提交中的临时状态继续留在组件里。
+  const [search, setSearch] = useSearchParams();
+  const status = search.get('status') ?? '';
+  const requestedPage = Number(search.get('page') ?? 1);
+  const page = Number.isSafeInteger(requestedPage) && requestedPage > 0 ? requestedPage : 1;
+  /**
+   * 更新 status/page 查询参数并保留其他参数；第一页省略 page。切换条件由调用方传入第一页。
+   */
+  function filter(nextStatus: string, nextPage: number) {
+    const params = new URLSearchParams(search);
+    nextStatus ? params.set('status', nextStatus) : params.delete('status');
+    nextPage === 1 ? params.delete('page') : params.set('page', String(nextPage));
+    setSearch(params);
+  }
   const [creating, setCreating] = useState(false);
   const [exporting, setExporting] = useState(false);
   const [exportId, setExportId] = useState<string | null>(null);
@@ -29,6 +43,10 @@ export function PurchaseOrdersPage({ pendingTasks }: { pendingTasks?: number })
   const { run, busy, message, clearMessage } = useCommand();
   // 列表和统计来自服务端；待办数量由 app 组合层传入，采购模块不依赖审批页面。
   const orders = usePurchaseOrderList({ status, page, pageSize: 10, sort: '-createdAt' });
+  /**
+   * 提交当前状态筛选的后台导出任务。成功只取得任务 ID，由 useTransfer 继续观察完成/失败/过期。
+   * 不把任务接受当作 CSV 已可下载，也不只导出当前十条表格数据。
+   */
   async function exportCsv() {
     setExporting(true);
     setExportError('');
@@ -37,6 +55,15 @@ export function PurchaseOrdersPage({ pendingTasks }: { pendingTasks?: number })
     if (result.ok) setExportId(result.data.id);
     else setExportError(errorMessage(result));
   }
+  if (orders.isError)
+    return (
+      <QueryFailure
+        error={orders.error}
+        to="/workspace"
+        label="返回工作台"
+        retry={() => void orders.refetch()}
+      />
+    );
   return (
     <>
       <PageHeading eyebrow="PURCHASE ORDERS" title="采购单" description="每一张单据的进展，清晰可见。">
@@ -104,8 +131,7 @@ export function PurchaseOrdersPage({ pendingTasks }: { pendingTasks?: number })
                 className={status === value ? 'active' : ''}
                 key={value}
                 onClick={() => {
-                  setStatus(value);
-                  setPage(1);
+                  filter(value, 1);
                 }}
               >
                 {label}
@@ -120,10 +146,6 @@ export function PurchaseOrdersPage({ pendingTasks }: { pendingTasks?: number })
         </div>
         {orders.isPending ? (
           <p className="empty">正在读取采购单…</p>
-        ) : orders.isError ? (
-          <p role="alert" className="error">
-            读取失败：{orders.error.message}
-          </p>
         ) : (
           <>
             <div className="table-wrap">
@@ -142,7 +164,12 @@ export function PurchaseOrdersPage({ pendingTasks }: { pendingTasks?: number })
                   {orders.data.items.map((order) => (
                     <tr key={order.id}>
                       <td>
-                        <strong className="mono">PO-{order.id.slice(0, 8).toUpperCase()}</strong>
+                        <Link
+                          className="record-link mono"
+                          to={`/procurement/orders/${encodeURIComponent(order.id)}`}
+                        >
+                          PO-{order.id.slice(0, 8).toUpperCase()}
+                        </Link>
                         <small>{new Date(order.createdAt).toLocaleString('zh-CN')}</small>
                       </td>
                       <td>{order.items.map((i) => `${i.sku} × ${i.qty}`).join('、')}</td>
@@ -193,10 +220,10 @@ export function PurchaseOrdersPage({ pendingTasks }: { pendingTasks?: number })
                 共 {orders.data.total} 单 · 第 {page} 页
               </span>
               <div>
-                <button disabled={page === 1} onClick={() => setPage(page - 1)}>
+                <button disabled={page === 1} onClick={() => filter(status, page - 1)}>
                   上一页
                 </button>
-                <button disabled={page * 10 >= orders.data.total} onClick={() => setPage(page + 1)}>
+                <button disabled={page * 10 >= orders.data.total} onClick={() => filter(status, page + 1)}>
                   下一页
                 </button>
               </div>
@@ -205,6 +232,9 @@ export function PurchaseOrdersPage({ pendingTasks }: { pendingTasks?: number })
         )}
       </section>
       {creating && <PurchaseOrderForm close={() => setCreating(false)} run={run} />}
+      <PurchaseAssistantContext context={{ page: { id: 'purchase-orders', title: '采购单列表', kind: 'list', route: `/procurement/orders?${search}` },
+        view: { aggregate: 'PurchaseOrder', input: { status, page, pageSize: 10 }, visibleIds: orders.data?.items.map(o => o.id) ?? [] },
+      }} suggestions={['汇总本月我有权限查看的采购金额', '采购单的审批规则是什么？']} />
     </>
   );
 }

package/templates/app/apps/web/src/modules/workspace/index.ts

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

package/templates/app/apps/web/src/modules/workspace/pages/home-page.tsx

@@ -0,0 +1,44 @@
+/**
+ * 采购工作台首页，提供采购、审批和库存的固定业务入口，不伪造业务统计。
+ * 实际记录与待办在对应页面通过生成契约读取，系统管理由独立页面负责。
+ */
+import { Link } from 'react-router-dom';
+import { PageHeading } from '../../../shared/ui/page-heading';
+import { AssistantPage } from '../../../shared/ui/assistant-scope';
+
+// 工作台展示实际配置的业务入口，不制造演示统计；访问权限由目标路由及接口检查。
+/**
+ * 渲染导航卡片，链接进入各模块独立 URL。
+ * 本页不按能力隐藏卡片，进入页面后仍需通过路由守卫和服务端检查。
+ */
+export function HomePage() {
+  return (
+    <>
+      <AssistantPage context={{ page: { id: 'workspace', title: '采购工作台', kind: 'dashboard', route: '/workspace' },
+        visibleContent: [{ id: 'workspace-entries', text: '工作台提供采购单、审批待办和库存台账入口。' }],
+      }} suggestions={['我有哪些待处理的审批？', '了解采购单的完整处理流程', '汇总本月我能查看的采购金额']} />
+      <PageHeading
+        eyebrow="WORKSPACE"
+        title="采购工作台"
+        description="从采购、审批到库存，每个页面都有可以收藏和分享的地址。"
+      />
+      <section className="entry-grid">
+        <Link to="/procurement/orders">
+          <small>01 / PROCUREMENT</small>
+          <h2>采购单 ↗</h2>
+          <p>查看单据、新建采购与跟踪处理进度。</p>
+        </Link>
+        <Link to="/approvals">
+          <small>02 / APPROVALS</small>
+          <h2>审批待办 ↗</h2>
+          <p>处理分配给你的任务，直接打开关联单据。</p>
+        </Link>
+        <Link to="/inventory">
+          <small>03 / INVENTORY</small>
+          <h2>库存台账 ↗</h2>
+          <p>查看物料与登记数量。</p>
+        </Link>
+      </section>
+    </>
+  );
+}