bun-app-template/openspec/changes/refactor-frontend-layout/design.md at 4caf502908f986807b1e2ed20b5fa3c2b99b0a27

Files

lanyuanxiaoyao 4caf502908 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 文档

2026-05-20 19:06:14 +08:00

3.4 KiB

Raw Blame History

Context

当前前端为单页面应用，app.tsx 直接渲染 Header + Content，无路由、无侧边栏。技术栈为 React 19 + TDesign React + TanStack Query + Vite。后端使用 Bun.serve，已支持 SPA fallback（无扩展名路径返回 index.html）。

目标：重构为经典企业 Admin 后台布局，引入路由，支持多页面导航。

约束：

前端样式开发优先使用 TDesign 组件和 CSS tokens，禁止内联 style、硬编码色值
新增代码需编写完善测试
后端无需改动

Goals / Non-Goals

Goals:

引入 React Router v7 (Declarative mode) 实现 SPA 路由
实现企业 Admin 后台布局：Header + 侧边栏 + 内容区
侧边栏支持折叠/展开，状态持久化到 localStorage
路由定义与菜单配置统一为单一数据源
提供示例页面（仪表盘、用户管理、系统设置、404）

Non-Goals:

不实现路由守卫/权限控制（预留接口但不启用）
不实现懒加载（页面少，暂不需要）
不实现面包屑导航
不实现用户认证

Decisions

1. 路由方案：React Router v7 Declarative mode

选择：react-router v7，使用 Declarative mode（BrowserRouter + Routes + Route）

理由：

v7 统一了 react-router 和 react-router-dom，单包导入
Declarative mode 满足当前需求，无需 framework mode 的文件系统路由
社区成熟，文档完善

替代方案：

TanStack Router：类型安全强，但较新、API 变动风险
自实现：零依赖但功能有限，扩展成本高

2. Routes 定义位置：独立文件

选择：抽离为 src/web/routes.tsx，app.tsx 引用

理由：

路由增删时改动范围小，不污染 app.tsx
便于后续扩展路由守卫、懒加载

3. 侧边栏折叠按钮位置：Header 左侧

选择：折叠按钮放在 Header 左侧，Sidebar 不使用 Menu 的 operations prop

理由：

Sidebar 折叠变窄后，底部按钮变小且易被忽略
Header 上的按钮始终可见且易触达
符合 Ant Design Pro 等主流企业后台习惯

选择：Header 页面标题直接使用 menu.tsx 中的 label 字段

理由：

简单直接，侧边栏标签即页面标题
如需差异化，后续加 title 字段即可

5. Layout 嵌套：保留嵌套结构

选择：Layout > (Header + Layout > (Aside + Content))

理由：

为 Footer 预留位置，将来加 Footer 无需重构
符合 TDesign 官方组合导航布局示例

6. Vite code splitting：react-router 单独分组

选择：新增 vendor-router 组，包含 react-router

理由：

路由库独立于 React 核心，更新节奏不同
便于缓存隔离

7. 菜单与路由数据源：menu.tsx

选择：src/web/menu.tsx 定义菜单项配置，Sidebar 和 Routes 共同引用

理由：

单一数据源，保证菜单项和路由同步
便于类型安全（as const）

Risks / Trade-offs

路由与菜单配置一致性：需人工保证 menu.tsx 与 routes.tsx 中 Route 定义一致 → 测试覆盖路由跳转和菜单点击
CSS 类名迁移影响：.dashboard-* → .app-* 可能影响测试选择器 → 全局搜索确认影响范围，更新测试
React Router v7 新版本风险：v7 较新，可能存在未发现的 bug → 使用成熟 API（BrowserRouter/Routes/Route），避免实验性特性

3.4 KiB Raw Blame History Unescape Escape