@yss123/cage-cli 0.2.0 → 0.3.1

package/templates/blank/docs/examples/purchase-admin/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/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/components/task-operation-dialog.tsx

@@ -0,0 +1,61 @@
+/**
+ * 人工待办的转办、委派和三种加签操作表单，由审批收件箱按当前任务快照打开。
+ * 选择来自业务协作名录，提交携带任务 revision 和必填原因；权限/同节点重复责任由引擎重查。
+ * 失败保留选人和原因；成功刷新真实任务并关闭。等待/受托任务不从页面打开本表单，不在前端改流程状态。
+ */
+import { useState, type FormEvent } from 'react';
+import { client } from '@app/contracts';
+import type { ApprovalTask, ApprovalTaskAction } from '@yss123/cage-client';
+import { ApprovalMemberPicker } from '../../../shared/ui/approval-member-picker';
+import { errorMessage } from '../../../shared/lib/error-message';
+import { useQueryClient } from '@tanstack/react-query';
+
+/** 页面允许发起的人员管理操作，归还/领取/释放在任务行直接处理。 */
+export type PersonnelOperation = 'transfer' | 'delegate' | 'parallel' | 'before' | 'after';
+/** 业务名称与引擎 placement 对应；不引入额外执行步骤或暗示自动授予权限。 */
+const labels = { transfer: '转办审批', delegate: '委派协助', parallel: '并行加签', before: '前加签', after: '后加签' } as const;
+const descriptions = {
+  transfer: '将这项审批责任交给另一位人员，你将不再处理此任务。',
+  delegate: '请他人核对材料，受托人归还后仍由你决定。',
+  parallel: '你与新增人员可以同时处理，所有追加意见都是必签。',
+  before: '先请新增人员签署，全部完成后这项任务才回到你手中。',
+  after: '你先签署，随后激活新增人员的必签任务。',
+};
+
+/**
+ * task 与 operation 在打开时固定；任务变化以服务端冲突响应为准，不自动改用新版本重试。
+ * close 返回当前收件箱，成功通过查询缓存刷新；无效输入禁用提交，Esc/取消不产生写入。
+ */
+export function TaskOperationDialog({ task, operation, close }: { task: ApprovalTask; operation: PersonnelOperation; close: () => void }) {
+  const [userIds, setUserIds] = useState<string[]>([]), [reason, setReason] = useState('');
+  const [busy, setBusy] = useState(false), [error, setError] = useState('');
+  const cache = useQueryClient();
+  const single = operation === 'transfer' || operation === 'delegate';
+  /**
+   * 将人员选择映射为对应动作；每次携带打开弹窗时的 revision，旧任务冲突时保留输入供用户核对。
+   * 只在服务端确认成功后刷新并关闭，不能把选中人员或提交请求本身视为已经完成交接。
+   */
+  async function submit(event: FormEvent) {
+    event.preventDefault();
+    if (busy || !userIds.length || !reason.trim()) return;
+    setBusy(true); setError('');
+    const input: ApprovalTaskAction = single
+      ? { action: operation, targetUserId: userIds[0], reason, expectedRevision: task.revision }
+      : { action: 'addSign', placement: operation, userIds, reason, expectedRevision: task.revision };
+    const result = await client.approvalTaskAction(task.id, input);
+    setBusy(false);
+    if (!result.ok) { setError(errorMessage(result)); return; }
+    await cache.invalidateQueries(); close();
+  }
+  return <div className="modal-backdrop"><section className="modal approval-operation-dialog" role="dialog" aria-modal="true" aria-labelledby="approval-operation-title"
+    onKeyDown={event => { if (event.key === 'Escape' && !busy) close(); }}>
+    <div className="section-head"><div><h2 id="approval-operation-title">{labels[operation]}</h2><p className="muted">{task.title}</p></div>
+      <button type="button" disabled={busy} onClick={close} aria-label="关闭操作">×</button></div>
+    <form onSubmit={submit}><p>{descriptions[operation]}</p>
+      <ApprovalMemberPicker value={userIds} onChange={setUserIds} max={single ? 1 : 20} exclude={[task.assigneeId, task.ownerId].filter((id): id is string => !!id)} disabled={busy} />
+      <label>操作原因<textarea autoFocus rows={3} maxLength={1000} required value={reason} disabled={busy} onChange={event => setReason(event.target.value)} placeholder="说明业务原因，供单据参与者查看" /></label>
+      {error && <p className="error" role="alert">{error}</p>}
+      <div className="actions"><button type="button" disabled={busy} onClick={close}>取消</button><button className="primary" disabled={busy || !userIds.length || !reason.trim()}>{busy ? '提交中…' : `确认${labels[operation]}`}</button></div>
+    </form>
+  </section></div>;
+}

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

@@ -1,18 +1,26 @@
+/**
+ * 当前账号本人、候选或等待加签任务的共享查询入口，默认待办供 app 数量组合复用。
+ * 任务分配与实际决策授权均来自服务端，不从角色名称在前端自行推导。
+ */
 import { useQuery } from '@tanstack/react-query';
 import { client } from '@app/contracts';
 import { errorMessage } from '../../../shared/lib/error-message';
 
-type Task = { id: string; businessKey: string; title: string; createdAt: string };
-
 /**
  * 审批是框架通用接口，不属于某个聚合的生成方法，因此请求封装在审批模块内。
  * 待办页面和导航角标复用同一缓存键，调用方不需要了解接口地址或响应形状。
  */
-export function useApprovalTasks() {
+/**
+ * 在 React Query 中读取审批待办，非 ok 结果转为查询错误。
+ * view 默认 pending，与导航角标共享；candidates/waiting 使用独立缓存，不混入可决定的任务数量。
+ * 返回查询状态及 refetch；空数组表示当前结果没有待办，未加载或失败不等同于零条。
+ */
+export function useApprovalTasks(view: 'pending' | 'candidates' | 'waiting' = 'pending') {
   return useQuery({
-    queryKey: ['tasks'],
+    queryKey: ['tasks', view],
     queryFn: async () => {
-      const result = await client.get<Task[]>('/api/approval/tasks');
+      // 使用框架任务协议保留 revision，避免页面决定丢失任务流转后的并发校验。
+      const result = await (view === 'candidates' ? client.approvalCandidateTasks() : client.approvalTasks(view));
       if (!result.ok) throw new Error(errorMessage(result));
       return result.data;
     },

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';