# 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

## 开发指南

### 环境准备

```bash
# 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
```

### 运行测试

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

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

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

### 数据库迁移

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

# 应用迁移
alembic upgrade head

# 回滚迁移
alembic downgrade -1

# 查看当前版本
alembic current

# 查看迁移历史
alembic history
```

## 下一步计划

### Phase 2 - 基础设施完善（进行中）
- [x] 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 完成)