Xiaoxia AI
cb2364a363
- .gitea/workflows/tests.yml: automated testing + linting on push/PR - .gitea/workflows/deploy.yml: deployment workflow (placeholder) - docs/CI-CD.md: CI/CD configuration guide - requirements-dev.txt: development dependencies (pytest, black, flake8, mypy) - test job: run pytest with coverage report - lint job: black + flake8 + mypy code quality checks
333 lines
8.4 KiB
Markdown
333 lines
8.4 KiB
Markdown
# 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 完成)
|