feat: 重构前端为企业 Admin 后台布局，引入 React Router 路由

- 引入 React Router v7 (Declarative mode) 实现 SPA 路由
- 重构 Layout 为 Header + 侧边栏 + 内容区的企业 Admin 布局
- 新增侧边栏菜单组件，支持折叠/展开，状态持久化到 localStorage
- 新增示例页面：仪表盘、用户管理、系统设置、404
- 菜单配置与路由统一为单一数据源 (menu.tsx)
- Vite code splitting 新增 vendor-router 组
- 更新 DEVELOPMENT.md 和 README.md 文档

tests/web/App.test.tsx

@@ -1,43 +1,14 @@
 /* eslint-disable @typescript-eslint/require-await */
-import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
-import { render, screen } from "@testing-library/react";
+import { screen } from "@testing-library/react";
 import { describe, expect, test } from "bun:test";
-import { createElement, StrictMode } from "react";
+import { createElement } from "react";
 
 import { APP } from "../../src/shared/app";
 import { App } from "../../src/web/app";
-import { ErrorBoundary } from "../../src/web/components/ErrorBoundary";
-
-function createTestQueryClient() {
-  return new QueryClient({
-    defaultOptions: {
-      queries: {
-        retry: false,
-        staleTime: 0,
-      },
-    },
-  });
-}
-
-function renderApp() {
-  const queryClient = createTestQueryClient();
-
-  return render(
-    createElement(
-      StrictMode,
-      null,
-      createElement(
-        ErrorBoundary,
-        null,
-        createElement(QueryClientProvider, { client: queryClient }, createElement(App)),
-      ),
-    ),
-  );
-}
+import { renderWithProviders } from "./test-utils";
 
 describe("App", () => {
   test("渲染 Layout 骨架和品牌名", () => {
-    // mock /health fetch 避免网络错误
     window.fetch = (async () => {
       return new Response(JSON.stringify({ ok: true, service: "test-app", timestamp: new Date().toISOString() }), {
         headers: { "Content-Type": "application/json" },
@@ -45,11 +16,26 @@ describe("App", () => {
       });
     }) as unknown as typeof fetch;
 
-    renderApp();
+    renderWithProviders(createElement(App));
 
     expect(screen.getByText(APP.title)).not.toBeNull();
     expect(screen.getByText("系统")).not.toBeNull();
     expect(screen.getByText("明亮")).not.toBeNull();
     expect(screen.getByText("黑暗")).not.toBeNull();
   });
+
+  test("渲染侧边栏菜单项", () => {
+    window.fetch = (async () => {
+      return new Response(JSON.stringify({ ok: true, service: "test-app", timestamp: new Date().toISOString() }), {
+        headers: { "Content-Type": "application/json" },
+        status: 200,
+      });
+    }) as unknown as typeof fetch;
+
+    renderWithProviders(createElement(App));
+
+    expect(screen.getAllByText("仪表盘").length).toBeGreaterThan(0);
+    expect(screen.getAllByText("用户管理").length).toBeGreaterThan(0);
+    expect(screen.getAllByText("系统设置").length).toBeGreaterThan(0);
+  });
 });

tests/web/components/Sidebar/index.test.tsx

@@ -0,0 +1,24 @@
+import { screen } from "@testing-library/react";
+import { describe, expect, test } from "bun:test";
+import { createElement } from "react";
+
+import { Sidebar } from "../../../../src/web/components/Sidebar";
+import { renderWithProviders } from "../../test-utils";
+
+describe("Sidebar", () => {
+  test("渲染菜单项", () => {
+    renderWithProviders(createElement(Sidebar, { collapsed: false }));
+
+    expect(screen.getByText("仪表盘")).not.toBeNull();
+    expect(screen.getByText("用户管理")).not.toBeNull();
+    expect(screen.getByText("系统设置")).not.toBeNull();
+  });
+
+  test("折叠状态下仍渲染菜单项", () => {
+    renderWithProviders(createElement(Sidebar, { collapsed: true }));
+
+    expect(screen.getByText("仪表盘")).not.toBeNull();
+    expect(screen.getByText("用户管理")).not.toBeNull();
+    expect(screen.getByText("系统设置")).not.toBeNull();
+  });
+});

tests/web/routes/404.test.tsx

@@ -0,0 +1,16 @@
+import { screen } from "@testing-library/react";
+import { describe, expect, test } from "bun:test";
+import { createElement } from "react";
+
+import { NotFoundPage } from "../../../src/web/pages/404";
+import { renderWithProviders } from "../test-utils";
+
+describe("NotFoundPage", () => {
+  test("渲染 404 页面", () => {
+    renderWithProviders(createElement(NotFoundPage));
+
+    expect(screen.getByText("404")).not.toBeNull();
+    expect(screen.getByText("您访问的页面不存在")).not.toBeNull();
+    expect(screen.getByText("返回首页")).not.toBeNull();
+  });
+});

tests/web/routes/dashboard.test.tsx

@@ -0,0 +1,22 @@
+/* eslint-disable @typescript-eslint/require-await */
+import { screen } from "@testing-library/react";
+import { describe, expect, test } from "bun:test";
+import { createElement } from "react";
+
+import { DashboardPage } from "../../../src/web/pages/dashboard";
+import { renderWithProviders } from "../test-utils";
+
+describe("DashboardPage", () => {
+  test("渲染欢迎信息", () => {
+    window.fetch = (async () => {
+      return new Response(JSON.stringify({ ok: true, service: "test-app", timestamp: new Date().toISOString() }), {
+        headers: { "Content-Type": "application/json" },
+        status: 200,
+      });
+    }) as unknown as typeof fetch;
+
+    renderWithProviders(createElement(DashboardPage));
+
+    expect(screen.getByText(/欢迎使用/)).not.toBeNull();
+  });
+});

tests/web/routes/settings.test.tsx

@@ -0,0 +1,15 @@
+import { screen } from "@testing-library/react";
+import { describe, expect, test } from "bun:test";
+import { createElement } from "react";
+
+import { SettingsPage } from "../../../src/web/pages/settings";
+import { renderWithProviders } from "../test-utils";
+
+describe("SettingsPage", () => {
+  test("渲染系统设置页面", () => {
+    renderWithProviders(createElement(SettingsPage));
+
+    expect(screen.getByText("系统设置")).not.toBeNull();
+    expect(screen.getByText("页面建设中...")).not.toBeNull();
+  });
+});

tests/web/routes/users.test.tsx

@@ -0,0 +1,15 @@
+import { screen } from "@testing-library/react";
+import { describe, expect, test } from "bun:test";
+import { createElement } from "react";
+
+import { UsersPage } from "../../../src/web/pages/users";
+import { renderWithProviders } from "../test-utils";
+
+describe("UsersPage", () => {
+  test("渲染用户管理页面", () => {
+    renderWithProviders(createElement(UsersPage));
+
+    expect(screen.getByText("用户管理")).not.toBeNull();
+    expect(screen.getByText("页面建设中...")).not.toBeNull();
+  });
+});

tests/web/test-utils.tsx

@@ -1,7 +1,10 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { render } from "@testing-library/react";
 import { mock } from "bun:test";
+import { createElement, StrictMode } from "react";
+import { MemoryRouter } from "react-router";
 
-// Note: jsdom and polyfills are now set up in tests/setup.ts
-// This file only contains component-specific mocks
+import { ErrorBoundary } from "../../src/web/components/ErrorBoundary";
 
 // Mock recharts BEFORE any component imports
 void mock.module("recharts", () => ({
@@ -15,6 +18,42 @@ void mock.module("recharts", () => ({
   YAxis: () => null,
 }));
 
+export interface RenderWithProvidersOptions {
+  initialRoute?: string;
+}
+
+export function renderWithProviders(ui: React.ReactElement, options?: RenderWithProvidersOptions) {
+  const queryClient = createTestQueryClient();
+  const initialRoute = options?.initialRoute ?? "/";
+
+  return render(
+    createElement(
+      StrictMode,
+      null,
+      createElement(
+        ErrorBoundary,
+        null,
+        createElement(
+          QueryClientProvider,
+          { client: queryClient },
+          createElement(MemoryRouter, { initialEntries: [initialRoute] }, ui),
+        ),
+      ),
+    ),
+  );
+}
+
+function createTestQueryClient() {
+  return new QueryClient({
+    defaultOptions: {
+      queries: {
+        retry: false,
+        staleTime: 0,
+      },
+    },
+  });
+}
+
 // Custom test helpers (替代 jest-dom matchers)
 export const testHelpers = {
   toBeInTheDocument: (element: Element | null) => {