commit e11366cae1aed2f7c17db478690859878acbd875 Author: CI Bot Date: Sat Jul 18 11:50:19 2026 +0800 test(preview): 预览环境端到端验证测试PR diff --git a/README.md b/README.md new file mode 100644 index 000000000..c68374bcf --- /dev/null +++ b/README.md @@ -0,0 +1,268 @@ +# 小虾 SaaS - 自动化视频剪辑平台 + +[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/) +[![FastAPI](https://img.shields.io/badge/FastAPI-0.115.0-009688.svg)](https://fastapi.tiangolo.com) +[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-16-336791.svg)](https://www.postgresql.org/) + +自动化视频剪辑 SaaS 平台，支持素材上传、AI 分类、智能剪辑计划生成、自动化视频合成与成片管理。 + +--- + +## ✨ 核心功能 + +### 🎬 视频剪辑主链路 +- 素材上传（直传 OSS + 分片上传大文件，最大 2GB） +- AI 智能分类与质量评分 +- 4 种剪辑模式：one_take / pip（画中画）/ voice_over（口播+B-roll）/ voice_pip +- 剪辑计划模板 + 智能生成 +- 自动化视频合成任务（Celery 异步） +- 成片下载与审核管理 +- 资产诊断（素材就绪度评估、缺口分析） + +### 🔐 认证系统 +- JWT Bearer Token 认证 +- 邮箱注册 + 邮箱验证 +- 密码重置（邮箱找回） +- bcrypt 密码加密 + +### 📋 项目管理 +- 项目 CRUD + 共享 +- 任务管理（创建/更新/状态流转/进度追踪） +- 里程碑管理 +- 任务问题追踪 + +### 📊 素材库管理 +- 素材库创建与管理 +- 素材上传、审核状态流转（pending_review → approved/rejected） +- 素材诊断（就绪度评分、缺口分析、智能视图） + +--- + +## 🚀 快速开始 + +### 方式 1: Docker Compose（推荐） + +```bash +# 1. 克隆仓库 +git clone https://git.xiaoxiajianji.com/xiaoxia/xiaoxia-saas.git +cd xiaoxia-saas + +# 2. 配置环境变量 +cp .env.example .env +# 编辑 .env 填写数据库、Redis、OSS 等配置 + +# 3. 启动所有服务 +docker-compose up -d + +# 4. 访问 API 文档 +open http://localhost:8000/docs +``` + +### 方式 2: 本地开发 + +```bash +# 1. 克隆仓库 +git clone https://git.xiaoxiajianji.com/xiaoxia/xiaoxia-saas.git +cd xiaoxia-saas + +# 2. 创建虚拟环境 +python -m venv venv +source venv/bin/activate # Windows: venv\Scripts\activate + +# 3. 安装依赖 +pip install -r requirements.txt + +# 4. 配置环境变量 +cp .env.example .env + +# 5. 启动 API 服务 +uvicorn apps.api.main:app --reload + +# 6. 访问 API 文档 +open http://localhost:8000/docs +``` + +--- + +## 📚 API 文档 + +### 交互式文档 +- **Swagger UI**: https://saas-api.xiaoxiajianji.com/docs +- **OpenAPI Schema**: https://saas-api.xiaoxiajianji.com/openapi.json + +### 核心 API 路径 + +**认证** (`/api/v1/auth`) + +| 方法 | 路径 | 说明 | +|------|------|------| +| POST | `/register` | 用户注册 | +| POST | `/login` | 用户登录 | +| GET | `/me` | 获取当前用户信息 | +| POST | `/password/forgot` | 忘记密码 | +| POST | `/password/reset` | 重置密码 | + +**视频剪辑主链路** + +``` +上传素材 → POST /api/v1/upload（直传）或 /api/v1/upload/chunk/init（分片） + ↓ +创建素材 → POST /api/v1/assets + ↓ +AI 分类 → POST /api/v1/classification-jobs + ↓ +生成剪辑计划 → POST /api/v1/projects/{id}/edit-plans/auto-generate + ↓ +创建生成任务 → POST /api/v1/generation/tasks/ + ↓ +查询结果 → GET /api/v1/generation/tasks/{task_id}/results/ + ↓ +获取成片 → GET /api/v1/generated-videos/{video_id}/download-url +``` + +**项目管理** (`/api/v1/project-management`) + +| 方法 | 路径 | 说明 | +|------|------|------| +| GET/POST | `/tasks` | 任务列表/创建 | +| PATCH | `/tasks/{id}` | 更新任务信息 | +| PATCH | `/tasks/{id}/status` | 更新任务状态 | +| PATCH | `/tasks/{id}/progress` | 更新任务进度 | +| GET/POST | `/milestones` | 里程碑列表/创建 | +| GET/POST | `/issues` | 问题列表/创建 | +| PATCH | `/issues/{id}/resolve` | 解决问题 | + +**素材与上传** + +| 方法 | 路径 | 说明 | +|------|------|------| +| POST | `/api/v1/upload` | 直传素材（multipart/form-data） | +| POST | `/api/v1/upload/direct/prepare` | 准备 OSS 直传签名 | +| POST | `/api/v1/upload/direct/complete` | 确认直传完成 | +| POST | `/api/v1/upload/chunk/init` | 初始化分片上传 | +| POST | `/api/v1/upload/chunk/{id}/{index}` | 上传分片 | +| POST | `/api/v1/upload/chunk/{id}/complete` | 完成分片上传 | +| GET | `/api/v1/assets` | 素材列表 | +| PATCH | `/api/v1/assets/{id}/review` | 更新素材审核状态 | +| GET | `/api/v1/projects/{id}/asset-diagnosis` | 资产诊断 | + +**成片管理** (`/api/v1/generated-videos`) + +| 方法 | 路径 | 说明 | +|------|------|------| +| GET | `/` | 成片列表 | +| GET | `/{video_id}` | 成片详情 | +| GET | `/{video_id}/download-url` | 下载链接 | +| PATCH | `/{video_id}/review` | 审核状态 | + +完整 API 列表请查看 [API 主线清单](docs/API-MAINLINE.md) + +--- + +## 🏗️ 架构 + +``` +小虾 SaaS +├── packages/ # 核心业务逻辑（Clean Architecture） +│ ├── domain/ # 领域模型（dataclass） +│ ├── application/ # 用例（Use Cases） +│ ├── ports/ # 接口定义（抽象端口） +│ └── adapters/ # 适配器实现（SQLAlchemy、Redis、SMTP 等） +├── apps/ # 应用层 +│ ├── api/ # FastAPI 应用 + 路由 + Pydantic schemas +│ ├── web/ # React + Vite 前端 +│ └── worker/ # Celery 异步任务（视频处理、分类等） +├── migrations/ # Alembic 数据库迁移 +├── tests/ # 测试 +│ ├── unit/ # 单元测试 +│ ├── integration/ # 集成测试 +│ └── e2e/ # 端到端测试 +└── docs/ # 文档 +``` + +**设计模式:** +- Clean Architecture（依赖方向：外层 → 内层） +- 依赖注入（FastAPI Depends） +- Repository 模式（通过 ports 抽象） +- Domain-Driven Design + +--- + +## 🛠️ 技术栈 + +**后端:** +- Python 3.12 + FastAPI 0.115.0 +- PostgreSQL 16（生产） +- Redis 7（缓存 + Celery Broker） +- Celery（异步任务：视频处理、素材导入、分类） +- 阿里云 OSS（文件存储） + +**前端:** +- React 18 + TypeScript +- Vite（构建工具） +- Ant Design（UI 组件） + +**部署:** +- Docker + Docker Compose +- Gitea + Gitea Actions（CI/CD） +- Nginx（反向代理） + +--- + +## 🧪 测试 + +```bash +# 运行所有测试 +pytest tests/ -v + +# 运行单元测试 +pytest tests/unit -v + +# 运行集成测试 +pytest tests/integration -v + +# 生成覆盖率报告 +pytest --cov=packages --cov-report=html +``` + +--- + +## 📊 当前状态 + +| 模块 | 状态 | +|------|------| +| 视频剪辑主链路（Phase 7） | ✅ 已完成 | +| 分片上传（最大 2GB） | ✅ 已完成 | +| 4 种剪辑模式 | ✅ 已完成 | +| 项目管理 + 任务追踪 | ✅ 已完成 | +| 资产诊断 | ✅ 已完成 | +| 认证系统（JWT） | ✅ 已完成 | +| CI/CD 流水线 | ✅ 运行中 | +| 前端界面（Vite） | ✅ 已完成 | + +--- + +## 📄 更多文档 + +- [API 主线清单](docs/API-MAINLINE.md) - 全部端点总览 +- [API 使用指南](docs/API-GUIDE.md) - 详细用法 +- [代码状态标注](docs/CODE-STATUS.md) - 代码库导航 +- [Docker 部署指南](docs/DOCKER-DEPLOYMENT.md) +- [CI/CD 文档](docs/CI-CD.md) +- [Git 工作流](docs/GIT-WORKFLOW.md) +- [环境配置指南](docs/ENVIRONMENT-CONFIG.md) + +--- + +## 🤝 贡献 + +欢迎贡献！请查看 [贡献指南](CONTRIBUTING.md) + +**仓库地址**: https://git.xiaoxiajianji.com/xiaoxia/xiaoxia-saas + +--- + +**License**: MIT + +### 预览环境测试 +此PR用于验证P1-4预览环境端到端部署流程，验证完成后将关闭。