lanyuanxiaoyao
4caf502908
- 引入 React Router v7 (Declarative mode) 实现 SPA 路由 - 重构 Layout 为 Header + 侧边栏 + 内容区的企业 Admin 布局 - 新增侧边栏菜单组件，支持折叠/展开，状态持久化到 localStorage - 新增示例页面：仪表盘、用户管理、系统设置、404 - 菜单配置与路由统一为单一数据源 (menu.tsx) - Vite code splitting 新增 vendor-router 组 - 更新 DEVELOPMENT.md 和 README.md 文档
96 lines
3.4 KiB
Markdown
96 lines
3.4 KiB
Markdown
## 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 等主流企业后台习惯
|
||
|
||
### 4. 页面标题来源：复用 menu label
|
||
|
||
**选择**：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），避免实验性特性
|