@yss123/cage-cli 0.1.0 → 0.3.0

package/templates/blank/apps/web/src/app/workspace-layout.tsx

@@ -0,0 +1,95 @@
+/**
+ * 已登录空白应用的公共外壳，装配品牌、导航、账号信息、退出登录和子页面 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';
+
+/**
+ * 从路由计算当前位置标题，读取当前账号与能力，承载各业务模块页面。
+ * onLogout 由 app 提供，退出请求成功并清空缓存后调用；失败在当前页面显示原因。
+ */
+export function WorkspaceLayout({ onLogout }: { onLogout: () => void }) {
+  // 能力只决定界面入口是否展示；系统管理接口还会再次校验授权。
+  const canManage = useCan('User.read');
+  const [busy, setBusy] = useState(false);
+  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();
+    setBusy(false);
+    if (result.ok) {
+      cache.clear();
+      onLogout();
+    } else setError(errorMessages[result.code]);
+  }
+
+  return (
+    <div className="workspace">
+      <aside className="sidebar">
+        <Brand />
+        <span className="sidebar-label">工作空间</span>
+        <NavLink className={({ isActive }) => `nav-item${isActive ? ' active' : ''}`} to="/workspace">
+          <span aria-hidden="true">◫</span>工作台<span className="nav-arrow">↗</span>
+        </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>
+          </a>
+        )}
+        <div className="sidebar-note">
+          <span className="status-dot" />
+          从一个好起点出发
+        </div>
+      </aside>
+      <div className="workspace-body">
+        <header className="topbar">
+          <span>
+            工作空间<span className="breadcrumb-divider">/</span>
+            <strong>{page}</strong>
+          </span>
+          <div className="account">
+            <span className="avatar">{user?.name.slice(0, 1)}</span>
+            <span>{user?.name}</span>
+            <button className="text-button" onClick={logout} disabled={busy}>
+              {busy ? '正在退出…' : '退出登录'}
+            </button>
+          </div>
+        </header>
+        <main className="workspace-content">
+          {error && (
+            <p className="error" role="alert">
+              {error}
+            </p>
+          )}
+          <Outlet />
+        </main>
+      </div>
+    </div>
+  );
+}

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

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

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

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

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

@@ -0,0 +1,104 @@
+/**
+ * 空白应用的登录表单，使用客户端完成认证并由 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);
+    setBusy(true);
+    setError('');
+    // SDK 自动处理会话 Cookie、CSRF 与幂等键；成功后同步当前用户和能力列表。
+    const result = await client.login(String(form.get('username')), String(form.get('password')));
+    setBusy(false);
+    if (result.ok) onLogin();
+    else if (result.code === 'NOT_FOUND') {
+      // login 的返回类型包含 loadMe 的读取错误；先处理该分支，剩余代码仍由 CommonError 映射穷尽检查。
+      setError('无法加载当前登录信息，请检查 API 配置或联系管理员。');
+    } else setError(errorMessages[result.code]);
+  }
+
+  return (
+    <main className="login-layout">
+      <section className="login-story">
+        <Brand />
+        <div className="story-copy">
+          <p className="eyebrow">为你的业务，留出空间</p>
+          <h1>
+            从这里，
+            <br />
+            开始自己的业务<span>。</span>
+          </h1>
+          <p className="story-description">
+            基础已经就绪。让每一个流程，
+            <br />
+            按你的业务方式运转。
+          </p>
+        </div>
+        <div className="story-foot">
+          <span className="status-dot" />
+          业务工作台<span className="edition">CAGE / WORKSPACE</span>
+        </div>
+      </section>
+      <section className="login-panel" aria-labelledby="login-title">
+        <div className="login-form-wrap">
+          <span className="section-number">01 / 欢迎回来</span>
+          <h2 id="login-title">登录工作台</h2>
+          <p className="muted">使用管理员为你配置的账号继续。</p>
+          <form onSubmit={submit} className="login-form">
+            <label htmlFor="username">账号</label>
+            <input
+              id="username"
+              name="username"
+              autoComplete="username"
+              placeholder="请输入账号"
+              required
+              autoFocus
+              disabled={busy}
+            />
+            <label htmlFor="password">密码</label>
+            <input
+              id="password"
+              name="password"
+              type="password"
+              autoComplete="current-password"
+              placeholder="请输入密码"
+              required
+              disabled={busy}
+            />
+            {error && (
+              <p className="error" role="alert">
+                {error}
+              </p>
+            )}
+            <button className="primary" disabled={busy}>
+              {busy ? '正在登录…' : '进入工作台'}
+              <span aria-hidden="true">↗</span>
+            </button>
+          </form>
+          <p className="login-note">首次使用的管理员账号，请查看 API 启动终端。</p>
+        </div>
+        <span className="panel-foot">一个属于你的业务起点</span>
+      </section>
+    </main>
+  );
+}

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

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

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

@@ -0,0 +1,62 @@
+/**
+ * 空白业务项目的工作台首页，解释尚未添加业务模块并提供真实成员目录和管理入口。
+ * 不注册采购演示、不制造统计；客户业务应建立相邻模块，再经 app 接入导航。
+ */
+// 空白工作台模块：新增业务时建立相邻模块，由 app 导航接入，不在本页堆全部业务。
+import { useCan } from '@app/contracts';
+import { Link } from 'react-router-dom';
+
+/**
+ * 根据 User.read 的界面能力展示组织相关入口，其余区域显示业务空状态。
+ * 拥有读取能力不等于获得全部管理权限；系统管理仍按具体操作检查能力。
+ */
+export function HomePage() {
+  const canManage = useCan('User.read');
+  return (
+    <>
+      <div className="page-heading">
+        <div>
+          <p className="eyebrow">你的工作空间</p>
+          <h1>工作台</h1>
+          <p className="muted">业务从这里开始，逐步长成你需要的样子。</p>
+        </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" />
+          <div className="sheet sheet-front">
+            <span />
+            <span />
+            <span />
+            <b>+</b>
+          </div>
+        </div>
+        <p className="eyebrow">准备好，开始新的业务</p>
+        <h2 id="empty-title">这里还没有业务模块</h2>
+        <p>
+          添加你的第一个业务对象和页面后，
+          <br />
+          这里就会成为团队日常工作的地方。
+        </p>
+        {canManage && (
+          <a className="primary manage-link" href="/admin/">
+            配置用户与权限<span aria-hidden="true">↗</span>
+          </a>
+        )}
+      </section>
+      <footer className="workspace-footer">
+        <span>Cage · 让业务有序发生</span>
+        <span>属于你的业务，由你定义</span>
+      </footer>
+    </>
+  );
+}

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

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

package/templates/blank/apps/web/src/shared/ui/brand.tsx

@@ -0,0 +1,19 @@
+/**
+ * 登录页与工作台复用的品牌组件，只负责显示品牌及首页链接。
+ * 依赖 Router 的 Link 导航，不读取会话、不决定用户权限，也不导入具体业务模块。
+ */
+// 登录与工作台共用的品牌组件；只呈现，不读取模块或会话。
+import { Link } from 'react-router-dom';
+/**
+ * 渲染可访问名称完整的首页链接；未登录时目标页面仍由 app 的会话守卫处理。
+ */
+export function Brand() {
+  return (
+    <Link className="brand" to="/workspace" aria-label="Cage 工作台首页">
+      <span className="brand-mark">C</span>
+      <span>
+        Cage<span className="brand-dot">.</span>
+      </span>
+    </Link>
+  );
+}

package/templates/blank/apps/web/src/shared/ui/page-state.css

@@ -0,0 +1,47 @@
+/**
+ * 共享页面状态卡与返回链接的样式，采购和空白模板均由同步流程取得同一版本。
+ * 颜色变量由应用主题提供；这里只排版标题、说明和操作，具体错误分类由 PageState/QueryFailure 决定。
+ */
+/* 与两套工作台共享的纸面状态卡；状态清楚可读，链接保持可聚焦和可复制。 */
+.route-state {
+  margin: 32px 0;
+  padding: 68px 36px;
+  border: 1px solid var(--line);
+  border-radius: 7px;
+  background: #fdfefb;
+  text-align: center;
+}
+.route-state-mark {
+  display: block;
+  margin-bottom: 20px;
+  color: #7d9866;
+  font:
+    italic 42px Georgia,
+    serif;
+}
+.route-state h1 {
+  font-size: 26px;
+  letter-spacing: -0.5px;
+}
+.route-state p {
+  margin: 16px 0 26px;
+  color: var(--muted);
+  font-size: 13px;
+  line-height: 1.9;
+}
+.route-link {
+  display: inline-flex;
+  align-items: center;
+  padding: 10px 16px;
+  border: 1px solid var(--line);
+  border-radius: 4px;
+  background: #f1f5eb;
+  color: var(--green);
+  font-size: 12px;
+}
+.route-link:hover {
+  background: #e4ecd9;
+}
+.route-state > button {
+  margin-left: 12px;
+}

package/templates/blank/apps/web/src/shared/ui/page-state.tsx

@@ -0,0 +1,76 @@
+/**
+ * 供列表、详情和路由守卫复用的页面级状态组件。
+ * 将服务端可确认的错误与可恢复操作对应，保留返回链接；不泄露范围外记录是否真实存在。
+ */
+import type { ReactNode } from 'react';
+import { Link } from 'react-router-dom';
+import { CageQueryError } from '@app/contracts';
+import './page-state.css';
+
+/** 页面级状态保留导航入口，详情直达失败时也能回到列表，而不是出现空白页。 */
+/**
+ * 渲染标题、说明、返回链接和可选附加操作。
+ * props.title/description 为调用方提供的当前状态；to 是业务返回地址，label 缺省为返回列表。
+ * children 可放重试按钮；组件只呈现内容，不自行读取数据或推断错误。
+ */
+export function PageState({
+  title,
+  description,
+  to,
+  label = '返回列表',
+  children,
+}: {
+  title: string;
+  description: string;
+  to: string;
+  label?: string;
+  children?: ReactNode;
+}) {
+  return (
+    <section className="route-state" aria-labelledby="route-state-title">
+      <span className="route-state-mark" aria-hidden="true">
+        ↗
+      </span>
+      <h1 id="route-state-title">{title}</h1>
+      <p>{description}</p>
+      <Link className="route-link" to={to}>
+        {label}
+      </Link>
+      {children}
+    </section>
+  );
+}
+
+/** 按服务端错误区分权限、范围/不存在和服务故障；不从 URL 推断记录是否存在。 */
+/**
+ * 将查询异常映射为页面状态。CageQueryError 的 FORBIDDEN 与 NOT_FOUND 不展示重试按钮，其他错误允许调用 retry。
+ * props.error 为实际查询异常；to/label 决定退出路径，retry 由页面绑定 refetch。
+ * NOT_FOUND 同时涵盖记录不存在与不在可访问范围，不能据此向用户确认数据库中有无此记录。
+ */
+export function QueryFailure({
+  error,
+  to,
+  label,
+  retry,
+}: {
+  error: Error;
+  to: string;
+  label?: string;
+  retry: () => void;
+}) {
+  const code = error instanceof CageQueryError ? error.result.code : undefined;
+  const title = code === 'FORBIDDEN' ? '暂无访问权限' : code === 'NOT_FOUND' ? '记录不可用' : '暂时无法读取';
+  const description =
+    code === 'FORBIDDEN'
+      ? '当前账号没有访问此页面所需的权限，请联系管理员。'
+      : code === 'NOT_FOUND'
+        ? '记录不存在，或不在你当前可访问的数据范围内。'
+        : code === 'UNAUTHENTICATED'
+          ? '登录已过期，请重新登录后继续。'
+          : '请检查网络或稍后重新尝试。';
+  return (
+    <PageState title={title} description={description} to={to} label={label}>
+      {code !== 'FORBIDDEN' && code !== 'NOT_FOUND' && <button onClick={retry}>重新读取</button>}
+    </PageState>
+  );
+}