hd-crane-gs/backend/docs/业务逻辑.md

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 分层架构：

📦 分层架构 (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的声明式模型
• 支持模型继承与混入
• 兼容多数据库平台