提交文件

2026-02-28 15:16:15 +08:00
parent 1a4e50e0a4
commit 44f250f58e
159 changed files with 61268 additions and 0 deletions
--- a/.qoder/repowiki/zh/content/前端开发指南/项目初始化与配置.md
+++ b/.qoder/repowiki/zh/content/前端开发指南/项目初始化与配置.md
@@ -0,0 +1,483 @@
+# 项目初始化与配置
+
+<cite>
+**本文档引用的文件**
+- [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)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构概览](#架构概览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排除指南](#故障排除指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本文件面向前端开发者，系统化阐述 Vue 3 应用的创建、初始化与配置流程，涵盖项目结构、依赖管理、Vite 构建与开发服务器配置、Element Plus 主题与国际化设置、全局样式引入、应用入口配置、插件注册与全局组件挂载等。同时提供开发环境搭建步骤、依赖安装命令、启动流程、常见配置问题解决方案以及性能优化建议。
+
+## 项目结构
+前端项目位于 `frontend` 目录，采用典型的 Vue 3 + Vite 单页应用结构：
+- 根目录包含构建脚本、依赖声明与 Vite 配置
+- `src` 目录包含应用源代码：入口文件、路由、状态管理、API 层、视图组件与全局样式
+- `public` 目录用于存放静态资源
+- `dist` 目录为构建产物输出目录
+
+```mermaid
+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/"]
+```
+
+图表来源
+- [package.json](file://frontend/package.json#L1-L27)
+- [vite.config.js](file://frontend/vite.config.js#L1-L22)
+- [index.html](file://frontend/index.html#L1-L14)
+- [main.js](file://frontend/src/main.js#L1-L24)
+
+章节来源
+- [package.json](file://frontend/package.json#L1-L27)
+- [vite.config.js](file://frontend/vite.config.js#L1-L22)
+- [index.html](file://frontend/index.html#L1-L14)
+
+## 核心组件
+本节聚焦于项目初始化的关键配置与组件，包括依赖管理、构建配置、应用入口、路由与状态管理、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 变量、布局容器、表格、搜索栏、统计卡片、状态标签、分数等级、图表容器等
+
+章节来源
+- [package.json](file://frontend/package.json#L6-L25)
+- [vite.config.js](file://frontend/vite.config.js#L5-L21)
+- [main.js](file://frontend/src/main.js#L1-L24)
+- [index.js](file://frontend/src/router/index.js#L1-L116)
+- [app.js](file://frontend/src/stores/app.js#L1-L31)
+- [user.js](file://frontend/src/stores/user.js#L1-L49)
+- [request.js](file://frontend/src/api/request.js#L1-L66)
+- [main.scss](file://frontend/src/assets/main.scss#L1-L186)
+
+## 架构概览
+前端采用“入口文件 -> 插件注册 -> 路由与状态管理 -> 视图组件 -> API 层 -> 全局样式”的线性架构，结合 Element Plus 提供 UI 能力与国际化支持。
+
+```mermaid
+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
+```
+
+图表来源
+- [main.js](file://frontend/src/main.js#L1-L24)
+- [App.vue](file://frontend/src/App.vue#L1-L17)
+- [index.js](file://frontend/src/router/index.js#L1-L116)
+- [app.js](file://frontend/src/stores/app.js#L1-L31)
+- [user.js](file://frontend/src/stores/user.js#L1-L49)
+- [request.js](file://frontend/src/api/request.js#L1-L66)
+- [vite.config.js](file://frontend/vite.config.js#L1-L22)
+- [package.json](file://frontend/package.json#L1-L27)
+
+## 详细组件分析
+
+### 依赖管理与脚本
+- 生产依赖
+  - 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：预览构建产物
+
+章节来源
+- [package.json](file://frontend/package.json#L11-L25)
+
+### Vite 构建工具与开发服务器配置
+- 插件：启用 Vue 插件以支持单文件组件
+- 路径别名：@ 指向 src，便于导入
+- 开发服务器：
+  - 端口：5173
+  - 代理：将 /api 前缀转发至后端 8000 端口，解决跨域问题
+- 该配置确保开发时前后端联调顺畅
+
+章节来源
+- [vite.config.js](file://frontend/vite.config.js#L5-L21)
+
+### 应用入口文件与插件注册
+- 创建应用实例并挂载根组件
+- 插件注册顺序：
+  - Pinia（状态管理）
+  - Vue Router（路由）
+  - Element Plus（UI 组件库，使用中文本地化）
+- 动态注册 Element Plus 图标组件，避免逐个手动注册
+- 引入全局样式 main.scss
+
+```mermaid
+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 : 渲染界面
+```
+
+图表来源
+- [index.html](file://frontend/index.html#L10-L11)
+- [main.js](file://frontend/src/main.js#L1-L24)
+- [App.vue](file://frontend/src/App.vue#L1-L17)
+- [index.js](file://frontend/src/router/index.js#L1-L116)
+- [app.js](file://frontend/src/stores/app.js#L1-L31)
+- [user.js](file://frontend/src/stores/user.js#L1-L49)
+
+章节来源
+- [index.html](file://frontend/index.html#L1-L14)
+- [main.js](file://frontend/src/main.js#L1-L24)
+- [App.vue](file://frontend/src/App.vue#L1-L17)
+
+### Element Plus 主题配置与国际化
+- 国际化：通过 zh-cn.mjs 设置 Element Plus 语言为中文，并在根组件中使用 el-config-provider 包裹，确保全局组件显示中文
+- 样式：引入 element-plus/dist/index.css 以加载默认样式
+- 图标：动态注册 Element Plus 图标组件，减少手动注册工作量
+
+章节来源
+- [main.js](file://frontend/src/main.js#L3-L6)
+- [App.vue](file://frontend/src/App.vue#L2-L4)
+
+### 全局样式引入与主题变量
+- 全局样式：在入口文件引入 main.scss，实现全局重置、字体、布局容器与通用组件样式
+- 主题变量：定义主色、状态色、文本色、边框色、背景色等 CSS 变量，便于统一主题风格
+- 组件级样式：表格、搜索栏、统计卡片、状态标签、分数等级、图表容器等样式集中维护
+
+章节来源
+- [main.js](file://frontend/src/main.js#L10-L10)
+- [main.scss](file://frontend/src/assets/main.scss#L14-L26)
+- [main.scss](file://frontend/src/assets/main.scss#L63-L186)
+
+### 路由与导航
+- 路由结构：
+  - 登录页：/login
+  - 主布局：/，包含工作台、科室管理、员工管理、考核指标、指标模板、考核管理、工资核算、统计报表、经济核算、绩效计划、系统管理（菜单管理）等子路由
+- 路由守卫：
+  - 设置页面标题
+  - 校验 token，未登录跳转至登录页
+
+```mermaid
+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
+```
+
+图表来源
+- [index.js](file://frontend/src/router/index.js#L104-L113)
+
+章节来源
+- [index.js](file://frontend/src/router/index.js#L1-L116)
+
+### 状态管理（Pinia）
+- 用户 Store（user.js）
+  - 状态：token、userInfo
+  - 方法：登录（调用认证 API，存储 token）、获取用户信息、登出（清除 token 并跳转登录）
+- 应用 Store（app.js）
+  - 状态：collapsed（侧边栏折叠状态）、departmentTree（科室树）
+  - 方法：切换侧边栏、加载科室树
+
+```mermaid
+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 : "使用"
+```
+
+图表来源
+- [user.js](file://frontend/src/stores/user.js#L6-L47)
+- [app.js](file://frontend/src/stores/app.js#L5-L30)
+- [auth.js](file://frontend/src/api/auth.js#L4-L11)
+- [department.js](file://frontend/src/api/department.js#L9-L11)
+
+章节来源
+- [user.js](file://frontend/src/stores/user.js#L1-L49)
+- [app.js](file://frontend/src/stores/app.js#L1-L31)
+- [index.js](file://frontend/src/stores/index.js#L1-L3)
+
+### API 层与拦截器
+- Axios 实例：
+  - baseURL：/api/v1
+  - timeout：30000ms
+  - Content-Type：application/json
+- 请求拦截器：自动附加 Authorization 头（Bearer token）
+- 响应拦截器：统一处理业务错误码、HTTP 状态码错误（401、403、404、500 等），并进行消息提示与路由跳转
+
+```mermaid
+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 : 返回数据
+```
+
+图表来源
+- [request.js](file://frontend/src/api/request.js#L6-L12)
+- [request.js](file://frontend/src/api/request.js#L14-L26)
+- [request.js](file://frontend/src/api/request.js#L28-L63)
+- [auth.js](file://frontend/src/api/auth.js#L4-L11)
+
+章节来源
+- [request.js](file://frontend/src/api/request.js#L1-L66)
+- [auth.js](file://frontend/src/api/auth.js#L1-L22)
+- [department.js](file://frontend/src/api/department.js#L1-L32)
+- [menu.js](file://frontend/src/api/menu.js#L1-L37)
+
+### 视图组件与布局
+- 登录页（Login.vue）
+  - 表单验证、加载状态、错误提示
+  - 调用用户 Store 登录，成功后跳转主页面
+- 主布局（Layout.vue）
+  - 侧边栏菜单：根据后端返回的菜单树渲染，支持折叠
+  - 顶部导航：面包屑、用户下拉菜单、退出登录
+  - 内容区域：路由视图过渡动画
+
+章节来源
+- [Login.vue](file://frontend/src/views/Login.vue#L1-L155)
+- [Layout.vue](file://frontend/src/views/Layout.vue#L1-L241)
+
+## 依赖关系分析
+- 入口文件依赖：main.js 依赖 App.vue、router、stores、Element Plus、全局样式
+- 路由依赖：router/index.js 依赖视图组件与菜单 API
+- 状态管理依赖：stores 依赖 API 模块
+- API 依赖：API 模块依赖 Axios 实例
+- 样式依赖：全局样式被入口文件引入
+
+```mermaid
+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
+```
+
+图表来源
+- [main.js](file://frontend/src/main.js#L1-L24)
+- [index.js](file://frontend/src/router/index.js#L1-L116)
+- [app.js](file://frontend/src/stores/app.js#L1-L31)
+- [user.js](file://frontend/src/stores/user.js#L1-L49)
+- [request.js](file://frontend/src/api/request.js#L1-L66)
+- [auth.js](file://frontend/src/api/auth.js#L1-L22)
+- [department.js](file://frontend/src/api/department.js#L1-L32)
+- [menu.js](file://frontend/src/api/menu.js#L1-L37)
+
+章节来源
+- [main.js](file://frontend/src/main.js#L1-L24)
+- [index.js](file://frontend/src/router/index.js#L1-L116)
+- [app.js](file://frontend/src/stores/app.js#L1-L31)
+- [user.js](file://frontend/src/stores/user.js#L1-L49)
+- [request.js](file://frontend/src/api/request.js#L1-L66)
+
+## 性能考虑
+- 代码分割与懒加载
+  - 路由组件采用动态导入，按需加载，减少首屏体积
+- 图标注册
+  - 通过循环注册 Element Plus 图标，避免重复注册导致的包体膨胀
+- 样式组织
+  - 全局样式集中管理，避免重复定义与样式冲突
+- 构建优化
+  - 使用 Vite 的原生 ES 模块与快速热更新，提升开发体验
+- 网络请求
+  - Axios 统一拦截器减少重复逻辑，提高可维护性
+
+章节来源
+- [index.js](file://frontend/src/router/index.js#L7-L94)
+- [main.js](file://frontend/src/main.js#L14-L17)
+- [main.scss](file://frontend/src/assets/main.scss#L1-L186)
+- [vite.config.js](file://frontend/vite.config.js#L5-L21)
+
+## 故障排除指南
+- CORS 错误
+  - 现象：浏览器控制台出现跨域错误
+  - 原因：开发阶段未正确配置代理或后端未允许跨域
+  - 解决：确认 Vite 代理配置与后端 CORS 设置一致
+- 404 Not Found
+  - 现象：请求路径返回 404
+  - 原因：Vite 代理未生效或后端路由不匹配
+  - 解决：重启前端开发服务器；检查后端路由与版本
+- 500 Internal Server Error
+  - 现象：后端服务异常
+  - 原因：后端代码错误或数据库问题
+  - 解决：查看后端日志目录，定位具体错误
+- Network Error
+  - 现象：无法连接后端
+  - 原因：后端服务未启动
+  - 解决：启动后端服务后再进行联调
+- 登录失败
+  - 检查点：后端健康检查、账号密码、Content-Type
+- 清理缓存与硬刷新
+  - 清空浏览器缓存、localStorage，执行硬刷新
+- 快速重启服务
+  - 停止 Python 进程，重启后端与前端
+
+章节来源
+- [DEBUG_GUIDE.md](file://frontend/DEBUG_GUIDE.md#L1-L119)
+- [vite.config.js](file://frontend/vite.config.js#L14-L19)
+- [request.js](file://frontend/src/api/request.js#L39-L62)
+
+## 结论
+本项目通过清晰的依赖管理、合理的 Vite 配置、完善的入口与插件注册、规范的路由与状态管理、统一的 API 封装以及全局样式体系，构建了一个可扩展、易维护的 Vue 3 前端应用。配合 Element Plus 的主题与国际化配置，能够快速实现企业级界面与交互体验。建议在后续迭代中持续关注代码分割、样式复用与错误处理的细节优化。
+
+## 附录
+- 开发环境搭建步骤
+  - 安装依赖：使用包管理器安装项目依赖
+  - 启动后端：在后端目录启动服务（参考调试指南中的命令）
+  - 启动前端：在前端目录执行开发服务器命令
+  - 访问应用：打开浏览器访问开发服务器地址
+- 依赖安装命令
+  - 安装生产与开发依赖
+- 启动流程
+  - 启动后端服务
+  - 启动前端开发服务器
+  - 在浏览器中打开应用并登录
+
+章节来源
+- [package.json](file://frontend/package.json#L6-L10)
+- [DEBUG_GUIDE.md](file://frontend/DEBUG_GUIDE.md#L81-L95)