@yss123/cage-cli 0.2.0 → 0.3.1

package/templates/app/AGENTS.md

@@ -10,7 +10,7 @@
 
 本节位于托管区之外，cage sync 会保留。下面的托管区提供框架工作方法。
 
-<!-- cage:begin v0.2.0 -->
+<!-- cage:begin v0.3.1 -->
 ## Cage 业务开发约定（框架托管）
 
 ### 先读，再按需求改业务
@@ -19,6 +19,33 @@
 
 先读项目说明指定的学习资料，默认入口为 `docs/ai/README.md`。第一次读 `architecture.md`、`project-structure.md` 和 `primitives.md`；具体任务读 `recipes.md`，采购全链路读 `purchase-example.md`，错误查 `docs/errors/README.md` 和 `docs/ai/troubleshooting.md`。资料相对该学习目录，项目说明可指定源码仓库中的规范资料位置。
 
+### 详细中文注释（每次开发必须遵守）
+
+所有新增和维护的手写源码都必须写详细中文注释，先读学习目录中的 `commenting.md`（独立项目为 `docs/ai/commenting.md`）。注释是交付内容，不能以“代码自解释”或“保持简洁”为由省略。
+
+- 每个文件开头说明模块职责、谁调用它、主要调用链和责任边界；纯导出入口也说明如何组合模块。
+- 导出函数、类、组件、hooks、接口和业务声明使用 JSDoc，写清用途、参数含义、返回结果、主要步骤、前置条件、失败行为和副作用；复杂内部函数同样说明。参数类型已表达的语法无需重复，业务单位、空值、默认行为与约束必须解释。
+- 领域代码说明字段和状态的业务意义、命令调用身份与权限/范围、reads 依赖、事件用途、事务与异步边界、幂等/重试及资源释放；只写实际声明和实现已有的保证。
+- 页面说明 URL/查询参数、数据来源、临时状态、加载/空态/失败/无权限、提交后的刷新、会话与订阅清理；复杂分支、计算、顺序、并发和缓存规则在附近解释原因与过程。
+- 测试说明场景、前置条件、动作、断言和所防止的回归；脚本说明输入、读写路径、执行顺序、外部副作用与退出条件。注释不含密钥、凭据或个人数据。
+- 注释同时回答“做什么、为什么、如何完成、有哪些边界”，不能只有一句标题，也不能机械逐行翻译、凑字数或批量粘贴空泛模板。代码变更时同步更新注释，交付前逐文件核对。
+- 生成契约的注释由生成器维护，不手改生成物；已执行/已发布迁移不能改写。仅补注释时不得顺便重构或改变逻辑、接口、配置值和运行文案。
+
+### 原生 AI 能力入口
+
+遇到以下需求，先读 `docs/ai/intelligence.md`，用 `pnpm exec cage capabilities "关键词" --format json` 核对当前安装版本的公开 API，再检查本项目 domain 导出和页面接入。关键词可直接使用下表需求名称；未命中时缩短关键词或查公开符号，不能据此断言能力不存在。
+
+| 需求 | 框架入口与应用职责 |
+| --- | --- |
+| AI审批 / 智能审批 | 现有 `step` 使用 `kind: 'ai'`，支持 pass 通过、return 退回修改、manual 转人工；应用声明策略、结论命令、自动执行角色及接管人 |
+| 业务助理 / 本体助理 | 导出 `ai({ models, assistant })`；框架提供执行循环、按领域声明生成的工具、会话、偏好记忆和 HTTP；应用配置授权及界面 |
+| 页面上下文 / 随页助理 | `useAssistant(client.ai, page)` 配合 `useAiPageContext` / `AiPageContext`；应用上报页面、对象、选中项和草稿，服务端重读并校验业务事实 |
+| 模型管理 / Responses | `managedModel` 接入 Admin 动态配置，支持 Chat Completions / Responses；应用配置部署加密密钥并显式授权管理者 |
+| 性格 / 流式输出 | Admin 管理性格，SDK 提供选择、增量文字与执行进度；应用实现悬浮窗、Markdown 和确认卡片 |
+| 上下文预算 | `ai({ context: ... })` 的配置形状见 `AiContextOptions`；框架按预算选择完整工具或发现模式，历史和本体按需读取 |
+
+前端只使用客户端、协议与契约；后端循环、通用工具和记忆使用框架实现。页面快照和性格不授予权限。分别核对**框架支持**（公开导出）、**项目已启用**（domain 导出、迁移、模型、权限、worker、SDK）和**实际验证通过**（真实角色与模型联调）；空白模板的参考代码不表示已启用。具体接入顺序和验收步骤见该指南，不必将整份指南塞入每次任务上下文。
+
 ### 业务代码放在哪里
 
 | 位置 | 职责 |
@@ -28,7 +55,7 @@
 | `packages/domain/src/index.ts` | 统一导出全部业务及组织模型；没导出的声明不会注册 |
 | `packages/contracts/src/aggregates/<聚合>`、`queries` | 生成协议；根 index.ts 提供 @app/contracts 公共入口，只用 cage gen 更新 |
 | `apps/api/src` | API/worker 薄启动入口，普通业务不手写 HTTP 路由 |
-| `apps/web/src/app` | 会话、导航、布局、模块组合；main.tsx 只挂载和装配 Provider |
+| `apps/web/src/app` | 会话、URL 路由、布局、模块组合；main.tsx 只挂载和装配 Provider |
 | `apps/web/src/modules/<业务>` | 页面、表单、专用 hooks/API/样式；从模块 index.ts 暴露页面 |
 | `apps/web/src/shared` | 跨模块复用且不绑定业务的 UI、hooks、纯辅助函数 |
 | `db/migrations` | 审查过的结构迁移，作用于已配置的数据库 |
@@ -40,11 +67,11 @@
 ### 实现一项需求的顺序
 
 1. 先运行 `pnpm exec cage context "需求关键词"`；按需 `graph search` 查候选、`graph inspect` 查完整节点、`graph path` 看关系路径。确认中文匹配入口后按源码位置阅读实现；候选和子图不是全部依赖，具体条件不能凭连线推断。完整用法见 `docs/ai/ontology-context.md`。从用户需求确定字段、状态/动作、角色/范围、约束与后续动作；能由业务声明表达的不改框架。
-2. 已有业务含义变化时，修改前保存本体图基线：`pnpm exec cage analyze` 后将 `.cage/ontology.json` 另存为独立文件；或使用真实 Git 基线。
+2. 已有业务含义变化时，修改前用 `pnpm exec cage snapshot save before-change` 保存不可覆盖的命名基线；或使用真实 Git 提交/独立本体图文件。
 3. 先声明 aggregate/states/command/constraints/event，再写 handler、reaction/query/approval/connector，最后接业务页面。声明使用模块顶层 `export const`，从 domain 入口导出，跨文件导出名保持唯一。
-4. 运行 `pnpm exec cage check` 和 `pnpm gen`，审查 contracts 和迁移草稿。按需运行 `pnpm exec cage impact --base-file 旧图.json`，补中文图谱名。
-5. 页面使用生成方法并处理 code/domainCode；新增能力由管理员授权。数据库结构变化审查后显式 `pnpm migrate`，dev 不代办迁移。
-6. 按改动运行必要验证，交付时说明体验步骤、授权配置、迁移，以及通过/跳过/未执行项。
+4. 运行 `pnpm exec cage check` 和 `pnpm gen`，审查 contracts 和迁移草稿。按需运行 `pnpm exec cage impact --snapshot before-change`，补中文图谱名。
+5. 页面使用生成方法并处理 code/domainCode；列表、详情等多页面注册到 React Router，Link/NavLink 导航，筛选/分页进入 URL。组件状态用于弹窗和表单等临时交互。新增能力由管理员授权。数据库结构变化审查后显式 `pnpm migrate`，dev 不代办迁移。
+6. 按 `commenting.md` 逐文件检查详细中文注释与实现一致，再按改动运行必要验证；交付时说明体验步骤、授权配置、迁移、注释覆盖，以及通过/跳过/未执行项。
 
 ### 必守边界
 
@@ -55,17 +82,25 @@
 - 自定义查询声明 reads，二选一使用 sql/build，只读 `safe.*`；值参数化。不得拼接 SQL、查询基表绕过范围或硬编码密钥。
 - scope 描述范围字段，角色数据决定实际范围；`scope.none()` 不代表所有人可访问。`can/useCan` 只控制按钮，后端负责授权。
 - 前端从 `@app/contracts` 导入生成 API/类型，按需使用 `@yss123/cage-client`；不导入 domain、内核或数据库包。
+- 多页面业务必须有独立 URL，不用 useState/tab 模拟整页导航；详情从 URL 取 ID 并独立加载。前端路由集中在 app，页面从模块公开入口接入 Outlet。登录后保留原路径/query/hash，401 回登录，403 展示权限提示；/admin/ 使用普通链接进入独立系统管理。前端路由不替代后端授权。实现、SPA 部署回退和浏览器配方见 docs/ai/routing.md。
 - 跨聚合写入通过 reaction 调用命令。`tx: 'same'` 共同提交/回滚，默认 outbox 异步执行。资源 acquires/releases 是图规则标签，实际占用/释放仍由命令完成；离开持有状态要检查每条释放路径。
-- 审批通过 approval + route 配置，结论是 process 命令；选中审批人不等于已具备能力、范围和额度。第三方 IO 通过连接器，回调验签后调用 external 命令。
+- 批量调用同一命令使用 reactionEach，声明 maxItems、唯一排序字段 orderBy、items 和 map；稳定键排序后串行执行。步骤依赖用 order，同事件同事务分组不得混用有序/无序或重复顺序。保持同事务回滚边界，见 docs/ai/primitives.md。
+- 审批通过 approval + route 配置，结论是 process 命令；选中审批人不等于已具备能力、范围和额度。parallel(title, ...branch(...)) 声明结构化 AND：分支同时开始，内部顺序独立，全部活动分支完成后汇合；when 支持嵌套并仍按提交快照求值，声明有深度/数量边界，不支持任意跳转。currentSteps 表示当前活动节点集合，兼容字段 currentStep 只是最小活动索引，不能据此隐藏其他分支。人工节点 assignment: 'candidate' 开放候选领取/释放，approver.field 从 routable 字段选人；actions 开放转办、委派归还和前后/并行必签。任务操作与决定携带 revision，waiting 任务只能查看。approvalOperations() 为框架通用时效运行时：step.sla 配置自然分钟节点总时限，route.reminders 配置申请人催办；迁移并运行 worker 后提供持久站内提醒、已读与 Admin 通用页面，不自动批准或授予权限。政策、SDK 和边界见 docs/ai/approvals.md。第三方 IO 通过连接器，回调验签后调用 external 命令。
 - job 的读取与调用必须列入 reads/calls。业务导入/导出放在需要的业务页面调用通用任务接口，202 只代表任务已接受；worker 必须运行。
 - 已部署事件只做兼容扩展；新增字段设为 optional，不兼容含义用新事件。已执行/已发布迁移不能改写，结构更新新增迁移。
 - 不手改生成物，不关闭门禁掩盖错误，不因方便自动授予生产角色新能力。unsafe 必须写明 reason/owner，不能替代普通业务声明。
-- 代码注释说明职责、关键流程和设计原因；避免无业务价值的防御分支和静默兜底。维护脚本用 TypeScript，不新增 .mjs。
+- 按前述详细中文注释规范完成文件、API、业务声明和关键流程说明；避免无业务价值的防御分支和静默兜底。维护脚本用 TypeScript，不新增 .mjs。
 
 ### 最小命令形状
 
 ```ts
 // 片段：Order 为已导出的聚合，OrderSubmitted 为事件，业务校验按需求添加。
+/**
+ * 将草稿订单提交审批：只有 draft 可进入 pending_approval。
+ * 入口使用 Order.submit 能力，真实授权、范围、状态和版本由内核检查；声明本身不自动授予权限。
+ * handler 返回草稿供后续校验和持久化，OrderSubmitted 随命令事务登记，后续由已配置消费者处理。
+ * 失败不会提交这次业务变更；事件已登记也不代表后续审批已经完成。
+ */
 export const submitOrder = command(Order, {
   name: 'submit',
   from: 'draft',
@@ -79,17 +114,22 @@ export const submitOrder = command(Order, {
 
 ### 启动、验证与排错
 
-在项目根目录执行：首次 `pnpm install`，复制并编辑 .env.example，仅提供已有库管理员连接后 `pnpm exec cage init`；再 `pnpm build:app`、`pnpm gen`，审查后 `pnpm migrate`，最后 `pnpm dev`。已有配置不能覆盖。
+在项目根目录执行：首次 `pnpm install`，复制并编辑 .env.example，仅提供已有库管理员连接后 `pnpm exec cage init`；再 `pnpm build:app`、`pnpm gen`，审查后 `pnpm migrate`；用 `pnpm exec cage bootstrap --credentials-file .cage/admin-credentials.json` 显式初始化组织，最后 `pnpm dev`。已有配置不能覆盖，凭据文件必须是新受限文件且父目录存在。
 
 init 只准备账号/schema/授权并填写三个连接，不创建数据库；APP/READ/MIGRATE 指向同一个库。已有集群账号复用原密码，日常启动不用管理员。普通项目不新增 Docker 生命周期命令。
 
+API 日常启动不初始化组织、不输出管理员密码；生产缺少合格 Cookie 密钥会拒绝启动。bootstrap 不自动授予业务能力。`/healthz` 只表示存活，`/readyz` 检查必要依赖。首阶段 API 与 worker 同版本部署，查看实际注册指纹和消费者心跳。
+
 - `pnpm exec cage graph`：浏览器图谱，默认端口 15418，以终端为准。
 - `pnpm exec cage context command:对象.命令 --format json --out .cage/context.json`：按完整 key 取精简上下文；默认 Markdown，可用 --depth/--limit 调整范围。CLI 每次重新抽取；Web“复制 AI 上下文”使用当前页面快照，改代码后先刷新图谱。
-- `graph inspect/path` 有歧义时复制候选完整 key；path 默认沿箭头，--direction both 的逆向遍历不表示执行方向。报告中的测试/前端文件是候选，须核对；查询也会覆盖当前 .cage/ontology.json，旧基线务必另存。
+- `graph inspect/path` 有歧义时复制候选完整 key；path 默认沿箭头，--direction both 的逆向遍历不表示执行方向。报告中的测试/前端文件是候选，须核对；context 与图谱查询不覆盖当前图或命名快照。
+- `pnpm exec cage capabilities 关键词 --format json`：查当前安装版本公开签名；`cage doctor`：区分注册、生成、构建、迁移、授权与实际进程证据，unknown 不能当作通过。`cage timeline/explain` 关联实际异步证据与解释授权，参数和权限见 docs/ai/diagnostics.md。
+- 生成方法支持 signal/timeoutMs/idempotencyKey 请求选项。底层 CageResult 与 mutation 行为有区别：useCageCommand 失败抛 CageCommandError，成功才返回业务数据。订阅 client.subscribe 在退出、401、切换账号时取消查询并清除应用缓存。
 - `pnpm exec cage gen --check`：生成一致性；`pnpm exec cage sync --check`：本托管区一致性。
 - `pnpm exec cage test --only project`：业务测试；`pnpm verify`：类型、依赖、lint、图规则、生成、托管区、预算和测试。
 - `pnpm exec cage verify --skip-tests` 表示不完整门禁；派生测试跳过不能当作通过。测试连接只用独立测试集群。
 - 重要业务改动验证成功路径及有风险的反例；文档或可逆的小改动不反复跑全量数据库测试。
+- 修改页面/导航后实际验收深链接、刷新、前进后退、登录回跳、无权限和 404；生产再查 SPA 回退。check/verify 不自动完成浏览器验收，未执行要明确报告。见 docs/ai/routing.md。
 - CLI 报错先看 code/at/reason/fix，再查错误码册；HTTP 错误查 runtime.md。异步失败先看 worker、同步记录和死信，修复后重放，不能直接 SQL 改状态。
 
 框架托管区由 cage sync 更新；项目独有的业务规则写在标记之外，避免升级覆盖。

package/templates/app/README.md

@@ -21,6 +21,7 @@ pnpm exec cage init
 pnpm gen
 # 审查 db/migrations 后执行表结构迁移。
 pnpm migrate
+pnpm exec cage bootstrap --credentials-file .cage/admin-credentials.json
 pnpm dev
 ```
 
@@ -48,18 +49,21 @@ pnpm dev
 
 测试环境会初始化集群级角色，因此 `CAGE_TEST_DATABASE_URL` 必须指向独立测试集群。运行 `pnpm cage verify` 验证示例；框架仓库根目录的 `pnpm test:docker` 验证全部框架测试。
 
-浏览器打开终端打印的 Web 地址；配置示例使用 <http://localhost:15173>。初始管理员凭证在 API 终端显示一次。
+浏览器打开终端打印的 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. 把经理设为采购员所在部门的负责人。提单人与审批人必须不同。
-4. 采购员新建并提交采购单；worker 建立审批待办。
-5. 经理在“审批待办”通过，内核同事务生成库存锁；worker 调用 fake ERP 并回写单号。
-6. 超过 50,000 元的采购走财务第二步，需另建 code 为 `finance` 的角色并分配审批人。
-7. 取消单据或收到 ERP 收货回调后，通过异步反应释放锁。回调需要 `ERP_WEBHOOK_SECRET` 对原始 JSON 的 HMAC-SHA256 签名。
+4. 为需要选人的采购参与者授予 `ApprovalMember.read` 与该聚合 `all` 范围，通过 `ApprovalMember.create` 登记审批协作人的公开业务姓名与专业领域；名录不授予实际审批能力。
+5. 采购员新建采购单，可开启专业复核并选择 1–5 人；草稿使用 `PurchaseOrder.setReviewers` 调整名单，提交时重新校验。worker 先执行 AI 材料预审；未配置模型或模型失败时按声明转人工接管。
+6. AI 预审/人工接管之后进入经理节点；启用专业复核时，经理后由所选人员全部会签。经理、专业和财务节点开放转办、委派归还和前置/后置/并行加签。
+7. 超过 50,000 元的采购继续进入财务共享候选池，需另建 code 为 `finance` 的角色并给实际用户配置权限、范围和额度；财务必须先领取，恰好 50,000 元跳过该步骤。
+8. 全部必签完成后，最终审批命令同事务生成库存锁；worker 调用 fake ERP 并回写单号。取消单据或收到 ERP 收货回调后异步释放锁；回调需要 `ERP_WEBHOOK_SECRET` 对原始 JSON 的 HMAC-SHA256 签名。
 
 `Inventory.available` 是演示台账数量。本例验证库存锁生命周期，尚未实现仓库级的并发扣减、实物库存及退货核算。
 

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.1",
+    "@yss123/cage-connectors": "0.3.1"
   }
 }

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.1",
     "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') };
+}