bun-app-template/openspec/changes/refactor-frontend-layout/specs/admin-layout/spec.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

4.0 KiB

Raw Blame History

ADDED Requirements

Requirement: 企业 Admin 后台布局

系统 SHALL 实现 Header + 侧边栏 + 内容区的企业 Admin 后台布局，使用 TDesign Layout 组件。

Scenario: 布局结构

WHEN 用户访问应用
THEN 系统 SHALL 渲染包含 Header、Aside、Content 的 Layout 结构

Scenario: Layout 嵌套结构

WHEN 布局渲染
THEN 系统 SHALL 使用嵌套 Layout 结构：Layout > (Header + Layout > (Aside + Content))

Requirement: Header 布局

Header SHALL 包含折叠按钮、页面标题、主题切换控件。

Scenario: Header 左侧折叠按钮

WHEN Header 渲染
THEN 系统 SHALL 在左侧显示侧边栏折叠/展开按钮

Scenario: Header 页面标题

WHEN Header 渲染
THEN 系统 SHALL 显示当前路由对应的页面标题（从 menu 获取）

Scenario: Header 右侧主题切换

WHEN Header 渲染
THEN 系统 SHALL 在右侧显示主题切换 RadioGroup（系统/明亮/黑暗）

Requirement: 侧边栏菜单

系统 SHALL 提供侧边栏菜单组件（Sidebar），使用 TDesign Menu 组件，支持折叠/展开。

Scenario: 侧边栏渲染菜单项

WHEN 侧边栏渲染
THEN 系统 SHALL 根据 menu.tsx 渲染所有菜单项

Scenario: 菜单项点击导航

WHEN 用户点击菜单项
THEN 系统 SHALL 使用 React Router 的 navigate 跳转到对应路径

Scenario: 菜单项激活状态

WHEN 当前路由与菜单项路径匹配
THEN 系统 SHALL 高亮显示该菜单项

Requirement: 侧边栏折叠

侧边栏 SHALL 支持折叠/展开，折叠状态持久化到 localStorage。

Scenario: 侧边栏折叠交互

WHEN 用户点击 Header 左侧的折叠按钮
THEN 系统 SHALL 切换侧边栏折叠状态

Scenario: 侧边栏折叠宽度

WHEN 侧边栏折叠
THEN Aside 宽度 SHALL 变为 80px，Menu 仅显示图标

Scenario: 侧边栏展开宽度

WHEN 侧边栏展开
THEN Aside 宽度 SHALL 变为 232px，Menu 显示图标和文字

Scenario: 折叠状态持久化

WHEN 用户切换侧边栏折叠状态
THEN 系统 SHALL 将状态存储到 localStorage key "sidebar.collapsed"

Scenario: 折叠状态恢复

WHEN 应用初始化
THEN 系统 SHALL 从 localStorage 读取 "sidebar.collapsed" 并恢复折叠状态

Requirement: 侧边栏主题跟随全局

侧边栏 Menu 的主题 SHALL 跟随全局主题设置，不单独设置 theme prop。

Scenario: 侧边栏跟随全局主题

WHEN 全局主题切换为 dark
THEN 侧边栏 SHALL 自动应用 dark 主题样式

Requirement: 菜单配置单一数据源

系统 SHALL 在 src/web/menu.tsx 定义菜单项配置，包含 value、label、path、icon 字段。

Scenario: 菜单配置类型安全

WHEN 定义菜单配置
THEN 系统 SHALL 使用 as const 保证字面量类型推断

Scenario: Sidebar 引用菜单配置

WHEN Sidebar 渲染
THEN 系统 SHALL 遍历 MENU_ITEMS 渲染 MenuItem

Requirement: 示例页面

系统 SHALL 提供示例页面组件：Dashboard、Users、Settings、NotFound。

Scenario: Dashboard 页面

WHEN 用户访问 /
THEN 系统 SHALL 渲染 Dashboard 页面（包含原 app.tsx 的欢迎语和 /health 展示）

Scenario: Users 页面占位

WHEN 用户访问 /users
THEN 系统 SHALL 渲染用户管理占位页面

Scenario: Settings 页面占位

WHEN 用户访问 /settings
THEN 系统 SHALL 渲染系统设置占位页面

Scenario: NotFound 页面

WHEN 用户访问未定义路径
THEN 系统 SHALL 渲染 404 页面，提供返回首页按钮

Requirement: CSS 类名迁移

原 .dashboard-* CSS 类名 SHALL 变更为 .app-*。

Scenario: 布局类名

WHEN 样式应用
THEN 系统 SHALL 使用 .app-layout、.app-header、.app-content、.app-sidebar 类名

4.0 KiB Raw Blame History Unescape Escape