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
@@ -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