diff --git a/openspec/changes/refactor-frontend-layout/.openspec.yaml b/openspec/changes/refactor-frontend-layout/.openspec.yaml deleted file mode 100644 index 8b76914..0000000 --- a/openspec/changes/refactor-frontend-layout/.openspec.yaml +++ /dev/null @@ -1,2 +0,0 @@ -schema: spec-driven -created: 2026-05-20 diff --git a/openspec/changes/refactor-frontend-layout/design.md b/openspec/changes/refactor-frontend-layout/design.md deleted file mode 100644 index a899a49..0000000 --- a/openspec/changes/refactor-frontend-layout/design.md +++ /dev/null @@ -1,95 +0,0 @@ -## 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),避免实验性特性 diff --git a/openspec/changes/refactor-frontend-layout/proposal.md b/openspec/changes/refactor-frontend-layout/proposal.md deleted file mode 100644 index ad369c5..0000000 --- a/openspec/changes/refactor-frontend-layout/proposal.md +++ /dev/null @@ -1,36 +0,0 @@ -## Why - -当前前端为单页面应用,仅有 Header + Content 的简单布局,无路由、无侧边栏,页面结构单一,无法支撑企业级 Admin 后台的多页面导航需求。作为 Bun 全栈应用模板,需要提供更完善的前端布局范例,便于使用者在此基础上扩展业务页面。 - -## What Changes - -- 引入 React Router v7 (Declarative mode) 实现前端 SPA 路由 -- 重构 Layout 为经典企业 Admin 后台布局:Header + 侧边栏 + 内容区 -- 新增侧边栏菜单组件,支持折叠/展开,折叠状态持久化到 localStorage -- 新增多个示例页面(仪表盘、用户管理、系统设置、404) -- 将路由定义与菜单配置统一为单一数据源,保证两者同步 -- 新增 `react-router` 依赖,Vite code splitting 单独分组 - -**BREAKING**: 原 `app.tsx` 的 Content 内容迁移至 Dashboard 页面;CSS 类名 `.dashboard-*` 变更为 `.app-*` - -## Capabilities - -### New Capabilities - -- `frontend-routing`: 前端 SPA 路由能力,基于 React Router v7,支持多页面导航、路由匹配、404 处理 -- `admin-layout`: 企业 Admin 后台布局能力,Header + 侧边栏 + 内容区,侧边栏可折叠 - -### Modified Capabilities - -- `app-constants`: 新增 localStorage key `"sidebar.collapsed"` 用于持久化侧边栏折叠状态 - -## Impact - -- 新增依赖:`react-router` -- 新增目录:`src/web/pages/`、`src/web/components/Sidebar/` -- 新增文件:`src/web/routes.tsx`、`src/web/menu.tsx`、`src/web/hooks/use-sidebar-collapsed.ts` -- 修改文件:`src/web/app.tsx`(重构 Layout)、`src/web/main.tsx`(+ BrowserRouter)、`src/web/styles.css`(布局样式重写) -- 修改配置:`vite.config.ts`(code splitting 新增 vendor-router 组) -- 更新文档:`DEVELOPMENT.md`、`README.md` -- 新增测试:Sidebar 组件测试、各页面测试、test-utils 增强 -- 后端无需改动(SPA fallback 已支持) diff --git a/openspec/changes/refactor-frontend-layout/specs/app-constants/spec.md b/openspec/changes/refactor-frontend-layout/specs/app-constants/spec.md deleted file mode 100644 index 94ab2dc..0000000 --- a/openspec/changes/refactor-frontend-layout/specs/app-constants/spec.md +++ /dev/null @@ -1,15 +0,0 @@ -## ADDED Requirements - -### Requirement: 侧边栏折叠状态 localStorage key - -侧边栏折叠状态存储 key SHALL 为 `"sidebar.collapsed"`,不包含应用名前缀。 - -#### Scenario: 折叠状态持久化 - -- **WHEN** 用户切换侧边栏折叠状态 -- **THEN** 系统 SHALL 将状态存储到 localStorage key `"sidebar.collapsed"` - -#### Scenario: 折叠状态读取 - -- **WHEN** 应用初始化时读取侧边栏折叠状态 -- **THEN** 系统 SHALL 从 localStorage key `"sidebar.collapsed"` 读取 diff --git a/openspec/changes/refactor-frontend-layout/tasks.md b/openspec/changes/refactor-frontend-layout/tasks.md deleted file mode 100644 index 20652b9..0000000 --- a/openspec/changes/refactor-frontend-layout/tasks.md +++ /dev/null @@ -1,56 +0,0 @@ -## 1. 依赖与配置 - -- [x] 1.1 安装 react-router 依赖 -- [x] 1.2 更新 vite.config.ts code splitting 配置,新增 vendor-router 组 - -## 2. 工具与 Hook - -- [x] 2.1 创建 src/web/menu.tsx,定义菜单项配置 -- [x] 2.2 创建 src/web/hooks/use-sidebar-collapsed.ts,实现侧边栏折叠状态 hook - -## 3. 页面组件 - -- [x] 3.1 创建 src/web/pages/dashboard/index.tsx,迁移原 app.tsx 内容区逻辑 -- [x] 3.2 创建 src/web/pages/users/index.tsx,实现用户管理占位页面 -- [x] 3.3 创建 src/web/pages/settings/index.tsx,实现系统设置占位页面 -- [x] 3.4 创建 src/web/pages/404/index.tsx,实现 404 页面 - -## 4. 侧边栏组件 - -- [x] 4.1 创建 src/web/components/Sidebar/index.tsx,实现侧边栏菜单组件 - -## 5. 路由配置 - -- [x] 5.1 创建 src/web/routes.tsx,定义所有路由 - -## 6. 根组件重构 - -- [x] 6.1 重构 src/web/app.tsx,实现 Header + Aside + Content 布局 -- [x] 6.2 修改 src/web/main.tsx,添加 BrowserRouter 包裹 - -## 7. 样式更新 - -- [x] 7.1 更新 src/web/styles.css,迁移 .dashboard-* 为 .app-*,新增布局样式 - -## 8. 测试工具增强 - -- [x] 8.1 增强 tests/web/test-utils.tsx,提供 renderWithProviders 函数 - -## 9. 组件测试 - -- [x] 9.1 创建 tests/web/components/Sidebar/index.test.tsx -- [x] 9.2 创建 tests/web/routes/dashboard.test.tsx -- [x] 9.3 创建 tests/web/routes/users.test.tsx -- [x] 9.4 创建 tests/web/routes/settings.test.tsx -- [x] 9.5 创建 tests/web/routes/404.test.tsx -- [x] 9.6 更新 tests/web/App.test.tsx 适配 BrowserRouter - -## 10. 文档更新 - -- [x] 10.1 更新 DEVELOPMENT.md,更新技术栈表格、组件树、目录结构说明 -- [x] 10.2 更新 README.md,更新技术栈表格、项目结构说明 - -## 11. 质量保障 - -- [x] 11.1 运行 bun run check 确保类型检查、lint、测试通过 -- [x] 11.2 运行 bun run build 验证构建成功 diff --git a/openspec/changes/refactor-frontend-layout/specs/admin-layout/spec.md b/openspec/specs/admin-layout/spec.md similarity index 97% rename from openspec/changes/refactor-frontend-layout/specs/admin-layout/spec.md rename to openspec/specs/admin-layout/spec.md index 3b192e8..0c2ef24 100644 --- a/openspec/changes/refactor-frontend-layout/specs/admin-layout/spec.md +++ b/openspec/specs/admin-layout/spec.md @@ -1,4 +1,4 @@ -## ADDED Requirements +## Requirements ### Requirement: 企业 Admin 后台布局 @@ -27,6 +27,7 @@ Header SHALL 包含折叠按钮、页面标题、主题切换控件。 - **WHEN** Header 渲染 - **THEN** 系统 SHALL 显示当前路由对应的页面标题(从 menu 获取) +- **AND** 若当前路由无匹配菜单项,SHALL 显示 `APP.title` 作为 fallback #### Scenario: Header 右侧主题切换 diff --git a/openspec/specs/app-constants/spec.md b/openspec/specs/app-constants/spec.md index 6dc8ae7..6857b92 100644 --- a/openspec/specs/app-constants/spec.md +++ b/openspec/specs/app-constants/spec.md @@ -59,3 +59,17 @@ - **WHEN** 应用初始化时读取用户主题偏好 - **THEN** 系统 SHALL 从 localStorage key `"theme.preference"` 读取 + +### Requirement: 侧边栏折叠状态 localStorage key + +侧边栏折叠状态存储 key SHALL 为 `"sidebar.collapsed"`,不包含应用名前缀。 + +#### Scenario: 折叠状态持久化 + +- **WHEN** 用户切换侧边栏折叠状态 +- **THEN** 系统 SHALL 将状态存储到 localStorage key `"sidebar.collapsed"` + +#### Scenario: 折叠状态读取 + +- **WHEN** 应用初始化时读取侧边栏折叠状态 +- **THEN** 系统 SHALL 从 localStorage key `"sidebar.collapsed"` 读取 diff --git a/openspec/changes/refactor-frontend-layout/specs/frontend-routing/spec.md b/openspec/specs/frontend-routing/spec.md similarity index 98% rename from openspec/changes/refactor-frontend-layout/specs/frontend-routing/spec.md rename to openspec/specs/frontend-routing/spec.md index 1257f0d..2151f2b 100644 --- a/openspec/changes/refactor-frontend-layout/specs/frontend-routing/spec.md +++ b/openspec/specs/frontend-routing/spec.md @@ -1,4 +1,4 @@ -## ADDED Requirements +## Requirements ### Requirement: 前端 SPA 路由 diff --git a/src/web/pages/404/index.tsx b/src/web/pages/404/index.tsx index 937f956..78e25dc 100644 --- a/src/web/pages/404/index.tsx +++ b/src/web/pages/404/index.tsx @@ -11,7 +11,7 @@ export function NotFoundPage() { return ( - +

404

您访问的页面不存在