From b395a9bef707d1ae130bdc96204af5ac3bd7bcad Mon Sep 17 00:00:00 2001 From: Guo Tiantian <1431335589@qq.com> Date: Sun, 24 Aug 2025 20:36:34 +0800 Subject: [PATCH 01/15] =?UTF-8?q?fix:=20=E4=BC=98=E5=8C=96=E5=BF=AB?= =?UTF-8?q?=E9=80=9F=E5=BC=80=E5=A7=8B/=E4=BE=BF=E6=8D=B7=E5=AF=BC?= =?UTF-8?q?=E8=88=AA?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- PROJECT_DOCUMENTATION.md | 403 +++++++++++++++++ frontend/.env.development | 4 +- frontend/src/types/auto-imports.d.ts | 2 + frontend/src/utils/quickStartManager.ts | 6 - frontend/src/views/dashboard/README.md | 406 ------------------ .../components/AddQuickLinkDialog.vue | 160 +------ .../views/dashboard/components/QuickStart.vue | 105 ++--- frontend/src/views/demo/quick-start-test.vue | 291 ------------- 8 files changed, 451 insertions(+), 926 deletions(-) create mode 100644 PROJECT_DOCUMENTATION.md delete mode 100644 frontend/src/views/dashboard/README.md delete mode 100644 frontend/src/views/demo/quick-start-test.vue diff --git a/PROJECT_DOCUMENTATION.md b/PROJECT_DOCUMENTATION.md new file mode 100644 index 00000000..f049340e --- /dev/null +++ b/PROJECT_DOCUMENTATION.md @@ -0,0 +1,403 @@ +# FastAPI Vue3 Admin 项目详细说明文档 + +
+

FastAPI Vue3 Admin

+

现代化全栈中后台管理系统

+

基于 FastAPI + Vue3 + TypeScript + Element Plus 的企业级后台管理解决方案

+
+ +## 📋 目录 + +- [项目概述](#项目概述) +- [技术架构](#技术架构) +- [功能特性](#功能特性) +- [项目结构](#项目结构) +- [核心模块](#核心模块) +- [技术栈详解](#技术栈详解) +- [环境要求](#环境要求) +- [快速开始](#快速开始) +- [部署指南](#部署指南) +- [API文档](#api文档) +- [开发规范](#开发规范) + +## 📖 项目概述 + +**FastAPI Vue3 Admin** 是一套完全开源、高度模块化、技术先进的现代化快速开发平台。该项目采用前后端分离架构,融合了 Python 后端框架 FastAPI 和前端主流框架 Vue3,为企业级中后台系统开发提供了一站式解决方案。 + +### 🎯 设计理念 + +- **模块化设计**:系统功能高度解耦,便于扩展和维护 +- **开箱即用**:提供完整的基础功能模块,快速启动项目开发 +- **技术先进**:采用最新的技术栈,保证项目的先进性和可维护性 +- **开发友好**:完善的中文文档和开发工具链,降低学习成本 +- **企业级**:满足企业级应用的性能、安全、稳定性要求 + +### 🌟 核心优势 + +1. **全栈整合**:前后端技术栈统一,开发效率高 +2. **高性能**:异步框架 + Redis 缓存,响应速度快 +3. **安全可靠**:JWT 认证 + RBAC 权限模型,安全性强 +4. **易于扩展**:模块化架构,便于功能扩展 +5. **部署简单**:支持 Docker 容器化部署 +6. **文档完善**:提供详细的开发文档和 API 文档 + +## 🏗️ 技术架构 + +### 整体架构图 + +``` +┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ +│ 前端应用层 │ │ 移动端应用 │ │ 管理后台 │ +│ (Vue3 SPA) │ │ (UniApp H5) │ │ (Element Plus)│ +└─────────────────┘ └─────────────────┘ └─────────────────┘ + │ │ │ + └───────────────────────┼───────────────────────┘ + │ +┌─────────────────────────────────┼─────────────────────────────────┐ +│ API 网关层 │ │ +│ (Nginx) │ │ +└─────────────────────────────────┼─────────────────────────────────┘ + │ +┌─────────────────────────────────┼─────────────────────────────────┐ +│ 应用服务层 │ │ +│ (FastAPI) │ │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ +│ │ 控制器层 │ │ 服务层 │ │ 数据访问层 │ │ +│ │ Controller │ │ Service │ │ CRUD │ │ +│ └─────────────┘ └─────────────┘ └─────────────┘ │ +└─────────────────────────────────┼─────────────────────────────────┘ + │ +┌─────────────────────────────────┼─────────────────────────────────┐ +│ 数据存储层 │ │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ +│ │ MySQL │ │ Redis │ │ 文件存储 │ │ +│ │ 主数据库 │ │ 缓存/会话 │ │ 静态资源 │ │ +│ └─────────────┘ └─────────────┘ └─────────────┘ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### 前后端分离架构 + +- **前端**:Vue3 + TypeScript + Element Plus + Vite +- **后端**:FastAPI + SQLAlchemy + Pydantic + Alembic +- **数据库**:MySQL 8.0+ (主数据库) + Redis 7.0+ (缓存) +- **部署**:Docker + Nginx + Docker Compose + +## ✨ 功能特性 + +### 🔐 认证授权 +- JWT Token 认证机制 +- OAuth2 标准实现 +- 用户登录/登出 +- 密码加密存储 +- 会话管理 + +### 👥 用户管理 +- 用户信息管理 +- 用户状态控制 +- 密码重置 +- 个人资料编辑 +- 头像上传 + +### 🛡️ 权限管理 (RBAC) +- 基于角色的访问控制 +- 菜单权限控制 +- 按钮权限控制 +- 数据权限控制 +- 角色分配管理 + +### 📊 系统监控 +- 在线用户监控 +- 服务器性能监控 +- Redis 缓存监控 +- 系统日志管理 +- 操作日志记录 + +### ⚙️ 系统配置 +- 系统参数配置 +- 字典数据管理 +- 公告通知管理 +- 定时任务管理 +- 代码生成器 + +### 🎨 界面特性 +- 响应式布局设计 +- 多主题切换 +- 国际化支持 +- 暗黑模式 +- 全屏功能 +- 面包屑导航 + +## 📁 项目结构 + +``` +fastapi_vue3_admin/ +├── backend/ # 后端工程 +│ ├── app/ # 应用核心代码 +│ │ ├── v1/ # API v1 版本 +│ │ │ ├── controllers/ # 控制器层 +│ │ │ ├── services/ # 业务逻辑层 +│ │ │ ├── cruds/ # 数据访问层 +│ │ │ ├── models/ # 数据模型 +│ │ │ ├── schemas/ # 数据验证模式 +│ │ │ ├── params/ # 请求参数模型 +│ │ │ └── urls/ # 路由配置 +│ │ ├── core/ # 核心配置 +│ │ ├── middleware/ # 中间件 +│ │ ├── utils/ # 工具函数 +│ │ └── scripts/ # 初始化脚本 +│ ├── env/ # 环境配置 +│ ├── static/ # 静态文件 +│ ├── sql/ # SQL 脚本 +│ ├── main.py # 应用入口 +│ └── requirements.txt # Python 依赖 +├── frontend/ # 前端工程 +│ ├── src/ # 源代码 +│ │ ├── api/ # API 接口 +│ │ ├── assets/ # 静态资源 +│ │ ├── components/ # 公共组件 +│ │ ├── layouts/ # 布局组件 +│ │ ├── router/ # 路由配置 +│ │ ├── store/ # 状态管理 +│ │ ├── styles/ # 样式文件 +│ │ ├── utils/ # 工具函数 +│ │ ├── views/ # 页面组件 +│ │ └── main.ts # 应用入口 +│ ├── public/ # 公共资源 +│ ├── package.json # 依赖配置 +│ └── vite.config.ts # 构建配置 +├── fastapp/ # 移动端工程 (UniApp) +├── fastdocs/ # 文档工程 +├── devops/ # 部署配置 +│ ├── nginx/ # Nginx 配置 +│ ├── backend/ # 后端部署配置 +│ └── redis/ # Redis 配置 +├── docker-compose.yaml # Docker 编排文件 +└── deploy.sh # 部署脚本 +``` + +## 🧩 核心模块 + +### 仪表盘模块 +- **工作台**:常用功能快捷入口,系统概览 +- **分析页**:数据统计图表,业务指标展示 + +### 系统管理模块 +- **用户管理**:用户信息CRUD,状态管理 +- **角色管理**:角色权限分配,角色层级管理 +- **菜单管理**:系统菜单配置,权限绑定 +- **部门管理**:组织架构管理,部门层级 +- **岗位管理**:职位信息管理 +- **字典管理**:系统字典数据维护 +- **配置管理**:系统参数配置 +- **公告管理**:系统公告发布 +- **日志管理**:操作日志记录查询 + +### 监控管理模块 +- **在线用户**:当前在线用户监控 +- **定时任务**:系统定时任务管理 +- **服务器监控**:服务器性能指标监控 +- **缓存监控**:Redis缓存状态监控 + +### 代码生成模块 +- **代码生成器**:根据数据表自动生成CRUD代码 + +### 接口文档模块 +- **Swagger文档**:自动生成的API文档 +- **Redoc文档**:美化版API文档 + +## 💻 技术栈详解 + +### 前端技术栈 + +| 技术 | 版本 | 描述 | +|------|------|------| +| Vue3 | ^3.5.17 | 渐进式JavaScript框架 | +| TypeScript | ^5.8.3 | JavaScript的超集,提供类型支持 | +| Vite | ^6.3.5 | 新一代前端构建工具 | +| Element Plus | ^2.10.4 | Vue3组件库 | +| Vue Router | ^4.5.1 | Vue官方路由管理器 | +| Pinia | ^3.0.3 | Vue状态管理库 | +| Axios | ^1.10.0 | HTTP客户端 | +| ECharts | ^5.6.0 | 数据可视化图表库 | +| UnoCSS | 66.2.3 | 原子化CSS引擎 | +| Vue I18n | ^11.1.10 | 国际化插件 | + +### 后端技术栈 + +| 技术 | 描述 | +|------|------| +| FastAPI | 现代、高性能的Python Web框架 | +| SQLAlchemy 2.0 | Python SQL工具包和ORM | +| Pydantic 2.0 | 数据验证和设置管理 | +| Alembic | 数据库迁移工具 | +| PyJWT | JWT令牌处理 | +| APScheduler | 定时任务调度器 | +| Redis | 内存数据库,用于缓存和会话 | +| MySQL | 关系型数据库 | + +### 开发工具 + +| 工具 | 描述 | +|------|------| +| ESLint | JavaScript代码检查工具 | +| Prettier | 代码格式化工具 | +| Husky | Git hooks工具 | +| Commitizen | 规范化提交信息 | +| Docker | 容器化部署 | +| Nginx | Web服务器和反向代理 | + +## 🔧 环境要求 + +### 开发环境 + +| 环境 | 版本要求 | +|------|----------| +| Node.js | >= 20.0 | +| Python | >= 3.10 | +| MySQL | >= 8.0 | +| Redis | >= 7.0 | +| pnpm | >= 8.1.0 | + +### 生产环境 + +| 环境 | 版本要求 | +|------|----------| +| Docker | >= 20.0 | +| Docker Compose | >= 2.0 | +| Nginx | >= 1.20 | + +## 🚀 快速开始 + +### 1. 克隆项目 + +```bash +git clone https://gitee.com/tao__tao/fastapi_vue3_admin.git +cd fastapi_vue3_admin +``` + +### 2. 后端启动 + +```bash +cd backend +pip install -r requirements.txt +python main.py run --env=dev +``` + +### 3. 前端启动 + +```bash +cd frontend +pnpm install +pnpm run dev +``` + +### 4. 访问系统 + +- 前端地址:http://localhost:5180/web +- 后端API:http://localhost:8000 +- API文档:http://localhost:8000/docs + +### 5. 默认账号 + +- 管理员:admin / 123456 +- 演示账号:demo / 123456 + +## 📦 部署指南 + +### Docker 部署 + +```bash +# 一键部署 +chmod +x deploy.sh +./deploy.sh + +# 查看服务状态 +docker-compose ps + +# 查看日志 +docker logs -f <容器名> +``` + +### 手动部署 + +1. **数据库配置** + - 创建MySQL数据库 + - 配置Redis服务 + +2. **后端部署** + - 配置环境变量 + - 安装Python依赖 + - 运行数据库迁移 + - 启动FastAPI服务 + +3. **前端部署** + - 构建前端项目 + - 配置Nginx + - 部署静态文件 + +## 📚 API文档 + +### 接口规范 + +- 基础路径:`/api/v1` +- 认证方式:Bearer Token (JWT) +- 数据格式:JSON +- 字符编码:UTF-8 + +### 响应格式 + +```json +{ + "code": 200, + "message": "success", + "data": {}, + "timestamp": 1640995200 +} +``` + +### 状态码说明 + +| 状态码 | 说明 | +|--------|------| +| 200 | 请求成功 | +| 400 | 请求参数错误 | +| 401 | 未授权 | +| 403 | 禁止访问 | +| 404 | 资源不存在 | +| 500 | 服务器内部错误 | + +## 📝 开发规范 + +### 代码规范 + +- 使用ESLint + Prettier进行代码格式化 +- 遵循Vue3 Composition API规范 +- 使用TypeScript进行类型约束 +- 组件命名采用PascalCase +- 文件命名采用kebab-case + +### Git规范 + +- 使用Conventional Commits规范 +- 分支命名:feature/功能名、bugfix/问题描述 +- 提交信息:type(scope): description + +### 目录规范 + +- 组件按功能模块组织 +- 公共组件放在components目录 +- 页面组件放在views目录 +- 工具函数放在utils目录 + +--- + +## 📞 联系方式 + +- 项目地址:https://gitee.com/tao__tao/fastapi_vue3_admin +- 在线演示:https://service.fastapiadmin.com/web +- 问题反馈:https://gitee.com/tao__tao/fastapi_vue3_admin/issues + +## 📄 许可证 + +本项目基于 [MIT](./LICENSE) 许可证开源。 diff --git a/frontend/.env.development b/frontend/.env.development index 1c96ad2b..3f08ecf7 100644 --- a/frontend/.env.development +++ b/frontend/.env.development @@ -5,8 +5,8 @@ VITE_APP_ENV=development VITE_APP_TITLE=fastapiadmin # 网络请求公用地址 -VITE_API_BASE_URL=http://localhost:8001 -# VITE_API_BASE_URL=https://service.fastapiadmin.com +# VITE_API_BASE_URL=http://localhost:8001 +VITE_API_BASE_URL=https://service.fastapiadmin.com # 代理前缀 VITE_APP_BASE_API=/api/v1 diff --git a/frontend/src/types/auto-imports.d.ts b/frontend/src/types/auto-imports.d.ts index 2c5a68f5..d800967e 100644 --- a/frontend/src/types/auto-imports.d.ts +++ b/frontend/src/types/auto-imports.d.ts @@ -325,6 +325,7 @@ declare module 'vue' { interface ComponentCustomProperties { readonly EffectScope: UnwrapRef readonly ElMessage: UnwrapRef + readonly ElMessageBox: UnwrapRef readonly ElNotification: UnwrapRef readonly acceptHMRUpdate: UnwrapRef readonly asyncComputed: UnwrapRef @@ -586,6 +587,7 @@ declare module 'vue' { readonly useThrottleFn: UnwrapRef readonly useThrottledRefHistory: UnwrapRef readonly useTimeAgo: UnwrapRef + readonly useTimeAgoIntl: UnwrapRef readonly useTimeout: UnwrapRef readonly useTimeoutFn: UnwrapRef readonly useTimeoutPoll: UnwrapRef diff --git a/frontend/src/utils/quickStartManager.ts b/frontend/src/utils/quickStartManager.ts index 78877b4f..27a225d0 100644 --- a/frontend/src/utils/quickStartManager.ts +++ b/frontend/src/utils/quickStartManager.ts @@ -5,7 +5,6 @@ export interface QuickLink { title: string; description: string; icon: string; - color: string; href: string; action: 'navigate' | 'external'; id?: string; @@ -35,7 +34,6 @@ class QuickStartManager { title: "用户管理", description: "管理系统用户信息", icon: "User", - color: "#409EFF", href: "/system/user", action: "navigate" }, @@ -44,7 +42,6 @@ class QuickStartManager { title: "系统监控", description: "监控系统状态", icon: "Monitor", - color: "#909399", href: "/monitor", action: "navigate" }, @@ -53,7 +50,6 @@ class QuickStartManager { title: "百度搜索", description: "访问百度搜索引擎", icon: "Search", - color: "#3385FF", href: "https://www.baidu.com", action: "external" }, @@ -62,7 +58,6 @@ class QuickStartManager { title: "GitHub", description: "访问代码托管平台", icon: "Monitor", - color: "#24292e", href: "https://github.com", action: "external" } @@ -177,7 +172,6 @@ class QuickStartManager { title: customTitle || route.meta?.title || route.name || '未命名页面', description: customDescription || `快速访问 ${route.meta?.title || route.name || '页面'}`, icon: routeIcon, - color: routeColor, href: route.fullPath || route.path, action: 'navigate', id: `route-${route.path.replace(/\//g, '-')}-${Date.now()}` diff --git a/frontend/src/views/dashboard/README.md b/frontend/src/views/dashboard/README.md deleted file mode 100644 index 4d16d6b6..00000000 --- a/frontend/src/views/dashboard/README.md +++ /dev/null @@ -1,406 +0,0 @@ -# Dashboard 仪表板模块 - -## 概述 - -Dashboard 仪表板模块是系统的核心展示区域,提供了数据概览、快速导航、工作台等功能。包含工作台页面、数据分析页面以及可复用的组件库。 - -## 模块结构 - -``` -dashboard/ -├── workplace.vue # 工作台主页面 -├── analysis.vue # 数据分析页面 -├── components/ # 可复用组件 -│ ├── QuickStart.vue # 快速开始组件 -│ ├── AddQuickLinkDialog.vue # 添加快速链接对话框 -│ └── index.ts # 组件导出文件 -└── README.md # 模块说明文档 -``` - -## 页面功能 - -### 1. 工作台页面 (workplace.vue) - -**核心功能:** -- ✅ 用户欢迎信息展示 -- ✅ 进行中的项目列表 -- ✅ 动态时间线 -- ✅ 快速开始/便捷导航 -- ✅ 数据指数图表 -- ✅ 团队成员展示 - -**布局特点:** -- 响应式栅格布局 -- 左右分栏设计 -- 卡片式组件展示 -- 移动端适配 - -### 2. 数据分析页面 (analysis.vue) - -**主要功能:** -- ✅ 数据统计图表 -- ✅ 趋势分析展示 -- ✅ 实时数据监控 -- ✅ 可视化数据报表 - -## 组件功能 - -### 1. 快速开始组件 (QuickStart.vue) - -#### 核心特性 -- ✅ 快速链接管理和展示 -- ✅ 支持内部路由跳转和外部链接访问 -- ✅ 固定高度容器,内容可滚动 -- ✅ 响应式设计,适配不同屏幕尺寸 - -#### 标签栏右键收藏 -- ✅ 在任意标签页右击可收藏到快速开始 -- ✅ 支持切换收藏状态(收藏/取消收藏) -- ✅ 自动获取路由配置的图标 -- ✅ 智能图标匹配和颜色配置 -- ✅ 实时状态显示和图标切换 - -#### 手动添加链接 -- ✅ 通过对话框手动添加自定义链接 -- ✅ 支持选择图标和自定义颜色 -- ✅ 表单验证确保数据正确性 -- ✅ 支持内部链接和外部链接 - -#### 右键管理链接 -- ✅ 在快速链接上右击可编辑或删除 -- ✅ 编辑功能自动预填充现有数据 -- ✅ 删除功能带有确认对话框 -- ✅ 防止误操作的安全提示 - -#### 数据持久化 -- ✅ 使用 localStorage 保存用户配置 -- ✅ 页面刷新后数据不丢失 -- ✅ 支持导入/导出配置(可扩展) - -### 2. 添加快速链接对话框 (AddQuickLinkDialog.vue) - -#### 功能特性 -- ✅ 支持新增和编辑两种模式 -- ✅ 完整的表单验证 -- ✅ 图标选择器(22个常用图标) -- ✅ 颜色自定义选择 -- ✅ 链接类型区分(内部/外部) - -## 使用指南 - -### 访问 Dashboard - -#### 工作台页面 -- **路径**:`/dashboard/workplace` -- **功能**:个人工作台,包含项目概览、动态信息、快速导航等 -- **适用场景**:日常工作的起始页面 - -#### 数据分析页面 -- **路径**:`/dashboard/analysis` -- **功能**:数据统计和分析展示 -- **适用场景**:查看系统数据和业务指标 - -### 快速开始组件使用 - -#### 从标签栏收藏页面 - -**收藏页面:** -1. 在任意页面的标签上右击 -2. 选择"收藏到快速开始" -3. 系统会自动获取路由图标和颜色 -4. 前往工作台查看新添加的链接 - -**取消收藏:** -1. 在已收藏页面的标签上右击 -2. 选择"取消收藏"(图标会显示为实心星星) -3. 链接立即从快速开始列表中移除 - -**自动图标获取:** -- **优先级1**:使用路由 `meta.icon` 配置 -- **优先级2**:根据路径智能匹配预设图标 -- **优先级3**:使用默认链接图标 - -#### 手动添加链接 - -1. 在快速开始组件中点击"添加"按钮 -2. 填写链接信息: - - **标题**:链接显示名称 - - **描述**:链接说明文字 - - **链接地址**:内部路径或外部URL - - **链接类型**:内部链接或外部链接 - - **图标**:从预设图标中选择 - - **颜色**:自定义图标颜色 -3. 点击确定保存 - -#### 管理快速链接 - -**编辑链接:** -1. 在快速开始组件中右击任意链接 -2. 选择"编辑链接" -3. 对话框会自动填充现有的链接信息 -4. 修改需要更改的字段 -5. 点击"确定"保存修改 - -**删除链接:** -1. 在快速开始组件中右击任意链接 -2. 选择"删除链接" -3. 在确认对话框中点击"确定" - -#### 使用快速链接 - -- **内部链接**:点击后在当前窗口跳转 -- **外部链接**:点击后在新标签页打开,带有"外链"标识 - -## 技术架构 - -### 目录结构 - -```text -dashboard/ -├── workplace.vue # 工作台主页面 -├── analysis.vue # 数据分析页面 -├── components/ # 组件库 -│ ├── QuickStart.vue # 快速开始组件 -│ ├── AddQuickLinkDialog.vue # 添加链接对话框 -│ └── index.ts # 组件导出 -└── README.md # 模块文档 -``` - -### 核心技术栈 - -- **Vue 3**: Composition API + ` diff --git a/frontend/src/views/dashboard/components/QuickStart.vue b/frontend/src/views/dashboard/components/QuickStart.vue index fbfc8437..8e8cf7f9 100644 --- a/frontend/src/views/dashboard/components/QuickStart.vue +++ b/frontend/src/views/dashboard/components/QuickStart.vue @@ -2,7 +2,14 @@