# 小虾 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 平台，专为自动化视频剪辑服务设计。

---

## ✨ 核心特性

### 🎬 视频剪辑主链路（Phase 7 已完成）
- 素材上传与管理
- AI 智能分类
- 自动化视频生成
- 成片下载与管理

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

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

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

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

---

## 🚀 快速开始

### 方式 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. 启动开发服务器
uvicorn apps.api.main:app --reload

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

---

## 📚 主要文档

### 快速入口
- **[API 主线清单](docs/API-MAINLINE.md)** - 所有 API endpoints 总览
- **[代码状态标注](docs/CODE-STATUS.md)** - 代码库导航指南
- **[API 使用指南](docs/API-GUIDE.md)** - API 详细用法

### Phase 7 交付
- **[Phase 7 进度](docs/PHASE7-PROGRESS.md)** - 核心视频剪辑业务已完成
- **[Phase 7 设计](docs/PHASE7-DESIGN.md)** - 设计文档

### 基础设施
- **[Docker 部署指南](docs/DOCKER-DEPLOYMENT.md)**
- **[CI/CD 文档](docs/CI-CD.md)**
- **[性能监控指南](docs/PERFORMANCE-MONITORING.md)**
- **[健康检查指南](docs/HEALTH-CHECKS.md)**

### 开发规范
- **[Git 工作流](docs/GIT-WORKFLOW.md)**
- **[环境配置指南](docs/ENVIRONMENT-CONFIG.md)**
- **[贡献指南](CONTRIBUTING.md)**

---

## 🏗️ 架构

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

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

---

## 🔑 核心 API 路径

### 视频剪辑主链路（Phase 7）

```
上传素材
  ↓
POST /api/v1/upload

创建 Asset
  ↓
POST /api/v1/assets

发起分类
  ↓
POST /api/v1/classification-jobs

创建生成任务
  ↓
POST /api/v1/generation/tasks

查询生成结果
  ↓
GET /api/v1/generation/tasks/{task_id}/results

获取下载链接
  ↓
GET /api/v1/generated-videos/{video_id}/download-url
```

完整 API 列表请查看 [API 主线清单](docs/API-MAINLINE.md)

---

## 🧪 测试

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

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

# 运行集成测试
pytest tests/integration -v

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

**测试统计:**
- 单元测试: 17+ 个 ✅
- 集成测试: 6+ 个 ✅
- 测试覆盖率: 持续提升中

---

## 🛠️ 技术栈

**后端:**
- Python 3.12
- FastAPI 0.115.0
- PostgreSQL 16
- Redis 7
- Celery
- MinIO

**前端:**
- React 18
- TypeScript
- Vite
- Ant Design

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

**部署:**
- Docker
- Docker Compose
- Gitea Actions

---

## 📊 当前状态

| 模块 | 状态 |
|------|------|
| Phase 7（视频剪辑主链） | ✅ 已完成 |
| CI/CD 稳定性 | ✅ 已修复 |
| 认证系统 | ✅ 完整 |
| 多租户架构 | ✅ 完整 |
| 订阅系统 | ✅ 完整 |
| 前端联调 | ✅ 完成 |

---

## 🤝 贡献

欢迎贡献！请查看 [贡献指南](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) 文件了解详情

---

## 📞 联系方式

- **问题反馈:** GitHub Issues
- **文档:** 参考 `docs/` 目录

---

## 🎉 致谢

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

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

---

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

---

**最后更新**: 2026-06-19  
**当前版本**: Phase 7 完成
ci test Fri Jun 26 06:59:37 PM CST 2026
debug test Fri Jun 26 07:05:38 PM CST 2026
docker daemon restart test
19:08:39 - final test
19:10:17 - new runner test