Xiaoxia SaaS - AI 视频自动化剪辑系统

新一代 SaaS 版小虾自动化剪辑系统，采用 Clean Architecture 重新设计与实现。

项目状态

当前阶段: 核心业务骨架已完成（Phase 1）

• ✅ Clean Architecture 架构就绪
• ✅ 核心业务对象（User, Workspace, Project, AssetLibrary, Asset, IngestJob, ClassificationJob）
• ✅ 完整上传→入库→Asset 创建链路
• ✅ 完整分类任务链路
• ✅ 双持久化实现（In-Memory + PostgreSQL）
• ✅ Alembic 数据库迁移
• ✅ 8 个集成测试全绿
• ✅ Docker Compose 开发环境

技术栈

Backend

• Python 3.12
• FastAPI - REST API
• Pydantic - 数据验证
• SQLAlchemy - ORM
• Alembic - 数据库迁移

Worker

• Celery - 异步任务队列
• Redis - 消息队列

Database

• PostgreSQL - 生产数据库
• SQLite - 测试环境

Frontend (占位)

• Next.js 14
• TypeScript
• React 18

Architecture

• Clean Architecture
• Ports & Adapters (Hexagonal)
• Repository Pattern
• Use Case Pattern

Testing

• pytest
• 集成测试优先策略

项目结构

xiaoxia-saas/
├── packages/                 # 共享业务逻辑包
│   ├── domain/              # 核心业务实体与规则
│   ├── application/         # 用例层
│   ├── ports/               # 接口定义
│   └── adapters/            # 接口实现
│       ├── in_memory/       # 内存实现（测试用）
│       └── sqlalchemy_impl/ # PostgreSQL 实现
├── apps/                    # 应用层
│   ├── api/                 # FastAPI REST API
│   ├── worker/              # Celery 异步任务
│   └── web/                 # Next.js 前端（占位）
├── infra/                   # 基础设施配置
│   ├── docker/              # Docker 配置
│   └── nginx/               # Nginx 配置
├── tests/                   # 测试
│   ├── integration/         # 集成测试
│   └── e2e/                 # 端到端测试（占位）
├── alembic/                 # 数据库迁移
└── docs/                    # 文档

核心业务对象

Domain Entities

User - 用户

• 基本信息：id, email, display_name

Workspace - 工作空间

• 用户的顶级组织单元
• 拥有者：owner_user_id

Project - 项目

• 属于某个 Workspace
• 包含多个 AssetLibrary

AssetLibrary - 素材库

• 类型：VIDEO（视频）/ VOICE（音频）
• 属于某个 Project

Asset - 素材

• 单个素材文件
• 属于某个 AssetLibrary
• 包含：storage_key, mime_type, metadata

IngestJob - 入库任务

• 状态：PENDING → PROCESSING → COMPLETED/FAILED
• 负责：文件上传后的元数据提取、Asset 创建
• 结果：result_asset_id

ClassificationJob - 分类任务

• 状态：PENDING → PROCESSING → COMPLETED/FAILED
• 负责：Asset 的自动分类
• 分类：scenic（风景）, product（产品）, person（人物）, animal（动物）, food（美食）, tech（科技）, sport（运动）, music（音乐）, other（其他）
• 结果：classification + confidence

已完成功能

API 接口（6 组）

健康检查

• GET /api/health - 健康检查

项目管理

• GET /api/projects?workspace_id=... - 项目列表
• POST /api/projects - 创建项目

素材库管理

• GET /api/asset-libraries?project_id=... - 素材库列表
• POST /api/asset-libraries - 创建素材库

素材管理

• GET /api/assets?library_id=... - 素材列表
• POST /api/assets - 创建素材

任务管理

• POST /api/ingest-jobs - 提交入库任务

文件上传

• POST /api/upload - 上传素材文件

Worker 任务（3 个）

健康检查

• worker.healthcheck - Worker 健康检查

入库任务

• worker.ingest_asset - 素材入库处理
  • 元数据提取（当前 mock，真实场景用 ffprobe）
  • Asset 创建
  • IngestJob 状态更新

分类任务

• worker.classify_asset - 素材分类处理
  • 自动分类（当前 mock，真实场景用 ML 模型或 vision API）
  • ClassificationJob 状态更新

完整业务流程

上传→入库→Asset 创建

1. 用户通过 POST /api/upload 上传文件
2. API 生成 storage_key，创建 IngestJob（状态 PENDING）
3. Celery 任务 ingest_asset 被入队
4. Worker 处理：
   • 更新状态为 PROCESSING
   • 提取元数据
   • 创建 Asset 实体
   • 更新 IngestJob 状态为 COMPLETED，记录 result_asset_id
5. 异常时更新状态为 FAILED，记录 error_message

分类→结果

1. 创建 ClassificationJob（状态 PENDING）
2. Celery 任务 classify_asset 被入队
3. Worker 处理：
   • 更新状态为 PROCESSING
   • 运行分类模型
   • 更新 ClassificationJob 状态为 COMPLETED，记录 classification + confidence
4. 异常时更新状态为 FAILED，记录 error_message

开发指南

环境准备

# 1. 安装依赖
pip install -r requirements.txt

# 2. 启动开发环境（Docker Compose）
cd infra/docker
docker-compose up -d

# 3. 运行数据库迁移
alembic upgrade head

# 4. 启动 API（开发模式）
cd apps/api
uvicorn main:app --reload --host 0.0.0.0 --port 8000

# 5. 启动 Worker（开发模式）
cd apps/worker
celery -A worker_app.celery_app.celery_app worker --loglevel=info

运行测试

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

# 运行指定测试
pytest tests/integration/test_ingest_pipeline.py -v

# 运行所有测试（包含覆盖率）
pytest --cov=packages --cov=apps --cov-report=html

数据库迁移

# 创建新迁移
alembic revision -m "description"

# 应用迁移
alembic upgrade head

# 回滚迁移
alembic downgrade -1

# 查看当前版本
alembic current

# 查看迁移历史
alembic history

下一步计划

Phase 2 - 基础设施完善（进行中）

• CI/CD 流水线（Gitea Actions）
• 真实文件存储（MinIO / S3）
• 生产环境配置（环境变量、密钥管理）
• 监控与日志（Prometheus + Grafana）
• API 文档（Swagger / ReDoc）

Phase 3 - 核心业务扩展

• 用户认证与授权（JWT）
• Workspace 多用户协作
• 视频剪辑任务（ClipJob）
• 音频处理任务（AudioProcessJob）
• 任务队列管理与监控
• Webhook 通知

Phase 4 - 前端开发

• 用户登录/注册页面
• 工作空间管理
• 项目管理
• 素材库管理
• 素材上传与预览
• 任务状态监控

Phase 5 - 高级功能

• 真实 ML 模型集成（分类、识别）
• 批量处理
• 定时任务
• 数据分析与报表
• API 限流与配额

架构决策记录

ADR-001: Clean Architecture

日期: 2026-06-15
状态: 已采纳
决策: 采用 Clean Architecture 重新设计系统
原因:

• 旧 desktop 系统耦合严重，难以测试和维护
• 新 SaaS 需要长期演进，架构需要可扩展
• Clean Architecture 提供清晰的依赖方向和边界

ADR-002: 双持久化实现

日期: 2026-06-15
状态: 已采纳
决策: 同时提供 In-Memory 和 SQLAlchemy 两种 Repository 实现
原因:

• In-Memory 实现用于测试，快速且无外部依赖
• SQLAlchemy 实现用于生产，真实数据库持久化
• Repository Pattern 使得实现可随时切换

ADR-003: 集成测试优先

日期: 2026-06-15
状态: 已采纳
决策: 集成测试优先于单元测试
原因:

• 核心业务流程需要端到端验证
• In-Memory 实现使得集成测试成本低
• 单元测试在架构稳定后逐步补充

Commits 历史

1. b5a62ee - feat: initial SaaS scaffold
2. 43fd071 - feat: implement ingest asset worker task
3. d550416 - feat: add upload asset endpoint
4. e4e2595 - feat: add PostgreSQL persistence layer
5. b43cdca - feat: add Alembic database migrations
6. a8177c1 - feat: add asset classification pipeline

贡献指南

代码风格

• 遵循 PEP 8
• 使用 Black 格式化代码
• 使用 type hints
• 中文注释与文档

Commit 规范

• feat: 新功能
• fix: 修复
• docs: 文档
• test: 测试
• refactor: 重构
• chore: 构建/工具

Pull Request

1. 基于 main 创建新分支
2. 编写测试并确保通过
3. 更新相关文档
4. 提交 PR，描述改动内容

许可证

内部项目，未公开。

联系方式

技术问题：请联系小虾 AI 团队

---

最后更新: 2026-06-15
当前版本: 0.1.0 (Phase 1 完成)