新增后台或工作台页面
在 /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 校验输入,先解析调用者,再委托给服务层。
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 的结构:
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 数组中:
{
...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 列表中:
{
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 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。