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

[![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 平台，支持素材上传、AI 分类、智能剪辑计划生成、自动化视频合成与成片管理。

---

## ✨ 核心功能

### 🎬 视频剪辑主链路
- 素材上传（直传 OSS + 分片上传大文件，最大 2GB）
- AI 智能分类与质量评分
- 4 种剪辑模式：one_take / pip（画中画）/ voice_over（口播+B-roll）/ voice_pip
- 剪辑计划模板 + 智能生成
- 自动化视频合成任务（Celery 异步）
- 成片下载与审核管理
- 资产诊断（素材就绪度评估、缺口分析）

### 🔐 认证系统
- JWT Bearer Token 认证
- 邮箱注册 + 邮箱验证
- 密码重置（邮箱找回）
- bcrypt 密码加密

### 📋 项目管理
- 项目 CRUD + 共享
- 任务管理（创建/更新/状态流转/进度追踪）
- 里程碑管理
- 任务问题追踪

### 📊 素材库管理
- 素材库创建与管理
- 素材上传、审核状态流转（pending_review → approved/rejected）
- 素材诊断（就绪度评分、缺口分析、智能视图）

---

## 🚀 快速开始

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

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

# 2. 配置环境变量
cp .env.example .env
# 编辑 .env 填写数据库、Redis、OSS 等配置

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

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

### 方式 2: 本地开发

```bash
# 1. 克隆仓库
git clone https://git.xiaoxiajianji.com/xiaoxia/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. 配置环境变量
cp .env.example .env

# 5. 启动 API 服务
uvicorn apps.api.main:app --reload

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

---

## 📚 API 文档

### 交互式文档
- **Swagger UI**: https://saas-api.xiaoxiajianji.com/docs
- **OpenAPI Schema**: https://saas-api.xiaoxiajianji.com/openapi.json

### 核心 API 路径

**认证** (`/api/v1/auth`)

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/register` | 用户注册 |
| POST | `/login` | 用户登录 |
| GET | `/me` | 获取当前用户信息 |
| POST | `/password/forgot` | 忘记密码 |
| POST | `/password/reset` | 重置密码 |

**视频剪辑主链路**

```
上传素材 → POST /api/v1/upload（直传）或 /api/v1/upload/chunk/init（分片）
   ↓
创建素材 → POST /api/v1/assets
   ↓
AI 分类 → POST /api/v1/classification-jobs
   ↓
生成剪辑计划 → POST /api/v1/projects/{id}/edit-plans/auto-generate
   ↓
创建生成任务 → POST /api/v1/generation/tasks/
   ↓
查询结果 → GET /api/v1/generation/tasks/{task_id}/results/
   ↓
获取成片 → GET /api/v1/generated-videos/{video_id}/download-url
```

**项目管理** (`/api/v1/project-management`)

| 方法 | 路径 | 说明 |
|------|------|------|
| GET/POST | `/tasks` | 任务列表/创建 |
| PATCH | `/tasks/{id}` | 更新任务信息 |
| PATCH | `/tasks/{id}/status` | 更新任务状态 |
| PATCH | `/tasks/{id}/progress` | 更新任务进度 |
| GET/POST | `/milestones` | 里程碑列表/创建 |
| GET/POST | `/issues` | 问题列表/创建 |
| PATCH | `/issues/{id}/resolve` | 解决问题 |

**素材与上传**

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/v1/upload` | 直传素材（multipart/form-data） |
| POST | `/api/v1/upload/direct/prepare` | 准备 OSS 直传签名 |
| POST | `/api/v1/upload/direct/complete` | 确认直传完成 |
| POST | `/api/v1/upload/chunk/init` | 初始化分片上传 |
| POST | `/api/v1/upload/chunk/{id}/{index}` | 上传分片 |
| POST | `/api/v1/upload/chunk/{id}/complete` | 完成分片上传 |
| GET | `/api/v1/assets` | 素材列表 |
| PATCH | `/api/v1/assets/{id}/review` | 更新素材审核状态 |
| GET | `/api/v1/projects/{id}/asset-diagnosis` | 资产诊断 |

**成片管理** (`/api/v1/generated-videos`)

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/` | 成片列表 |
| GET | `/{video_id}` | 成片详情 |
| GET | `/{video_id}/download-url` | 下载链接 |
| PATCH | `/{video_id}/review` | 审核状态 |

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

---

## 🏗️ 架构

```
小虾 SaaS
├── packages/              # 核心业务逻辑（Clean Architecture）
│   ├── domain/           # 领域模型（dataclass）
│   ├── application/      # 用例（Use Cases）
│   ├── ports/            # 接口定义（抽象端口）
│   └── adapters/         # 适配器实现（SQLAlchemy、Redis、SMTP 等）
├── apps/                 # 应用层
│   ├── api/             # FastAPI 应用 + 路由 + Pydantic schemas
│   ├── web/             # React + Vite 前端
│   └── worker/          # Celery 异步任务（视频处理、分类等）
├── migrations/           # Alembic 数据库迁移
├── tests/               # 测试
│   ├── unit/           # 单元测试
│   ├── integration/    # 集成测试
│   └── e2e/            # 端到端测试
└── docs/                # 文档
```

**设计模式:**
- Clean Architecture（依赖方向：外层 → 内层）
- 依赖注入（FastAPI Depends）
- Repository 模式（通过 ports 抽象）
- Domain-Driven Design

---

## 🛠️ 技术栈

**后端:**
- Python 3.12 + FastAPI 0.115.0
- PostgreSQL 16（生产）
- Redis 7（缓存 + Celery Broker）
- Celery（异步任务：视频处理、素材导入、分类）
- 阿里云 OSS（文件存储）

**前端:**
- React 18 + TypeScript
- Vite（构建工具）
- Ant Design（UI 组件）

**部署:**
- Docker + Docker Compose
- Gitea + Gitea Actions（CI/CD）
- Nginx（反向代理）

---

## 🧪 测试

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

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

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

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

---

## 📊 当前状态

| 模块 | 状态 |
|------|------|
| 视频剪辑主链路（Phase 7） | ✅ 已完成 |
| 分片上传（最大 2GB） | ✅ 已完成 |
| 4 种剪辑模式 | ✅ 已完成 |
| 项目管理 + 任务追踪 | ✅ 已完成 |
| 资产诊断 | ✅ 已完成 |
| 认证系统（JWT） | ✅ 已完成 |
| CI/CD 流水线 | ✅ 运行中 |
| 前端界面（Vite） | ✅ 已完成 |

---

## 📄 更多文档

- [API 主线清单](docs/API-MAINLINE.md) - 全部端点总览
- [API 使用指南](docs/API-GUIDE.md) - 详细用法
- [代码状态标注](docs/CODE-STATUS.md) - 代码库导航
- [Docker 部署指南](docs/DOCKER-DEPLOYMENT.md)
- [CI/CD 文档](docs/CI-CD.md)
- [Git 工作流](docs/GIT-WORKFLOW.md)
- [环境配置指南](docs/ENVIRONMENT-CONFIG.md)

---

## 🤝 贡献

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

**仓库地址**: https://git.xiaoxiajianji.com/xiaoxia/xiaoxia-saas

---

**License**: MIT