simple-admin-fastapi

simple-admin-fastapi 是一个基于 FastAPI 的后台管理系统后端，提供 /api/v1 接口，包含认证、用户、角色、权限、部门、字典、区域、上传等基础管理能力。

项目结构

项目按业务模块划分：

apps/
  core/        # 配置、数据库、安全、异常、日志、依赖注入
  system/      # 系统模块
    api/
    schemas/
    models/
    repositories/
    services/

当前能力

• 应用入口位于 apps/__init__.py
• 公共基础设施位于 apps/core
• 系统模块位于 apps/system
• 系统模块按 api / schemas / models / repositories / services 分层
• 数据库迁移使用 Alembic
• 初始化数据使用 scripts/bootstrap_db.py 和 scripts/seed_data.py
• 主干接口声明 response_model / status_code / summary / description

代码约定

• 顶层按模块组织，模块内按 api / schemas / models / repositories / services 分层
• 路由层只负责参数接收、依赖注入、调用 service、返回响应
• 业务逻辑放在 service
• 数据访问放在 repository
• 共享基础设施放在 apps/core
• 主路由优先使用复数 REST 风格，例如 /users、/roles、/permissions
• 详细命名约定见 docs/naming-guidelines.md

快速开始

安装依赖

# 使用 uv (推荐)
uv sync

初始化数据库

# 执行数据库迁移
uv run alembic upgrade head
# 初始化种子数据
uv run python scripts/seed_data.py

如需重建数据库：

uv run python scripts/bootstrap_db.py --drop

scripts/bootstrap_db.py 用于重建数据库并重新灌入完整基础数据。

启动服务

# 开发模式
uv run python main.py

访问 API 文档：http://127.0.0.1:8000/docs

默认账号：

• 手机号：18675867241
• 密码：123456

开发约定

• 新增业务模块时，沿用 apps/<module>/api|schemas|models|repositories|services 结构
• 新接口优先声明 response_model / status_code / summary / description
• 通用依赖优先复用 apps/core/deps.py
• 业务异常优先使用 apps/core/exceptions.py 中的统一异常入口
• 不再在应用启动时自动建表或灌种子数据；使用 Alembic 和独立 seed 脚本
• 认证相关接口当前使用：
  • /api/v1/auth/login
  • /api/v1/auth/oauth-login
  • /api/v1/auth/refresh
  • /api/v1/auth/change-password

待完善方向

• 管理接口登录鉴权和权限码依赖继续补齐
• Token 过期时间、生产环境密钥、CORS 和未知异常响应继续收紧
• 事务边界继续向 service 层收敛
• Alembic 后续迁移优先使用显式 op.* 操作
• 补 ruff、接口冒烟测试和基础 CI