新增后台或工作台页面

在 /admin 或 /app 下新增一个页面:带守卫的服务端函数、两种语言的文案和一个导航入口。

本指南新增单个页面:/admin 下面向运营人员的页面,或 /app 下面向用户的页面。布局已经保护了这个页面,所以你只需要添加一个路由文件、一个检查调用者身份的服务端函数、两种语言的文案和一个导航入口。带有自己数据表的完整功能应该做成模块,见构建模块。

准备工作

  • 一个能用 pnpm dev 跑起来的项目,以及一个管理员账号。见运行管理后台。
  • 页面路径(/admin/<name> 或 /app/<name>),以及它读取什么、写入什么。
  • 后台页面还需要确定用哪个权限键做门禁。/admin/permissions 的权限目录里有合适的就复用。
  • 如果你使用编码 agent,new-page 技能包含同样的步骤。见使用 agent 技能。

了解布局已经做了什么

区域布局路由在页面加载前做的事
/admin/*src/routes/{-$locale}/admin.tsx要求有会话并具备 admin.access 权限。没有会话跳转到 /system/session-expired,没有权限跳转到 /system/permission-denied
/app/*src/routes/{-$locale}/app.tsx要求有会话。没有会话跳转到 /system/session-expired,账号被封禁跳转到 /system/permission-denied

两个布局还会对属于已停用插件的页面返回 not found,并通过 AuthProvider 把当前用户的权限传给页面。在这两个目录下新建的文件不需要额外代码就受保护。

布局只保护页面,不保护数据。服务端函数是任何人都能调用的 HTTP 端点,所以每个服务端函数都必须检查调用者。

新增页面

编写服务端函数

加到 src/server/functions/ 下对应的文件里,或在那里新建文件。用 zod 校验输入,先解析调用者,再委托给服务层。

src/server/functions/reports.ts
import { createServerFn } from "@tanstack/react-start";
import { requireAdminPermission } from "./admin-permissions";
import { requireCurrentUserId } from "./session";

// Admin: gate on a permission.
export const getAdminReports = createServerFn({ method: "GET" }).handler(async () => {
  await requireAdminPermission("reports.read");
  return listReports();
});

// Workspace: bind to the signed-in user.
export const getMyReports = createServerFn({ method: "GET" }).handler(async () => {
  const userId = await requireCurrentUserId();
  return listReportsForUser(userId);
});

调用者没有权限时,requireAdminPermission() 抛出 Permission denied: <key>。requireCurrentUserId() 拒绝没有会话或已被封禁的调用者,不存在兜底身份。数据库访问写在 src/server/db/repositories/ 下的仓储里,由服务层调用。

在两种语言里添加文案

在 src/i18n/locales/en/messages.ts 和 src/i18n/locales/zh/messages.ts 中新增键完全一致的命名空间,并在 shell.nav(后台)或 appConsole(工作台)下为导航入口加一个标签。见新增与修改文案。

创建路由文件

后台页面参考 src/routes/{-$locale}/admin/rate-limits.tsx 的结构:

src/routes/{-$locale}/admin/reports.tsx
import { createFileRoute } from "@tanstack/react-router";
import { AdminRecords } from "@/components/admin/admin-records";
import { adminRouteFeedback } from "@/components/admin/admin-route-feedback";
import { AppShell } from "@/components/layout/app-shell";
import { getMessageNamespace, normalizeLocale } from "@/i18n/messages";
import { getAdminReports } from "@/server/functions/reports";

export const Route = createFileRoute("/{-$locale}/admin/reports")({
  ...adminRouteFeedback,
  loader: () => getAdminReports(),
  component: AdminReportsPage,
});

function AdminReportsPage() {
  const rows = Route.useLoaderData();
  const locale = normalizeLocale(Route.useParams().locale);
  const copy = getMessageNamespace(locale, "adminReportsCopy");
  return (
    <AppShell activeNav="Reports" currentPage={copy.currentPage} locale={locale} mode="admin">
      <AdminRecords
        columns={[{ key: "name", label: copy.name, render: (row) => row.name }]}
        emptyLabel={copy.empty}
        rowKey={(row) => row.id}
        rows={rows}
      />
    </AppShell>
  );
}

adminRouteFeedback 提供加载中和出错时的组件,每个后台路由都要展开它。

工作台页面参考 src/routes/{-$locale}/app/tickets/index.tsx。这个页面渲染在 @/components/layout/app-console-sidebar 的 AppConsoleLayout 里,用 useI18n() 读取文案,并把自己导航入口的 id 作为 active 传入。

带详情子页面的列表页,在路径更深时返回 <Outlet />,写法参考 src/routes/{-$locale}/admin/orders.tsx。

用设计系统搭建页面主体

组合后台模式(AdminRecords、AdminMetrics、AdminPanel、Config* 布局、useAdminSave)和 src/components/motion 里的组件。不要导入 src/components/ui,也不要添加 <main>,<main> 由外壳渲染。见使用设计系统。

需要保存的页面调用 useAdminSave("<key>.write")。allowed 为 false 时禁用表单,并在执行写入的服务端函数里再检查一次同样的权限。

添加导航入口

侧边栏入口由插件贡献。属于你产品本身的页面,加到 src/plugins/foundation/plugin.ts 的底座插件里。

后台入口加在 adminNav 数组中:

src/plugins/foundation/plugin.ts
{
  ...operations,
  label: "Reports",
  labelKey: "shell.nav.reports",
  to: "/admin/reports",
  icon: ListChecks,
  permission: "reports.read",
  order: 650,
},

文件顶部的分组常量(overview、operations、commerce、platform、security、settings)决定入口出现在侧边栏的哪个分组。order 决定位置。底座入口以 100 为步长,你的入口可以插在两个入口之间。permission 必填,没有该权限的用户看不到这个入口。

工作台入口加在同一插件的 app.nav 列表中:

src/plugins/foundation/plugin.ts
{
  id: "reports",
  icon: ListTodo,
  labelKey: "appConsole.reports",
  path: "/app/reports",
  section: "product",
  order: 35,
},

section 取 product 或 account。页面把同一个 id 作为 active 传给 AppConsoleLayout。

如果希望这个页面可以在 /admin/plugins 里整体开关,就为它单独写一个插件,见后台插件。

授予新权限

复用已有权限键时跳过这一步。新增权限键时,在 src/server/services/super-admin-bootstrap.service.ts 的 superAdminPermissionTemplates 中加一行,然后运行:

pnpm db:bootstrap-super-admin

脚本会写入全部权限,并全部授予 Super Admin 角色。其他角色在 /admin/roles 中授权。见管理用户、角色与权限。

重新生成路由树

pnpm dev

启动开发服务器会重写 src/routeTree.gen.ts,收录新路由。然后运行 pnpm typecheck。

验证

pnpm typecheck
pnpm validate:auth-boundary
pnpm validate:plugins
pnpm validate:beui-console
pnpm validate:route-i18n
pnpm validate:app-i18n

这些校验器在新页面上检查以下问题:

校验器何时失败
pnpm validate:auth-boundary某个导出的服务端函数既不解析身份也不检查权限。确实需要公开的函数必须连同理由写进 scripts/validate/auth-boundary.ts 的 publicServerFunctions
pnpm validate:plugins导航入口指向不存在的路由文件、后台入口没有 permission,或工作台页面传入的 active id 没有任何 app.nav 入口声明
pnpm validate:beui-console页面导入了 src/components/ui、没有渲染在外壳里,或自带 <main>
pnpm validate:route-i18n路由文件不在 src/routes/{-$locale}/ 下

然后在浏览器里检查:

  • 在浅色和深色主题下,分别用英文路径和 /zh 路径打开页面。
  • 用没有该权限的用户登录。侧边栏入口消失,直接打开 URL 会显示路由的出错状态,因为 loader 调用的服务端函数拒绝了请求。
  • 退出登录后打开 URL,页面跳转到 /system/session-expired。

下一步