@yss123/cage-cli 0.2.0 → 0.3.0

package/templates/app/_gitignore

@@ -1,6 +1,7 @@
 node_modules/
 dist/
 .cage/
+.cage-files/
 generated/
 .env
 .env.*

package/templates/app/apps/api/package.json

@@ -10,7 +10,7 @@
   },
   "dependencies": {
     "@app/domain": "workspace:*",
-    "@yss123/cage-http": "0.2.0",
-    "@yss123/cage-connectors": "0.2.0"
+    "@yss123/cage-http": "0.3.0",
+    "@yss123/cage-connectors": "0.3.0"
   }
 }

package/templates/app/apps/api/src/main.ts

@@ -1,9 +1,13 @@
 // 启动入口只装配框架：认证、业务路由和 /admin 都由 createServer 提供。
 // WEB_DIR 在部署镜像中指向 Vite 构建产物；本地由 Vite 独立提供前端。
+// 进程启动只建立服务，不迁移结构、不初始化账号；这些操作由受控 CLI 流程提前完成。
+// 声明中启用的 AI、审批与文件接口由框架挂载，后台事件消费仍需要独立 worker 进程。
 import { createServer } from '@yss123/cage-http';
 import * as domain from '@app/domain';
 
-const server = createServer({ domain, webDir: process.env.WEB_DIR, title: 'Cage 采购工作台' });
+// 默认不接受转发头；部署在代理后时，仅在这里填写实际可信代理的地址或网段。
+const server = createServer({ domain, webDir: process.env.WEB_DIR, title: 'Cage 采购工作台', trustProxy: false });
+// listen 先等待路由、扩展与授权通知初始化；失败直接拒绝顶层启动，不伪装为已就绪。
 await server.listen();
 // 退出时释放数据库池及 LISTEN 连接，部署滚动替换时不会留下旧连接。
 process.once('SIGINT', () => void server.close());

package/templates/app/apps/api/src/worker.ts

@@ -1,4 +1,5 @@
 // API 与 worker 使用相同声明。worker 专门处理审批启动、异步反应和 ERP 推送。
+// 两个进程部署同一版本，消费者依据声明发现工作；事件提交成功不等于这些后台动作已经完成。
 import { startWorker } from '@yss123/cage-http/worker';
 import { fakeConnector, stage } from '@yss123/cage-connectors';
 import * as domain from '@app/domain';
@@ -9,6 +10,8 @@ if (stage() === 'fake') {
     pushOrder: (request) => ({ erpNo: `DEMO-${request.externalId.slice(0, 8)}` }),
   });
 }
+// 框架拥有轮询、重试、调度和连接生命周期；应用只注册本地 fake，不另建数据库池或业务重试循环。
 const worker = await startWorker({ domain });
+// 停止句柄等待框架在途工作收尾并释放连接，避免进程退出时留下仍在续租的消费者。
 process.once('SIGINT', () => void worker.stop());
 process.once('SIGTERM', () => void worker.stop());

package/templates/app/apps/web/index.html

@@ -1,4 +1,5 @@
 <!doctype html>
+<!-- 浏览器文档外壳：提供 React 挂载节点与模块入口；业务路由、会话及数据加载由 src/main.tsx 装配的应用处理。 -->
 <html lang="zh-CN">
   <head>
     <meta charset="UTF-8" />

package/templates/app/apps/web/package.json

@@ -10,13 +10,17 @@
   "dependencies": {
     "@app/contracts": "workspace:*",
     "@tanstack/react-query": "^5.87.1",
+    "@yss123/cage-client": "0.3.0",
     "react": "^19.1.1",
-    "react-dom": "^19.1.1"
+    "react-dom": "^19.1.1",
+    "react-markdown": "^10.1.0",
+    "react-router-dom": "^7.18.5",
+    "remark-gfm": "^4.0.1"
   },
   "devDependencies": {
     "@types/react": "^19.1.13",
     "@types/react-dom": "^19.1.9",
-    "vite": "^7.1.4",
-    "typescript": "~5.9.3"
+    "typescript": "~5.9.3",
+    "vite": "^7.1.4"
   }
 }

package/templates/app/apps/web/src/app/app.tsx

@@ -1,18 +1,128 @@
-// 应用组合层只决定会话与页面的切换；具体业务交给 modules 下的页面。
-import { useEffect, useState } from 'react';
-import { loadMe } from '@app/contracts';
+/**
+ * 采购应用的路由组合层，集中连接认证、工作台、采购、库存和审批模块的公开入口。
+ * 会话先恢复，再决定展示页面、跳转登录或保留原地址提示网络故障。
+ * 页面身份来自 URL，模块间导航通过 app 注入；前端能力守卫不能代替服务端授权。
+ */
+// URL 是页面身份；应用壳只组合路由、会话与模块，不用组件状态模拟多页面导航。
+import { BrowserRouter, Navigate, Route, Routes, useLocation } from 'react-router-dom';
 import { LoginPage } from '../modules/auth';
+import { HomePage } from '../modules/workspace';
+import { PurchaseOrdersPage, PurchaseOrderDetailPage } from '../modules/purchase';
+import { InventoryPage } from '../modules/inventory';
+import { ApprovalTasksPage, useApprovalTasks } from '../modules/approval';
+import { PageState } from '../shared/ui/page-state';
+import { RequireCapability } from '../shared/ui/require-capability';
+import { loginReturnTo } from '../shared/lib/navigation';
+import { useSession } from './use-session';
 import { WorkspaceLayout } from './workspace-layout';
 
+const home = '/workspace';
+
+/**
+ * 安装 BrowserRouter 并渲染路由树。部署方需为业务深链接提供 SPA 回退，/api 和 /admin 由各自服务处理。
+ */
 export function App() {
-  const [session, setSession] = useState<'loading' | 'guest' | 'ready'>('loading');
-  useEffect(() => {
-    void loadMe().then((result) => setSession(result.ok ? 'ready' : 'guest'));
-  }, []);
-  if (session === 'loading') return <div className="loading">正在连接工作台…</div>;
-  return session === 'guest' ? (
-    <LoginPage onLogin={() => setSession('ready')} />
-  ) : (
-    <WorkspaceLayout onLogout={() => setSession('guest')} />
+  return (
+    <BrowserRouter>
+      <AppRoutes />
+    </BrowserRouter>
+  );
+}
+
+/**
+ * 在组合层读取审批待办数量并传给采购列表，使采购模块不依赖审批页面的内部实现。
+ * 待办尚未加载或失败时允许数量缺省，页面显示未知而不伪造零。
+ */
+function OrdersRoute() {
+  const tasks = useApprovalTasks();
+  return <PurchaseOrdersPage pendingTasks={tasks.data?.length} />;
+}
+
+/**
+ * 根据 useSession 的 loading/guest/ready/error 状态组装路由。
+ * guest 使用完整路径、查询参数和 hash 构造 returnTo；ready 经 loginReturnTo 校验后回跳。
+ * 网络错误保持当前地址以便重试；未知业务地址展示 404 页面，记录读取错误由各页面处理。
+ */
+function AppRoutes() {
+  const { session, restore, onLogin, onLogout } = useSession();
+  const location = useLocation();
+  if (session === 'loading')
+    return (
+      <div className="loading" role="status">
+        正在连接工作台…
+      </div>
+    );
+  if (session === 'error')
+    return (
+      <PageState
+        title="暂时无法连接工作台"
+        description="请检查网络和 API 服务，重试后继续访问当前地址。"
+        to={home}
+        label="返回工作台"
+      >
+        <button onClick={restore}>重新连接</button>
+      </PageState>
+    );
+  const login = `/login?returnTo=${encodeURIComponent(location.pathname + location.search + location.hash)}`;
+  return (
+    <Routes>
+      <Route
+        path="/login"
+        element={
+          session === 'ready' ? (
+            <Navigate to={loginReturnTo(location.search, home)} replace />
+          ) : (
+            <LoginPage onLogin={onLogin} />
+          )
+        }
+      />
+      <Route
+        element={
+          session === 'ready' ? <WorkspaceLayout onLogout={onLogout} /> : <Navigate to={login} replace />
+        }
+      >
+        <Route index element={<Navigate to={home} replace />} />
+        <Route path="workspace" element={<HomePage />} />
+        <Route
+          path="procurement/orders"
+          element={
+            <RequireCapability capability="PurchaseOrder.read" home={home}>
+              <OrdersRoute />
+            </RequireCapability>
+          }
+        />
+        <Route
+          path="procurement/orders/:id"
+          element={
+            <RequireCapability capability="PurchaseOrder.read" home={home}>
+              <PurchaseOrderDetailPage />
+            </RequireCapability>
+          }
+        />
+        <Route
+          path="inventory"
+          element={
+            <RequireCapability capability="Inventory.read" home={home}>
+              <InventoryPage />
+            </RequireCapability>
+          }
+        />
+        <Route
+          path="approvals"
+          element={<ApprovalTasksPage orderUrl={(id) => `/procurement/orders/${encodeURIComponent(id)}`} />}
+        />
+        <Route
+          path="*"
+          element={
+            <PageState
+              title="页面不存在"
+              description="请检查地址，或从工作台导航进入已有页面。"
+              to={home}
+              label="返回工作台"
+            />
+          }
+        />
+      </Route>
+    </Routes>
   );
 }

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

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