# 小虾 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