## 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），避免实验性特性