17 KiB
17 KiB
项目初始化与配置
**本文档引用的文件** - [package.json](file://frontend/package.json) - [vite.config.js](file://frontend/vite.config.js) - [main.js](file://frontend/src/main.js) - [App.vue](file://frontend/src/App.vue) - [index.js](file://frontend/src/router/index.js) - [main.scss](file://frontend/src/assets/main.scss) - [index.js](file://frontend/src/stores/index.js) - [app.js](file://frontend/src/stores/app.js) - [user.js](file://frontend/src/stores/user.js) - [index.html](file://frontend/index.html) - [request.js](file://frontend/src/api/request.js) - [Layout.vue](file://frontend/src/views/Layout.vue) - [Login.vue](file://frontend/src/views/Login.vue) - [auth.js](file://frontend/src/api/auth.js) - [department.js](file://frontend/src/api/department.js) - [menu.js](file://frontend/src/api/menu.js) - [DEBUG_GUIDE.md](file://frontend/DEBUG_GUIDE.md)目录
简介
本文件面向前端开发者，系统化阐述 Vue 3 应用的创建、初始化与配置流程，涵盖项目结构、依赖管理、Vite 构建与开发服务器配置、Element Plus 主题与国际化设置、全局样式引入、应用入口配置、插件注册与全局组件挂载等。同时提供开发环境搭建步骤、依赖安装命令、启动流程、常见配置问题解决方案以及性能优化建议。
项目结构
前端项目位于 frontend 目录，采用典型的 Vue 3 + Vite 单页应用结构：
- 根目录包含构建脚本、依赖声明与 Vite 配置
src目录包含应用源代码：入口文件、路由、状态管理、API 层、视图组件与全局样式public目录用于存放静态资源dist目录为构建产物输出目录
graph TB
A["frontend/"] --> B["package.json"]
A --> C["vite.config.js"]
A --> D["index.html"]
A --> E["src/"]
E --> F["main.js"]
E --> G["App.vue"]
E --> H["router/index.js"]
E --> I["stores/"]
E --> J["api/"]
E --> K["views/"]
E --> L["assets/main.scss"]
A --> M["dist/"]
A --> N["public/"]
图表来源
章节来源
核心组件
本节聚焦于项目初始化的关键配置与组件，包括依赖管理、构建配置、应用入口、路由与状态管理、API 层与样式系统。
- 依赖管理与脚本
- 生产依赖：Vue 3、Vue Router、Pinia、Axios、Element Plus、图标库、ECharts、Day.js
- 开发依赖：@vitejs/plugin-vue、Vite、Sass
- 脚本命令：dev、build、preview
- Vite 配置
- 插件：Vue 插件
- 路径别名：@ 指向 src
- 开发服务器：端口 5173，代理 /api 到后端 8000 端口
- 应用入口与插件注册
- 创建应用实例，注册 Pinia、路由、Element Plus（中文本地化）
- 动态注册 Element Plus 图标组件
- 引入全局样式 main.scss
- 路由与导航
- 基于 History 模式的路由，包含登录页与多级菜单路由
- 路由守卫：设置页面标题、校验登录状态
- 状态管理
- Pinia Store：用户状态（token、用户信息）、应用状态（侧边栏折叠、科室树）
- API 层
- Axios 实例封装：统一 base URL、超时、请求/响应拦截器、错误处理
- 认证、菜单、科室等 API 模块
- 全局样式
- SCSS 变量、布局容器、表格、搜索栏、统计卡片、状态标签、分数等级、图表容器等
章节来源
架构概览
前端采用“入口文件 -> 插件注册 -> 路由与状态管理 -> 视图组件 -> API 层 -> 全局样式”的线性架构，结合 Element Plus 提供 UI 能力与国际化支持。
graph TB
subgraph "应用入口"
M["main.js"]
A["App.vue"]
end
subgraph "核心框架"
R["Vue Router"]
S["Pinia"]
EP["Element Plus"]
end
subgraph "业务层"
V["Views"]
API["API Modules"]
ST["Stores"]
end
subgraph "基础设施"
VITE["Vite Dev Server"]
CONF["vite.config.js"]
PKG["package.json"]
end
M --> A
M --> R
M --> S
M --> EP
A --> V
V --> API
V --> ST
API --> |"Axios"| API
VITE --> CONF
PKG --> VITE
图表来源
详细组件分析
依赖管理与脚本
- 生产依赖
- Vue 3：核心框架
- Vue Router：前端路由
- Pinia：状态管理
- Axios：HTTP 客户端
- Element Plus：UI 组件库
- @element-plus/icons-vue：图标库
- ECharts：可视化图表
- Day.js：日期时间处理
- 开发依赖
- @vitejs/plugin-vue：Vite 的 Vue 支持
- Vite：构建工具与开发服务器
- Sass：CSS 预处理器
- 脚本命令
- dev：启动开发服务器
- build：构建生产包
- preview：预览构建产物
章节来源
Vite 构建工具与开发服务器配置
- 插件：启用 Vue 插件以支持单文件组件
- 路径别名：@ 指向 src，便于导入
- 开发服务器：
- 端口：5173
- 代理：将 /api 前缀转发至后端 8000 端口，解决跨域问题
- 该配置确保开发时前后端联调顺畅
章节来源
应用入口文件与插件注册
- 创建应用实例并挂载根组件
- 插件注册顺序：
- Pinia（状态管理）
- Vue Router（路由）
- Element Plus（UI 组件库，使用中文本地化）
- 动态注册 Element Plus 图标组件，避免逐个手动注册
- 引入全局样式 main.scss
sequenceDiagram
participant Browser as "浏览器"
participant HTML as "index.html"
participant Main as "main.js"
participant App as "App.vue"
participant Router as "router/index.js"
participant Store as "stores/*"
participant EP as "Element Plus"
Browser->>HTML : 加载页面
HTML->>Main : 执行入口脚本
Main->>Main : 创建应用实例
Main->>EP : 注册 Element Plus(中文)
Main->>Main : 动态注册图标组件
Main->>Store : 使用 Pinia
Main->>Router : 使用 Vue Router
Main->>App : 挂载根组件
App-->>Browser : 渲染界面
图表来源
章节来源
Element Plus 主题配置与国际化
- 国际化：通过 zh-cn.mjs 设置 Element Plus 语言为中文，并在根组件中使用 el-config-provider 包裹，确保全局组件显示中文
- 样式：引入 element-plus/dist/index.css 以加载默认样式
- 图标：动态注册 Element Plus 图标组件，减少手动注册工作量
章节来源
全局样式引入与主题变量
- 全局样式：在入口文件引入 main.scss，实现全局重置、字体、布局容器与通用组件样式
- 主题变量：定义主色、状态色、文本色、边框色、背景色等 CSS 变量，便于统一主题风格
- 组件级样式：表格、搜索栏、统计卡片、状态标签、分数等级、图表容器等样式集中维护
章节来源
路由与导航
- 路由结构：
- 登录页：/login
- 主布局：/，包含工作台、科室管理、员工管理、考核指标、指标模板、考核管理、工资核算、统计报表、经济核算、绩效计划、系统管理（菜单管理）等子路由
- 路由守卫：
- 设置页面标题
- 校验 token，未登录跳转至登录页
flowchart TD
Start(["进入路由"]) --> CheckPath["判断路径是否为 /login"]
CheckPath --> |是| NextTrue["放行"]
CheckPath --> |否| CheckToken["读取 localStorage 中的 token"]
CheckToken --> HasToken{"是否存在 token?"}
HasToken --> |是| NextTrue
HasToken --> |否| Redirect["重定向到 /login"]
NextTrue --> SetTitle["设置页面标题"]
Redirect --> End(["结束"])
SetTitle --> End
图表来源
章节来源
状态管理（Pinia）
- 用户 Store（user.js）
- 状态：token、userInfo
- 方法：登录（调用认证 API，存储 token）、获取用户信息、登出（清除 token 并跳转登录）
- 应用 Store（app.js）
- 状态：collapsed（侧边栏折叠状态）、departmentTree（科室树）
- 方法：切换侧边栏、加载科室树
classDiagram
class UserStore {
+string token
+object userInfo
+login(username, password) Promise~boolean~
+getUserInfo() Promise~object|null~
+logout() void
}
class AppStore {
+boolean collapsed
+array departmentTree
+toggleSidebar() void
+loadDepartmentTree() Promise~void~
}
class API {
+login(data) Promise
+getCurrentUser() Promise
+getDepartmentTree(params) Promise
}
UserStore --> API : "使用"
AppStore --> API : "使用"
图表来源
章节来源
API 层与拦截器
- Axios 实例：
- baseURL：/api/v1
- timeout：30000ms
- Content-Type：application/json
- 请求拦截器：自动附加 Authorization 头（Bearer token）
- 响应拦截器：统一处理业务错误码、HTTP 状态码错误（401、403、404、500 等），并进行消息提示与路由跳转
sequenceDiagram
participant View as "视图组件"
participant Store as "Pinia Store"
participant API as "API 模块"
participant Axios as "Axios 实例"
participant Interceptor as "拦截器"
participant Backend as "后端服务"
View->>Store : 调用 Store 方法
Store->>API : 发起 API 请求
API->>Axios : request.post/get(...)
Axios->>Interceptor : 进入请求拦截器
Interceptor->>Axios : 添加 Authorization 头
Axios->>Backend : 发送 HTTP 请求
Backend-->>Axios : 返回响应
Axios->>Interceptor : 进入响应拦截器
Interceptor->>View : 统一错误处理与业务码校验
Interceptor-->>View : 返回数据
图表来源
章节来源
视图组件与布局
- 登录页（Login.vue）
- 表单验证、加载状态、错误提示
- 调用用户 Store 登录，成功后跳转主页面
- 主布局（Layout.vue）
- 侧边栏菜单：根据后端返回的菜单树渲染，支持折叠
- 顶部导航：面包屑、用户下拉菜单、退出登录
- 内容区域：路由视图过渡动画
章节来源
依赖关系分析
- 入口文件依赖：main.js 依赖 App.vue、router、stores、Element Plus、全局样式
- 路由依赖：router/index.js 依赖视图组件与菜单 API
- 状态管理依赖：stores 依赖 API 模块
- API 依赖：API 模块依赖 Axios 实例
- 样式依赖：全局样式被入口文件引入
graph LR
Main["main.js"] --> App["App.vue"]
Main --> Router["router/index.js"]
Main --> Stores["stores/*"]
Main --> EP["Element Plus"]
Main --> Styles["assets/main.scss"]
Router --> Views["views/*"]
Router --> MenuAPI["api/menu.js"]
Stores --> AuthAPI["api/auth.js"]
Stores --> DeptAPI["api/department.js"]
Views --> AuthAPI
Views --> MenuAPI
Views --> DeptAPI
AuthAPI --> Request["api/request.js"]
MenuAPI --> Request
DeptAPI --> Request
图表来源
章节来源
性能考虑
- 代码分割与懒加载
- 路由组件采用动态导入，按需加载，减少首屏体积
- 图标注册
- 通过循环注册 Element Plus 图标，避免重复注册导致的包体膨胀
- 样式组织
- 全局样式集中管理，避免重复定义与样式冲突
- 构建优化
- 使用 Vite 的原生 ES 模块与快速热更新，提升开发体验
- 网络请求
- Axios 统一拦截器减少重复逻辑，提高可维护性
章节来源
故障排除指南
- CORS 错误
- 现象：浏览器控制台出现跨域错误
- 原因：开发阶段未正确配置代理或后端未允许跨域
- 解决：确认 Vite 代理配置与后端 CORS 设置一致
- 404 Not Found
- 现象：请求路径返回 404
- 原因：Vite 代理未生效或后端路由不匹配
- 解决：重启前端开发服务器；检查后端路由与版本
- 500 Internal Server Error
- 现象：后端服务异常
- 原因：后端代码错误或数据库问题
- 解决：查看后端日志目录，定位具体错误
- Network Error
- 现象：无法连接后端
- 原因：后端服务未启动
- 解决：启动后端服务后再进行联调
- 登录失败
- 检查点：后端健康检查、账号密码、Content-Type
- 清理缓存与硬刷新
- 清空浏览器缓存、localStorage，执行硬刷新
- 快速重启服务
- 停止 Python 进程，重启后端与前端
章节来源
结论
本项目通过清晰的依赖管理、合理的 Vite 配置、完善的入口与插件注册、规范的路由与状态管理、统一的 API 封装以及全局样式体系，构建了一个可扩展、易维护的 Vue 3 前端应用。配合 Element Plus 的主题与国际化配置，能够快速实现企业级界面与交互体验。建议在后续迭代中持续关注代码分割、样式复用与错误处理的细节优化。
附录
- 开发环境搭建步骤
- 安装依赖：使用包管理器安装项目依赖
- 启动后端：在后端目录启动服务（参考调试指南中的命令）
- 启动前端：在前端目录执行开发服务器命令
- 访问应用：打开浏览器访问开发服务器地址
- 依赖安装命令
- 安装生产与开发依赖
- 启动流程
- 启动后端服务
- 启动前端开发服务器
- 在浏览器中打开应用并登录
章节来源