@yss123/cage-cli 0.2.0 → 0.3.1

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

@@ -1,22 +1,39 @@
-// 根组件恢复会话并选择登录页/应用壳，不放客户业务的表单和数据请求。
-import { useEffect, useState } from 'react';
-import { loadMe } from '@app/contracts';
+/**
+ * 空白应用的路由组合层，连接登录、工作台和成员目录的公开模块入口。
+ * 先恢复会话，再按 URL 展示页面；认证失败与网络错误分开处理，保留可回跳的原始地址。
+ * 新业务路由在此组合到 Outlet，模块内部实现不直接跨目录互相导入。
+ */
+// 页面身份交给 React Router；会话恢复、布局和业务模块在应用层组合。
+import { BrowserRouter, Navigate, Route, Routes, useLocation } from 'react-router-dom';
 import { LoginPage } from '../modules/auth';
+import { HomePage } from '../modules/workspace';
+import { UsersPage, UserDetailPage } from '../modules/directory';
 import { Brand } from '../shared/ui/brand';
+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';
 
+/**
+ * 安装 BrowserRouter 作为页面身份来源；生产服务器须为业务深链接提供 SPA 回退。
+ */
 export function App() {
-  const [session, setSession] = useState<'loading' | 'guest' | 'ready' | 'error'>('loading');
+  return (
+    <BrowserRouter>
+      <AppRoutes />
+    </BrowserRouter>
+  );
+}
 
-  async function restoreSession() {
-    setSession('loading');
-    const result = await loadMe();
-    // 未登录进入表单；服务故障单独展示，避免把连接失败误当作需要重新登录。
-    setSession(result.ok ? 'ready' : result.code === 'UNAUTHENTICATED' ? 'guest' : 'error');
-  }
-  useEffect(() => {
-    void restoreSession();
-  }, []);
+/**
+ * 依据 useSession 的加载、未认证、就绪和故障状态生成路由。
+ * 登录回跳经 loginReturnTo 验证；成员列表和详情要求 User.read，未知路径呈现独立 404 状态。
+ * 前端守卫只控制交互，成员的可见范围和字段掩码仍由服务端执行。
+ */
+function AppRoutes() {
+  const { session, restore, onLogin, onLogout } = useSession();
+  const location = useLocation();
 
   if (session === 'loading')
     return (
@@ -31,14 +48,59 @@ export function App() {
         <Brand />
         <h1>暂时无法连接工作台</h1>
         <p role="alert">请检查网络和 API 服务，然后重新尝试。</p>
-        <button className="primary" onClick={restoreSession}>
+        <button className="primary" onClick={restore}>
           重新连接<span aria-hidden="true">↗</span>
         </button>
       </main>
     );
-  return session === 'guest' ? (
-    <LoginPage onLogin={() => setSession('ready')} />
-  ) : (
-    <WorkspaceLayout onLogout={() => setSession('guest')} />
+  const login = `/login?returnTo=${encodeURIComponent(location.pathname + location.search + location.hash)}`;
+  return (
+    <Routes>
+      <Route
+        path="/login"
+        element={
+          session === 'ready' ? (
+            <Navigate to={loginReturnTo(location.search, '/workspace')} replace />
+          ) : (
+            <LoginPage onLogin={onLogin} />
+          )
+        }
+      />
+      <Route
+        element={
+          session === 'ready' ? <WorkspaceLayout onLogout={onLogout} /> : <Navigate to={login} replace />
+        }
+      >
+        <Route index element={<Navigate to="/workspace" replace />} />
+        <Route path="workspace" element={<HomePage />} />
+        <Route
+          path="directory/users"
+          element={
+            <RequireCapability capability="User.read" home="/workspace">
+              <UsersPage />
+            </RequireCapability>
+          }
+        />
+        <Route
+          path="directory/users/:id"
+          element={
+            <RequireCapability capability="User.read" home="/workspace">
+              <UserDetailPage />
+            </RequireCapability>
+          }
+        />
+        <Route
+          path="*"
+          element={
+            <PageState
+              title="页面不存在"
+              description="请检查地址，或从工作空间导航进入已有页面。"
+              to="/workspace"
+              label="返回工作台"
+            />
+          }
+        />
+      </Route>
+    </Routes>
   );
 }

package/templates/blank/apps/web/src/app/styles/global.css

@@ -1,3 +1,8 @@
+/**
+ * 空白应用的主题、品牌、登录布局、工作台外壳与成员目录样式，独立于采购模板维护。
+ * 颜色和间距供共享 UI 复用；成员详情与空状态只负责呈现真实接口结果或尚未添加模块的状态。
+ * 布局样式不授予管理能力，入口显示条件仍由组件与真实授权控制。
+ */
 /* 空白工作台以留白、细线和深绿建立层次；这里不包含演示统计或客户业务样式。 */
 @import url('https://fonts.googleapis.com/css2?family=DM+Sans:wght@400;500;600;700&display=swap');
 
@@ -514,3 +519,88 @@ button {
 .session-state .primary {
   min-width: 200px;
 }
+
+/* 目录复用真实组织数据，独立列表与详情是业务模块的最小导航参考。 */
+.directory-intro {
+  display: flex;
+  gap: 16px;
+  align-items: center;
+  margin: 0 0 24px;
+  font-size: 12px;
+  color: var(--muted);
+}
+.directory-panel {
+  border: 1px solid var(--line);
+  border-radius: 7px;
+  background: #fdfefb;
+  overflow: hidden;
+}
+.directory-panel table {
+  width: 100%;
+  border-collapse: collapse;
+  text-align: left;
+}
+.directory-panel th,
+.directory-panel td {
+  padding: 18px 24px;
+  border-bottom: 1px solid var(--line);
+  font-size: 12px;
+}
+.directory-panel th {
+  background: #f1f5eb;
+  color: var(--muted);
+  font-size: 11px;
+  font-weight: 500;
+}
+.record-link {
+  color: var(--green);
+  text-decoration: underline;
+  text-decoration-color: #c6d5b5;
+  text-underline-offset: 4px;
+}
+.record-link:hover {
+  text-decoration-color: var(--green);
+}
+.directory-pagination {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 20px 24px;
+  color: var(--muted);
+  font-size: 11px;
+}
+.directory-pagination button {
+  padding: 8px 12px;
+  margin-left: 8px;
+  background: #f1f5eb;
+  color: var(--green);
+  border: 1px solid var(--line);
+  border-radius: 4px;
+}
+.directory-empty {
+  text-align: center;
+  padding: 48px;
+  color: var(--muted);
+  font-size: 13px;
+}
+.record-facts {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  margin: 0;
+  padding: 8px 24px;
+  gap: 0 36px;
+}
+.record-facts > div {
+  padding: 24px 0;
+  border-bottom: 1px solid var(--line);
+}
+.record-facts dt {
+  color: var(--muted);
+  font-size: 11px;
+  margin-bottom: 12px;
+}
+.record-facts dd {
+  margin: 0;
+  font-size: 14px;
+  overflow-wrap: anywhere;
+}

package/templates/blank/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/apps/web/src/app/workspace-layout.tsx

@@ -1,11 +1,19 @@
+/**
+ * 已登录空白应用的公共外壳，装配品牌、导航、账号信息、退出登录和子页面 Outlet。
+ * 成员目录和系统管理入口依据 User.read 能力显示；该显示判断不代表拥有全部管理操作。
+ */
 // 应用壳负责导航和账号状态；具体页面通过业务模块的公开入口组合。
 import { useState } from 'react';
+import { NavLink, Outlet, useLocation } from 'react-router-dom';
 import { useQueryClient } from '@tanstack/react-query';
 import { client, currentUser, useCan } from '@app/contracts';
 import { errorMessages } from '../shared/lib/error-message';
 import { Brand } from '../shared/ui/brand';
-import { HomePage } from '../modules/workspace';
 
+/**
+ * 从路由计算当前位置标题，读取当前账号与能力，承载各业务模块页面。
+ * onLogout 由 app 提供，退出请求成功并清空缓存后调用；失败在当前页面显示原因。
+ */
 export function WorkspaceLayout({ onLogout }: { onLogout: () => void }) {
   // 能力只决定界面入口是否展示；系统管理接口还会再次校验授权。
   const canManage = useCan('User.read');
@@ -13,7 +21,19 @@ export function WorkspaceLayout({ onLogout }: { onLogout: () => void }) {
   const [error, setError] = useState('');
   const user = currentUser();
   const cache = useQueryClient();
+  const location = useLocation();
+  const page = location.pathname.startsWith('/directory/users/')
+    ? '成员详情'
+    : location.pathname === '/directory/users'
+      ? '成员目录'
+      : location.pathname === '/workspace'
+        ? '工作台'
+        : '页面';
 
+  /**
+   * 等待 SDK 结束服务端会话，成功才清除查询缓存并通知 app。
+   * 失败不伪造已退出状态；按钮在结果返回前保持忙碌。
+   */
   async function logout() {
     setBusy(true);
     const result = await client.logout();
@@ -29,9 +49,14 @@ export function WorkspaceLayout({ onLogout }: { onLogout: () => void }) {
       <aside className="sidebar">
         <Brand />
         <span className="sidebar-label">工作空间</span>
-        <a className="nav-item active" href="/" aria-current="page">
+        <NavLink className={({ isActive }) => `nav-item${isActive ? ' active' : ''}`} to="/workspace">
           <span aria-hidden="true">◫</span>工作台<span className="nav-arrow">↗</span>
-        </a>
+        </NavLink>
+        {canManage && (
+          <NavLink className={({ isActive }) => `nav-item${isActive ? ' active' : ''}`} to="/directory/users">
+            <span aria-hidden="true">♧</span>成员目录<span className="nav-arrow">↗</span>
+          </NavLink>
+        )}
         {canManage && (
           <a className="nav-item" href="/admin/">
             <span aria-hidden="true">⚙</span>系统管理<span className="nav-arrow">↗</span>
@@ -46,7 +71,7 @@ export function WorkspaceLayout({ onLogout }: { onLogout: () => void }) {
         <header className="topbar">
           <span>
             工作空间<span className="breadcrumb-divider">/</span>
-            <strong>工作台</strong>
+            <strong>{page}</strong>
           </span>
           <div className="account">
             <span className="avatar">{user?.name.slice(0, 1)}</span>
@@ -62,7 +87,7 @@ export function WorkspaceLayout({ onLogout }: { onLogout: () => void }) {
               {error}
             </p>
           )}
-          <HomePage />
+          <Outlet />
         </main>
       </div>
     </div>

package/templates/blank/apps/web/src/main.tsx

@@ -1,3 +1,8 @@
+/**
+ * 空白业务应用的浏览器启动入口，创建共享 QueryClient 并挂载 app 路由。
+ * 新增业务页面使用同一 Provider 内的生成查询 hooks；此处只装配前端，不注册领域或连接数据库。
+ * 全局样式由入口加载，会话失效与账号切换时的查询清理由 useSession 负责。
+ */
 // 浏览器入口只负责挂载和全局 Provider。QueryClient 让新增模块可直接使用生成查询 hooks。
 import { createRoot } from 'react-dom/client';
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

package/templates/blank/apps/web/src/modules/auth/index.ts

@@ -1 +1,5 @@
+/**
+ * auth 模块的公开导出边界，向 app 提供登录页面。
+ * 其他模块通过这个入口组合页面，不依赖内部页面文件路径；具体读取与交互留在实现文件。
+ */
 export { LoginPage } from './pages/login-page';

package/templates/blank/apps/web/src/modules/auth/pages/login-page.tsx

@@ -1,13 +1,27 @@
+/**
+ * 空白应用的登录表单，使用客户端完成认证并由 app 决定成功后的导航。
+ * SDK 先认证再读取当前用户和能力，两阶段都成功才通知 app；身份读取失败保留在登录页展示。
+ * 账号密码仅用于本次提交，不在本组件持久化或输出日志。
+ */
 // 认证模块拥有登录表单；登录后的导航由 app 组合层处理。
 import { useState, type FormEvent } from 'react';
 import { client } from '@app/contracts';
 import { errorMessages } from '../../../shared/lib/error-message';
 import { Brand } from '../../../shared/ui/brand';
 
+/**
+ * 维护本地忙碌与错误状态，使用统一错误文案；成功调用 onLogin 更新应用会话状态。
+ * 页面不直接消费未验证的 returnTo，也不会把网络错误当成登录成功。
+ */
 export function LoginPage({ onLogin }: { onLogin: () => void }) {
   const [busy, setBusy] = useState(false);
   const [error, setError] = useState('');
 
+  /**
+   * 读取表单中的账号密码并等待 client.login；SDK 完成会话协议与用户能力同步。
+   * 返回失败结果时保留页面并提示原因，成功后回跳由 app 路由处理。
+   * NOT_FOUND 来自认证后读取当前身份的 GET 结果，单独提示服务配置问题，不误报为账号密码错误。
+   */
   async function submit(event: FormEvent<HTMLFormElement>) {
     event.preventDefault();
     const form = new FormData(event.currentTarget);
@@ -17,7 +31,10 @@ export function LoginPage({ onLogin }: { onLogin: () => void }) {
     const result = await client.login(String(form.get('username')), String(form.get('password')));
     setBusy(false);
     if (result.ok) onLogin();
-    else setError(errorMessages[result.code]);
+    else if (result.code === 'NOT_FOUND') {
+      // login 的返回类型包含 loadMe 的读取错误；先处理该分支，剩余代码仍由 CommonError 映射穷尽检查。
+      setError('无法加载当前登录信息，请检查 API 配置或联系管理员。');
+    } else setError(errorMessages[result.code]);
   }
 
   return (

package/templates/blank/apps/web/src/modules/directory/index.ts

@@ -0,0 +1,7 @@
+/**
+ * directory 模块的公开导出边界，向 app 提供成员列表及独立详情页。
+ * 其他模块通过这个入口组合页面，不依赖内部页面文件路径；具体读取与交互留在实现文件。
+ */
+// 空白模板利用已有组织模型演示列表/详情路由，不注册额外客户业务或演示数据。
+export { UsersPage } from './pages/users-page';
+export { UserDetailPage } from './pages/user-detail-page';

package/templates/blank/apps/web/src/modules/directory/pages/user-detail-page.tsx

@@ -0,0 +1,78 @@
+/**
+ * 成员详情路由，从地址栏独立校验和加载成员，支持直接访问与刷新。
+ * 姓名、联系方式等均来自安全契约结果，敏感字段是否可见由后端决定。
+ */
+import { Link, useParams } from 'react-router-dom';
+import { UserSchema, useUser } from '@app/contracts';
+import { PageState, QueryFailure } from '../../../shared/ui/page-state';
+
+/** ID 来自地址栏，详情不依赖“先打开列表”的内存对象，也不自行放宽读侧权限。 */
+/**
+ * 校验 URL 中的成员 id，非法时显示地址错误与返回目录入口；通过后才挂载读取组件。
+ */
+export function UserDetailPage() {
+  const { id } = useParams();
+  const parsed = UserSchema.shape.id.safeParse(id);
+  if (!parsed.success)
+    return <PageState title="成员地址无效" description="请从成员目录选择有效记录。" to="/directory/users" />;
+  return <UserDetail id={parsed.data} />;
+}
+
+/**
+ * 对合法 id 调用 useUser，分别呈现加载、权限/范围/网络错误及真实成员信息。
+ * 电话邮箱为空时显示未填写；该展示不能恢复被服务端掩码或裁剪的原始字段。
+ */
+function UserDetail({ id }: { id: string }) {
+  const query = useUser(id);
+  if (query.isPending)
+    return (
+      <p className="muted" role="status">
+        正在读取成员详情…
+      </p>
+    );
+  if (query.isError)
+    return <QueryFailure error={query.error} to="/directory/users" retry={() => void query.refetch()} />;
+  const user = query.data;
+  return (
+    <>
+      <div className="page-heading">
+        <div>
+          <p className="eyebrow">成员详情</p>
+          <h1>{user.name}</h1>
+          <p className="muted">联系方式按当前账号的权限展示。</p>
+        </div>
+        <Link className="route-link" to="/directory/users">
+          ← 返回成员目录
+        </Link>
+      </div>
+      <section className="directory-panel">
+        <dl className="record-facts">
+          <div>
+            <dt>账号</dt>
+            <dd>{user.username}</dd>
+          </div>
+          <div>
+            <dt>状态</dt>
+            <dd>{user.status === 'active' ? '使用中' : '已停用'}</dd>
+          </div>
+          <div>
+            <dt>电话</dt>
+            <dd>{user.phone ?? '未填写'}</dd>
+          </div>
+          <div>
+            <dt>邮箱</dt>
+            <dd>{user.email ?? '未填写'}</dd>
+          </div>
+          <div>
+            <dt>成员 ID</dt>
+            <dd>{user.id}</dd>
+          </div>
+          <div>
+            <dt>加入时间</dt>
+            <dd>{new Date(user.createdAt).toLocaleString('zh-CN')}</dd>
+          </div>
+        </dl>
+      </section>
+    </>
+  );
+}

package/templates/blank/apps/web/src/modules/directory/pages/users-page.tsx

@@ -0,0 +1,93 @@
+/**
+ * 组织成员的只读目录，使用生成的 useUserList 读取当前账号可访问的安全投影。
+ * 分页存入 URL，姓名排序、每页二十条；不会直接访问组织基表或承担账号维护。
+ */
+import { Link, useSearchParams } from 'react-router-dom';
+import { useUserList } from '@app/contracts';
+import { QueryFailure } from '../../../shared/ui/page-state';
+
+/** 列表来自真实安全接口；分页写入 URL，使刷新、分享和前进后退保留当前页。 */
+/**
+ * 从 page 查询参数恢复页码，非法或非正整数按第一页处理。
+ * 加载、查询失败与空列表分别展示；列表 total 是当前读取范围的结果，详情链接使用成员 ID。
+ */
+export function UsersPage() {
+  const [search, setSearch] = useSearchParams();
+  const requested = Number(search.get('page') ?? 1);
+  const page = Number.isSafeInteger(requested) && requested > 0 ? requested : 1;
+  const query = useUserList({ page, pageSize: 20, sort: 'name' });
+  /**
+   * 更新页码并保留其他查询参数，第一页移除 page，让浏览器历史承担前进后退。
+   */
+  function go(next: number) {
+    const params = new URLSearchParams(search);
+    next === 1 ? params.delete('page') : params.set('page', String(next));
+    setSearch(params);
+  }
+  if (query.isPending)
+    return (
+      <p className="muted" role="status">
+        正在读取成员目录…
+      </p>
+    );
+  if (query.isError)
+    return (
+      <QueryFailure
+        error={query.error}
+        to="/workspace"
+        label="返回工作台"
+        retry={() => void query.refetch()}
+      />
+    );
+  return (
+    <>
+      <div className="page-heading">
+        <div>
+          <p className="eyebrow">团队与协作</p>
+          <h1>成员目录</h1>
+          <p className="muted">仅显示你有权查看的成员；账号维护请进入系统管理。</p>
+        </div>
+      </div>
+      <section className="directory-panel">
+        <table>
+          <thead>
+            <tr>
+              <th>成员</th>
+              <th>账号</th>
+              <th>状态</th>
+              <th>查看</th>
+            </tr>
+          </thead>
+          <tbody>
+            {query.data.items.map((user) => (
+              <tr key={user.id}>
+                <td>{user.name}</td>
+                <td>{user.username}</td>
+                <td>{user.status === 'active' ? '使用中' : '已停用'}</td>
+                <td>
+                  <Link className="record-link" to={`/directory/users/${encodeURIComponent(user.id)}`}>
+                    成员详情 ↗
+                  </Link>
+                </td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+        {!query.data.items.length && <p className="directory-empty">当前范围内没有成员。</p>}
+        <footer className="directory-pagination">
+          <span>
+            共 {query.data.total} 人 · 第 {page} 页
+          </span>
+          <div>
+            <button disabled={page === 1} onClick={() => go(page - 1)}>
+              上一页
+            </button>
+            <button disabled={page * 20 >= query.data.total} onClick={() => go(page + 1)}>
+              下一页
+            </button>
+          </div>
+        </footer>
+      </section>
+    </>
+  );
+}

package/templates/blank/apps/web/src/modules/workspace/index.ts

@@ -1 +1,5 @@
+/**
+ * workspace 模块的公开导出边界，向 app 提供空白工作台首页。
+ * 其他模块通过这个入口组合页面，不依赖内部页面文件路径；具体读取与交互留在实现文件。
+ */
 export { HomePage } from './pages/home-page';

package/templates/blank/apps/web/src/modules/workspace/pages/home-page.tsx

@@ -1,6 +1,15 @@
+/**
+ * 空白业务项目的工作台首页，解释尚未添加业务模块并提供真实成员目录和管理入口。
+ * 不注册采购演示、不制造统计；客户业务应建立相邻模块，再经 app 接入导航。
+ */
 // 空白工作台模块：新增业务时建立相邻模块，由 app 导航接入，不在本页堆全部业务。
 import { useCan } from '@app/contracts';
+import { Link } from 'react-router-dom';
 
+/**
+ * 根据 User.read 的界面能力展示组织相关入口，其余区域显示业务空状态。
+ * 拥有读取能力不等于获得全部管理权限；系统管理仍按具体操作检查能力。
+ */
 export function HomePage() {
   const canManage = useCan('User.read');
   return (
@@ -13,6 +22,14 @@ export function HomePage() {
         </div>
         <span className="project-tag">空白业务项目</span>
       </div>
+      {canManage && (
+        <p className="directory-intro">
+          <Link className="record-link" to="/directory/users">
+            打开成员目录 ↗
+          </Link>
+          <span>查看真实组织成员，也可作为新增业务列表与详情页的参考。</span>
+        </p>
+      )}
       <section className="empty-state" aria-labelledby="empty-title">
         <div className="empty-illustration" aria-hidden="true">
           <div className="sheet sheet-back" />

package/templates/blank/apps/web/src/shared/lib/error-message.ts

@@ -1,6 +1,15 @@
+/**
+ * 空白应用通用错误码的中文展示表，由登录页和公共外壳共享。
+ * 保持与 CommonError 类型覆盖一致；错误文案只供提示，控制流应仍判断客户端 ok/code。
+ * 取消和超时由客户端请求生命周期产生，不代表服务端一定没有完成操作，提示用户先确认当前状态。
+ */
 import type { CommonError } from '@app/contracts';
 
 // 通用错误提示不依赖具体业务，登录页和应用壳复用它。
+/**
+ * 完整映射认证、授权、输入、限流、服务异常、网络、取消和超时错误；新增业务领域错误由其模块单独说明。
+ * Record 保留穷尽检查，SDK 增加通用错误码时必须补充文案，不能用空提示或静默默认值掩盖缺项。
+ */
 export const errorMessages: Record<CommonError, string> = {
   UNAUTHENTICATED: '账号或密码不正确，请重新输入。',
   FORBIDDEN: '当前账号无法执行此操作，请联系管理员。',
@@ -8,4 +17,6 @@ export const errorMessages: Record<CommonError, string> = {
   RATE_LIMITED: '操作过于频繁，请稍后重试。',
   INTERNAL: '服务暂时无法处理请求，请稍后重试。',
   NETWORK: '无法连接服务，请检查网络和 API 是否已启动。',
+  CANCELLED: '请求已取消，请确认当前页面状态后重试。',
+  TIMEOUT: '请求超时，请检查网络并确认操作结果后重试。',
 };

package/templates/blank/apps/web/src/shared/lib/navigation.ts

@@ -0,0 +1,21 @@
+/**
+ * 登录回跳的应用边界：只接受本应用的业务路径，阻止外站及认证/API/静态资源路径回跳。
+ * 由路由组合层调用，纯解析 URL 字符串，不发起导航或网络请求。
+ */
+/** 登录回跳只接受本应用页面；固定基址只用于解析，不会发起网络请求。 */
+/**
+ * 提取 search 中的 returnTo，使用固定解析基准检查同源路径并排除保留前缀。
+ * @param search 登录页查询字符串，可含 URL 编码的 returnTo。
+ * @param fallback 缺失、格式不合法或越界时返回的可信业务首页。
+ * @returns 可回跳路径，保留其查询参数与 hash；不返回外站 URL。
+ */
+export function loginReturnTo(search: string, fallback: string): string {
+  const requested = new URLSearchParams(search).get('returnTo');
+  const origin = 'https://cage.local';
+  if (!requested?.startsWith('/') || !URL.canParse(requested, origin)) return fallback;
+  const url = new URL(requested, origin);
+  // 保留查询条件和锚点；阻止外站跳转、登录循环及把服务端入口当成 React 页面。
+  if (url.origin !== origin || /^\/(login|admin|api|auth|hooks|assets)(\/|$)/.test(url.pathname))
+    return fallback;
+  return url.pathname + url.search + url.hash;
+}