# 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的声明式模型
- 支持模型继承与混入
- 兼容多数据库平台