public/FastapiAdmin
1
0
Fork 0
mirror of https://github.com/fastapiadmin/FastapiAdmin.git synced 2026-09-20 20:39:55 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: Add role code to system_role.json and update system_users.json creator_id to null

Browse Source 
fix: Refactor initialize.py to handle nested children data during initialization

feat: Implement tree structure traversal functions in common_util.py

chore: Update requirements.txt to specify sqlalchemy-crud-plus version and add rich

refactor: Change API endpoints in dept.ts and menu.ts to return tree structure

feat: Add code field to role, dept, and menu interfaces in respective TypeScript files

fix: Update dept and role Vue components to display and handle code field

docs: Add comprehensive project documentation for FastAPI Vue3 Admin
This commit is contained in:
zhangtao
2025-09-15 00:19:11 +08:00
parent 1f7c934e41
commit e159b31e62
47 changed files with 2543 additions and 2206 deletions
Download Patch File Download Diff File Expand all files Collapse all files
fastdocs/src/PROJECT_DOCUMENTATION.md
+403
View File
@@ -0,0 +1,403 @@
# FastAPI Vue3 Admin 项目详细说明文档
<div align="center">
<h1>FastAPI Vue3 Admin</h1>
<h3>现代化全栈中后台管理系统</h3>
<p>基于 FastAPI + Vue3 + TypeScript + Element Plus 的企业级后台管理解决方案</p>
</div>
## 📋 目录
- [项目概述](#项目概述)
- [技术架构](#技术架构)
- [功能特性](#功能特性)
- [项目结构](#项目结构)
- [核心模块](#核心模块)
- [技术栈详解](#技术栈详解)
- [环境要求](#环境要求)
- [快速开始](#快速开始)
- [部署指南](#部署指南)
- [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) 许可证开源。