@yss123/cage-cli 0.2.0 → 0.3.1

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

@@ -0,0 +1,156 @@
+/**
+ * 采购详情路由，直接从地址栏校验单据 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 { OrderReviewers } from '../components/order-reviewers';
+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>
+        <OrderReviewers order={order} />
+        <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/blank/docs/examples/purchase-admin/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,14 @@ 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>
+                        {/* 用途摘要帮助采购员辨认单据；完整材料仍在详情页按安全读权限展示。 */}
+                        {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>
@@ -193,10 +222,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 +234,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/blank/docs/examples/purchase-admin/apps/web/src/modules/workspace/index.ts

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

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

package/templates/blank/docs/examples/purchase-admin/apps/web/src/shared/hooks/use-command.ts

@@ -1,8 +1,16 @@
+/**
+ * 页面命令调用的轻量状态封装，统一提交中状态、成功反馈和领域错误文案。
+ * 消费契约客户端返回的 CageResult；不会自行写数据库或将前端显示状态当作授权。
+ */
 import { useState } from 'react';
 import { useQueryClient } from '@tanstack/react-query';
 import type { CageResult } from '@app/contracts';
 import { errorMessage } from '../lib/error-message';
 
+/**
+ * 页面传入 action 执行一次命令，success 为业务成功提示。
+ * Promise<boolean> 只表示本次结果是否 ok，供表单决定关闭或保留草稿；调用者仍需提供目标和版本。
+ */
 export type RunCommand = (
   action: () => Promise<CageResult<unknown, string>>,
   success: string,
@@ -12,6 +20,11 @@ export type RunCommand = (
  * 页面间复用提交状态和结果提示，不包含采购或库存的业务判断。
  * 成功后使查询缓存失效，让列表从服务端重新读取版本和状态；写入仍由生成 SDK 完成。
  */
+/**
+ * 返回 run、busy、message 和 clearMessage，供按钮禁用与结果提示复用。
+ * run 等待 action 返回 CageResult 后解除 busy，成功时请求刷新查询缓存，失败时保留错误文案。
+ * 本封装没有捕获 action 抛出的异常；action 应遵守客户端的结果协议，不能把它当作任意异步任务的异常屏障。
+ */
 export function useCommand() {
   const cache = useQueryClient();
   const [busy, setBusy] = useState(false);

package/templates/blank/docs/examples/purchase-admin/apps/web/src/shared/lib/error-message.ts

@@ -1,14 +1,28 @@
+/**
+ * 把契约命令的失败结果转换为页面提示，集中维护本应用的错误码文案。
+ * 请求追踪标识只用于排错关联，不能用显示文案代替对 ok/code 的控制流判断。
+ */
 import type { CageResult } from '@app/contracts';
 
 /** 将框架错误码转换成操作提示，保留 requestId 供用户向维护人员反馈。 */
+/**
+ * 选取 domainCode（缺省时取 code）查文案，未知值保留错误码，并在存在 requestId 时附上短追踪标识。
+ * @param r 已经判定 ok 为 false 的客户端结果，不接收成功数据。
+ * @returns 适合 Notice 展示的错误描述；不会重试命令或修改结果。
+ */
 export function errorMessage(r: Extract<CageResult<unknown, string>, { ok: false }>): string {
   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/blank/docs/examples/purchase-admin/apps/web/src/shared/lib/navigation.ts

@@ -0,0 +1,21 @@
+/**
+ * 登录回跳的应用边界：只接受本应用的业务路径，阻止外站及认证/API/静态资源路径回跳。
+ * 由路由组合层调用，纯解析 URL 字符串，不发起导航或网络请求。
+ */
+/** 登录回跳只接受本应用页面；固定基址只用于解析，不会发起网络请求。 */
+/**
+ * 提取 search 中的 returnTo，使用固定解析基准检查同源路径并排除保留前缀。
+ * @param search 登录页查询字符串，可含 URL 编码的 returnTo。
+ * @param fallback 缺失、格式不合法或越界时返回的可信业务首页。
+ * @returns 可回跳路径，保留其查询参数与 hash；不返回外站 URL。
+ */
+export function loginReturnTo(search: string, fallback: string): string {
+  const requested = new URLSearchParams(search).get('returnTo');
+  const origin = 'https://cage.local';
+  if (!requested?.startsWith('/') || !URL.canParse(requested, origin)) return fallback;
+  const url = new URL(requested, origin);
+  // 保留查询条件和锚点；阻止外站跳转、登录循环及把服务端入口当成 React 页面。
+  if (url.origin !== origin || /^\/(login|admin|api|auth|hooks|assets)(\/|$)/.test(url.pathname))
+    return fallback;
+  return url.pathname + url.search + url.hash;
+}

package/templates/blank/docs/examples/purchase-admin/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/blank/docs/examples/purchase-admin/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/blank/docs/examples/purchase-admin/apps/web/src/shared/ui/assistant-markdown.tsx

@@ -0,0 +1,19 @@
+/**
+ * 助理输出的 Markdown 展示边界，支持 GFM 表格及链接，并跳过原始 HTML。
+ * 图片转换为纯文字说明，避免模型文本直接触发图片加载；业务状态仍由真实查询呈现。
+ */
+import Markdown from 'react-markdown';
+import remarkGfm from 'remark-gfm';
+
+/** 模型文字是不可信内容：支持 Markdown/GFM，不执行 HTML，也不自动加载模型给出的远端图片。 */
+/**
+ * 将 children 中的模型文本渲染为受限 Markdown；外链使用独立窗口和 noopener 等关系属性。
+ * 只负责显示，不执行代码块、不把文本转成业务命令，也不对内容的事实准确性背书。
+ */
+export function AssistantMarkdown({ children }: { children: string }) {
+  return <div className="assistant-markdown"><Markdown remarkPlugins={[remarkGfm]} skipHtml components={{
+    a: ({ children, href }) => <a href={href} target="_blank" rel="noopener noreferrer">{children}</a>,
+    img: ({ alt }) => <span className="assistant-image-label">[图片：{alt || '未提供说明'}]</span>,
+    table: ({ children }) => <div className="assistant-table"><table>{children}</table></div>,
+  }}>{children}</Markdown></div>;
+}