API文档维护Agent
8064b64ff5
1. 修正上传端点schema命名：新增UploadAssetRequest模型替代自动生成的Body_upload_asset名称 2. 清理认证重复端点：移除/forgot-password和/reset-password旧路由，保留/password/forgot和/password/reset 3. 清理workspace_id残留：从edit_plan/asset_diagnosis/task_center/project_title等schema中移除，project_management和projects中改为可选 4. 更新README：移除过时的多租户/订阅/refresh token描述，修正仓库地址为git.xiaoxiajianji.com，更新API路径列表
266 lines
7.2 KiB
Markdown
266 lines
7.2 KiB
Markdown
# 小虾 SaaS - 自动化视频剪辑平台
|
||
|
||
[](https://www.python.org/downloads/)
|
||
[](https://fastapi.tiangolo.com)
|
||
[](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
|