@yss123/cage-cli 0.1.0 → 0.3.0

package/templates/app/Dockerfile

@@ -16,6 +16,8 @@ FROM node:24-bookworm-slim AS runtime
 WORKDIR /app
 COPY --from=build --chown=node:node /out/api /app
 COPY --from=build --chown=node:node /app/apps/web/dist /app/web
+# 系统管理与图谱共享中文显示配置；运行时工作目录同样保持为 /app。
+COPY --from=build --chown=node:node /app/cage.config.json /app/cage.config.json
 ENV NODE_ENV=production PORT=3000 WEB_DIR=/app/web
 USER node
 EXPOSE 3000

package/templates/app/README.md

@@ -1,30 +1,61 @@
-# 采购工作台
+# Cage 业务应用（含采购示例）
 
 这是可启动的标准范例：组织管理、采购单、审批待办、库存台账、库存锁生命周期和 ERP 出入站映射。
 
+## 让 AI 在本项目开发业务
+
+把本目录交给 Codex 等编程工具时，先让它读 [AGENTS.md](AGENTS.md)，再按[业务开发指南](docs/ai/README.md)和[任务配方](docs/ai/recipes.md)实现需求。普通业务不需要修改框架源码。
+
+[采购全链路导读](docs/ai/purchase-example.md)说明每个文件和异步步骤；[原语与最小业务](docs/ai/primitives.md)提供可添加的普通管理对象；[错误码册](docs/errors/README.md)用于按码修复。脚手架会将这些资料放入生成项目本地的 `docs/ai` 与 `docs/errors`，无需再次克隆框架。
+
 ## 启动
 
-在框架仓库根目录执行 `pnpm install`、`pnpm build`，然后进入本目录。独立模板项目先执行 `pnpm install`、`pnpm build:app`、`pnpm cage gen`。
+在本项目根目录执行 `pnpm install`、`pnpm build:app`；无需克隆或构建框架仓库。
 
 ```powershell
-pnpm cage db setup
-pnpm cage db up
-# 仅首次初始化独立新集群时执行；已有库随后用 cage migrate。
-pnpm cage db init
+# 首次配置时复制，已有 .env 时直接编辑原文件。
+Copy-Item .env.example .env
+# 编辑 .env，只填写 CAGE_ADMIN_DATABASE_URL，连接已经存在的数据库。
+pnpm exec cage init
+# init 自动创建账号、生成密码和 Cookie 密钥，并写回 .env。
+pnpm gen
+# 审查 db/migrations 后执行表结构迁移。
+pnpm migrate
+pnpm exec cage bootstrap --credentials-file .cage/admin-credentials.json
 pnpm dev
 ```
 
-连接池、事务、数据库初始化和凭证生成均由框架提供，项目不写连接或建库脚本。`cage db setup` 生成随机密码和本地 `.env`，重复运行保留已有配置。开发库位于 `127.0.0.1:54329/cage_dev`，测试库位于独立容器的 54330 端口。`cage db down` 停止容器但保留开发数据卷；`cage db up` 再次启动。package.json 中的 `db:*` 是相同命令的简写。
+数据库配置位于本项目根目录的 `.env`，与 `package.json`、`cage.config.json` 同级。[`.env.example`](.env.example) 为每项提供中文注释、填写格式和是否必填。连接池和事务由框架提供，项目只需配置连接。
+
+| 配置项 | 用途 |
+| --- | --- |
+| `CAGE_APP_DATABASE_URL` | `cage_app` 账号：API/worker 业务读写 |
+| `CAGE_READ_DATABASE_URL` | `cage_read` 账号：仅查询安全视图 |
+| `CAGE_MIGRATE_DATABASE_URL` | `cage_migrate` 账号：手动执行表结构迁移 |
+
+三个连接由 `cage init` 自动生成，指向**同一个已经存在的数据库**，主机、端口和库名一致。CLI 自动读取 `.env`，部署环境中的同名变量优先。修改后重启 `dev`。`migrate` 在下次执行时读取配置。
+
+`pnpm migrate` 更新该库中的表、视图和索引；迁移历史记录在 `sys.schema_migrations`。`pnpm dev` 连接该库并启动 API、worker 和 Web，domain 变化后仅重新生成文件；表结构变更需审查迁移后手动执行。框架不创建数据库、不安装 PostgreSQL、不管理 Docker。
 
-CLI 自动读取项目 `.env`，部署环境变量优先。`CAGE_APP_DATABASE_URL`、`CAGE_READ_DATABASE_URL`、`CAGE_MIGRATE_DATABASE_URL` 分别连接写入、只读和迁移账号。超级用户仅用于初始化，API/worker 不接收其凭证。
+### 首次只提供管理员连接
+
+在 `.env` 中填写 `CAGE_ADMIN_DATABASE_URL=postgresql://postgres:管理员密码@主机:端口/已有数据库名`。PostgreSQL 管理员通常叫 `postgres`，已有管理员叫 `root` 时使用实际账号名；连接串中的密码特殊字符需要 URL 编码。
+
+执行 `pnpm exec cage init` 会创建框架账号和授权，生成三个独立随机密码及 Cookie 密钥，自动填写 `.env`，成功后移除文件中的管理员连接。业务端口、自定义配置和已有 Cookie 密钥会保留；失败会回滚数据库并保留原 `.env`。日常启动不需要管理员连接。
+
+重复 `init` 会验证并复用已保存的三个账号，不更改密码。若集群已有 Cage 账号但本项目没有原连接，请先复用原凭证再运行 `init`；命令不会为了新项目重置其他项目的账号。部署时也可由平台直接提供三个账号连接，无需执行本地初始化。
+
+数据库除三个登录账号外，还有不允许登录的 `cage_view_owner`，由 `init` 一并创建，用于持有安全视图，无需填写密码。角色名属于整个 PostgreSQL 集群，不能为另一个项目随意重置密码。业务表及系统表由后续 `pnpm migrate` 创建，`init` 只准备角色、schema 和授权。连接现有数据库不表示框架会自动识别、接管其中任意历史业务表；接入历史表需另行映射和审查迁移。
 
 测试环境会初始化集群级角色，因此 `CAGE_TEST_DATABASE_URL` 必须指向独立测试集群。运行 `pnpm cage verify` 验证示例；框架仓库根目录的 `pnpm test:docker` 验证全部框架测试。
 
-浏览器打开 <http://localhost:5173>。初始管理员凭证在 API 终端显示一次。
-如果 Windows Docker/Hyper-V 保留了该端口，在 `.env` 设置 `CAGE_WEB_PORT=15173`；终端会打印实际地址。`PORT` 控制 API 端口，Vite 代理同步使用它。未配置数据库连接串时才使用原有内嵌 PostgreSQL。
+浏览器打开终端打印的 Web 地址；配置示例使用 <http://localhost:15173>。管理员凭证由显式 bootstrap 交付到新的受限文件，交付后移除。初始化仅授予系统管理能力，采购能力需要管理员明确配置。
+`CAGE_WEB_PORT` 控制 Web 端口，`PORT` 控制 API 端口，Vite 代理同步使用它。缺少数据库配置时会给出错误，需填写 `.env` 后重新启动。
 
 ## 体验完整采购流程
 
+前端使用 React Router：工作台 `/workspace`，采购列表 `/procurement/orders`，单据详情 `/procurement/orders/:id`，审批 `/approvals`，库存 `/inventory`，登录 `/login`。单号和审批待办可直接打开详情；刷新、前进后退和登录回跳保留页面地址。新增页面与部署按[路由和浏览器验收指南](docs/ai/routing.md)执行；Nginx 示例见 [deploy/nginx.conf](deploy/nginx.conf)。
+
 1. 管理员在“库存台账”登记 `A-01` 等物料。
 2. 进入 `/admin/` 创建采购员、经理，分别分配采购命令和审批能力；经理的 `PurchaseOrder.approve` 参数配置 `ceiling`。
 3. 把经理设为采购员所在部门的负责人。提单人与审批人必须不同。
@@ -47,12 +78,14 @@ CLI 自动读取项目 `.env`，部署环境变量优先。`CAGE_APP_DATABASE_UR
 
 图谱主标题显示中文业务名称，下面保留英文代码标识。框架会读取声明现有的 `description`；本项目在 `cage.config.json` 的 `graph.labels` 中补充状态、字段等名称，也可覆盖较长描述。例如 `"command:PurchaseOrder.approve": "通过审批"`。键为 `节点类型:本体节点 ID`，可从节点详情复制 ID；中文标题只用于显示，不改变命令、权限标识或数据库。新增业务声明时同时补上需要的名称，然后在图谱中点击“重新抽取”。
 
-- `packages/domain/src/inventory.ts`：最简聚合和库存锁。
-- `purchase-order.ts`：状态、命令、约束和事件。
-- `reactions.ts`：同事务建锁与异步释放，包含资源配对标记。
-- `approvals.ts`、`erp.ts`：封闭审批路由、出站和入站映射。
-- `queries.ts`、`jobs.ts`：安全视图查询及过期草稿清理。
+- `packages/domain/src/modules/inventory`：最简聚合和库存锁。
+- `packages/domain/src/modules/purchase`：采购状态、命令、约束、事件、审批、查询和任务。
+- `packages/domain/src/workflows/purchase-inventory.ts`：同事务建锁与异步释放，包含资源配对标记。
+- `packages/domain/src/integrations/erp.ts`：出站、入站映射和验签。
+- `packages/contracts/src/aggregates/<聚合>`：生成的 SDK；页面统一从 `@app/contracts` 引入。
 - `apps/api/src`：API 和 worker 的薄启动入口。
-- `apps/web/src`：仅依赖生成契约的 React 界面。
+- `apps/web/src/app`、`modules`、`shared`：应用组合、业务页面、共享基础组件；`main.tsx` 只挂载。
+
+新增业务先读[工程目录与代码组织](docs/ai/project-structure.md)，不要继续在 src 根目录平铺文件。模板已启用模块目录门禁，`cage check` 和 `verify` 会指出目录与依赖越界。
 
 先运行 `pnpm cage gen` 再提交契约和迁移草稿；`pnpm cage verify` 检查完整工具链。派生测试遇到无法推断的业务输入会显示跳过，`purchase-order.test.ts` 另外准备真实业务数据覆盖成功审批和约束反例。

package/templates/app/_gitignore

@@ -0,0 +1,9 @@
+node_modules/
+dist/
+.cage/
+.cage-files/
+generated/
+.env
+.env.*
+!.env.example
+*.log

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

@@ -10,7 +10,7 @@
   },
   "dependencies": {
     "@app/domain": "workspace:*",
-    "@yss123/cage-http": "0.1.0",
-    "@yss123/cage-connectors": "0.1.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

@@ -0,0 +1,128 @@
+/**
+ * 采购应用的路由组合层，集中连接认证、工作台、采购、库存和审批模块的公开入口。
+ * 会话先恢复，再决定展示页面、跳转登录或保留原地址提示网络故障。
+ * 页面身份来自 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() {
+  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/{style.css → 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

@@ -0,0 +1,109 @@
+/**
+ * 已登录工作台的公共外壳：导航、当前账号、退出登录、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 { 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 [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>
+        <Link className="brand" to="/workspace">
+          cage<span>采购工作台</span>
+        </Link>
+        <span className="nav-caption">工作空间</span>
+        <nav>
+          {(
+            [
+              ['/workspace', '00', '工作台'],
+              ['/procurement/orders', '01', '采购单'],
+              ['/approvals', '02', '审批待办'],
+              ['/inventory', '03', '库存台账'],
+            ] as const
+          ).map(([key, no, label]) => (
+            <NavLink key={key} to={key} className={({ isActive }) => (isActive ? 'selected' : '')}>
+              <span>{no}</span>
+              {label}
+              {key === '/approvals' && <b>{tasks.data?.length ?? 0}</b>}
+            </NavLink>
+          ))}
+        </nav>
+        <div className="aside-bottom">
+          <a href="/admin/">系统管理 ↗</a>
+          <div className="user">
+            <span className="avatar">{currentUser()?.name?.slice(0, 1) ?? '用'}</span>
+            <div>
+              {currentUser()?.name}
+              <small>已登录</small>
+            </div>
+          </div>
+          <button
+            className="logout"
+            disabled={busy}
+            onClick={async () => {
+              setBusy(true);
+              const result = await client.logout();
+              setBusy(false);
+              if (result.ok) {
+                cache.clear();
+                onLogout();
+              } else setError(errorMessage(result));
+            }}
+          >
+            退出登录
+          </button>
+        </div>
+      </aside>
+      <main className="content">
+        <header>
+          <span>采购管理 / {page}</span>
+          <span className="live-dot">团队工作空间</span>
+        </header>
+        {error && (
+          <p className="error" role="alert">
+            {error}
+          </p>
+        )}
+        <Outlet />
+        <div className="page-footer">
+          CAGE / PROCUREMENT WORKSPACE<span>业务操作均受权限与数据范围约束</span>
+        </div>
+      </main>
+    </div>
+    </AssistantScope>
+  );
+}