SmileX 项目

SmileX 是一个基于 FastAPI 和 Vue 的全栈云服务平台，提供完整的前后端解决方案，支持用户认证、权限管理、系统配置等核心功能。

项目结构

本项目采用前后端分离架构，后端代码位于 backend 目录，前端代码位于 frontend 目录。

SmileX-Fastapi-Cloud/
├── backend/            # 后端代码
│   ├── app/            # 应用核心模块
│   ├── config/         # 配置文件
│   ├── core/           # 核心功能模块
│   ├── database/       # 数据库相关
│   ├── modules/        # 业务模块
│   ├── scripts/        # 脚本工具
│   ├── main.py         # 后端入口文件
│   └── pyproject.toml  # 项目依赖配置
├── frontend/           # 前端代码
│   ├── packages/       # 前端包
│   ├── public/         # 静态资源
│   ├── src/            # 前端源码
│   ├── index.html      # 前端入口文件
│   └── package.json    # 前端依赖配置
└── README.md           # 项目说明文档

技术栈

后端

• 框架: FastAPI
• 语言: Python
• 包管理: uv
• 数据库: PostgreSQL (使用 SQLAlchemy ORM)
• 缓存: Redis
• 认证: JWT
• 数据库迁移: Alembic
• 日志: 自定义日志系统

前端

• 框架: Vue 3
• 语言: TypeScript
• 构建工具: Vite
• 包管理: pnpm
• 状态管理: Pinia
• UI 库: Naive UI
• 路由: Vue Router
• CSS 框架: UnoCSS
• 国际化: i18n

快速开始

后端环境搭建

1. 进入后端目录

   cd backend

2. 激活虚拟环境

   ./venv/Scripts/activate.bat

3. 安装依赖

   uv add

4. 配置环境变量 复制 .env.dev 文件为 .env 并修改相关配置

5. 数据库迁移

   alembic upgrade head

6. 创建超级用户

   python scripts/create_superuser.py

7. 启动后端服务

   python main.py

前端环境搭建

1. 进入前端目录

   cd frontend

2. 安装依赖

   pnpm install

3. 配置环境变量 复制 .env 文件为 .env.local 并修改相关配置

4. 启动前端开发服务器

   pnpm dev

核心功能

后端核心功能

• 用户认证与授权: 基于 JWT 的认证系统，支持角色权限管理
• 系统配置管理: 可配置系统参数，支持多环境配置
• 数据字典管理: 统一管理系统中的数据字典
• 菜单管理: 动态生成系统菜单，支持权限控制
• 角色管理: 基于角色的权限控制系统
• 用户管理: 完整的用户CRUD操作，支持用户状态管理
• 日志系统: 完整的日志记录与管理
• 缓存系统: 基于Redis的缓存实现

前端核心功能

• 响应式布局: 适配不同屏幕尺寸
• 主题系统: 支持多种主题切换
• 国际化: 支持中英文切换
• 菜单管理: 动态生成菜单，支持多级菜单
• 权限控制: 基于后端权限的前端路由控制
• 数据可视化: 集成ECharts实现数据图表
• 表单验证: 完整的表单验证系统
• 文件上传: 支持文件上传功能

开发指南

后端开发

1. 模块划分: 后端按照功能模块划分，每个模块有独立的目录结构
2. 数据库模型: 数据库模型定义在 app/models 目录下
3. API 路由: API 路由定义在 modules 目录下的对应模块中
4. 业务逻辑: 业务逻辑封装在 services 目录下
5. 配置管理: 配置文件位于 config 目录下，支持多环境配置

前端开发

1. 页面划分: 前端按照页面划分，每个页面有独立的目录结构
2. 组件开发: 公共组件位于 components 目录下
3. 路由配置: 路由配置位于 router 目录下
4. 状态管理: 状态管理使用 Pinia，定义在 store 目录下
5. API 调用: API 调用封装在 service 目录下

部署指南

后端部署

1. 环境配置: 确保服务器安装了 Python 3.9+
2. 依赖安装: 使用 uv 安装依赖
3. 环境变量: 配置生产环境的 .env 文件
4. 数据库迁移: 执行数据库迁移
5. 服务启动: 使用 Gunicorn 或 Uvicorn 启动服务

前端部署

1. 构建: 执行 pnpm build 命令构建前端代码
2. 静态文件: 将构建后的静态文件部署到 Nginx 或其他静态文件服务器
3. 配置: 配置 Nginx 代理后端 API 请求

项目配置

后端配置

后端配置文件位于 backend/config 目录下，主要配置文件包括：

• logging_dev.ini: 开发环境日志配置
• logging_prod.ini: 生产环境日志配置

环境变量配置文件包括：

• .env.dev: 开发环境变量
• .env.prod: 生产环境变量
• .env.test: 测试环境变量

前端配置

前端配置文件包括：

• .env: 基础环境变量
• .env.prod: 生产环境变量
• .env.test: 测试环境变量

开发规范

后端开发规范

1. 代码风格: 遵循 PEP 8 代码风格
2. 命名规范:
   • 类名使用大驼峰命名法
   • 函数名使用小写字母加下划线
   • 变量名使用小写字母加下划线
3. 注释规范: 为函数和类添加详细的注释
4. 错误处理: 对异常进行捕获和处理
5. 日志记录: 关键操作添加日志记录

前端开发规范

1. 代码风格: 遵循 ESLint 代码风格
2. 命名规范:
   • 组件名使用大驼峰命名法
   • 变量名使用小驼峰命名法
   • 常量名使用全大写加下划线
3. 注释规范: 为组件和关键函数添加注释
4. 错误处理: 对异步操作和 API 调用进行错误处理
5. 性能优化: 合理使用计算属性和监听器，避免不必要的渲染

许可证

本项目采用 MIT 许可证，详见 LICENSE 文件。

贡献指南

欢迎贡献代码，提交 Issue 和 Pull Request。

提交代码流程

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 打开 Pull Request

联系方式

• 项目地址: https://github.com/SmileX/SmileX-Fastapi-Cloud
• 问题反馈: https://github.com/SmileX/SmileX-Fastapi-Cloud/issues

---

SmileX - 让云服务更简单，让开发更高效！