@yss123/cage-cli 0.2.0 → 0.3.0

package/templates/blank/docs/examples/purchase-admin/apps/web/src/app/styles/global.css

@@ -1,3 +1,7 @@
+/**
+ * 采购应用的全局视觉与布局基础，随浏览器入口加载；依次定义主题、工作台、业务表格、表单及登录页。
+ * 模块专用样式在模块附近维护。状态类只映射已有 UI 状态，不承担权限、审批或数据计算。
+ */
 /* 暖白纸面配墨绿导航；用边线、字重和留白建立信息层次，避免装饰压过业务数据。 */
 :root {
   font-family: 'Segoe UI', 'Microsoft YaHei', sans-serif;
@@ -83,6 +87,9 @@ h3 {
   font-family: Consolas, 'Courier New', monospace;
   font-size: 12px;
 }
+/**
+ * 固定侧栏与主内容区的桌面组合；窄屏规则在文件后部覆盖布局，保留导航可达性。
+ */
 .workspace {
   display: flex;
   min-height: 100vh;
@@ -124,7 +131,7 @@ nav {
   display: grid;
   gap: 7px;
 }
-nav button {
+nav a {
   display: flex;
   align-items: center;
   gap: 16px;
@@ -134,22 +141,22 @@ nav button {
   text-align: left;
   padding: 14px 13px;
 }
-nav button span {
+nav a span {
   font-size: 10px;
   opacity: 0.6;
 }
-nav button b {
+nav a b {
   margin-left: auto;
   font-size: 11px;
 }
-nav button.selected {
+nav a.selected {
   background: var(--accent);
   color: var(--green);
 }
-nav button:hover {
+nav a:hover {
   background: #31594e;
 }
-nav button.selected:hover {
+nav a.selected:hover {
   background: #d9efa9;
 }
 .aside-bottom {
@@ -301,6 +308,9 @@ header {
 .toolbar > button {
   font-size: 11px;
 }
+/**
+ * 宽表格在容器中横向滚动，避免列内容把页面宽度撑出视口。
+ */
 .table-wrap {
   overflow: auto;
 }
@@ -470,6 +480,9 @@ input {
 input:focus {
   outline: 2px solid #b2cb8b;
 }
+/**
+ * 创建弹窗的遮罩与居中层；具体采购弹窗高度及内部滚动由模块样式补充。
+ */
 .modal-backdrop {
   position: fixed;
   inset: 0;
@@ -560,6 +573,9 @@ input:focus {
   color: var(--muted);
 }
 /* 窄屏将导航转成横向工具栏，表格保留横向滚动，操作列不会挤成不可点击的小按钮。 */
+/**
+ * 在九百像素及以下调整导航与表单布局，减少桌面侧栏对内容宽度的挤占。
+ */
 @media (max-width: 900px) {
   aside {
     position: static;
@@ -581,11 +597,11 @@ input:focus {
     display: flex;
     margin-top: 20px;
   }
-  nav button {
+  nav a {
     flex: 1;
     padding: 10px;
   }
-  nav button span {
+  nav a span {
     display: none;
   }
   .aside-bottom {
@@ -656,8 +672,72 @@ input:focus {
     padding: 10px;
   }
 }
+/**
+ * 尊重系统减少动画偏好，避免将过渡效果作为理解操作反馈的唯一依据。
+ */
 @media (prefers-reduced-motion: reduce) {
   * {
     transition: none !important;
   }
 }
+
+/* 链接保持原生导航语义，单据编号可复制地址或在新标签页打开。 */
+.record-link {
+  color: var(--green);
+  font-weight: 600;
+  text-decoration: underline;
+  text-decoration-color: #c6d5b5;
+  text-underline-offset: 4px;
+}
+.record-link:hover {
+  text-decoration-color: var(--green);
+}
+.record-facts {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  margin: 0;
+  padding: 8px 24px;
+  gap: 0 36px;
+}
+.record-facts > div {
+  padding: 22px 0;
+  border-bottom: 1px solid var(--line);
+}
+.record-facts dt {
+  color: var(--muted);
+  font-size: 11px;
+  margin-bottom: 11px;
+}
+.record-facts dd {
+  margin: 0;
+  font-size: 14px;
+  overflow-wrap: anywhere;
+}
+.entry-grid {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  gap: 18px;
+}
+.entry-grid > a {
+  padding: 30px 25px;
+  background: #fff;
+  border: 1px solid var(--line);
+  border-radius: 6px;
+}
+.entry-grid > a:hover {
+  border-color: #99b47f;
+  background: #fafdf6;
+}
+.entry-grid small {
+  color: var(--muted);
+  font-size: 10px;
+  letter-spacing: 1px;
+}
+.entry-grid h2 {
+  margin: 24px 0 14px;
+}
+.entry-grid p {
+  font-size: 12px;
+  color: var(--muted);
+  line-height: 1.8;
+}

package/templates/blank/docs/examples/purchase-admin/apps/web/src/app/use-session.ts

@@ -0,0 +1,43 @@
+/**
+ * 应用会话生命周期：首次加载 /me，并把 SDK 的账号退出或失效通知同步到路由状态。
+ * 与 URL 路由分离，网络故障不会被误判成未登录；查询缓存不能跨账号继续使用。
+ */
+// 应用会话与 URL 导航分别管理：401 才进入登录，网络故障保留原地址并允许重试。
+import { useCallback, useEffect, useState } from 'react';
+import { useQueryClient } from '@tanstack/react-query';
+import { client, loadMe } from '@app/contracts';
+
+/**
+ * 在 QueryClientProvider 内使用。挂载时恢复用户，卸载时解除 SDK 订阅。
+ * 返回 session：loading 为恢复中，guest 为未认证，ready 为已加载身份，error 为其他恢复失败。
+ * restore 可重试恢复；onLogin/onLogout 由已完成认证动作的页面调用，只更新应用状态。
+ * 账号失效时发起取消查询并清空缓存；这里不负责服务端退出操作，也不保证取消已提交的业务命令。
+ */
+export function useSession() {
+  const [session, setSession] = useState<'loading' | 'guest' | 'ready' | 'error'>('loading');
+  const cache = useQueryClient();
+  /**
+   * 每次恢复先显示 loading，再按 loadMe 的明确结果分类；只有 UNAUTHENTICATED 进入 guest。
+   */
+  const restore = useCallback(async () => {
+    setSession('loading');
+    const result = await loadMe();
+    setSession(result.ok ? 'ready' : result.code === 'UNAUTHENTICATED' ? 'guest' : 'error');
+  }, []);
+
+  useEffect(() => {
+    const unsubscribe = client.subscribe((_snapshot, reason) => {
+      if (reason === 'loaded') return;
+      // 先取消在途查询，再清除上一账号的缓存；路由守卫保留 URL 并决定登录回跳。
+      void cache.cancelQueries();
+      cache.clear();
+      setSession('guest');
+    });
+    void restore();
+    return () => {
+      unsubscribe();
+    };
+  }, [cache, restore]);
+
+  return { session, restore, onLogin: () => setSession('ready'), onLogout: () => setSession('guest') };
+}

package/templates/blank/docs/examples/purchase-admin/apps/web/src/app/workspace-layout.tsx

@@ -1,35 +1,65 @@
+/**
+ * 已登录工作台的公共外壳：导航、当前账号、退出登录、Outlet 和唯一的业务助理。
+ * 业务页面经路由模块入口进入 Outlet；系统管理使用独立链接。
+ * 助理随页面更新语义快照，账号退出成功后清空查询缓存。
+ */
 // 应用壳组合模块公开入口，只持有导航和会话；表单、筛选、命令留在各业务模块。
 import { useState } from 'react';
+import { Link, NavLink, Outlet, useLocation } from 'react-router-dom';
 import { useQueryClient } from '@tanstack/react-query';
 import { client, currentUser } from '@app/contracts';
-import { PurchaseOrdersPage } from '../modules/purchase';
-import { InventoryPage } from '../modules/inventory';
-import { ApprovalTasksPage, useApprovalTasks } from '../modules/approval';
+import { useApprovalTasks } from '../modules/approval';
+import { errorMessage } from '../shared/lib/error-message';
+import { AssistantScope } from '../shared/ui/assistant-scope';
 
+/**
+ * 渲染工作台公共区域并把子路由放入内容区。
+ * @param onLogout SDK 退出成功后通知 app 切换会话状态的回调。
+ * 本壳提供固定导航入口；目标路由和服务端分别处理页面访问与真实请求的权限。
+ * location.key 标识一次页面导航，用于防止新页面沿用上一张单据的助理上下文。
+ */
 export function WorkspaceLayout({ onLogout }: { onLogout: () => void }) {
-  const [tab, setTab] = useState<'orders' | 'tasks' | 'stock'>('orders');
+  const [error, setError] = useState('');
+  const [busy, setBusy] = useState(false);
+  const location = useLocation();
+  const page = location.pathname.startsWith('/procurement/orders/')
+    ? '采购单详情'
+    : location.pathname === '/procurement/orders'
+      ? '采购单'
+      : location.pathname === '/approvals'
+        ? '审批待办'
+        : location.pathname === '/inventory'
+          ? '库存台账'
+          : location.pathname === '/workspace'
+            ? '工作台'
+            : '页面';
   const tasks = useApprovalTasks();
   const cache = useQueryClient();
   return (
+    <AssistantScope pageKey={location.key} fallback={{
+      context: { page: { id: 'workspace-page', title: page, kind: 'custom', route: location.pathname + location.search } },
+      suggestions: ['我在当前页面可以做什么？', '帮我查看待处理的审批'],
+    }}>
     <div className="workspace">
       <aside>
-        <a className="brand" href="/">
+        <Link className="brand" to="/workspace">
           cage<span>采购工作台</span>
-        </a>
+        </Link>
         <span className="nav-caption">工作空间</span>
         <nav>
           {(
             [
-              ['orders', '01', '采购单'],
-              ['tasks', '02', '审批待办'],
-              ['stock', '03', '库存台账'],
+              ['/workspace', '00', '工作台'],
+              ['/procurement/orders', '01', '采购单'],
+              ['/approvals', '02', '审批待办'],
+              ['/inventory', '03', '库存台账'],
             ] as const
           ).map(([key, no, label]) => (
-            <button key={key} className={tab === key ? 'selected' : ''} onClick={() => setTab(key)}>
+            <NavLink key={key} to={key} className={({ isActive }) => (isActive ? 'selected' : '')}>
               <span>{no}</span>
               {label}
-              {key === 'tasks' && <b>{tasks.data?.length ?? 0}</b>}
-            </button>
+              {key === '/approvals' && <b>{tasks.data?.length ?? 0}</b>}
+            </NavLink>
           ))}
         </nav>
         <div className="aside-bottom">
@@ -43,10 +73,15 @@ export function WorkspaceLayout({ onLogout }: { onLogout: () => void }) {
           </div>
           <button
             className="logout"
+            disabled={busy}
             onClick={async () => {
-              await client.logout();
-              cache.clear();
-              onLogout();
+              setBusy(true);
+              const result = await client.logout();
+              setBusy(false);
+              if (result.ok) {
+                cache.clear();
+                onLogout();
+              } else setError(errorMessage(result));
             }}
           >
             退出登录
@@ -55,16 +90,20 @@ export function WorkspaceLayout({ onLogout }: { onLogout: () => void }) {
       </aside>
       <main className="content">
         <header>
-          <span>采购管理 / {tab === 'orders' ? '采购单' : tab === 'tasks' ? '审批待办' : '库存台账'}</span>
+          <span>采购管理 / {page}</span>
           <span className="live-dot">团队工作空间</span>
         </header>
-        {tab === 'orders' && <PurchaseOrdersPage pendingTasks={tasks.data?.length} />}
-        {tab === 'tasks' && <ApprovalTasksPage />}
-        {tab === 'stock' && <InventoryPage />}
+        {error && (
+          <p className="error" role="alert">
+            {error}
+          </p>
+        )}
+        <Outlet />
         <div className="page-footer">
           CAGE / PROCUREMENT WORKSPACE<span>业务操作均受权限与数据范围约束</span>
         </div>
       </main>
     </div>
+    </AssistantScope>
   );
 }

package/templates/blank/docs/examples/purchase-admin/apps/web/src/main.tsx

@@ -1,3 +1,8 @@
+/**
+ * 采购 Web 的浏览器启动入口：创建共享查询缓存，将应用路由挂到 root DOM 节点。
+ * 契约客户端负责网络与会话协议，页面只在 Provider 内消费 hooks；这里不注册领域或启动后端。
+ * 全局样式在此加载，账号切换时的缓存清理由 useSession 和应用壳负责。
+ */
 // 唯一浏览器启动入口：挂载 React、全局 Provider 和样式；业务从 app 组合进入。
 import { createRoot } from 'react-dom/client';
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

package/templates/blank/docs/examples/purchase-admin/apps/web/src/modules/approval/hooks/use-approval-tasks.ts

@@ -1,13 +1,24 @@
+/**
+ * 当前账号审批待办的共享查询入口，供审批页及 app 的数量组合复用同一缓存键。
+ * 任务分配与实际决策授权均来自服务端，不从角色名称在前端自行推导。
+ */
 import { useQuery } from '@tanstack/react-query';
 import { client } from '@app/contracts';
 import { errorMessage } from '../../../shared/lib/error-message';
 
+/**
+ * 待办列表展示所需字段：id 是任务标识，businessKey 是业务记录键，title 为任务标题，createdAt 为创建时间字符串。
+ */
 type Task = { id: string; businessKey: string; title: string; createdAt: string };
 
 /**
  * 审批是框架通用接口，不属于某个聚合的生成方法，因此请求封装在审批模块内。
  * 待办页面和导航角标复用同一缓存键，调用方不需要了解接口地址或响应形状。
  */
+/**
+ * 在 React Query 中读取审批待办，非 ok 结果转为查询错误。
+ * 返回查询状态及 refetch；空数组表示当前结果没有待办，未加载或失败不等同于零条。
+ */
 export function useApprovalTasks() {
   return useQuery({
     queryKey: ['tasks'],

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

@@ -1,2 +1,6 @@
+/**
+ * approval 模块的公开入口，对 app 暴露审批待办页与共享待办查询。
+ * 外部组合通过本入口导入，页面、组件与内部 helper 的组织由模块自行维护。
+ */
 export { ApprovalTasksPage } from './pages/approval-tasks-page';
 export { useApprovalTasks } from './hooks/use-approval-tasks';

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

@@ -1,15 +1,29 @@
+/**
+ * 个人审批待办页，展示服务端分配的任务并调用标准审批接口提交结论。
+ * 通过 app 注入业务详情链接，避免审批模块直接依赖采购页面文件。
+ */
 // 审批待办独立成页；结论调用框架审批接口，领域约束仍在后端执行。
 import { client } from '@app/contracts';
+import { Link } from 'react-router-dom';
 import { useCommand } 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';
 
-export function ApprovalTasksPage() {
+/**
+ * 查询待办并区分加载、失败与已清空状态；按钮使用 useCommand 共享忙碌及消息反馈。
+ * @param orderUrl 由 app 将 businessKey 转为采购详情 URL 的函数。
+ * 通过/驳回/退回对应不同后端流程，页面不直接更新单据状态；成功后刷新查询取得真实任务变化。
+ */
+export function ApprovalTasksPage({ orderUrl }: { orderUrl: (id: string) => string }) {
   const tasks = useApprovalTasks();
   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} 项，以重新查询的待办为准。` : '审批待办正在读取或暂时不可用。' }],
+      }} suggestions={['查看当前待我处理的审批', '通过、驳回和退回修改有什么区别？']} />
       <PageHeading eyebrow="APPROVAL INBOX" title="审批待办" description="处理分配给你的审批任务。" />
       {message && <Notice onClose={clearMessage}>{message}</Notice>}
       <section className="panel">
@@ -26,12 +40,17 @@ export function ApprovalTasksPage() {
               <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"

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,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/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/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; }