用户CI Test
f5f54b98b6
CI/CD Pipeline / Validate Code Quality And Tests (pull_request) Failing after 8s
CI/CD Pipeline / Frontend Lint (pull_request) Successful in 1m38s
CI/CD Pipeline / Build & Push Staging (Watchtower auto-deploy) (pull_request) Has been skipped
CI/CD Pipeline / Build Production Runtime Images (pull_request) Has been skipped
CI/CD Pipeline / Staging E2E Tests (pull_request) Has been skipped
CI/CD Pipeline / Staging API Integration Tests (pull_request) Has been skipped
CI/CD Pipeline / Deploy Production (pull_request) Has been skipped
CI/CD Pipeline / Production Browser E2E (pull_request) Has been skipped
## 问题根因
generate_video Celery 任务完全没有状态更新逻辑：
- 任务开始执行时，不更新 GenerationTask 状态为 running
- 任务成功时，不更新状态为 completed
- 任务失败时，不更新状态为 failed
- GenerationTask 领域模型缺少 mark_processing/mark_completed/mark_failed 方法
结果：任务状态永远停留在 pending，前端查询时一直显示"生成中"或超时显示失败，即使视频实际上已经生成成功了。
## 修复方案
### 1. GenerationTask 领域模型增加完整状态机
- 新增 TERMINAL_STATUSES 终态集合
- 新增 _VALID_TRANSITIONS 合法状态转换表
- 新增 transition_to() 通用状态转换方法（含合法性校验）
- 新增 mark_processing() — pending → running，设置 started_at
- 新增 mark_completed(result_count) — running → completed，设置 completed_at/progress/result_count
- 新增 mark_failed(error_message) — pending/running → failed，设置 error_message/completed_at
- 新增 mark_cancelled() — pending/running → cancelled
- 新增 mark_pending_from_failed() — failed → pending（用于重试）
- 新增 is_terminal/is_completed/is_failed/is_running 属性
状态机：
pending → running → completed
↘ failed → pending (重试)
↘ cancelled
### 2. generate_video Celery 任务增加状态更新
- 新增 _update_task_status() 辅助函数：独立 session + 异常隔离
- 任务开始时：调用 mark_processing() 更新为 running
- 任务成功时：调用 mark_completed() 更新为 completed，传入视频数量
- 任务失败时：在 except 块中调用 mark_failed() 记录错误信息
- _create_video_record_and_dedup 返回值改为 int，方便统计成功数量
状态更新使用独立数据库 session，且所有状态更新操作都包裹在 try/except 中，确保不会因为状态更新失败导致整个任务异常。
### 3. 新增状态机单元测试
新增 tests/unit/test_generation_task_status.py，覆盖 42 个测试用例：
- 初始状态验证
- mark_processing 正常/异常路径
- mark_completed 正常/异常路径
- mark_failed 正常/异常路径
- mark_cancelled 正常/异常路径
- mark_pending_from_failed 重试路径
- transition_to 通用方法
- 完整流转路径（成功、失败、重试、取消）
## 影响范围
- packages/domain/generation_task.py — 领域模型状态机方法
- apps/worker/worker_app/tasks/generation.py — Celery 任务状态更新
- tests/unit/test_generation_task_status.py — 新增单元测试
## 验证方式
- 42 个状态机单元测试全部通过
- 现有 8 个生成相关测试全部通过
- 现有 15 个生成 API 集成测试全部通过
- 现有 6 个编辑计划 worker 失败测试全部通过
- 现有 25 个生成视频管理测试全部通过
小虾 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