upload project source code
This commit is contained in:
278
后端源码/yifan.action-ai.cn/api/docs/业务逻辑.md
Normal file
278
后端源码/yifan.action-ai.cn/api/docs/业务逻辑.md
Normal file
@@ -0,0 +1,278 @@
|
||||
# FastAPI Admin 业务逻辑
|
||||
|
||||
## 1. 项目概述
|
||||
|
||||
FastAPI Admin 是一个基于 FastAPI 构建的企业级后台管理系统框架，提供完整的 RBAC 权限控制体系、多租户架构支持、任务调度系统和日志监控功能。
|
||||
|
||||
## 2. 技术架构
|
||||
|
||||
### 2.1 核心技术栈
|
||||
|
||||
| 技术 | 版本 | 说明 |
|
||||
|------|------|------|
|
||||
| FastAPI | 0.115.2 | 现代 Web 框架 |
|
||||
| SQLAlchemy | 2.0.36 | ORM 框架 |
|
||||
| Alembic | 1.15.1 | 数据库迁移工具 |
|
||||
| Pydantic | 2.x | 数据验证与序列化 |
|
||||
| APScheduler | 3.11.0 | 定时任务调度 |
|
||||
| Redis | 5.2.1 | 缓存与会话存储 |
|
||||
| Uvicorn | 0.30.6 | ASGI 服务器 |
|
||||
| Python | 3.10+ | 运行环境 |
|
||||
|
||||
### 2.2 多数据库支持
|
||||
|
||||
- MySQL
|
||||
- PostgreSQL
|
||||
- SQLite
|
||||
|
||||
### 2.3 架构设计
|
||||
|
||||
采用经典的 MVC 分层架构：
|
||||
|
||||
```sh
|
||||
📦 分层架构 (MVC)
|
||||
├── 🎯 Controller # 控制器层 - 处理HTTP请求
|
||||
├── 🏢 Service # 业务层 - 核心业务逻辑
|
||||
├── 💾 CRUD # 数据访问层 - 数据库操作
|
||||
└── 📊 Model # 模型层 - 数据模型定义
|
||||
```
|
||||
|
||||
## 3. 核心业务模块
|
||||
|
||||
### 3.1 系统管理模块 (module_system)
|
||||
|
||||
#### 3.1.1 用户管理
|
||||
|
||||
- 支持不同类型用户：系统用户、租户管理员、租户普通用户、客户用户
|
||||
- 实现用户与角色、岗位的多对多关联
|
||||
- 提供用户状态管理、密码重置等功能
|
||||
|
||||
#### 3.1.2 角色管理
|
||||
|
||||
- 完整的 RBAC 权限体系
|
||||
- 支持菜单权限和数据权限双重控制
|
||||
- 自定义数据权限范围设置
|
||||
|
||||
#### 3.1.3 菜单管理
|
||||
|
||||
- 树形菜单结构设计
|
||||
- 支持目录、菜单、按钮/权限三种类型
|
||||
- 系统级菜单与租户级菜单隔离
|
||||
|
||||
#### 3.1.4 部门管理
|
||||
|
||||
- 树形部门结构
|
||||
- 支持无限层级嵌套
|
||||
- 部门负责人设置
|
||||
|
||||
#### 3.1.5 租户管理
|
||||
|
||||
- 多租户 SaaS 架构
|
||||
- 租户数据完全隔离
|
||||
- 系统租户管理所有普通租户
|
||||
|
||||
#### 3.1.6 客户管理
|
||||
|
||||
- 租户内部的二级业务单元
|
||||
- 客户数据隔离
|
||||
- 客户用户权限控制
|
||||
|
||||
### 3.2 系统监控模块 (module_monitor)
|
||||
|
||||
- 操作日志记录与查询
|
||||
- 系统资源监控
|
||||
- 性能指标统计
|
||||
|
||||
### 3.3 AI 功能模块 (module_ai)
|
||||
|
||||
- OpenAI 大模型集成
|
||||
- AI 辅助功能
|
||||
|
||||
### 3.4 定时任务模块 (module_task)
|
||||
|
||||
- 基于 APScheduler 的任务调度
|
||||
- 支持多种任务类型
|
||||
- 任务执行日志记录
|
||||
|
||||
## 4. 数据模型与关系
|
||||
|
||||
### 4.1 核心数据模型
|
||||
|
||||
#### 4.1.1 UserModel (用户模型)
|
||||
|
||||
- 表名：`sys_user`
|
||||
- 关键字段：
|
||||
- username: 用户名/登录账号
|
||||
- name: 昵称
|
||||
- user_type: 用户类型(0:系统用户 1:租户用户 2:客户用户)
|
||||
- dept_id: 所属部门
|
||||
|
||||
#### 4.1.2 RoleModel (角色模型)
|
||||
|
||||
- 表名：`sys_role`
|
||||
- 关键字段：
|
||||
- name: 角色名称
|
||||
- code: 角色编码
|
||||
- data_scope: 数据权限范围(1:仅本人 2:本部门 3:本部门及以下 4:全部 5:自定义)
|
||||
|
||||
#### 4.1.3 MenuModel (菜单模型)
|
||||
|
||||
- 表名：`sys_menu`
|
||||
- 关键字段：
|
||||
- name: 菜单名称
|
||||
- type: 菜单类型(1:目录 2:菜单 3:按钮/权限 4:链接)
|
||||
- permission: 权限标识
|
||||
- route_path: 路由路径
|
||||
- parent_id: 父菜单ID
|
||||
|
||||
#### 4.1.4 DeptModel (部门模型)
|
||||
|
||||
- 表名：`sys_dept`
|
||||
- 关键字段：
|
||||
- name: 部门名称
|
||||
- code: 部门编码
|
||||
- leader: 部门负责人
|
||||
- parent_id: 父级部门ID
|
||||
|
||||
### 4.2 关联关系表
|
||||
|
||||
#### 4.2.1 UserRolesModel (用户角色关联)
|
||||
|
||||
- 表名：`sys_user_roles`
|
||||
- 关键字段：user_id, role_id
|
||||
|
||||
#### 4.2.2 RoleMenusModel (角色菜单关联)
|
||||
|
||||
- 表名：`sys_role_menus`
|
||||
- 关键字段：role_id, menu_id
|
||||
|
||||
#### 4.2.3 RoleDeptsModel (角色部门关联)
|
||||
|
||||
- 表名：`sys_role_depts`
|
||||
- 关键字段：role_id, dept_id
|
||||
|
||||
#### 4.2.4 UserPositionsModel (用户岗位关联)
|
||||
|
||||
- 表名：`sys_user_positions`
|
||||
- 关键字段：user_id, position_id
|
||||
|
||||
## 5. 数据隔离与权限体系
|
||||
|
||||
### 5.2 数据权限机制
|
||||
|
||||
#### 5.2.1 权限范围定义
|
||||
|
||||
- 1(仅本人): `WHERE created_id = current_user.id`
|
||||
- 2(本部门): `WHERE user.dept_id = current_user.dept_id`
|
||||
- 3(本部门及以下):
|
||||
- 4(全部数据):
|
||||
- 5(自定义): `WHERE dept_id IN (SELECT dept_id FROM role_depts WHERE role_id IN current_user.role_ids)`
|
||||
|
||||
#### 5.2.2 权限叠加规则
|
||||
|
||||
- 一个用户可以有多个角色
|
||||
- 取所有角色data_scope的最大值(4>3>2>5>1)
|
||||
- 5(自定义)需要合并所有角色关联的部门
|
||||
|
||||
## 6. 核心业务流程
|
||||
|
||||
### 6.1 用户登录流程
|
||||
|
||||
1. 用户提交用户名密码
|
||||
2. 系统验证用户凭据
|
||||
3. 加载用户角色和权限信息
|
||||
4. 生成JWT Token
|
||||
5. 返回用户信息和权限列表
|
||||
|
||||
### 6.2 权限验证流程
|
||||
|
||||
1. 用户请求受保护的API接口
|
||||
2. 中间件验证JWT Token
|
||||
3. 加载用户权限列表
|
||||
4. 验证用户是否拥有该接口的权限
|
||||
5. 根据数据权限过滤查询结果
|
||||
|
||||
### 6.3 数据权限过滤流程
|
||||
|
||||
1. 获取当前用户角色的data_scope
|
||||
2. 根据data_scope构建SQL过滤条件
|
||||
3. 将过滤条件应用到数据库查询
|
||||
4. 返回符合权限要求的数据
|
||||
|
||||
## 7. 特色功能
|
||||
|
||||
### 7.1 智能代码生成
|
||||
|
||||
- 基于模板的代码生成工具
|
||||
- 支持模型、CRUD、API接口等自动生成
|
||||
- 提高开发效率
|
||||
|
||||
### 7.2 AI 集成
|
||||
|
||||
- OpenAI 大模型调用接口
|
||||
- 支持在管理系统中集成AI功能
|
||||
|
||||
### 7.3 云存储支持
|
||||
|
||||
- 阿里云 OSS 对象存储集成
|
||||
- 支持文件上传、下载、管理
|
||||
|
||||
### 7.4 任务调度系统
|
||||
|
||||
- 基于APScheduler的定时任务
|
||||
- 支持多种调度策略
|
||||
- 任务执行状态监控
|
||||
|
||||
## 8. 系统安全
|
||||
|
||||
### 8.1 认证与授权
|
||||
|
||||
- JWT Token认证
|
||||
- 细粒度的RBAC权限控制
|
||||
- 密码加密存储(bcrypt)
|
||||
|
||||
### 8.2 数据安全
|
||||
|
||||
- 多级别数据隔离
|
||||
- 操作日志记录
|
||||
- 敏感数据加密存储
|
||||
|
||||
### 8.3 接口安全
|
||||
|
||||
- 请求参数验证(Pydantic)
|
||||
- 接口限流保护
|
||||
- CORS配置管理
|
||||
|
||||
## 9. 部署与维护
|
||||
|
||||
### 9.1 环境要求
|
||||
|
||||
- Python 3.10+
|
||||
- 数据库: MySQL 8.0+ / PostgreSQL 13+ / SQLite 3.x
|
||||
- Redis 6.0+
|
||||
|
||||
### 9.2 数据库迁移
|
||||
|
||||
- 使用Alembic管理数据库版本
|
||||
- 支持多数据库平台迁移
|
||||
- 提供初始化脚本
|
||||
|
||||
### 9.3 日志系统
|
||||
|
||||
- 操作日志记录
|
||||
- 系统日志监控
|
||||
- 异常记录与告警
|
||||
|
||||
## 10. 扩展开发
|
||||
|
||||
### 10.1 模块扩展
|
||||
|
||||
- 标准化的模块开发流程
|
||||
- 支持自定义业务模块
|
||||
- 插件化架构设计
|
||||
|
||||
### 10.2 数据模型扩展
|
||||
|
||||
- 基于SQLAlchemy 2.0的声明式模型
|
||||
- 支持模型继承与混入
|
||||
- 兼容多数据库平台
|
||||
Reference in New Issue
Block a user