Files

T

2026-06-30 14:46:52 +08:00

18 KiB

Raw Blame History

前端架构

**本文引用的文件** - [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)

引言

本文件面向前端工程团队与技术管理者，系统性阐述该 Vue 3 单页应用的前端架构设计与实现要点。重点覆盖 Composition API 使用模式、组件层次结构、路由配置与鉴权策略、状态管理策略（以 Tabs 视图与会话存储为核心）、Vite 构建与开发服务器配置、前后端交互模式与错误处理机制、性能优化策略、组件通信方式、依赖管理与打包部署流程，以及开发环境配置与调试指南。

项目结构

前端采用基于目录的功能分层组织：

应用入口与全局配置：main.js、App.vue、router、utils、styles
页面视图：views 下按业务模块划分
可复用组件：components 下抽取通用 UI 组件
API 层：api 下按领域模块封装请求方法
构建与运行：vite.config.js、package.json

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/>主题样式"]

图表来源

章节来源

核心组件

应用启动与插件注册：在入口中挂载 Element Plus、路由与主题样式，随后进行首屏可见性控制。
根组件：最外层容器，承载路由出口。
布局容器：提供侧边导航、面包屑、头部用户菜单与 Tabs 视图。
多页签视图：集中管理页面标签、上下文菜单与 KeepAlive 缓存。
登录页：表单校验、登录请求与令牌持久化。
今日统计页：演示 Composition API 数据加载与模板渲染。
HTTP 客户端：统一请求头注入、响应拦截与错误处理。
鉴权工具：本地令牌与用户信息读取、过期判断与清理。
主题样式：深色宇宙风主题变量与组件态样式覆盖。

章节来源

架构总览

应用采用“布局容器 + 多页签 + 业务视图”的结构，路由守卫负责鉴权与跳转，HTTP 层统一处理认证头与错误提示，主题样式通过 CSS 变量与组件作用域样式实现一致性视觉。

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"]

图表来源

组件详解

路由与鉴权

路由定义：登录页无需鉴权；其余页面默认 require 鉴权；部分系统管理页面要求超级管理员。
导航守卫：检查令牌是否存在与未过期；对超级管理员页面进行角色校验；防止已登录用户访问登录页；自动重定向到首页。
令牌与用户信息：本地存储令牌与用户信息；支持从 JWT 解析用户信息与过期时间；提供清理鉴权信息的工具函数。

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

图表来源

章节来源

多页签与缓存

功能点：根据路由动态增删标签、点击切换、右键上下文菜单（关闭、关闭其他、关闭全部）、持久化到 sessionStorage。
KeepAlive：根据激活页签名称集合动态 include，减少重复渲染开销。
默认首页：始终保留首页标签且不可关闭。

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

图表来源

章节来源

布局容器与用户交互

侧边栏：折叠/展开逻辑；根据当前路由自动展开对应菜单组；面包屑标题与分区联动。
头部：用户下拉菜单（修改密码、账号管理、退出登录）；根据用户角色显示不同菜单项。
页签：与 TabsView 协作，承载具体业务视图。

章节来源

frontend/src/layout/index.vue:1-338

登录流程

表单校验：账号与密码必填。
登录请求：调用登录 API，成功后写入令牌与用户信息，清空标签缓存并跳转首页。
错误处理：统一提示与异常捕获。

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:1-453

首页与今日统计

首页卡片：欢迎语、快捷入口、今日新增型号与 OTA 列表。
数据加载：进入页面时异步获取统计数据，展示加载态与空态。
时间格式化：本地格式化时间字符串。

章节来源

HTTP 客户端与错误处理

基础配置：baseURL 指向 /api；超时 10 秒。
请求拦截：自动注入 Bearer 令牌（除登录接口）。
响应拦截：统一处理业务错误（code=0）、401 清理鉴权并跳转登录、403 提示权限不足、其他网络错误统一提示。
与路由守卫协作：401 场景下路由守卫配合跳转。

章节来源

主题与样式

全站主题：深色背景、卡片与玻璃体效果、青紫主色调。
CSS 变量：集中定义字体、颜色、背景等变量，便于主题切换与维护。
组件级样式：通过 scoped 与深度选择器覆盖 Element Plus 组件态。

章节来源

frontend/src/styles/lux-theme.css:1-471

依赖关系分析

运行时依赖：Vue 3、Element Plus、Vue Router、Axios。
开发依赖：Vite、@vitejs/plugin-vue。
项目内依赖：utils/request 作为 HTTP 客户端被 api/* 使用；api/* 被各页面调用；layout 与 TabsView 联动；路由守卫依赖鉴权工具。

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

图表来源

章节来源

性能考量

组件缓存：TabsView 结合 KeepAlive，按页签名称 include，减少重复渲染与请求。
路由懒加载：路由组件使用动态导入，降低首屏体积。
图标按需：Element Plus 图标通过动态组件按需渲染。
样式隔离：scoped 与深度选择器避免全局污染，提升样式计算效率。
构建优化：Vite 默认启用按需编译与热更新；可通过插件扩展压缩与分析。

章节来源

故障排查指南

登录失败
- 检查表单校验规则与必填项。
- 查看响应拦截器返回的错误消息与业务码。
401 未授权
- 检查请求拦截器是否正确注入 Authorization。
- 确认路由守卫是否触发清理鉴权与跳转登录。
403 权限不足
- 检查用户角色与页面 meta.requiresSuperAdmin。
网络错误
- 查看响应拦截器统一错误提示与控制台日志。
标签页异常
- 检查 sessionStorage 是否被清理或损坏。
- 确认 TabsView 的持久化与恢复逻辑。

章节来源

结论

该前端架构以 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

依赖管理与脚本

依赖：Vue、Element Plus、Vue Router、Axios。
开发依赖：Vite、@vitejs/plugin-vue。
脚本：dev、build、preview。

章节来源

frontend/package.json:1-24

开发环境配置与调试

启动：使用 dev 脚本启动 Vite 开发服务器。
调试：利用浏览器断点与 Vue DevTools；关注请求拦截器与路由守卫日志。
代理：开发阶段通过 /api 代理到后端，避免跨域问题。

章节来源

18 KiB Raw Blame History

前端架构

目录

引言

项目结构

核心组件

架构总览

组件详解

路由与鉴权

多页签与缓存

布局容器与用户交互

登录流程

首页与今日统计

HTTP 客户端与错误处理

主题与样式

依赖关系分析

性能考量

故障排查指南

结论

附录

Vite 配置与优化要点

依赖管理与脚本

开发环境配置与调试

18 KiB

Raw Blame History