@locode2/harness 0.1.0-preview.1

package/bundled-plugins/fast-frontend/templates/antd-admin/pnpm-workspace.yaml

@@ -0,0 +1,4 @@
+packages:
+  - .
+
+onlyBuiltDependencies: []

package/bundled-plugins/fast-frontend/templates/antd-admin/public/generated/.gitkeep

@@ -0,0 +1 @@
+

package/bundled-plugins/fast-frontend/templates/antd-admin/scripts/validate-routes.mjs

@@ -0,0 +1,153 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import ts from "typescript";
+
+const projectRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const pagesRoot = join(projectRoot, "src", "pages");
+const allowedKeys = new Set([
+  "id",
+  "path",
+  "title",
+  "icon",
+  "order",
+  "parentId",
+  "hidden",
+]);
+const allowedIcons = new Set([
+  "AppstoreOutlined",
+  "DashboardOutlined",
+  "FileTextOutlined",
+  "FormOutlined",
+  "SettingOutlined",
+  "TeamOutlined",
+]);
+
+async function collectRouteFiles(directory) {
+  const entries = await readdir(directory, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const entryPath = join(directory, entry.name);
+    if (entry.isDirectory()) files.push(...await collectRouteFiles(entryPath));
+    else if (entry.isFile() && entry.name === "route.ts") files.push(entryPath);
+  }
+  return files;
+}
+
+function displayPath(path) {
+  return relative(projectRoot, path).split(sep).join("/");
+}
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+function unwrapExpression(expression) {
+  let current = expression;
+  while (
+    ts.isParenthesizedExpression(current) ||
+    ts.isAsExpression(current) ||
+    ts.isSatisfiesExpression(current)
+  ) {
+    current = current.expression;
+  }
+  return current;
+}
+
+function propertyName(property, file) {
+  const name = property.name;
+  if (ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNumericLiteral(name)) {
+    return name.text;
+  }
+  throw new Error(`${displayPath(file)} 只能使用静态属性名`);
+}
+
+function literalValue(expression, file, key) {
+  const value = unwrapExpression(expression);
+  if (ts.isStringLiteral(value) || ts.isNoSubstitutionTemplateLiteral(value)) return value.text;
+  if (ts.isNumericLiteral(value)) return Number(value.text);
+  if (value.kind === ts.SyntaxKind.TrueKeyword) return true;
+  if (value.kind === ts.SyntaxKind.FalseKeyword) return false;
+  throw new Error(`${displayPath(file)} 的 ${key} 必须是静态字符串、数字或布尔字面量`);
+}
+
+function parseRouteSource(source, file) {
+  const sourceFile = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+  const exportAssignment = sourceFile.statements.find(
+    (statement) => ts.isExportAssignment(statement) && !statement.isExportEquals,
+  );
+  assert(exportAssignment !== undefined, `${displayPath(file)} 必须 default export definePageRoute({...})`);
+
+  let expression = unwrapExpression(exportAssignment.expression);
+  if (ts.isCallExpression(expression)) {
+    assert(
+      ts.isIdentifier(expression.expression) && expression.expression.text === "definePageRoute",
+      `${displayPath(file)} 的默认导出必须调用 definePageRoute`,
+    );
+    assert(expression.arguments.length === 1, `${displayPath(file)} 的 definePageRoute 只接受一个参数`);
+    expression = unwrapExpression(expression.arguments[0]);
+  }
+  assert(ts.isObjectLiteralExpression(expression), `${displayPath(file)} 必须导出静态路由对象`);
+
+  const route = {};
+  for (const property of expression.properties) {
+    assert(ts.isPropertyAssignment(property), `${displayPath(file)} 不允许展开、方法或计算属性`);
+    const key = propertyName(property, file);
+    assert(allowedKeys.has(key), `${displayPath(file)} 包含未知字段：${key}`);
+    route[key] = literalValue(property.initializer, file, key);
+  }
+  return route;
+}
+
+function validateRoute(route, file) {
+  const label = displayPath(file);
+  assert(typeof route.id === "string" && /^[a-zA-Z0-9][a-zA-Z0-9._:-]*$/.test(route.id), `${label} 的 id 无效`);
+  assert(typeof route.path === "string" && /^\/(?:[^\s?#]*)$/.test(route.path), `${label} 的 path 必须是以 / 开头且不含空白、查询或片段的路径`);
+  assert(typeof route.title === "string" && route.title.trim().length > 0, `${label} 的 title 不能为空`);
+  if (route.icon !== undefined) assert(typeof route.icon === "string" && allowedIcons.has(route.icon), `${label} 的 icon 不受支持：${String(route.icon)}`);
+  if (route.order !== undefined) assert(Number.isFinite(route.order), `${label} 的 order 必须是有限数字`);
+  if (route.parentId !== undefined) assert(typeof route.parentId === "string" && route.parentId.length > 0, `${label} 的 parentId 无效`);
+  if (route.hidden !== undefined) assert(typeof route.hidden === "boolean", `${label} 的 hidden 必须是布尔值`);
+  return route;
+}
+
+function validateParentGraph(routes) {
+  const byId = new Map(routes.map(({ route }) => [route.id, route]));
+  for (const { route, file } of routes) {
+    if (route.parentId === undefined) continue;
+    assert(route.parentId !== route.id, `${displayPath(file)} 不能把自身设为父级`);
+    assert(byId.has(route.parentId), `${displayPath(file)} 引用了不存在的父级：${route.parentId}`);
+
+    const visited = new Set([route.id]);
+    let current = route;
+    while (current.parentId !== undefined) {
+      assert(!visited.has(current.parentId), `${displayPath(file)} 的父级关系存在循环`);
+      visited.add(current.parentId);
+      current = byId.get(current.parentId);
+      assert(current !== undefined, `${displayPath(file)} 引用了不存在的父级`);
+    }
+  }
+}
+
+const routeFiles = await collectRouteFiles(pagesRoot);
+assert(routeFiles.length > 0, "src/pages 中至少需要一个 route.ts");
+
+const routes = [];
+for (const file of routeFiles) {
+  const route = validateRoute(parseRouteSource(await readFile(file, "utf8"), file), file);
+  const pageFile = join(dirname(file), "page.tsx");
+  assert((await stat(pageFile).catch(() => undefined))?.isFile() === true, `${displayPath(file)} 缺少同目录 page.tsx`);
+  routes.push({ route, file });
+}
+
+const ids = new Map();
+const paths = new Map();
+for (const { route, file } of routes) {
+  assert(!ids.has(route.id), `${displayPath(file)} 与 ${ids.get(route.id)} 使用了重复 id：${route.id}`);
+  assert(!paths.has(route.path), `${displayPath(file)} 与 ${paths.get(route.path)} 使用了重复 path：${route.path}`);
+  ids.set(route.id, displayPath(file));
+  paths.set(route.path, displayPath(file));
+}
+validateParentGraph(routes);
+
+console.log(`路由校验通过：${routes.length} 个页面`);

package/bundled-plugins/fast-frontend/templates/antd-admin/src/app/App.tsx

@@ -0,0 +1,27 @@
+import { App as AntApp, ConfigProvider, theme } from "antd";
+import zhCN from "antd/locale/zh_CN";
+import { RouterProvider } from "react-router-dom";
+
+import { router } from "../routes/router";
+
+export function App() {
+  return (
+    <ConfigProvider
+      locale={zhCN}
+      theme={{
+        algorithm: theme.defaultAlgorithm,
+        token: {
+          borderRadius: 10,
+          colorPrimary: "#635bff",
+          colorBgLayout: "#f5f7fb",
+          fontFamily:
+            "Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif",
+        },
+      }}
+    >
+      <AntApp>
+        <RouterProvider router={router} />
+      </AntApp>
+    </ConfigProvider>
+  );
+}

package/bundled-plugins/fast-frontend/templates/antd-admin/src/app/NotFoundPage.tsx

@@ -0,0 +1,15 @@
+import { Button, Result } from "antd";
+import { useNavigate } from "react-router-dom";
+
+export function NotFoundPage() {
+  const navigate = useNavigate();
+
+  return (
+    <Result
+      status="404"
+      title="404"
+      subTitle="抱歉，你访问的页面不存在或已经被移动。"
+      extra={<Button type="primary" onClick={() => navigate("/")}>返回工作台</Button>}
+    />
+  );
+}

package/bundled-plugins/fast-frontend/templates/antd-admin/src/features/.gitkeep

@@ -0,0 +1 @@
+

package/bundled-plugins/fast-frontend/templates/antd-admin/src/layouts/MainLayout.tsx

@@ -0,0 +1,77 @@
+import {
+  BellOutlined,
+  MenuFoldOutlined,
+  MenuUnfoldOutlined,
+  ProductOutlined,
+} from "@ant-design/icons";
+import { Avatar, Breadcrumb, Button, Flex, Layout, Menu, Space, Typography, theme } from "antd";
+import { useMemo, useState } from "react";
+import { Outlet, useLocation, useNavigate } from "react-router-dom";
+
+import { menuItems } from "../routes/menu";
+import { findPageByLocation } from "../routes/registry";
+
+const { Content, Header, Sider } = Layout;
+
+export function MainLayout() {
+  const [collapsed, setCollapsed] = useState(false);
+  const location = useLocation();
+  const navigate = useNavigate();
+  const {
+    token: { colorBgContainer, colorBorderSecondary },
+  } = theme.useToken();
+  const activePage = useMemo(() => findPageByLocation(location.pathname), [location.pathname]);
+
+  return (
+    <Layout className="app-shell">
+      <Sider
+        breakpoint="lg"
+        className="app-sider"
+        collapsed={collapsed}
+        collapsedWidth={72}
+        trigger={null}
+        width={244}
+        onBreakpoint={setCollapsed}
+      >
+        <Flex align="center" className="brand" gap={12}>
+          <span className="brand-mark"><ProductOutlined /></span>
+          {!collapsed && <span className="brand-name">业务工作台</span>}
+        </Flex>
+        <Menu
+          items={menuItems}
+          mode="inline"
+          selectedKeys={[activePage?.path ?? location.pathname]}
+          onClick={({ key }) => navigate(key)}
+        />
+      </Sider>
+
+      <Layout>
+        <Header
+          className="app-header"
+          style={{ background: colorBgContainer, borderColor: colorBorderSecondary }}
+        >
+          <Flex align="center" justify="space-between">
+            <Space size={12}>
+              <Button
+                aria-label={collapsed ? "展开导航" : "收起导航"}
+                icon={collapsed ? <MenuUnfoldOutlined /> : <MenuFoldOutlined />}
+                type="text"
+                onClick={() => setCollapsed((value) => !value)}
+              />
+              <Breadcrumb items={[{ title: "首页" }, { title: activePage?.title ?? "页面" }]} />
+            </Space>
+            <Space size={14}>
+              <Button aria-label="通知" icon={<BellOutlined />} type="text" />
+              <Avatar className="user-avatar">管</Avatar>
+              <Typography.Text className="user-name">管理员</Typography.Text>
+            </Space>
+          </Flex>
+        </Header>
+
+        <Content className="app-content">
+          <Outlet />
+        </Content>
+      </Layout>
+    </Layout>
+  );
+}

package/bundled-plugins/fast-frontend/templates/antd-admin/src/main.tsx

@@ -0,0 +1,14 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+
+import { App } from "./app/App";
+import "./styles/global.css";
+
+const root = document.getElementById("root");
+if (root === null) throw new Error("缺少 #root 挂载节点");
+
+createRoot(root).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);

package/bundled-plugins/fast-frontend/templates/antd-admin/src/mocks/dashboard.ts

@@ -0,0 +1,48 @@
+export interface Metric {
+  readonly key: string;
+  readonly label: string;
+  readonly value: number;
+  readonly suffix?: string;
+  readonly trend: number;
+  readonly note: string;
+}
+
+export interface WorkItem {
+  readonly id: string;
+  readonly title: string;
+  readonly owner: string;
+  readonly status: "待处理" | "进行中" | "已完成";
+  readonly dueAt: string;
+}
+
+export interface DashboardOverview {
+  readonly metrics: readonly Metric[];
+  readonly workItems: readonly WorkItem[];
+  readonly completionRate: number;
+}
+
+const overview: DashboardOverview = {
+  metrics: [
+    { key: "visits", label: "今日访问", value: 8236, trend: 12.8, note: "较昨日" },
+    { key: "orders", label: "新增订单", value: 386, trend: 8.2, note: "较昨日" },
+    { key: "revenue", label: "本月营收", value: 128.6, suffix: "万元", trend: 18.4, note: "较上月" },
+    { key: "conversion", label: "转化率", value: 6.42, suffix: "%", trend: -0.6, note: "较上周" },
+  ],
+  completionRate: 76,
+  workItems: [
+    { id: "WK-1048", title: "确认华东区域季度目标", owner: "李敏", status: "进行中", dueAt: "今天 17:00" },
+    { id: "WK-1047", title: "审核重点客户折扣方案", owner: "王岩", status: "待处理", dueAt: "明天 10:30" },
+    { id: "WK-1042", title: "发布新版运营周报", owner: "陈晨", status: "已完成", dueAt: "昨天 16:20" },
+    { id: "WK-1039", title: "补充供应商风险材料", owner: "赵宁", status: "待处理", dueAt: "8 月 30 日" },
+  ],
+};
+
+export function loadDashboardOverview(signal?: AbortSignal): Promise<DashboardOverview> {
+  return new Promise((resolve, reject) => {
+    const timer = window.setTimeout(() => resolve(overview), 180);
+    signal?.addEventListener("abort", () => {
+      window.clearTimeout(timer);
+      reject(new DOMException("请求已取消", "AbortError"));
+    }, { once: true });
+  });
+}

package/bundled-plugins/fast-frontend/templates/antd-admin/src/pages/dashboard/page.tsx

@@ -0,0 +1,151 @@
+import {
+  ArrowDownOutlined,
+  ArrowRightOutlined,
+  ArrowUpOutlined,
+  CheckCircleFilled,
+  ClockCircleFilled,
+  SyncOutlined,
+} from "@ant-design/icons";
+import {
+  Alert,
+  Button,
+  Card,
+  Col,
+  Flex,
+  Progress,
+  Row,
+  Skeleton,
+  Space,
+  Statistic,
+  Table,
+  Tag,
+  Typography,
+  type TableColumnsType,
+} from "antd";
+import { useEffect, useState } from "react";
+
+import {
+  loadDashboardOverview,
+  type DashboardOverview,
+  type WorkItem,
+} from "../../mocks/dashboard";
+
+const statusPresentation = {
+  待处理: { color: "gold", icon: <ClockCircleFilled /> },
+  进行中: { color: "processing", icon: <SyncOutlined spin /> },
+  已完成: { color: "success", icon: <CheckCircleFilled /> },
+} as const;
+
+const columns: TableColumnsType<WorkItem> = [
+  {
+    title: "事项",
+    dataIndex: "title",
+    render: (title: string, record) => (
+      <Space orientation="vertical" size={2}>
+        <Typography.Text strong>{title}</Typography.Text>
+        <Typography.Text type="secondary">{record.id}</Typography.Text>
+      </Space>
+    ),
+  },
+  { title: "负责人", dataIndex: "owner", width: 110 },
+  {
+    title: "状态",
+    dataIndex: "status",
+    width: 120,
+    render: (status: WorkItem["status"]) => {
+      const presentation = statusPresentation[status];
+      return <Tag color={presentation.color} icon={presentation.icon}>{status}</Tag>;
+    },
+  },
+  { title: "截止时间", dataIndex: "dueAt", width: 140 },
+];
+
+export default function DashboardPage() {
+  const [data, setData] = useState<DashboardOverview>();
+  const [error, setError] = useState<string>();
+
+  useEffect(() => {
+    const controller = new AbortController();
+    void loadDashboardOverview(controller.signal)
+      .then(setData)
+      .catch((reason: unknown) => {
+        if (!(reason instanceof DOMException && reason.name === "AbortError")) {
+          setError(reason instanceof Error ? reason.message : "数据加载失败");
+        }
+      });
+    return () => controller.abort();
+  }, []);
+
+  return (
+    <main className="dashboard-page">
+      <Flex align="flex-end" className="page-heading" justify="space-between" wrap>
+        <div>
+          <Typography.Title level={2}>下午好，管理员</Typography.Title>
+          <Typography.Text type="secondary">这里是今天的业务进展和待办事项。</Typography.Text>
+        </div>
+        <Button type="primary">新建业务单</Button>
+      </Flex>
+
+      {error === undefined ? null : <Alert message="无法加载工作台" description={error} showIcon type="error" />}
+
+      <Row gutter={[16, 16]}>
+        {(data?.metrics ?? [null, null, null, null]).map((metric, index) => (
+          <Col key={metric?.key ?? index} lg={6} md={12} xs={24}>
+            <Card className="metric-card" variant="borderless">
+              {metric === null ? <Skeleton active paragraph={false} /> : (
+                <>
+                  <Statistic
+                    title={metric.label}
+                    value={metric.value}
+                    {...(metric.suffix === undefined ? {} : { suffix: metric.suffix })}
+                    {...(metric.suffix === "%" ? { precision: 2 } : {})}
+                  />
+                  <Space className={metric.trend >= 0 ? "trend-positive" : "trend-negative"} size={4}>
+                    {metric.trend >= 0 ? <ArrowUpOutlined /> : <ArrowDownOutlined />}
+                    <span>{Math.abs(metric.trend)}%</span>
+                    <Typography.Text type="secondary">{metric.note}</Typography.Text>
+                  </Space>
+                </>
+              )}
+            </Card>
+          </Col>
+        ))}
+      </Row>
+
+      <Row gutter={[16, 16]}>
+        <Col lg={16} xs={24}>
+          <Card
+            className="work-card"
+            title="重点待办"
+            extra={<Button icon={<ArrowRightOutlined />} iconPlacement="end" type="link">查看全部</Button>}
+          >
+            <Table<WorkItem>
+              columns={columns}
+              dataSource={data?.workItems}
+              loading={data === undefined && error === undefined}
+              pagination={false}
+              rowKey="id"
+              scroll={{ x: 620 }}
+            />
+          </Card>
+        </Col>
+        <Col lg={8} xs={24}>
+          <Card className="progress-card" title="本月目标" variant="borderless">
+            <Flex align="center" className="progress-content" vertical>
+              <Progress
+                percent={data?.completionRate ?? 0}
+                size={168}
+                strokeColor={{ "0%": "#8178ff", "100%": "#4e7cff" }}
+                type="dashboard"
+              />
+              <Typography.Title level={4}>稳步推进中</Typography.Title>
+              <Typography.Paragraph type="secondary">
+                当前进度领先计划 4.2%，继续关注重点客户的交付节奏。
+              </Typography.Paragraph>
+            </Flex>
+          </Card>
+        </Col>
+      </Row>
+    </main>
+  );
+}

package/bundled-plugins/fast-frontend/templates/antd-admin/src/pages/dashboard/route.ts

@@ -0,0 +1,9 @@
+import { definePageRoute } from "../../routes/definition";
+
+export default definePageRoute({
+  id: "dashboard",
+  path: "/",
+  title: "工作台",
+  icon: "DashboardOutlined",
+  order: 10,
+});

package/bundled-plugins/fast-frontend/templates/antd-admin/src/routes/definition.ts

@@ -0,0 +1,21 @@
+export type RouteIconName =
+  | "AppstoreOutlined"
+  | "DashboardOutlined"
+  | "FileTextOutlined"
+  | "FormOutlined"
+  | "SettingOutlined"
+  | "TeamOutlined";
+
+export interface PageRouteDefinition {
+  readonly id: string;
+  readonly path: string;
+  readonly title: string;
+  readonly icon?: RouteIconName;
+  readonly order?: number;
+  readonly parentId?: string;
+  readonly hidden?: boolean;
+}
+
+export function definePageRoute<const T extends PageRouteDefinition>(definition: T): T {
+  return definition;
+}

package/bundled-plugins/fast-frontend/templates/antd-admin/src/routes/menu.tsx

@@ -0,0 +1,44 @@
+import {
+  AppstoreOutlined,
+  DashboardOutlined,
+  FileTextOutlined,
+  FormOutlined,
+  SettingOutlined,
+  TeamOutlined,
+} from "@ant-design/icons";
+import type { MenuProps } from "antd";
+import type { ReactNode } from "react";
+
+import type { RouteIconName } from "./definition";
+import { registeredPages, type RegisteredPage } from "./registry";
+
+type MenuItem = Required<MenuProps>["items"][number];
+
+const icons: Record<RouteIconName, ReactNode> = {
+  AppstoreOutlined: <AppstoreOutlined />,
+  DashboardOutlined: <DashboardOutlined />,
+  FileTextOutlined: <FileTextOutlined />,
+  FormOutlined: <FormOutlined />,
+  SettingOutlined: <SettingOutlined />,
+  TeamOutlined: <TeamOutlined />,
+};
+
+function childrenOf(parent: RegisteredPage): MenuItem[] {
+  return registeredPages
+    .filter((page) => !page.hidden && page.parentId === parent.id)
+    .map(toMenuItem);
+}
+
+function toMenuItem(page: RegisteredPage): MenuItem {
+  const children = childrenOf(page);
+  return {
+    key: page.path,
+    label: page.title,
+    ...(page.icon === undefined ? {} : { icon: icons[page.icon] }),
+    ...(children.length === 0 ? {} : { children }),
+  };
+}
+
+export const menuItems: NonNullable<MenuProps["items"]> = registeredPages
+  .filter((page) => !page.hidden && page.parentId === undefined)
+  .map(toMenuItem);

package/bundled-plugins/fast-frontend/templates/antd-admin/src/routes/registry.ts

@@ -0,0 +1,48 @@
+import { lazy, type ComponentType, type LazyExoticComponent } from "react";
+
+import type { PageRouteDefinition } from "./definition";
+
+export interface RegisteredPage extends PageRouteDefinition {
+  readonly Component: LazyExoticComponent<ComponentType>;
+  readonly sourceDirectory: string;
+}
+
+interface PageModule {
+  readonly default: ComponentType;
+}
+
+const routeModules = import.meta.glob<PageRouteDefinition>("../pages/**/route.ts", {
+  eager: true,
+  import: "default",
+});
+const pageModules = import.meta.glob<PageModule>("../pages/**/page.tsx");
+
+function pageFileFor(routeFile: string): string {
+  return `${routeFile.slice(0, -"route.ts".length)}page.tsx`;
+}
+
+function comparePages(left: RegisteredPage, right: RegisteredPage): number {
+  const byOrder = (left.order ?? 0) - (right.order ?? 0);
+  return byOrder === 0 ? left.title.localeCompare(right.title, "zh-CN") : byOrder;
+}
+
+export const registeredPages: readonly RegisteredPage[] = Object.entries(routeModules)
+  .map(([routeFile, definition]) => {
+    const pageFile = pageFileFor(routeFile);
+    const loadPage = pageModules[pageFile];
+    if (loadPage === undefined) {
+      throw new Error(`${routeFile} 缺少同目录 page.tsx，请先运行 pnpm run validate:routes`);
+    }
+    return {
+      ...definition,
+      Component: lazy(loadPage),
+      sourceDirectory: routeFile.slice(0, -"route.ts".length),
+    };
+  })
+  .sort(comparePages);
+
+export function findPageByLocation(pathname: string): RegisteredPage | undefined {
+  return [...registeredPages]
+    .sort((left, right) => right.path.length - left.path.length)
+    .find(({ path }) => path === "/" ? pathname === "/" : pathname === path || pathname.startsWith(`${path}/`));
+}

package/bundled-plugins/fast-frontend/templates/antd-admin/src/routes/router.tsx

@@ -0,0 +1,34 @@
+import type { RouteObject } from "react-router-dom";
+import { createBrowserRouter } from "react-router-dom";
+import { Suspense } from "react";
+
+import { NotFoundPage } from "../app/NotFoundPage";
+import { MainLayout } from "../layouts/MainLayout";
+import { BusinessProviders } from "../shared/components/business/BusinessProviders";
+import { registeredPages, type RegisteredPage } from "./registry";
+
+function pageRoute(page: RegisteredPage): RouteObject {
+  const Page = page.Component;
+  const element = (
+    <Suspense fallback={<div className="page-loading" role="status">正在加载页面…</div>}>
+      <Page />
+    </Suspense>
+  );
+  if (page.path === "/") return { index: true, element };
+  return { path: page.path.replace(/^\//, ""), element };
+}
+
+export const router = createBrowserRouter([
+  {
+    path: "/",
+    element: (
+      <BusinessProviders>
+        <MainLayout />
+      </BusinessProviders>
+    ),
+    children: [
+      ...registeredPages.map(pageRoute),
+      { path: "*", element: <NotFoundPage /> },
+    ],
+  },
+]);

package/bundled-plugins/fast-frontend/templates/antd-admin/src/shared/components/business/.gitkeep

@@ -0,0 +1 @@
+

package/bundled-plugins/fast-frontend/templates/antd-admin/src/shared/components/business/BusinessProviders.tsx

@@ -0,0 +1,9 @@
+import type { ReactNode } from "react";
+
+/**
+ * Register application-wide business Context providers here.
+ * The protected router mounts this component around every business route.
+ */
+export function BusinessProviders({ children }: { readonly children: ReactNode }) {
+  return <>{children}</>;
+}