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

自动化视频剪辑 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（推荐）

# 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: 本地开发

# 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 主线清单

---

🏗️ 架构

小虾 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（反向代理）

---

🧪 测试

# 运行所有测试
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 主线清单 - 全部端点总览
• API 使用指南 - 详细用法
• 代码状态标注 - 代码库导航
• Docker 部署指南
• CI/CD 文档
• Git 工作流
• 环境配置指南

---

🤝 贡献

欢迎贡献！请查看 贡献指南

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

---

License: MIT