Web 前端概览
项目提供 Vue 3 和 Vue 2 两套 Web 管理端。它们调用同一个 FastAPI 后端，使用相同的接口路径、菜单模型、权限字符和主要业务流程；差异集中在 Vue API、组件库、状态管理、路由 API 与构建工具。
文档因此分为一条公共主线和两条实现轨道。开发业务功能时先阅读公共主线，只有写组件、使用 Store、配置构建或定位框架问题时，才进入对应版本页面。
一套业务契约，两套前端实现
| 层次 | 两个版本共用 | 分版本实现 |
|---|---|---|
| 后端契约 | API、响应结构、Token、菜单树、权限字符、字典与参数 | 无 |
| 页面组织 | api、views、components、layout、router、store 等职责 | 组件语法和生命周期 |
| 访问控制 | 登录流程、路由守卫目标、菜单权限、按钮权限、数据范围 | Router 与 Store 的具体 API |
| 公共能力 | 分页、字典、上传、下载、页签、弹窗等使用目标 | Element Plus / Element UI 的 props、事件与插槽 |
| 工程工具 | development、staging、production、docker 等环境目的 | Vite / Vue CLI 与 Webpack |
| 插件视图 | plugin/<pluginId>/<viewPath> 组件协议 | import.meta.glob / require.context |
页面进入运行态的过程
src/main.js创建应用，装配 Router、Store、指令、应用插件、全局组件和 UI 组件库。src/permission.js在导航前检查 Token、白名单和锁屏状态。- 首次进入受保护页面时，用户 Store 请求当前用户、角色和权限。
- 权限 Store 请求后端菜单树，把组件字符串解析为布局容器或异步页面组件。
- 路由注册完成后进入
src/layout，侧栏、顶栏、页签与主内容区开始协同工作。 - 业务页面通过
src/api调用统一 Axios 实例，请求拦截器处理 Token、防重复提交和传输加密，响应拦截器统一处理业务码与会话失效。
这条运行链是理解登录后空白、菜单不显示、刷新 404、按钮权限失效、页面缓存异常和接口重复提示的基础。各环节的实现分别放在请求、认证与会话、菜单、路由与页签和功能、角色与数据权限。
文档地图
| 分组 | 解决的问题 | 入口 |
|---|---|---|
| 认识 Web 前端 | 系统由哪些层组成，代码应该放在哪里，两个版本怎样选择 | 工程结构与代码归属、版本选择与实现差异 |
| 运行时、认证与权限 | 请求怎样发出，登录态怎样建立，菜单怎样变成路由，权限怎样落到页面 | 请求、认证与会话、菜单、路由与页签、功能、角色与数据权限 |
| 业务页面与公共能力 | 怎样完成一个页面并复用字典、文件和公共组件 | 开发一个业务页面、字典、参数与缓存、文件上传与下载、通用组件与交互能力 |
| Vue 3 实现 | Vite、createApp、Pinia、Router 4 和 Composition API 的具体实现 | Vue 3 实现概览 |
| Vue 2 实现 | Vue CLI、new Vue、Vuex、Router 3 和 Options API 的具体实现 | Vue 2 实现概览 |
按当前任务阅读
| 当前任务 | 建议阅读顺序 |
|---|---|
| 第一次开发管理端页面 | 工程结构与代码归属 → 开发一个业务页面 → 对应版本的页面写法 |
| 登录成功后没有菜单 | 菜单、路由与页签 → 功能、角色与数据权限 |
| 请求没有 Token、频繁弹错或加密失败 | 请求、认证与会话 |
| 页面有菜单但按钮不显示 | 功能、角色与数据权限 |
| 接入字典、参数、上传或下载 | 字典、参数与缓存 → 文件上传与下载 |
| 从 Vue 2 迁移到 Vue 3 | 版本选择与实现差异 → Vue 3 实现概览 |
| 修改环境变量或代理 | Vue 3 环境与代理或Vue 2 环境与代理 |
| 构建和发布 | Vue 3 Vite 构建或Vue 2 Vue CLI 构建 |
| 开发前端业务插件 | 插件前端开发；动态加载原理回看菜单、路由与页签 |
关键源码入口
| 源码 | 先看什么 |
|---|---|
src/main.js | 应用装配顺序和全局能力 |
src/permission.js | 登录态、用户信息和路由生成时序 |
src/utils/request.js | 请求与响应拦截行为 |
src/store/modules/user.js | 用户、角色、权限与退出登录 |
src/store/modules/permission.js | 后端菜单转换、动态路由与组件加载 |
src/layout/ | 管理端布局、导航、页签与主内容区 |
src/components/ | 可直接复用的通用组件 |
plugins/<pluginId>/ | 独立交付的业务插件页面与 API |
尚未完成本地启动时，先使用 Vue 3 Web 快速开始 或 Vue 2 Web 快速开始。已经能登录管理端时，从工程结构与代码归属继续。