xiaoxia-saas/README.md

# 小虾 SaaS - 自动化剪辑 SaaS 平台

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.115.0-009688.svg)](https://fastapi.tiangolo.com)
[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-16-336791.svg)](https://www.postgresql.org/)

一个功能完整、生产就绪的多租户 SaaS 平台，专为自动化视频剪辑服务设计。

---

## ✨ 特性

### 🔐 完整的认证系统
- JWT 认证（access + refresh token）
- 邮箱验证和密码重置
- Session 管理
- bcrypt 密码加密

### 🏢 多租户架构
- 工作空间隔离
- 团队成员管理
- 基于角色的权限控制（Owner/Admin/Member/Viewer）
- 邀请和审批流程

### 💳 订阅管理
- 3 级订阅计划（Free/Pro/Enterprise）
- 配额管理（项目数/存储空间）
- 升级和取消订阅

### ⚡ 高性能
- 数据库连接池（5-6x 性能提升）
- 请求日志和监控
- 慢查询检测
- 健康检查（Kubernetes 就绪）

### 📚 完整文档
- API 文档（Swagger/ReDoc）
- 部署指南
- 性能优化指南
- 11+ 篇技术文档

---

## 🚀 快速开始

### 方式 1: Docker（推荐）

```bash
# 1. 克隆仓库
git clone https://github.com/your-org/xiaoxia-saas.git
cd xiaoxia-saas

# 2. 启动所有服务
docker-compose up -d

# 3. 访问 API 文档
open http://localhost:8000/docs
```

就这么简单！🎉

### 方式 2: 本地开发

```bash
# 1. 克隆仓库
git clone https://github.com/your-org/xiaoxia-saas.git
cd xiaoxia-saas

# 2. 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 3. 安装依赖
pip install -r requirements.txt

# 4. 使用内存数据库（无需 PostgreSQL）
echo "USE_IN_MEMORY_DB=true" > .env

# 5. 启动开发服务器
uvicorn apps.api.main:app --reload

# 6. 访问 API 文档
open http://localhost:8000/docs
```

---

## 📖 API 示例

### 注册用户

```bash
curl -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePass123",
    "username": "myuser",
    "display_name": "My Name"
  }'
```

### 登录

```bash
curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePass123"
  }'
```

### 创建工作空间

```bash
curl -X POST http://localhost:8000/api/v1/workspaces \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "我的团队",
    "subscription_plan": "free"
  }'
```

---

## 🏗️ 架构

```
小虾 SaaS
├── packages/              # 核心业务逻辑
│   ├── domain/           # 领域模型
│   ├── application/      # 用例
│   ├── ports/            # 接口定义
│   └── adapters/         # 适配器实现
├── apps/                 # 应用层
│   └── api/             # FastAPI 应用
├── migrations/           # 数据库迁移
├── tests/               # 测试
│   ├── unit/           # 单元测试（170 个）
│   └── integration/    # 集成测试（12 个）
└── docs/                # 文档
```

**设计模式:**
- Clean Architecture
- 依赖注入
- Repository 模式
- Domain-Driven Design

---

## 🔧 配置

### 环境变量

```env
# 数据库切换
USE_IN_MEMORY_DB=true          # 开发环境（无需 PostgreSQL）
USE_IN_MEMORY_DB=false         # 生产环境（使用 PostgreSQL）

# 数据库连接
DATABASE_URL=postgresql://user:pass@localhost:5432/xiaoxia_saas

# JWT 配置
JWT_SECRET_KEY=your-secret-key-at-least-32-chars

# 邮件配置
SMTP_HOST=smtp.gmail.com
SMTP_USER=your-email@gmail.com
SMTP_PASSWORD=your-app-password
```

完整配置参考 `.env.example`

---

## 🧪 测试

```bash
# 运行所有测试
pytest tests/ -v

# 运行单元测试
pytest tests/unit -v

# 生成覆盖率报告
pytest --cov=packages --cov-report=html

# 查看覆盖率
open htmlcov/index.html
```

**测试统计:**
- 单元测试: 170 个 ✅
- 测试覆盖率: 85%+
- 集成测试: 12 个

---

## 📚 文档

- [API 使用指南](docs/API-GUIDE.md)
- [Docker 部署指南](docs/DOCKER-DEPLOYMENT.md)
- [数据库切换指南](docs/DATABASE-SWITCH.md)
- [性能监控指南](docs/PERFORMANCE-MONITORING.md)
- [环境配置指南](docs/ENVIRONMENT-CONFIG.md)
- [健康检查指南](docs/HEALTH-CHECKS.md)
- [分页使用指南](docs/PAGINATION.md)
- [生产部署检查清单](docs/PRODUCTION-CHECKLIST.md)
- [贡献指南](CONTRIBUTING.md)

---

## 🚢 部署

### Kubernetes

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: xiaoxia-api
spec:
  replicas: 3
  template:
    spec:
      containers:
      - name: api
        image: xiaoxia-saas:latest
        ports:
        - containerPort: 8000
        livenessProbe:
          httpGet:
            path: /health
            port: 8000
        readinessProbe:
          httpGet:
            path: /ready
            port: 8000
```

### Docker Compose

```yaml
version: '3.8'
services:
  api:
    build: .
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://...
      - REDIS_URL=redis://...
```

查看 [完整部署指南](docs/DOCKER-DEPLOYMENT.md)

---

## 🎯 技术栈

**后端:**
- Python 3.12
- FastAPI 0.115.0
- Pydantic 2.9
- PostgreSQL 16
- Redis 7

**测试:**
- pytest
- pytest-asyncio
- pytest-cov

**部署:**
- Docker
- Docker Compose
- Kubernetes（可选）

---

## 📊 性能

| 指标 | 数值 |
|------|------|
| API 平均响应时间 | < 50ms |
| 数据库查询时间 | < 10ms |
| 并发支持 | 1000+ RPS |
| 连接池性能提升 | 5-6x |
| 测试覆盖率 | 85%+ |

---

## 🤝 贡献

欢迎贡献！请查看 [贡献指南](CONTRIBUTING.md)

1. Fork 项目
2. 创建分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'feat: Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

---

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情

---

## 📞 联系方式

- **文档:** https://docs.xiaoxia-saas.com
- **问题反馈:** GitHub Issues
- **邮箱:** support@xiaoxia-saas.com

---

## 🎉 致谢

感谢所有贡献者和使用者！

**开发团队:** 小虾 🦐

---

**⭐ 如果这个项目对你有帮助，请给一个 Star！**