diff --git a/README.md b/README.md index 0f81abcb6..92bc906a8 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,332 @@ -# xiaoxia-saas +# Xiaoxia SaaS - AI 视频自动化剪辑系统 -小虾自动剪辑 SaaS 新主线仓库。 +新一代 SaaS 版小虾自动化剪辑系统，采用 Clean Architecture 重新设计与实现。 -## 目标 +## 项目状态 -- 与旧桌面版彻底隔离 -- 按正规 SaaS 工程方式重建 -- 先按文档、架构、制度启动，再进入开发 +**当前阶段**: 核心业务骨架已完成（Phase 1） -## 目录 +- ✅ Clean Architecture 架构就绪 +- ✅ 核心业务对象（User, Workspace, Project, AssetLibrary, Asset, IngestJob, ClassificationJob） +- ✅ 完整上传→入库→Asset 创建链路 +- ✅ 完整分类任务链路 +- ✅ 双持久化实现（In-Memory + PostgreSQL） +- ✅ Alembic 数据库迁移 +- ✅ 8 个集成测试全绿 +- ✅ Docker Compose 开发环境 -- `docs/`：产品、架构、流程、盘点和启动文档 -- `apps/web/`：前端 Web 应用 -- `apps/api/`：后端 API 应用 -- `apps/worker/`：后台任务执行应用 -- `packages/domain/`：核心业务对象与规则 -- `packages/application/`：用例层 -- `packages/ports/`：接口定义 -- `packages/adapters/`：外部实现 -- `packages/shared/`：共享基础模块 -- `infra/`：部署与运行基础设施 -- `tests/`：集成测试与端到端测试 +## 技术栈 -## 当前状态 +**Backend** +- Python 3.12 +- FastAPI - REST API +- Pydantic - 数据验证 +- SQLAlchemy - ORM +- Alembic - 数据库迁移 -当前仓库已完成 SaaS 启动期文档骨架和目录骨架，下一步进入工程初始化。 +**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 - 基础设施完善 +- [ ] CI/CD 流水线（GitHub Actions / 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 完成)