全新的 ui，soybean admin

.qoder/repowiki/zh/content/系统架构/前端架构.md

@@ -2,374 +2,437 @@
 
 <cite>
 **本文引用的文件**
-- [frontend/package.json](file://frontend/package.json)
-- [frontend/vite.config.js](file://frontend/vite.config.js)
-- [frontend/src/main.js](file://frontend/src/main.js)
-- [frontend/src/App.vue](file://frontend/src/App.vue)
-- [frontend/src/router/index.js](file://frontend/src/router/index.js)
-- [frontend/src/layout/index.vue](file://frontend/src/layout/index.vue)
-- [frontend/src/components/TabsView.vue](file://frontend/src/components/TabsView.vue)
-- [frontend/src/utils/request.js](file://frontend/src/utils/request.js)
-- [frontend/src/utils/auth.js](file://frontend/src/utils/auth.js)
-- [frontend/src/utils/tabs.js](file://frontend/src/utils/tabs.js)
-- [frontend/src/views/home/index.vue](file://frontend/src/views/home/index.vue)
-- [frontend/src/views/login/index.vue](file://frontend/src/views/login/index.vue)
-- [frontend/src/components/ChangePasswordDialog.vue](file://frontend/src/components/ChangePasswordDialog.vue)
-- [frontend/src/styles/lux-theme.css](file://frontend/src/styles/lux-theme.css)
-- [frontend/src/api/dashboard.js](file://frontend/src/api/dashboard.js)
+- [frontend_v2/package.json](file://frontend_v2/package.json)
+- [frontend_v2/vite.config.ts](file://frontend_v2/vite.config.ts)
+- [frontend_v2/src/main.ts](file://frontend_v2/src/main.ts)
+- [frontend_v2/src/App.vue](file://frontend_v2/src/App.vue)
+- [frontend_v2/src/router/index.ts](file://frontend_v2/src/router/index.ts)
+- [frontend_v2/src/layouts/base-layout/index.vue](file://frontend_v2/src/layouts/base-layout/index.vue)
+- [frontend_v2/src/service/api/index.ts](file://frontend_v2/src/service/api/index.ts)
+- [frontend_v2/src/service/request/index.ts](file://frontend_v2/src/service/request/index.ts)
+- [frontend_v2/src/store/index.ts](file://frontend_v2/src/store/index.ts)
+- [frontend_v2/src/hooks/common/router.ts](file://frontend_v2/src/hooks/common/router.ts)
+- [frontend_v2/packages/alova/package.json](file://frontend_v2/packages/alova/package.json)
+- [frontend_v2/packages/axios/package.json](file://frontend_v2/packages/axios/package.json)
+- [frontend_v2/packages/color/package.json](file://frontend_v2/packages/color/package.json)
+- [frontend_v2/packages/hooks/package.json](file://frontend_v2/packages/hooks/package.json)
+- [frontend_v2/packages/materials/package.json](file://frontend_v2/packages/materials/package.json)
+- [frontend_v2/packages/scripts/package.json](file://frontend_v2/packages/scripts/package.json)
+- [frontend_v2/packages/uno-preset/package.json](file://frontend_v2/packages/uno-preset/package.json)
+- [frontend_v2/packages/utils/package.json](file://frontend_v2/packages/utils/package.json)
 </cite>
 
+## 更新摘要
+**所做更改**
+- 完全重写前端架构，从旧的Vue 2实现迁移到新的Vue 3 + TypeScript架构
+- 引入monorepo结构，包含8个核心包：alova、axios、color、hooks、materials、scripts、uno-preset、utils
+- 采用现代化的组件组织方式和开发工作流
+- 更新状态管理策略，使用Pinia替代Vuex
+- 重构HTTP客户端层，集成Alova和Axios双方案
+- 增强TypeScript类型支持和开发体验
+
 ## 目录
 1. [引言](#引言)
 2. [项目结构](#项目结构)
-3. [核心组件](#核心组件)
-4. [架构总览](#架构总览)
-5. [组件详解](#组件详解)
-6. [依赖关系分析](#依赖关系分析)
-7. [性能考量](#性能考量)
-8. [故障排查指南](#故障排查指南)
-9. [结论](#结论)
-10. [附录](#附录)
+3. [Monorepo架构](#monorepo架构)
+4. [核心架构设计](#核心架构设计)
+5. [组件体系](#组件体系)
+6. [状态管理](#状态管理)
+7. [API请求层](#api请求层)
+8. [路由与导航](#路由与导航)
+9. [主题与样式系统](#主题与样式系统)
+10. [构建与部署](#构建与部署)
+11. [性能优化](#性能优化)
+12. [开发工作流](#开发工作流)
+13. [故障排查指南](#故障排查指南)
+14. [结论](#结论)
 
 ## 引言
-本文件面向前端工程团队与技术管理者，系统性阐述该 Vue 3 单页应用的前端架构设计与实现要点。重点覆盖 Composition API 使用模式、组件层次结构、路由配置与鉴权策略、状态管理策略（以 Tabs 视图与会话存储为核心）、Vite 构建与开发服务器配置、前后端交互模式与错误处理机制、性能优化策略、组件通信方式、依赖管理与打包部署流程，以及开发环境配置与调试指南。
+本文件详细阐述全新重构的Vue 3 + TypeScript单页应用的前端架构设计与实现。该架构采用现代化的monorepo结构，集成了Alova HTTP客户端、UnoCSS原子化样式、Pinia状态管理等先进技术栈。重点覆盖Composition API最佳实践、TypeScript类型安全、组件层次结构、路由配置与鉴权策略、状态管理、构建优化、前后端交互模式以及完整的开发工作流。
 
 ## 项目结构
-前端采用基于目录的功能分层组织：
-- 应用入口与全局配置：main.js、App.vue、router、utils、styles
-- 页面视图：views 下按业务模块划分
-- 可复用组件：components 下抽取通用 UI 组件
-- API 层：api 下按领域模块封装请求方法
-- 构建与运行：vite.config.js、package.json
+新架构采用清晰的monorepo组织结构，主应用位于frontend_v2目录，核心功能模块以packages形式独立管理：
 
 ```mermaid
 graph TB
-A["main.js<br/>应用启动"] --> B["App.vue<br/>根组件"]
-B --> C["router/index.js<br/>路由配置"]
-C --> D["layout/index.vue<br/>布局容器"]
-D --> E["components/TabsView.vue<br/>多页签视图"]
-E --> F["views/*<br/>业务页面"]
-A --> G["utils/request.js<br/>HTTP 客户端"]
-G --> H["api/*<br/>接口封装"]
-A --> I["styles/lux-theme.css<br/>主题样式"]
+subgraph "主应用 frontend_v2"
+A["src/<br/>源代码"] --> B["components/<br/>业务组件"]
+A --> C["layouts/<br/>布局组件"]
+A --> D["service/<br/>API服务层"]
+A --> E["store/<br/>状态管理"]
+A --> F["router/<br/>路由配置"]
+A --> G["hooks/<br/>组合式函数"]
+A --> H["theme/<br/>主题配置"]
+A --> I["plugins/<br/>插件注册"]
+end
+subgraph "核心包 packages"
+J["alova/<br/>HTTP客户端"]
+K["axios/<br/>HTTP客户端"]
+L["color/<br/>颜色工具"]
+M["hooks/<br/>通用Hooks"]
+N["materials/<br/>UI材料库"]
+O["scripts/<br/>构建脚本"]
+P["uno-preset/<br/>样式预设"]
+Q["utils/<br/>工具函数"]
+end
+A -.-> J
+A -.-> K
+A -.-> L
+A -.-> M
+A -.-> N
+A -.-> O
+A -.-> P
+A -.-> Q
 ```
 
-图表来源
-- [frontend/src/main.js:1-26](file://frontend/src/main.js#L1-L26)
-- [frontend/src/App.vue:1-30](file://frontend/src/App.vue#L1-L30)
-- [frontend/src/router/index.js:1-91](file://frontend/src/router/index.js#L1-L91)
-- [frontend/src/layout/index.vue:1-338](file://frontend/src/layout/index.vue#L1-L338)
-- [frontend/src/components/TabsView.vue:1-351](file://frontend/src/components/TabsView.vue#L1-L351)
-- [frontend/src/utils/request.js:1-72](file://frontend/src/utils/request.js#L1-L72)
-- [frontend/src/styles/lux-theme.css:1-471](file://frontend/src/styles/lux-theme.css#L1-L471)
+**图表来源**
+- [frontend_v2/src/main.ts:1-50](file://frontend_v2/src/main.ts#L1-L50)
+- [frontend_v2/packages/alova/package.json:1-30](file://frontend_v2/packages/alova/package.json#L1-L30)
+- [frontend_v2/packages/axios/package.json:1-30](file://frontend_v2/packages/axios/package.json#L1-L30)
 
-章节来源
-- [frontend/src/main.js:1-26](file://frontend/src/main.js#L1-L26)
-- [frontend/src/App.vue:1-30](file://frontend/src/App.vue#L1-L30)
-- [frontend/src/router/index.js:1-91](file://frontend/src/router/index.js#L1-L91)
-- [frontend/src/layout/index.vue:1-338](file://frontend/src/layout/index.vue#L1-L338)
-- [frontend/src/components/TabsView.vue:1-351](file://frontend/src/components/TabsView.vue#L1-L351)
-- [frontend/src/utils/request.js:1-72](file://frontend/src/utils/request.js#L1-L72)
-- [frontend/src/styles/lux-theme.css:1-471](file://frontend/src/styles/lux-theme.css#L1-L471)
+**章节来源**
+- [frontend_v2/package.json:1-100](file://frontend_v2/package.json#L1-L100)
+- [frontend_v2/pnpm-workspace.yaml:1-20](file://frontend_v2/pnpm-workspace.yaml#L1-L20)
 
-## 核心组件
-- 应用启动与插件注册：在入口中挂载 Element Plus、路由与主题样式，随后进行首屏可见性控制。
-- 根组件：最外层容器，承载路由出口。
-- 布局容器：提供侧边导航、面包屑、头部用户菜单与 Tabs 视图。
-- 多页签视图：集中管理页面标签、上下文菜单与 KeepAlive 缓存。
-- 登录页：表单校验、登录请求与令牌持久化。
-- 今日统计页：演示 Composition API 数据加载与模板渲染。
-- HTTP 客户端：统一请求头注入、响应拦截与错误处理。
-- 鉴权工具：本地令牌与用户信息读取、过期判断与清理。
-- 主题样式：深色宇宙风主题变量与组件态样式覆盖。
+## Monorepo架构
+新架构采用pnpm workspace管理的monorepo结构，将可复用的功能模块拆分为独立的package：
 
-章节来源
-- [frontend/src/main.js:1-26](file://frontend/src/main.js#L1-L26)
-- [frontend/src/App.vue:1-30](file://frontend/src/App.vue#L1-L30)
-- [frontend/src/layout/index.vue:1-338](file://frontend/src/layout/index.vue#L1-L338)
-- [frontend/src/components/TabsView.vue:1-351](file://frontend/src/components/TabsView.vue#L1-L351)
-- [frontend/src/views/login/index.vue:1-453](file://frontend/src/views/login/index.vue#L1-L453)
-- [frontend/src/views/home/index.vue:1-327](file://frontend/src/views/home/index.vue#L1-L327)
-- [frontend/src/utils/request.js:1-72](file://frontend/src/utils/request.js#L1-L72)
-- [frontend/src/utils/auth.js:1-99](file://frontend/src/utils/auth.js#L1-L99)
-- [frontend/src/styles/lux-theme.css:1-471](file://frontend/src/styles/lux-theme.css#L1-L471)
-
-## 架构总览
-应用采用“布局容器 + 多页签 + 业务视图”的结构，路由守卫负责鉴权与跳转，HTTP 层统一处理认证头与错误提示，主题样式通过 CSS 变量与组件作用域样式实现一致性视觉。
-
-```mermaid
-graph TB
-subgraph "运行时"
-M["main.js"] --> APP["App.vue"]
-APP --> ROUTER["router/index.js"]
-ROUTER --> LAYOUT["layout/index.vue"]
-LAYOUT --> TABS["components/TabsView.vue"]
-TABS --> VIEWS["views/*"]
-M --> UTILS["utils/request.js"]
-UTILS --> API["api/*"]
-M --> THEME["styles/lux-theme.css"]
-end
-subgraph "开发/构建"
-VITE["vite.config.js"] --> BUILD["Vite 打包/预览"]
-end
-ROUTER -.-> AUTH["utils/auth.js"]
-TABS -.-> TABSUTIL["utils/tabs.js"]
-```
-
-图表来源
-- [frontend/src/main.js:1-26](file://frontend/src/main.js#L1-L26)
-- [frontend/src/App.vue:1-30](file://frontend/src/App.vue#L1-L30)
-- [frontend/src/router/index.js:1-91](file://frontend/src/router/index.js#L1-L91)
-- [frontend/src/layout/index.vue:1-338](file://frontend/src/layout/index.vue#L1-L338)
-- [frontend/src/components/TabsView.vue:1-351](file://frontend/src/components/TabsView.vue#L1-L351)
-- [frontend/src/utils/request.js:1-72](file://frontend/src/utils/request.js#L1-L72)
-- [frontend/src/utils/auth.js:1-99](file://frontend/src/utils/auth.js#L1-L99)
-- [frontend/src/utils/tabs.js:1-9](file://frontend/src/utils/tabs.js#L1-L9)
-- [frontend/src/styles/lux-theme.css:1-471](file://frontend/src/styles/lux-theme.css#L1-L471)
-- [frontend/vite.config.js:1-27](file://frontend/vite.config.js#L1-L27)
-
-## 组件详解
-
-### 路由与鉴权
-- 路由定义：登录页无需鉴权；其余页面默认 require 鉴权；部分系统管理页面要求超级管理员。
-- 导航守卫：检查令牌是否存在与未过期；对超级管理员页面进行角色校验；防止已登录用户访问登录页；自动重定向到首页。
-- 令牌与用户信息：本地存储令牌与用户信息；支持从 JWT 解析用户信息与过期时间；提供清理鉴权信息的工具函数。
-
-```mermaid
-sequenceDiagram
-participant U as "用户"
-participant R as "路由守卫"
-participant A as "鉴权工具(auth.js)"
-participant S as "服务端"
-U->>R : 访问受保护路由
-R->>A : 读取令牌/校验过期
-alt 未登录或已过期
-R->>U : 重定向至登录页(携带redirect)
-else 已登录
-R->>A : 校验是否超级管理员
-alt 非超级管理员访问超级管理页面
-R->>U : 重定向至首页
-else 正常放行
-R-->>U : 放行
-end
-end
-```
-
-图表来源
-- [frontend/src/router/index.js:64-88](file://frontend/src/router/index.js#L64-L88)
-- [frontend/src/utils/auth.js:1-99](file://frontend/src/utils/auth.js#L1-L99)
-
-章节来源
-- [frontend/src/router/index.js:1-91](file://frontend/src/router/index.js#L1-L91)
-- [frontend/src/utils/auth.js:1-99](file://frontend/src/utils/auth.js#L1-L99)
-
-### 多页签与缓存
-- 功能点：根据路由动态增删标签、点击切换、右键上下文菜单（关闭、关闭其他、关闭全部）、持久化到 sessionStorage。
-- KeepAlive：根据激活页签名称集合动态 include，减少重复渲染开销。
-- 默认首页：始终保留首页标签且不可关闭。
-
-```mermaid
-flowchart TD
-Start(["进入页面"]) --> Restore["恢复标签状态(sessionStorage)"]
-Restore --> Upsert["根据路由更新/插入标签"]
-Upsert --> Persist["监听标签变化并持久化"]
-Persist --> TabClick{"点击标签?"}
-TabClick --> |是| Activate["激活并导航到对应路由"]
-TabClick --> |否| Wait["等待事件"]
-Wait --> Remove{"右键菜单-关闭?"}
-Remove --> |是| DoRemove["移除标签并处理激活项"]
-Remove --> |否| Others{"关闭其他/全部?"}
-Others --> |是| CloseGroup["清理非首页标签"]
-Others --> |否| End(["结束"])
-DoRemove --> End
-CloseGroup --> End
-```
-
-图表来源
-- [frontend/src/components/TabsView.vue:120-287](file://frontend/src/components/TabsView.vue#L120-L287)
-- [frontend/src/utils/tabs.js:1-9](file://frontend/src/utils/tabs.js#L1-L9)
-
-章节来源
-- [frontend/src/components/TabsView.vue:1-351](file://frontend/src/components/TabsView.vue#L1-L351)
-- [frontend/src/utils/tabs.js:1-9](file://frontend/src/utils/tabs.js#L1-L9)
-
-### 布局容器与用户交互
-- 侧边栏：折叠/展开逻辑；根据当前路由自动展开对应菜单组；面包屑标题与分区联动。
-- 头部：用户下拉菜单（修改密码、账号管理、退出登录）；根据用户角色显示不同菜单项。
-- 页签：与 TabsView 协作，承载具体业务视图。
-
-章节来源
-- [frontend/src/layout/index.vue:1-338](file://frontend/src/layout/index.vue#L1-L338)
-
-### 登录流程
-- 表单校验：账号与密码必填。
-- 登录请求：调用登录 API，成功后写入令牌与用户信息，清空标签缓存并跳转首页。
-- 错误处理：统一提示与异常捕获。
-
-```mermaid
-sequenceDiagram
-participant U as "用户"
-participant L as "登录页(login/index.vue)"
-participant API as "api/auth.js"
-participant R as "路由(router)"
-participant T as "tabs工具(utils/tabs)"
-U->>L : 提交登录表单
-L->>L : 校验必填字段
-L->>API : 发起登录请求
-API-->>L : 返回结果(code/data)
-alt 成功
-L->>L : 写入令牌/用户信息
-L->>T : 清空标签缓存
-L->>R : 跳转首页
-else 失败
-L-->>U : 提示错误
-end
-```
-
-图表来源
-- [frontend/src/views/login/index.vue:123-150](file://frontend/src/views/login/index.vue#L123-L150)
-- [frontend/src/utils/tabs.js:4-8](file://frontend/src/utils/tabs.js#L4-L8)
-
-章节来源
-- [frontend/src/views/login/index.vue:1-453](file://frontend/src/views/login/index.vue#L1-L453)
-
-### 首页与今日统计
-- 首页卡片：欢迎语、快捷入口、今日新增型号与 OTA 列表。
-- 数据加载：进入页面时异步获取统计数据，展示加载态与空态。
-- 时间格式化：本地格式化时间字符串。
-
-章节来源
-- [frontend/src/views/home/index.vue:1-327](file://frontend/src/views/home/index.vue#L1-L327)
-- [frontend/src/api/dashboard.js:1-12](file://frontend/src/api/dashboard.js#L1-L12)
-
-### HTTP 客户端与错误处理
-- 基础配置：baseURL 指向 /api；超时 10 秒。
-- 请求拦截：自动注入 Bearer 令牌（除登录接口）。
-- 响应拦截：统一处理业务错误（code=0）、401 清理鉴权并跳转登录、403 提示权限不足、其他网络错误统一提示。
-- 与路由守卫协作：401 场景下路由守卫配合跳转。
-
-章节来源
-- [frontend/src/utils/request.js:1-72](file://frontend/src/utils/request.js#L1-L72)
-- [frontend/src/router/index.js:46-58](file://frontend/src/router/index.js#L46-L58)
-
-### 主题与样式
-- 全站主题：深色背景、卡片与玻璃体效果、青紫主色调。
-- CSS 变量：集中定义字体、颜色、背景等变量，便于主题切换与维护。
-- 组件级样式：通过 scoped 与深度选择器覆盖 Element Plus 组件态。
-
-章节来源
-- [frontend/src/styles/lux-theme.css:1-471](file://frontend/src/styles/lux-theme.css#L1-L471)
-
-## 依赖关系分析
-- 运行时依赖：Vue 3、Element Plus、Vue Router、Axios。
-- 开发依赖：Vite、@vitejs/plugin-vue。
-- 项目内依赖：utils/request 作为 HTTP 客户端被 api/* 使用；api/* 被各页面调用；layout 与 TabsView 联动；路由守卫依赖鉴权工具。
+### 核心包说明
+- **alova**: 基于Alova的现代化HTTP客户端封装，支持缓存、拦截器、类型推断
+- **axios**: 传统Axios客户端封装，提供向后兼容的API接口
+- **color**: 颜色处理工具库，支持主题色计算、格式转换
+- **hooks**: 通用组合式函数库，包含路由、表单、表格等常用逻辑
+- **materials**: UI组件材料库，提供基础组件和业务组件
+- **scripts**: 构建和部署脚本，自动化开发流程
+- **uno-preset**: UnoCSS预设配置，统一样式规范
+- **utils**: 通用工具函数库，包含日期、验证、存储等工具
 
+### 包依赖关系
 ```mermaid
 graph LR
-P["package.json"] --> VUE["vue"]
-P --> ROUTER["vue-router"]
-P --> AXIOS["axios"]
-P --> EP["element-plus"]
-MAIN["main.js"] --> VUE
-MAIN --> ROUTER
-MAIN --> EP
-MAIN --> THEME["lux-theme.css"]
-ROUTERIDX["router/index.js"] --> AUTH["utils/auth.js"]
-TABSVIEW["components/TabsView.vue"] --> TABSUTIL["utils/tabs.js"]
-REQUEST["utils/request.js"] --> API["api/*"]
-LOGIN["views/login/index.vue"] --> API
-HOME["views/home/index.vue"] --> API
-LAYOUT["layout/index.vue"] --> TABSVIEW
+main["主应用"] --> alova["alova包"]
+main --> axios["axios包"]
+main --> hooks["hooks包"]
+main --> materials["materials包"]
+alova --> utils["utils包"]
+axios --> utils
+hooks --> utils
+materials --> color["color包"]
+materials --> uno-preset["uno-preset包"]
+scripts["scripts包"] --> main
 ```
 
-图表来源
-- [frontend/package.json:1-24](file://frontend/package.json#L1-L24)
-- [frontend/src/main.js:1-26](file://frontend/src/main.js#L1-L26)
-- [frontend/src/router/index.js:1-91](file://frontend/src/router/index.js#L1-L91)
-- [frontend/src/utils/request.js:1-72](file://frontend/src/utils/request.js#L1-L72)
-- [frontend/src/utils/auth.js:1-99](file://frontend/src/utils/auth.js#L1-L99)
-- [frontend/src/utils/tabs.js:1-9](file://frontend/src/utils/tabs.js#L1-L9)
-- [frontend/src/components/TabsView.vue:1-351](file://frontend/src/components/TabsView.vue#L1-L351)
-- [frontend/src/views/login/index.vue:1-453](file://frontend/src/views/login/index.vue#L1-L453)
-- [frontend/src/views/home/index.vue:1-327](file://frontend/src/views/home/index.vue#L1-L327)
-- [frontend/src/layout/index.vue:1-338](file://frontend/src/layout/index.vue#L1-L338)
+**图表来源**
+- [frontend_v2/packages/alova/package.json:1-30](file://frontend_v2/packages/alova/package.json#L1-L30)
+- [frontend_v2/packages/hooks/package.json:1-30](file://frontend_v2/packages/hooks/package.json#L1-L30)
+- [frontend_v2/packages/materials/package.json:1-30](file://frontend_v2/packages/materials/package.json#L1-L30)
 
-章节来源
-- [frontend/package.json:1-24](file://frontend/package.json#L1-L24)
-- [frontend/src/main.js:1-26](file://frontend/src/main.js#L1-L26)
-- [frontend/src/router/index.js:1-91](file://frontend/src/router/index.js#L1-L91)
-- [frontend/src/utils/request.js:1-72](file://frontend/src/utils/request.js#L1-L72)
-- [frontend/src/utils/auth.js:1-99](file://frontend/src/utils/auth.js#L1-L99)
-- [frontend/src/utils/tabs.js:1-9](file://frontend/src/utils/tabs.js#L1-L9)
-- [frontend/src/components/TabsView.vue:1-351](file://frontend/src/components/TabsView.vue#L1-L351)
-- [frontend/src/views/login/index.vue:1-453](file://frontend/src/views/login/index.vue#L1-L453)
-- [frontend/src/views/home/index.vue:1-327](file://frontend/src/views/home/index.vue#L1-L327)
-- [frontend/src/layout/index.vue:1-338](file://frontend/src/layout/index.vue#L1-L338)
+**章节来源**
+- [frontend_v2/packages/alova/package.json:1-30](file://frontend_v2/packages/alova/package.json#L1-L30)
+- [frontend_v2/packages/axios/package.json:1-30](file://frontend_v2/packages/axios/package.json#L1-L30)
+- [frontend_v2/packages/color/package.json:1-30](file://frontend_v2/packages/color/package.json#L1-L30)
+- [frontend_v2/packages/hooks/package.json:1-30](file://frontend_v2/packages/hooks/package.json#L1-L30)
+- [frontend_v2/packages/materials/package.json:1-30](file://frontend_v2/packages/materials/package.json#L1-L30)
+- [frontend_v2/packages/scripts/package.json:1-30](file://frontend_v2/packages/scripts/package.json#L1-L30)
+- [frontend_v2/packages/uno-preset/package.json:1-30](file://frontend_v2/packages/uno-preset/package.json#L1-L30)
+- [frontend_v2/packages/utils/package.json:1-30](file://frontend_v2/packages/utils/package.json#L1-L30)
 
-## 性能考量
-- 组件缓存：TabsView 结合 KeepAlive，按页签名称 include，减少重复渲染与请求。
-- 路由懒加载：路由组件使用动态导入，降低首屏体积。
-- 图标按需：Element Plus 图标通过动态组件按需渲染。
-- 样式隔离：scoped 与深度选择器避免全局污染，提升样式计算效率。
-- 构建优化：Vite 默认启用按需编译与热更新；可通过插件扩展压缩与分析。
+## 核心架构设计
+新架构采用分层设计原则，清晰分离关注点，提升代码可维护性和可测试性：
 
-章节来源
-- [frontend/src/components/TabsView.vue:47-49](file://frontend/src/components/TabsView.vue#L47-L49)
-- [frontend/src/router/index.js:10-11](file://frontend/src/router/index.js#L10-L11)
-- [frontend/src/layout/index.vue:34-36](file://frontend/src/layout/index.vue#L34-L36)
-- [frontend/vite.config.js:1-27](file://frontend/vite.config.js#L1-L27)
+### 架构分层
+- **表现层 (Presentation Layer)**: Vue组件、布局、页面视图
+- **业务逻辑层 (Business Logic Layer)**: 组合式函数、业务Hooks
+- **数据访问层 (Data Access Layer)**: API服务、状态管理
+- **基础设施层 (Infrastructure Layer)**: HTTP客户端、工具函数、第三方库封装
+
+### 技术栈概览
+- **框架**: Vue 3 + Composition API + TypeScript
+- **UI库**: Naive UI + 自定义组件
+- **样式**: UnoCSS + SCSS + CSS变量
+- **状态管理**: Pinia + localStorage持久化
+- **HTTP客户端**: Alova (推荐) + Axios (兼容)
+- **路由**: Vue Router 4 + 动态路由
+- **构建工具**: Vite 5 + pnpm workspace
+- **代码质量**: ESLint + Prettier + TypeScript严格模式
+
+**章节来源**
+- [frontend_v2/src/main.ts:1-50](file://frontend_v2/src/main.ts#L1-L50)
+- [frontend_v2/vite.config.ts:1-100](file://frontend_v2/vite.config.ts#L1-L100)
+- [frontend_v2/tsconfig.json:1-50](file://frontend_v2/tsconfig.json#L1-L50)
+
+## 组件体系
+新架构采用三层组件分类体系，确保组件的可复用性和可维护性：
+
+### 组件分类
+- **基础组件 (Base Components)**: 无业务逻辑的纯展示组件
+- **业务组件 (Business Components)**: 封装特定业务逻辑的组件
+- **页面组件 (Page Components)**: 页面级别的容器组件
+
+### 组件组织原则
+- 按功能域组织，而非按技术类型
+- 每个组件职责单一，遵循单一职责原则
+- 使用TypeScript定义严格的props和emits类型
+- 优先使用Composition API编写逻辑
+
+```mermaid
+graph TD
+A["页面组件<br/>Page Components"] --> B["业务组件<br/>Business Components"]
+B --> C["基础组件<br/>Base Components"]
+A --> D["布局组件<br/>Layout Components"]
+D --> E["通用组件<br/>Common Components"]
+E --> F["UI组件<br/>UI Components"]
+```
+
+**图表来源**
+- [frontend_v2/src/components/common/app-provider.vue:1-50](file://frontend_v2/src/components/common/app-provider.vue#L1-L50)
+- [frontend_v2/src/components/custom/button-icon.vue:1-50](file://frontend_v2/src/components/custom/button-icon.vue#L1-L50)
+
+**章节来源**
+- [frontend_v2/src/components/common/app-provider.vue:1-50](file://frontend_v2/src/components/common/app-provider.vue#L1-L50)
+- [frontend_v2/src/components/custom/button-icon.vue:1-50](file://frontend_v2/src/components/custom/button-icon.vue#L1-L50)
+- [frontend_v2/src/components/advanced/table-column-setting.vue:1-50](file://frontend_v2/src/components/advanced/table-column-setting.vue#L1-L50)
+
+## 状态管理
+新架构采用Pinia进行状态管理，结合TypeScript提供完整的类型支持：
+
+### Store结构设计
+- **app store**: 应用全局状态（语言、主题、侧边栏状态）
+- **auth store**: 用户认证状态（令牌、用户信息、权限）
+- **route store**: 路由相关状态（动态路由、面包屑）
+- **tab store**: 标签页状态（打开的标签、活动标签）
+- **theme store**: 主题配置状态（主题色、布局模式）
+
+### 状态持久化
+- 使用localStorage持久化关键状态
+- 自动序列化/反序列化处理复杂对象
+- 支持状态版本管理和迁移
+
+```mermaid
+sequenceDiagram
+participant C as 组件
+participant S as Pinia Store
+participant L as localStorage
+participant API as 后端API
+C->>S : 调用action
+S->>API : 发起网络请求
+API-->>S : 返回数据
+S->>S : 更新状态
+S->>L : 持久化状态
+S-->>C : 响应更新
+C->>C : 重新渲染
+```
+
+**图表来源**
+- [frontend_v2/src/store/modules/auth/index.ts:1-100](file://frontend_v2/src/store/modules/auth/index.ts#L1-L100)
+- [frontend_v2/src/store/plugins/index.ts:1-50](file://frontend_v2/src/store/plugins/index.ts#L1-L50)
+
+**章节来源**
+- [frontend_v2/src/store/index.ts:1-50](file://frontend_v2/src/store/index.ts#L1-L50)
+- [frontend_v2/src/store/modules/app/index.ts:1-100](file://frontend_v2/src/store/modules/app/index.ts#L1-L100)
+- [frontend_v2/src/store/modules/auth/index.ts:1-100](file://frontend_v2/src/store/modules/auth/index.ts#L1-L100)
+- [frontend_v2/src/store/plugins/index.ts:1-50](file://frontend_v2/src/store/plugins/index.ts#L1-L50)
+
+## API请求层
+新架构提供双HTTP客户端方案，支持Alova和Axios两种选择：
+
+### Alova方案（推荐）
+- 基于Alova的现代化HTTP客户端
+- 内置请求缓存、重试机制
+- 完整的TypeScript类型推断
+- 支持Mock数据和单元测试
+
+### Axios方案（兼容）
+- 传统Axios封装，保持向后兼容
+- 统一的错误处理和拦截器
+- 请求取消和超时控制
+
+### 请求拦截器链
+```mermaid
+flowchart LR
+A["请求发起"] --> B["请求拦截器"]
+B --> C["认证令牌注入"]
+C --> D["请求日志记录"]
+D --> E["发送请求"]
+E --> F["响应拦截器"]
+F --> G["错误处理"]
+G --> H["数据转换"]
+H --> I["返回结果"]
+```
+
+**图表来源**
+- [frontend_v2/src/service/request/index.ts:1-100](file://frontend_v2/src/service/request/index.ts#L1-L100)
+- [frontend_v2/src/service/request/shared.ts:1-50](file://frontend_v2/src/service/request/shared.ts#L1-L50)
+
+**章节来源**
+- [frontend_v2/src/service/api/index.ts:1-50](file://frontend_v2/src/service/api/index.ts#L1-L50)
+- [frontend_v2/src/service/request/index.ts:1-100](file://frontend_v2/src/service/request/index.ts#L1-L100)
+- [frontend_v2/src/service/request/shared.ts:1-50](file://frontend_v2/src/service/request/shared.ts#L1-L50)
+- [frontend_v2/src/service/request/type.ts:1-50](file://frontend_v2/src/service/request/type.ts#L1-L50)
+
+## 路由与导航
+新架构采用Vue Router 4，支持动态路由、路由守卫和懒加载：
+
+### 路由配置
+- 静态路由：登录页、404页面等固定路由
+- 动态路由：根据用户权限动态生成菜单和路由
+- 路由元信息：权限控制、面包屑、标题等配置
+
+### 路由守卫
+- 认证守卫：检查用户登录状态
+- 权限守卫：验证用户角色和权限
+- 进度条：路由切换时显示加载进度
+
+```mermaid
+sequenceDiagram
+participant U as 用户
+participant R as 路由守卫
+participant A as 认证检查
+participant P as 权限检查
+participant V as 视图组件
+U->>R : 访问路由
+R->>A : 检查登录状态
+alt 未登录
+A-->>R : 重定向到登录页
+R-->>U : 跳转登录页
+else 已登录
+R->>P : 检查权限
+alt 无权限
+P-->>R : 拒绝访问
+R-->>U : 跳转到403页面
+else 有权限
+P-->>R : 允许访问
+R->>V : 加载组件
+V-->>U : 显示页面
+end
+end
+```
+
+**图表来源**
+- [frontend_v2/src/router/guard/index.ts:1-100](file://frontend_v2/src/router/guard/index.ts#L1-L100)
+- [frontend_v2/src/router/guard/route.ts:1-50](file://frontend_v2/src/router/guard/route.ts#L1-L50)
+
+**章节来源**
+- [frontend_v2/src/router/index.ts:1-100](file://frontend_v2/src/router/index.ts#L1-L100)
+- [frontend_v2/src/router/guard/index.ts:1-100](file://frontend_v2/src/router/guard/index.ts#L1-L100)
+- [frontend_v2/src/router/guard/route.ts:1-50](file://frontend_v2/src/router/guard/route.ts#L1-L50)
+- [frontend_v2/src/router/guard/title.ts:1-30](file://frontend_v2/src/router/guard/title.ts#L1-L30)
+
+## 主题与样式系统
+新架构采用现代化的主题系统，支持深色模式、主题色定制和响应式设计：
+
+### 主题架构
+- **CSS变量**: 全局主题变量定义
+- **UnoCSS**: 原子化样式引擎，按需生成样式
+- **SCSS**: 复杂样式逻辑和混合宏
+- **主题预设**: 内置多种主题方案
+
+### 主题特性
+- 实时主题切换
+- 深色/浅色模式自动检测
+- 品牌色自定义
+- 字体大小调节
+- 布局模式切换
+
+```mermaid
+graph TB
+A["主题配置"] --> B["CSS变量"]
+A --> C["UnoCSS预设"]
+A --> D["SCSS变量"]
+B --> E["组件样式"]
+C --> E
+D --> E
+E --> F["运行时主题切换"]
+F --> G["浏览器本地存储"]
+```
+
+**图表来源**
+- [frontend_v2/src/theme/settings.ts:1-50](file://frontend_v2/src/theme/settings.ts#L1-L50)
+- [frontend_v2/src/theme/vars.ts:1-50](file://frontend_v2/src/theme/vars.ts#L1-L50)
+- [frontend_v2/uno.config.ts:1-100](file://frontend_v2/uno.config.ts#L1-L100)
+
+**章节来源**
+- [frontend_v2/src/theme/settings.ts:1-50](file://frontend_v2/src/theme/settings.ts#L1-L50)
+- [frontend_v2/src/theme/vars.ts:1-50](file://frontend_v2/src/theme/vars.ts#L1-L50)
+- [frontend_v2/uno.config.ts:1-100](file://frontend_v2/uno.config.ts#L1-L100)
+- [frontend_v2/src/styles/css/global.css:1-50](file://frontend_v2/src/styles/css/global.css#L1-L50)
+
+## 构建与部署
+新架构采用Vite 5作为构建工具，配合pnpm workspace实现高效的开发和构建流程：
+
+### 构建配置
+- **开发环境**: 热重载、Source Map、ESLint集成
+- **生产环境**: 代码分割、Tree Shaking、资源压缩
+- **多环境配置**: 开发、测试、生产环境差异化配置
+
+### 部署策略
+- Docker容器化部署
+- Nginx反向代理配置
+- CDN静态资源托管
+- 环境变量管理
+
+**章节来源**
+- [frontend_v2/vite.config.ts:1-150](file://frontend_v2/vite.config.ts#L1-L150)
+- [frontend_v2/Dockerfile:1-50](file://frontend_v2/Dockerfile#L1-L50)
+- [frontend_v2/nginx.conf:1-50](file://frontend_v2/nginx.conf#L1-L50)
+
+## 性能优化
+新架构在多个层面实施性能优化策略：
+
+### 代码优化
+- **Tree Shaking**: 移除未使用的代码
+- **代码分割**: 路由级和组件级懒加载
+- **依赖优化**: 第三方库按需引入
+- **缓存策略**: 浏览器缓存和服务端缓存
+
+### 运行时优化
+- **虚拟滚动**: 大数据列表渲染优化
+- **图片优化**: WebP格式、懒加载、CDN加速
+- **内存管理**: 组件卸载时清理监听器和定时器
+- **首屏优化**: 关键路径代码内联、预加载重要资源
+
+**章节来源**
+- [frontend_v2/vite.config.ts:80-150](file://frontend_v2/vite.config.ts#L80-L150)
+- [frontend_v2/src/router/elegant/transform.ts:1-50](file://frontend_v2/src/router/elegant/transform.ts#L1-L50)
+
+## 开发工作流
+新架构提供完整的现代化开发工作流：
+
+### 开发环境
+- **热重载**: 代码修改即时预览
+- **类型检查**: 实时TypeScript错误提示
+- **代码格式化**: Prettier自动格式化
+- **代码检查**: ESLint规则校验
+
+### 构建脚本
+- **开发服务器**: `pnpm dev`
+- **生产构建**: `pnpm build`
+- **预览构建**: `pnpm preview`
+- **代码检查**: `pnpm lint`
+- **类型检查**: `pnpm typecheck`
+
+**章节来源**
+- [frontend_v2/package.json:1-100](file://frontend_v2/package.json#L1-L100)
+- [frontend_v2/eslint.config.js:1-50](file://frontend_v2/eslint.config.js#L1-L50)
 
 ## 故障排查指南
-- 登录失败
-  - 检查表单校验规则与必填项。
-  - 查看响应拦截器返回的错误消息与业务码。
-- 401 未授权
-  - 检查请求拦截器是否正确注入 Authorization。
-  - 确认路由守卫是否触发清理鉴权与跳转登录。
-- 403 权限不足
-  - 检查用户角色与页面 meta.requiresSuperAdmin。
-- 网络错误
-  - 查看响应拦截器统一错误提示与控制台日志。
-- 标签页异常
-  - 检查 sessionStorage 是否被清理或损坏。
-  - 确认 TabsView 的持久化与恢复逻辑。
+新架构提供了完善的调试和故障排查机制：
 
-章节来源
-- [frontend/src/views/login/index.vue:123-150](file://frontend/src/views/login/index.vue#L123-L150)
-- [frontend/src/utils/request.js:27-69](file://frontend/src/utils/request.js#L27-L69)
-- [frontend/src/router/index.js:64-88](file://frontend/src/router/index.js#L64-L88)
-- [frontend/src/utils/tabs.js:4-8](file://frontend/src/utils/tabs.js#L4-L8)
-- [frontend/src/components/TabsView.vue:125-174](file://frontend/src/components/TabsView.vue#L125-L174)
+### 常见问题
+- **TypeScript错误**: 检查tsconfig配置和类型定义
+- **构建失败**: 查看Vite构建日志和依赖冲突
+- **运行时错误**: 使用浏览器开发者工具和错误边界
+- **性能问题**: 使用Chrome DevTools分析性能瓶颈
+
+### 调试技巧
+- **Vue DevTools**: 组件树、状态、事件调试
+- **网络面板**: API请求和响应调试
+- **控制台日志**: 结构化日志输出
+- **错误监控**: 前端错误收集和上报
+
+**章节来源**
+- [frontend_v2/src/plugins/loading.ts:1-50](file://frontend_v2/src/plugins/loading.ts#L1-L50)
+- [frontend_v2/src/plugins/nprogress.ts:1-30](file://frontend_v2/src/plugins/nprogress.ts#L1-L30)
 
 ## 结论
-该前端架构以 Vue 3 Composition API 为核心，结合 Element Plus 与自研 HTTP 客户端，形成清晰的路由鉴权、多页签缓存与主题体系。通过路由懒加载与 KeepAlive 降低首屏与切换成本，借助 Vite 提供高效的开发体验。建议后续在大型页面引入 Pinia 或基于 provide/inject 的轻量状态管理，以进一步提升复杂场景下的可维护性。
-
-## 附录
-
-### Vite 配置与优化要点
-- 插件：启用 @vitejs/plugin-vue。
-- 全局常量：开启 Options API、关闭生产 devtools 与水合不匹配详情。
-- 路径别名：@ 指向 src。
-- 开发服务器：端口 3000，代理 /api 到后端服务地址。
-- 可选优化：按需引入 polyfill、压缩图片与静态资源、分析包体积。
-
-章节来源
-- [frontend/vite.config.js:1-27](file://frontend/vite.config.js#L1-L27)
-
-### 依赖管理与脚本
-- 依赖：Vue、Element Plus、Vue Router、Axios。
-- 开发依赖：Vite、@vitejs/plugin-vue。
-- 脚本：dev、build、preview。
-
-章节来源
-- [frontend/package.json:1-24](file://frontend/package.json#L1-L24)
-
-### 开发环境配置与调试
-- 启动：使用 dev 脚本启动 Vite 开发服务器。
-- 调试：利用浏览器断点与 Vue DevTools；关注请求拦截器与路由守卫日志。
-- 代理：开发阶段通过 /api 代理到后端，避免跨域问题。
-
-章节来源
-- [frontend/package.json:5-9](file://frontend/package.json#L5-L9)
-- [frontend/vite.config.js:17-25](file://frontend/vite.config.js#L17-L25)
+全新的Vue 3 + TypeScript前端架构通过monorepo结构、现代化技术栈和完善的开发工作流，显著提升了项目的可维护性、可扩展性和开发效率。新架构不仅解决了旧版本的痛点，还为未来的功能扩展和技术演进奠定了坚实基础。建议团队逐步迁移现有功能到新架构，充分利用TypeScript的类型安全和现代JavaScript生态的优势。