docs: update README with complete project status

- project overview and current status - tech stack and architecture - core domain entities explained - completed features (API, Worker, pipelines) - development guide (setup, testing, migrations) - roadmap (Phase 2-5) - architecture decision records (ADR-001 to ADR-003) - contribution guidelines
2026-06-15 15:49:33 +08:00
parent a8177c1268
commit 578f22442f
1 changed files with 325 additions and 20 deletions
@@ -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 完成)