test(preview): 预览环境端到端验证测试PR

2026-07-18 11:50:19 +08:00
commit e11366cae1
1 changed files with 268 additions and 0 deletions
@@ -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预览环境端到端部署流程，验证完成后将关闭。