CI Bot
84abfbcfcd
新增 PiP 引擎，支持在统一渲染管道中加入多图层画中画叠加： 核心能力： - 多图层叠加：主画面 + 多个副画面，按 z_index 排序 - 位置：9宫格（top_left/top_center/top_right/center_left/center/center_right/bottom_left/bottom_center/bottom_right）+ 自由坐标（像素或百分比）+ 边距配置 - 大小：宽高缩放（像素或百分比），高度自适应比例 - 圆角裁剪：支持圆角矩形（geq 实现四角圆弧） - 边框：边框宽度 + 颜色 - 透明度：0-100%（colorchannelmixer） - 入场出场动画：淡入淡出（fade）、滑入滑出（left/right/top/bottom 四方向） - 时间同步：每个副画面独立 start_time + duration，enable 表达式控制 - 降级策略：素材不存在/无效时自动跳过，不阻断渲染 系统集成： - UnifiedRenderService 接入：从 plan.config.pip_config 读取配置 - 在 filter_complex 最终合成环节（字幕之前）叠加 PiP 图层 - 有 PiP 时自动禁用直通模式（需要额外图层叠加） - 输入索引偏移处理：PiP 素材追加在主输入之后，滤镜引用正确索引 测试覆盖： - PiPLayerConfig.validate：source/position/opacity/corner_radius/timing/animation 等边界校验 - PiPConfig.from_dict：字典解析、z_index 排序、无效层跳过、默认值 - 位置计算：9宫格全位置 + 自定义像素/百分比 + 边界 - 尺寸解析：像素/百分比/零值/负值 - 滤镜构建：单图层/多图层/透明度/圆角/边框/时间控制/淡入淡出/滑入滑出 - 降级策略：asset_id不存在/本地路径不存在/URL不支持/异常处理 55个新增单测 + 84个现有测试，共139个全绿，零回归
小虾 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） | ✅ 已完成 |
📄 更多文档
🤝 贡献
欢迎贡献！请查看 贡献指南
仓库地址: https://git.xiaoxiajianji.com/xiaoxia/xiaoxia-saas
License: MIT