docs: add comprehensive API usage guide and changelog
- Create detailed API usage guide with examples - Cover all 19 API endpoints with request/response samples - Add authentication flow documentation - Include error handling and best practices - Add rate limiting and token management guide - Create CHANGELOG.md tracking all Phase 4 changes Phase 4 Task 34/68 completed
This commit is contained in:
Xiaoxia AI
+130
@@ -0,0 +1,130 @@
|
||||
# Changelog
|
||||
|
||||
All notable changes to this project will be documented in this file.
|
||||
|
||||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
||||
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
||||
|
||||
## [1.0.0] - 2026-06-17
|
||||
|
||||
### Phase 4: SAAS 产品化 - 完成
|
||||
|
||||
#### Added
|
||||
|
||||
**认证系统:**
|
||||
- 用户注册（邮箱验证）
|
||||
- 用户登录（JWT + Session）
|
||||
- 用户登出（单设备/所有设备）
|
||||
- 邮箱验证
|
||||
- 密码重置（邮件重置链接）
|
||||
- JWT Service（access + refresh token）
|
||||
- Password Hasher（bcrypt, cost=12）
|
||||
- Session Store（Redis-based）
|
||||
- Email Service（SMTP with templates）
|
||||
|
||||
**工作空间管理:**
|
||||
- 创建工作空间
|
||||
- 获取工作空间列表
|
||||
- 获取工作空间详情
|
||||
- 邀请成员（邮件邀请）
|
||||
- 接受/拒绝邀请
|
||||
- 移除成员
|
||||
- 离开工作空间
|
||||
- 修改成员角色
|
||||
- 获取成员列表
|
||||
|
||||
**权限系统:**
|
||||
- 基于角色的访问控制（RBAC）
|
||||
- 4 种角色（Owner/Admin/Member/Viewer）
|
||||
- 细粒度权限定义
|
||||
- 权限检查中间件
|
||||
|
||||
**订阅系统:**
|
||||
- 3 级订阅计划（Free/Pro/Enterprise）
|
||||
- 升级订阅
|
||||
- 取消订阅（降级到 Free）
|
||||
- 自动配额调整
|
||||
|
||||
**配额系统:**
|
||||
- 项目数量限制检查
|
||||
- 存储空间限制检查
|
||||
- 配额使用状态查询
|
||||
- 警告级别（normal/warning/critical/exceeded）
|
||||
- 存储使用量更新
|
||||
|
||||
**Repository 层:**
|
||||
- UserRepository（InMemory + PostgreSQL）
|
||||
- WorkspaceRepository（InMemory）
|
||||
- WorkspaceMemberRepository（InMemory）
|
||||
- WorkspaceInvitationRepository（InMemory）
|
||||
|
||||
**API 层:**
|
||||
- FastAPI 应用主入口
|
||||
- 依赖注入容器
|
||||
- 认证中间件（JWT 验证）
|
||||
- 权限中间件
|
||||
- 全局异常处理
|
||||
- 请求日志中间件
|
||||
- 速率限制中间件
|
||||
- CORS 配置
|
||||
- 6 个认证接口
|
||||
- 13 个工作空间接口
|
||||
|
||||
**数据库:**
|
||||
- PostgreSQL 表结构设计
|
||||
- 初始化迁移脚本
|
||||
- 索引优化
|
||||
- 外键约束
|
||||
|
||||
**部署:**
|
||||
- Dockerfile
|
||||
- docker-compose.yml
|
||||
- 环境变量配置
|
||||
- 部署文档
|
||||
|
||||
**文档:**
|
||||
- README（快速开始）
|
||||
- API 使用指南
|
||||
- 数据库迁移指南
|
||||
- Docker 部署指南
|
||||
- Phase 4 设计文档
|
||||
- Phase 4 完成总结
|
||||
|
||||
#### Changed
|
||||
- N/A (首次发布)
|
||||
|
||||
#### Deprecated
|
||||
- N/A
|
||||
|
||||
#### Removed
|
||||
- N/A
|
||||
|
||||
#### Fixed
|
||||
- N/A
|
||||
|
||||
#### Security
|
||||
- bcrypt 密码加密（cost=12）
|
||||
- JWT token 签名验证
|
||||
- SQL 注入防护（参数化查询）
|
||||
- CORS 安全配置
|
||||
- 速率限制（防止暴力破解）
|
||||
|
||||
---
|
||||
|
||||
## [0.1.0] - 2026-06-16
|
||||
|
||||
### Phase 1-3: 基础功能
|
||||
|
||||
- 基础视频处理功能
|
||||
- 素材库管理
|
||||
- 项目管理
|
||||
|
||||
---
|
||||
|
||||
**说明:**
|
||||
- [Added] 新增功能
|
||||
- [Changed] 功能变更
|
||||
- [Deprecated] 即将废弃的功能
|
||||
- [Removed] 已删除的功能
|
||||
- [Fixed] Bug 修复
|
||||
- [Security] 安全相关更新
|
||||
@@ -0,0 +1,417 @@
|
||||
# 小虾 SaaS API 使用指南
|
||||
|
||||
## 📖 概述
|
||||
|
||||
小虾 SaaS 是一个完整的多租户 SaaS 平台，提供用户认证、工作空间管理、团队协作和订阅管理功能。
|
||||
|
||||
**基础 URL:** `http://localhost:8000` (开发环境)
|
||||
|
||||
**API 文档:**
|
||||
- Swagger UI: http://localhost:8000/docs
|
||||
- ReDoc: http://localhost:8000/redoc
|
||||
|
||||
---
|
||||
|
||||
## 🔐 认证流程
|
||||
|
||||
### 1. 注册用户
|
||||
|
||||
```http
|
||||
POST /api/v1/auth/register
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"email": "user@example.com",
|
||||
"password": "SecurePass123",
|
||||
"username": "myusername",
|
||||
"display_name": "My Name"
|
||||
}
|
||||
```
|
||||
|
||||
**响应:**
|
||||
```json
|
||||
{
|
||||
"user_id": "abc123...",
|
||||
"email": "user@example.com",
|
||||
"username": "myusername",
|
||||
"display_name": "My Name",
|
||||
"email_verification_sent": true
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 验证邮箱
|
||||
|
||||
点击邮件中的链接，或访问：
|
||||
```http
|
||||
GET /api/v1/auth/verify-email?token=VERIFICATION_TOKEN
|
||||
```
|
||||
|
||||
### 3. 登录
|
||||
|
||||
```http
|
||||
POST /api/v1/auth/login
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"email": "user@example.com",
|
||||
"password": "SecurePass123"
|
||||
}
|
||||
```
|
||||
|
||||
**响应:**
|
||||
```json
|
||||
{
|
||||
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
|
||||
"refresh_token": "abc123...",
|
||||
"token_type": "bearer",
|
||||
"user_id": "...",
|
||||
"email": "user@example.com",
|
||||
"username": "myusername",
|
||||
"display_name": "My Name",
|
||||
"expires_in": 1800
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 使用 Access Token
|
||||
|
||||
在所有需要认证的接口中添加 Header：
|
||||
```http
|
||||
Authorization: Bearer YOUR_ACCESS_TOKEN
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🏢 工作空间管理
|
||||
|
||||
### 1. 创建工作空间
|
||||
|
||||
```http
|
||||
POST /api/v1/workspaces
|
||||
Authorization: Bearer YOUR_TOKEN
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"name": "我的团队",
|
||||
"subscription_plan": "free"
|
||||
}
|
||||
```
|
||||
|
||||
**响应:**
|
||||
```json
|
||||
{
|
||||
"workspace_id": "ws123...",
|
||||
"name": "我的团队",
|
||||
"subscription_plan": "free",
|
||||
"max_projects": 3,
|
||||
"max_storage_gb": 10
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 获取工作空间列表
|
||||
|
||||
```http
|
||||
GET /api/v1/workspaces
|
||||
Authorization: Bearer YOUR_TOKEN
|
||||
```
|
||||
|
||||
**响应:**
|
||||
```json
|
||||
{
|
||||
"workspaces": [
|
||||
{
|
||||
"workspace_id": "ws123...",
|
||||
"name": "我的团队",
|
||||
"subscription_plan": "free",
|
||||
"max_projects": 3,
|
||||
"max_storage_gb": 10,
|
||||
"member_count": 1,
|
||||
"user_role": "owner"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 获取工作空间详情
|
||||
|
||||
```http
|
||||
GET /api/v1/workspaces/{workspace_id}
|
||||
Authorization: Bearer YOUR_TOKEN
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 👥 成员管理
|
||||
|
||||
### 1. 邀请成员
|
||||
|
||||
```http
|
||||
POST /api/v1/workspaces/{workspace_id}/members/invite
|
||||
Authorization: Bearer YOUR_TOKEN
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"email": "member@example.com",
|
||||
"role": "member"
|
||||
}
|
||||
```
|
||||
|
||||
**角色类型:**
|
||||
- `owner` - 所有者（自动分配，不可邀请）
|
||||
- `admin` - 管理员
|
||||
- `member` - 成员
|
||||
- `viewer` - 查看者
|
||||
|
||||
### 2. 获取成员列表
|
||||
|
||||
```http
|
||||
GET /api/v1/workspaces/{workspace_id}/members
|
||||
Authorization: Bearer YOUR_TOKEN
|
||||
```
|
||||
|
||||
### 3. 修改成员角色
|
||||
|
||||
```http
|
||||
PATCH /api/v1/workspaces/{workspace_id}/members/{user_id}/role
|
||||
Authorization: Bearer YOUR_TOKEN
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"role": "admin"
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 移除成员
|
||||
|
||||
```http
|
||||
DELETE /api/v1/workspaces/{workspace_id}/members/{user_id}
|
||||
Authorization: Bearer YOUR_TOKEN
|
||||
```
|
||||
|
||||
### 5. 离开工作空间
|
||||
|
||||
```http
|
||||
POST /api/v1/workspaces/{workspace_id}/leave
|
||||
Authorization: Bearer YOUR_TOKEN
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎟️ 邀请管理
|
||||
|
||||
### 1. 接受邀请
|
||||
|
||||
```http
|
||||
POST /api/v1/workspaces/invitations/{token}/accept
|
||||
Authorization: Bearer YOUR_TOKEN
|
||||
```
|
||||
|
||||
### 2. 拒绝邀请
|
||||
|
||||
```http
|
||||
POST /api/v1/workspaces/invitations/{token}/decline
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💳 订阅管理
|
||||
|
||||
### 1. 升级订阅
|
||||
|
||||
```http
|
||||
POST /api/v1/workspaces/{workspace_id}/subscription/upgrade
|
||||
Authorization: Bearer YOUR_TOKEN
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"new_plan": "pro"
|
||||
}
|
||||
```
|
||||
|
||||
**订阅计划:**
|
||||
- `free` - 免费版（3 projects, 10GB）
|
||||
- `pro` - 专业版（无限 projects, 100GB）
|
||||
- `enterprise` - 企业版（无限 projects, 1TB）
|
||||
|
||||
### 2. 取消订阅
|
||||
|
||||
```http
|
||||
POST /api/v1/workspaces/{workspace_id}/subscription/cancel
|
||||
Authorization: Bearer YOUR_TOKEN
|
||||
```
|
||||
|
||||
### 3. 查看配额状态
|
||||
|
||||
```http
|
||||
GET /api/v1/workspaces/{workspace_id}/quota
|
||||
Authorization: Bearer YOUR_TOKEN
|
||||
```
|
||||
|
||||
**响应:**
|
||||
```json
|
||||
{
|
||||
"workspace_id": "ws123...",
|
||||
"subscription_plan": "free",
|
||||
"projects": {
|
||||
"used": 2,
|
||||
"limit": 3,
|
||||
"unlimited": false,
|
||||
"usage_percent": 66.67
|
||||
},
|
||||
"storage": {
|
||||
"used_gb": 5.5,
|
||||
"limit_gb": 10,
|
||||
"remaining_gb": 4.5,
|
||||
"usage_percent": 55.0
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔑 密码管理
|
||||
|
||||
### 1. 忘记密码
|
||||
|
||||
```http
|
||||
POST /api/v1/auth/password/forgot
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"email": "user@example.com"
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 重置密码
|
||||
|
||||
```http
|
||||
POST /api/v1/auth/password/reset
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"token": "RESET_TOKEN_FROM_EMAIL",
|
||||
"new_password": "NewSecurePass123"
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 登出
|
||||
|
||||
```http
|
||||
POST /api/v1/auth/logout
|
||||
Authorization: Bearer YOUR_TOKEN
|
||||
```
|
||||
|
||||
**登出所有设备:**
|
||||
```http
|
||||
POST /api/v1/auth/logout?logout_all_devices=true
|
||||
Authorization: Bearer YOUR_TOKEN
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 错误处理
|
||||
|
||||
所有错误响应遵循统一格式：
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": "ERROR_CODE",
|
||||
"message": "Human readable error message",
|
||||
"details": [] // 可选，仅在验证错误时出现
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**常见错误码:**
|
||||
- `AUTH_ERROR` - 认证失败
|
||||
- `PERMISSION_DENIED` - 权限不足
|
||||
- `NOT_FOUND` - 资源不存在
|
||||
- `VALIDATION_ERROR` - 请求验证失败
|
||||
- `RATE_LIMIT_EXCEEDED` - 请求过于频繁
|
||||
- `INTERNAL_ERROR` - 服务器内部错误
|
||||
|
||||
**HTTP 状态码:**
|
||||
- `200` - 成功
|
||||
- `201` - 创建成功
|
||||
- `204` - 成功（无内容）
|
||||
- `400` - 请求错误
|
||||
- `401` - 未认证
|
||||
- `403` - 权限不足
|
||||
- `404` - 资源不存在
|
||||
- `422` - 验证失败
|
||||
- `429` - 请求过于频繁
|
||||
- `500` - 服务器错误
|
||||
|
||||
---
|
||||
|
||||
## 🚀 最佳实践
|
||||
|
||||
### 1. Token 管理
|
||||
|
||||
- Access Token 有效期 30 分钟
|
||||
- Refresh Token 有效期 30 天
|
||||
- Token 过期时自动使用 Refresh Token 获取新的 Access Token
|
||||
- 在登出时清除本地存储的 Token
|
||||
|
||||
### 2. 错误处理
|
||||
|
||||
```javascript
|
||||
try {
|
||||
const response = await fetch('/api/v1/workspaces', {
|
||||
headers: {
|
||||
'Authorization': `Bearer ${accessToken}`,
|
||||
'Content-Type': 'application/json'
|
||||
}
|
||||
});
|
||||
|
||||
if (!response.ok) {
|
||||
const error = await response.json();
|
||||
console.error(`Error: ${error.error.code} - ${error.error.message}`);
|
||||
}
|
||||
|
||||
const data = await response.json();
|
||||
return data;
|
||||
} catch (error) {
|
||||
console.error('Network error:', error);
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 分页
|
||||
|
||||
目前 API 不支持分页，返回所有结果。后续版本将添加分页支持。
|
||||
|
||||
### 4. 速率限制
|
||||
|
||||
- 默认限制：100 请求/分钟（每个 IP）
|
||||
- 超出限制返回 429 错误
|
||||
- 响应头包含：
|
||||
- `X-RateLimit-Limit` - 限制数量
|
||||
- `X-RateLimit-Remaining` - 剩余请求数
|
||||
|
||||
---
|
||||
|
||||
## 🧪 测试环境
|
||||
|
||||
**测试账号:**
|
||||
```
|
||||
Email: demo@example.com
|
||||
Password: Demo123456
|
||||
```
|
||||
|
||||
**测试工作空间:**
|
||||
```
|
||||
Workspace ID: ws-demo-001
|
||||
Name: Demo Workspace
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📞 技术支持
|
||||
|
||||
- **文档:** http://localhost:8000/docs
|
||||
- **问题反馈:** GitHub Issues
|
||||
- **邮箱:** support@xiaoxia-saas.com
|
||||
|
||||
---
|
||||
|
||||
**最后更新:** 2026-06-17
|
||||
Reference in New Issue
Block a user