Metadata-Version: 2.4
Name: nova-admin
Version: 1.0.0
Summary: Enterprise-level FastAPI admin framework with SQLModel and Starlette Admin
Project-URL: Homepage, https://gitee.com/xyoc/nova-admin
Project-URL: Documentation, https://gitee.com/xyoc/nova-admin#readme
Project-URL: Repository, https://gitee.com/xyoc/nova-admin
Project-URL: Issues, https://gitee.com/xyoc/nova-admin/issues
Project-URL: Source, https://gitee.com/xyoc/nova-admin
Author-email: "william.ren" <william.ren@petalmail.com>
License: Apache-2.0
License-File: LICENSE
Keywords: admin,dashboard,fastapi,rbac,report,sqlmodel,starlette,workflow
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: aiofiles>=23.0.0
Requires-Dist: alembic>=1.12.0
Requires-Dist: authlib>=1.2.0
Requires-Dist: fastapi-users[jwt,oauth,sqlalchemy]<16.0.0,>=13.0.0
Requires-Dist: fastapi>=0.100.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: loguru>=0.7.0
Requires-Dist: passlib[bcrypt]>=1.7.4
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pyotp>=2.9.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: python-jose[cryptography]>=3.3.0
Requires-Dist: python-multipart>=0.0.6
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: qrcode>=7.4.0
Requires-Dist: scalar-fastapi>=1.0.0
Requires-Dist: sqlalchemy[asyncio]>=2.0.0
Requires-Dist: sqlmodel>=0.0.14
Requires-Dist: starlette-admin<0.17.0,>=0.14.0
Requires-Dist: user-agents>=2.2.0
Provides-Extra: all
Requires-Dist: aiomysql>=0.2.0; extra == 'all'
Requires-Dist: aiosmtplib>=3.0.0; extra == 'all'
Requires-Dist: asyncpg>=0.28.0; extra == 'all'
Requires-Dist: email-validator>=2.1.0; extra == 'all'
Requires-Dist: grpcio>=1.60.0; extra == 'all'
Requires-Dist: openpyxl>=3.1.0; extra == 'all'
Requires-Dist: protobuf>=4.25.0; extra == 'all'
Requires-Dist: psutil>=5.9.0; extra == 'all'
Requires-Dist: psycopg2-binary>=2.9.0; extra == 'all'
Requires-Dist: pymysql>=1.1.0; extra == 'all'
Requires-Dist: python3-saml>=1.16.0; extra == 'all'
Requires-Dist: redis>=5.0.0; extra == 'all'
Requires-Dist: reportlab>=4.0.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: coverage>=7.3.0; extra == 'dev'
Requires-Dist: httpx>=0.24.0; extra == 'dev'
Requires-Dist: isort>=5.12.0; extra == 'dev'
Requires-Dist: mypy>=1.5.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.0.290; extra == 'dev'
Provides-Extra: email
Requires-Dist: aiosmtplib>=3.0.0; extra == 'email'
Requires-Dist: email-validator>=2.1.0; extra == 'email'
Provides-Extra: excel
Requires-Dist: openpyxl>=3.1.0; extra == 'excel'
Provides-Extra: grafana
Requires-Dist: psutil>=5.9.0; extra == 'grafana'
Provides-Extra: grpc
Requires-Dist: grpcio>=1.60.0; extra == 'grpc'
Requires-Dist: protobuf>=4.25.0; extra == 'grpc'
Provides-Extra: mysql
Requires-Dist: aiomysql>=0.2.0; extra == 'mysql'
Requires-Dist: pymysql>=1.1.0; extra == 'mysql'
Provides-Extra: pdf
Requires-Dist: reportlab>=4.0.0; extra == 'pdf'
Provides-Extra: postgres
Requires-Dist: asyncpg>=0.28.0; extra == 'postgres'
Requires-Dist: psycopg2-binary>=2.9.0; extra == 'postgres'
Provides-Extra: redis
Requires-Dist: redis>=5.0.0; extra == 'redis'
Provides-Extra: saml
Requires-Dist: python3-saml>=1.16.0; extra == 'saml'
Description-Content-Type: text/markdown

# Nova Admin

<div align="center">

**🏗️ 企业级 FastAPI 后台管理框架**

基于 FastAPI + SQLModel + Starlette Admin 构建，集成权限、多租户、工作流、报表、API 网关等全套企业级功能的一站式后台解决方案。

[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.100+-green.svg)](https://fastapi.tiangolo.com/)
[![SQLModel](https://img.shields.io/badge/SQLModel-0.14+-orange.svg)](https://sqlmodel.tiangolo.com/)
[![code style](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)

</div>

---

## 📋 项目状态

| Phase | 版本 | 状态 |
|-------|------|------|
| Phase 1: MVP | v0.1.0 | ✅ 已完成 |
| Phase 2: 进阶功能 | v0.5.0 | ✅ 已完成 |
| Phase 2.5: 用户认证增强 | v0.6.6 | ✅ 已完成 |
| **Phase 3: 功能完善** | **v1.0.0** | **✅ 100% 完成** |

---

## 🚀 核心特性

### 基础能力
- 🚀 **异步高性能** — 基于 FastAPI 原生异步支持
- 🔐 **RBAC 权限系统** — 用户-角色-权限三级模型，支持行级数据权限
- 🏢 **多租户支持** — 字段隔离策略，自动租户过滤
- 📝 **灵活 CRUD** — 物理删除/逻辑删除切换，乐观锁并发控制
- 🔒 **安全防护** — SQL 注入检测、XSS 防护、限流保护
- 🌍 **国际化 (i18n)** — 内置多语言支持，可扩展翻译管理

### 进阶功能
- 🎨 **主题系统** — 支持多主题切换（亮色/暗色），CSS 变量，自定义主题
- 🔌 **插件系统** — 插件生命周期管理，钩子系统，插件配置
- 📊 **Dashboard 组件** — 统计卡片、折线图、柱状图、饼图、表格组件的可视化看板
- 📈 **报表系统** — 5 类报表（业务/系统/财务/运营/自定义），8 种图表类型，定时报表，多维分析
- ⚙️ **工作流引擎** — 审批流（或签/会签/依次审批），条件分支，抄送，驳回/退回，任务分配
- 📁 **文件管理** — 完整的上传、下载、存储、预览功能
- 📋 **数据导入导出** — CSV/Excel/JSON 双向导入导出

### 微服务&部署
- 🌐 **API 网关** — 动态路由、熔断器（CLOSED→OPEN→HALF_OPEN）、负载均衡（轮询/加权/一致性Hash）、API 版本管理
- 🔍 **服务注册与发现** — 内存/Consul/DNS 后端，心跳检测，标签过滤
- ⚙️ **配置中心** — YAML/JSON 热加载，环境变量覆盖，命名空间隔离
- 🔗 **分布式追踪** — W3C Trace Context 传播，Span 嵌套，Jaeger/Zipkin 导出
- 🐳 **容器化部署** — Docker 镜像、Docker Compose 微服务编排、Kubernetes 配置（含 HPA）
- 📋 **CI/CD 流水线** — GitHub Actions：测试（3 个 Python 版本）、Lint、Build、PyPI 发布、Docker 镜像

---

## 🛠️ 技术栈

| 组件 | 技术 | 说明 |
|------|------|------|
| **Web 框架** | FastAPI | 高性能异步 Web 框架，自动 OpenAPI 文档 |
| **ORM** | SQLModel | Pydantic + SQLAlchemy 合体，类型安全 |
| **数据库迁移** | Alembic | SQLAlchemy 官方迁移工具 |
| **Admin UI** | Starlette Admin | 多 ORM 支持，Tabler UI 界面 |
| **API 文档** | Scalar | 现代化 API 文档 UI |
| **日志** | Loguru | 开箱即用，比 logging 友好 |
| **配置管理** | Pydantic Settings | 类型安全，多环境支持 |
| **缓存** | Redis / InMemory | 可插拔缓存后端 |
| **依赖管理** | UV | Rust 编写的极速包管理器 |

---

## 📦 安装

```bash
# 使用 UV 安装
uv pip install nova-admin

# 或使用 pip
pip install nova-admin

# 安装可选依赖
pip install "nova-admin[postgres]"    # PostgreSQL 支持
pip install "nova-admin[mysql]"       # MySQL 支持
pip install "nova-admin[redis]"       # Redis 缓存支持
pip install "nova-admin[all]"         # 全部功能
```

---

## 🚀 快速开始

### 最简示例

```python
from fastapi import FastAPI
from sqlmodel import SQLModel, Field, create_engine
from nova_admin import Admin, ModelView

class User(SQLModel, table=True):
    id: int = Field(default=None, primary_key=True)
    username: str
    email: str

app = FastAPI()
engine = create_engine("sqlite:///./app.db")

admin = Admin(engine, title="Nova Admin")
admin.add_view(ModelView(User))
admin.mount_to(app)

# 访问 http://localhost:8000/admin
```

### CRUD API 快速生成

```python
from fastapi import FastAPI
from nova_admin.api.crud_api import create_crud_router

app = FastAPI()

# 一行代码为任意 Model 生成完整 CRUD 路由
# app.include_router(create_crud_router(User, prefix="/api/users"))
```

### 完整示例

```bash
cd examples/complete_demo
python main.py
# 默认账号: admin / admin123
# API: http://localhost:8000/docs
# Admin: http://localhost:8000/admin
```

---

## 📚 文档

| 文档 | 说明 |
|------|------|
| [项目概述](docs/01-project-overview.md) | 项目介绍和功能概览 |
| [技术可行性分析](docs/02-technical-analysis.md) | 技术选型和可行性评估 |
| [架构设计](docs/03-architecture.md) | 系统架构和模块设计 |
| [RBAC 权限系统](docs/04-rbac-permission.md) | 权限模型和使用方法 |
| [多租户设计](docs/05-multi-tenant.md) | 多租户实现方案 |
| [CRUD 基类](docs/06-crud-base.md) | CRUD 操作封装与高级用法 |
| [开发计划](docs/07-development-plan.md) | 开发进度和里程碑 |
| [认证系统完善方案](docs/08-authentication-enhancement.md) | 认证增强详细方案 |
| [认证使用指南](docs/AUTHENTICATION-GUIDE.md) | 认证系统快速上手指南 |

---

## 📁 项目结构

```
nova-admin/
├── nova_admin/                    # 核心代码包
│   ├── core/                      # 核心模块
│   │   ├── config.py              # 配置管理
│   │   ├── database.py            # 数据库连接
│   │   ├── database_multi.py      # 多数据库支持
│   │   ├── logging.py             # 日志配置
│   │   ├── security.py            # 安全认证
│   │   ├── security_audit.py      # 安全审计
│   │   ├── auth_manager.py        # 认证管理器
│   │   └── response.py            # 统一响应
│   ├── models/                    # 数据模型
│   │   ├── base.py                # 基础模型 Mixin
│   │   ├── system.py              # 系统模型
│   │   ├── auth.py                # 认证模型
│   │   ├── workflow.py            # 工作流模型
│   │   └── report.py              # 报表模型
│   ├── admin/                     # Admin 模块
│   │   ├── base.py                # Admin 基类
│   │   ├── views.py               # ModelView 视图
│   │   ├── auth.py                # Admin 认证
│   │   └── data_permission.py     # 行级权限
│   ├── api/                       # API 路由
│   │   ├── auth.py                # 认证 API
│   │   ├── oauth.py               # OAuth2.0 API
│   │   ├── chinese_oauth.py       # 国内平台 OAuth
│   │   ├── saml.py                # SAML 2.0 API
│   │   ├── audit.py               # 审计日志 API
│   │   ├── crud_api.py            # 高级 CRUD API
│   │   ├── workflow_api.py        # 工作流 API
│   │   └── report_api.py          # 报表 API
│   ├── crud/                      # CRUD 服务层
│   │   ├── base.py                # CRUD 基类
│   │   └── tenant_aware.py        # 多租户 CRUD
│   ├── services/                  # 业务服务
│   │   ├── email_service.py       # 邮件服务
│   │   ├── token_manager.py       # Token 管理
│   │   ├── permission_service.py  # 权限服务
│   │   ├── two_factor_service.py  # 双因素认证
│   │   ├── login_security_service.py  # 登录安全
│   │   ├── oauth_service.py       # OAuth2.0 服务
│   │   ├── saml_service.py        # SAML 服务
│   │   ├── audit_log_service.py   # 审计日志
│   │   ├── advanced_crud_service.py  # 高级 CRUD 服务
│   │   ├── workflow_service.py    # 工作流引擎
│   │   └── report_service.py      # 报表引擎
│   ├── extensions/                # 扩展模块
│   │   ├── permission_service.py  # 权限服务
│   │   ├── tenant_middleware.py   # 租户中间件
│   │   ├── audit_log.py           # 审计日志
│   │   ├── file_upload.py         # 文件上传
│   │   ├── data_io.py             # 数据导入导出
│   │   ├── quota_service.py       # 配额管理
│   │   ├── cache.py               # 缓存管理
│   │   ├── rate_limiter.py        # 限流保护
│   │   ├── plugin_system.py       # 插件系统
│   │   ├── theme_system.py        # 主题系统
│   │   ├── dashboard.py           # Dashboard 组件
│   │   ├── i18n.py                # 国际化
│   │   ├── api_gateway.py         # API 网关
│   │   ├── healthcheck.py         # 健康检查
│   │   ├── service_registry.py    # 服务注册与发现
│   │   ├── config_center.py       # 配置中心
│   │   └── distributed_tracing.py # 分布式追踪
│   └── cli/                       # CLI 工具
│       ├── generator.py           # 代码生成器
│       └── commands.py            # CLI 命令
├── examples/                      # 示例项目
│   ├── basic/                     # 基础示例
│   └── complete_demo/             # 完整示例
├── deploy/                        # 部署配置
│   └── k8s-nova-admin.yaml        # Kubernetes 部署
├── .github/workflows/
│   └── ci-cd.yml                  # CI/CD 流水线
├── docs/                          # 文档
├── tests/                         # 测试
├── alembic/                       # 数据库迁移
├── Dockerfile                     # 多阶段构建
├── docker-compose.yml             # 微服务编排
└── pyproject.toml                 # 项目配置
```

---

## 🐳 Docker 部署

```bash
# 使用 Docker Compose（PostgreSQL + Redis + API Gateway + Auth + Worker）
docker-compose up -d

# 仅构建并运行单个服务
docker build -t nova-admin .
docker run -p 8000:8000 nova-admin

# Kubernetes 部署
kubectl apply -f deploy/k8s-nova-admin.yaml
```

---

## 🔨 CLI 工具

```bash
# 创建新模块
nova-admin generate model Product --fields name:str,price:float,stock:int

# 从数据库反向生成
nova-admin generate from-db --table products --model Product

# 运行迁移
nova-admin migrate --autogenerate -m "Add product table"
```

---

## 🤝 贡献

欢迎提交 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

---

## 📄 许可证

本项目采用 [Apache 2.0 License](LICENSE) 开源协议。

---

<div align="center">

Made with ❤️ by william.ren

</div>
