# API 接口文档（v1）- ImageForge

面向两类使用者：
- **网站（Web）**：上传/批量/历史/账单等（可能包含匿名试用）。
- **对外 API（Developer API）**：API Key 调用、可计量可计费、适配 CI/CD 与服务端集成。

产品范围与计费口径见：
- `docs/prd.md`
- `docs/billing.md`

---

## 1. 基础信息

- **Base URL**: `https://your-domain.com/api/v1`
- **数据格式**: JSON（除明确标注“返回二进制”接口）
- **时间格式**: ISO 8601 / UTC（如：`2025-01-15T10:30:00Z`）
- **ID 格式**: UUID 字符串

---

## 2. 认证

支持三种身份：

### 2.1 JWT（网站/管理后台）
```http
Authorization: Bearer <token>
```

### 2.2 API Key（对外 API）
```http
X-API-Key: <your-api-key>
```

> **注意**：仅 **Pro** 和 **Business** 套餐用户可创建 API Key。Free 用户尝试创建时返回 `FORBIDDEN`（HTTP `403`）。

### 2.3 匿名试用（仅网站场景）
- 不提供 API Key；
- 通过 Cookie 维持匿名会话（服务端签发），仅允许较小文件与较低频率。
- 每日 10 次（以成功压缩文件数计）；超出返回 `QUOTA_EXCEEDED`（HTTP `402`）。
- 日界：自然日（UTC+8），次日 00:00 重置。
- **匿名试用硬限制：Cookie + IP 双限制**（两者任一超出都拒绝），降低刷会话绕过风险。

---

## 3. 通用约定

### 3.1 幂等（强烈建议）
对会产生计费/创建任务的接口，建议客户端传：
```http
Idempotency-Key: <uuid-or-random-string>
```

规则（建议口径）：
- 同一个 `Idempotency-Key` 在 TTL 内重复请求，若请求参数一致则返回首次结果（不重复扣费/不重复创建任务）。
- 若参数不一致，返回 `409 IDEMPOTENCY_CONFLICT`。

### 3.2 限流（Rate Limit）
超出限制返回：
- HTTP `429`
- 头：`Retry-After: <seconds>`

建议头（可选）：
- `RateLimit-Limit`
- `RateLimit-Remaining`
- `RateLimit-Reset`

### 3.3 配额（Quota / Billing）
配额不足（当期额度耗尽）返回：
- HTTP `402`
- 错误码：`QUOTA_EXCEEDED`

配额周期：
- Pro/Business（付费）：按订阅周期重置（`period_start` ~ `period_end`），不是自然月。
- Free（未订阅）：按自然月（UTC+8）重置。
- 匿名试用：按自然日（UTC+8）重置。

建议头（可选）：
- `X-Quota-Limit`
- `X-Quota-Remaining`
- `X-Quota-Reset-At`

### 3.4 通用响应格式（JSON）
成功：
```json
{ "success": true, "data": {} }
```

错误：
```json
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "错误描述",
    "request_id": "req_..."
  }
}
```

### 3.5 错误码（建议集合）
| 错误码 | HTTP | 说明 |
|---|---:|---|
| `INVALID_REQUEST` | 400 | 参数不合法 |
| `INVALID_IMAGE` | 400 | 图片解码失败/文件损坏 |
| `UNSUPPORTED_FORMAT` | 400 | 不支持的格式 |
| `TOO_MANY_PIXELS` | 400 | 像素超限（防图片炸弹） |
| `UNAUTHORIZED` | 401 | 未认证 |
| `FORBIDDEN` | 403 | 权限不足 |
| `NOT_FOUND` | 404 | 资源不存在 |
| `IDEMPOTENCY_CONFLICT` | 409 | 幂等 key 冲突 |
| `QUOTA_EXCEEDED` | 402 | 配额不足 |
| `FILE_TOO_LARGE` | 413 | 文件过大 |
| `RATE_LIMITED` | 429 | 请求过于频繁 |
| `EMAIL_NOT_VERIFIED` | 403 | 邮箱未验证 |
| `INVALID_TOKEN` | 400 | Token 无效或已过期 |
| `COMPRESSION_FAILED` | 500 | 压缩失败 |
| `STORAGE_UNAVAILABLE` | 503 | 存储不可用 |
| `MAIL_SEND_FAILED` | 500 | 邮件发送失败 |

---

## 4. 认证接口

### 4.1 用户注册
```http
POST /auth/register
Content-Type: application/json
```

请求体：
```json
{ "email": "user@example.com", "password": "securepassword123", "username": "myusername" }
```

响应：
```json
{
  "success": true,
  "data": {
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "user@example.com",
      "username": "myusername",
      "email_verified": false,
      "created_at": "2025-01-15T10:30:00Z"
    },
    "token": "eyJhbGciOi...",
    "message": "注册成功，验证邮件已发送至您的邮箱"
  }
}
```

> **注意**：注册后自动发送验证邮件。用户需验证邮箱后才能使用压缩功能（未验证时调用压缩接口返回 `EMAIL_NOT_VERIFIED`）。

### 4.2 用户登录
```http
POST /auth/login
Content-Type: application/json
```

请求体：
```json
{ "email": "user@example.com", "password": "securepassword123" }
```

响应：
```json
{
  "success": true,
  "data": {
    "token": "eyJhbGciOi...",
    "expires_at": "2025-01-22T10:30:00Z",
    "user": { "id": "550e8400-e29b-41d4-a716-446655440000", "email": "user@example.com", "username": "myusername", "role": "user" }
  }
}
```

### 4.3 刷新 Token
```http
POST /auth/refresh
Authorization: Bearer <token>
```

### 4.4 登出
```http
POST /auth/logout
Authorization: Bearer <token>
```

### 4.5 发送验证邮件
用户注册后自动发送一次；此接口用于重新发送。

```http
POST /auth/send-verification
Authorization: Bearer <token>
```

**限流**：同一用户 1 分钟内最多 1 次

响应：
```json
{ "success": true, "data": { "message": "验证邮件已发送，请查收" } }
```

### 4.6 验证邮箱
```http
POST /auth/verify-email
Content-Type: application/json
```

请求体：
```json
{ "token": "verification-token-from-email" }
```

响应：
```json
{ "success": true, "data": { "message": "邮箱验证成功" } }
```

### 4.7 请求密码重置
```http
POST /auth/forgot-password
Content-Type: application/json
```

请求体：
```json
{ "email": "user@example.com" }
```

**限流**：同一 IP 1 分钟内最多 3 次

响应（无论邮箱是否存在都返回成功，防止枚举）：
```json
{ "success": true, "data": { "message": "如果该邮箱已注册，您将收到重置邮件" } }
```

### 4.8 重置密码
```http
POST /auth/reset-password
Content-Type: application/json
```

请求体：
```json
{ "token": "reset-token-from-email", "new_password": "new-secure-password" }
```

响应：
```json
{ "success": true, "data": { "message": "密码重置成功，请重新登录" } }
```

---

## 5. 图片压缩接口

### 5.1 单图压缩（同步，返回 JSON + 下载链接）
适用于网站与轻量同步调用（服务端可选择是否落盘/落对象存储）。

```http
POST /compress
Content-Type: multipart/form-data
Authorization: Bearer <token>   # 或 X-API-Key；网站匿名试用可不带
Idempotency-Key: <key>          # 建议
```

表单字段：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---:|---|
| `file` | File | 是 | 图片文件 |
| `compression_rate` | Integer | 否 | 压缩率 1-100（数值越大压缩越强），优先级高于 `level` |
| `level` | String | 否 | `high` / `medium` / `low`（兼容参数，默认 `medium`） |
| `output_format` | String | 否 | 已停用，仅支持保持原格式 |
| `max_width` | Integer | 否 | 最大宽度（等比缩放） |
| `max_height` | Integer | 否 | 最大高度（等比缩放） |
| `preserve_metadata` | Boolean | 否 | 是否保留元数据（默认 `false`） |

响应：
```json
{
  "success": true,
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440100",
    "file_id": "550e8400-e29b-41d4-a716-446655440101",
    "format_in": "png",
    "format_out": "png",
    "original_size": 1024000,
    "compressed_size": 256000,
    "saved_bytes": 768000,
    "saved_percent": 75.0,
    "download_url": "/downloads/550e8400-e29b-41d4-a716-446655440101",
    "expires_at": "2025-01-15T11:30:00Z",
    "billing": { "units_charged": 1 }
  }
}
```

### 5.2 单图压缩（同步，直接返回二进制）
更贴近开发者体验，适用于 SDK/CI。

```http
POST /compress/direct
Content-Type: multipart/form-data
X-API-Key: <your-api-key>        # 或 Bearer token（不建议匿名）
Idempotency-Key: <key>           # 建议
```

成功响应：
- HTTP `200`
- Body：压缩后的图片二进制
- `Content-Type`: `image/png` / `image/jpeg` / `image/webp` / `image/avif` / `image/gif` / `image/bmp` / `image/tiff` / `image/x-icon`

建议响应头（示例）：
```http
ImageForge-Original-Size: 1024000
ImageForge-Compressed-Size: 256000
ImageForge-Saved-Bytes: 768000
ImageForge-Saved-Percent: 75.0
ImageForge-Units-Charged: 1
```

### 5.3 批量压缩（异步任务）
适用于多文件或大文件；由 Worker 处理并持续更新进度。

```http
POST /compress/batch
Content-Type: multipart/form-data
Authorization: Bearer <token>    # 或 X-API-Key
Idempotency-Key: <key>           # 建议
```

表单字段：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---:|---|
| `files[]` | File[] | 是 | 图片文件数组（上限由套餐决定） |
| `compression_rate` | Integer | 否 | 压缩率 1-100（数值越大压缩越强），优先级高于 `level` |
| `level` | String | 否 | `high` / `medium` / `low`（兼容参数） |
| `output_format` | String | 否 | 已停用，仅支持保持原格式 |
| `preserve_metadata` | Boolean | 否 | 是否保留元数据（默认 `false`） |

响应：
```json
{
  "success": true,
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440200",
    "total_files": 10,
    "status": "pending",
    "status_url": "/compress/tasks/550e8400-e29b-41d4-a716-446655440200"
  }
}
```

配额规则补充：
- 若本周期剩余单位不足以覆盖本次上传的文件数，服务端应直接返回 `402 QUOTA_EXCEEDED`（不创建任务）。

### 5.4 查询任务状态
```http
GET /compress/tasks/{task_id}
Authorization: Bearer <token>    # 或 X-API-Key；匿名试用需携带 Cookie 会话
```

响应：
```json
{
  "success": true,
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440200",
    "status": "completed",
    "progress": 100,
    "total_files": 10,
    "completed_files": 10,
    "failed_files": 0,
    "files": [
      {
        "file_id": "550e8400-e29b-41d4-a716-446655440201",
        "original_name": "photo1.png",
        "original_size": 1024000,
        "compressed_size": 256000,
        "saved_percent": 75.0,
        "status": "completed",
        "download_url": "/downloads/550e8400-e29b-41d4-a716-446655440201"
      }
    ],
    "download_all_url": "/downloads/tasks/550e8400-e29b-41d4-a716-446655440200",
    "created_at": "2025-01-15T10:30:00Z",
    "completed_at": "2025-01-15T10:31:00Z",
    "expires_at": "2025-01-22T10:30:00Z"
  }
}
```

### 5.5 取消任务（可选）
```http
POST /compress/tasks/{task_id}/cancel
Authorization: Bearer <token>
```

### 5.6 删除任务与文件（隐私/合规）
```http
DELETE /compress/tasks/{task_id}
Authorization: Bearer <token>
```

---

## 6. 下载接口

### 6.1 下载单个文件
```http
GET /downloads/{file_id}
Authorization: Bearer <token>    # 或 X-API-Key；匿名试用需 Cookie 会话
```

### 6.2 下载批量 ZIP
```http
GET /downloads/tasks/{task_id}
Authorization: Bearer <token>    # 或 X-API-Key；匿名试用需 Cookie 会话
```

---

## 7. 用户接口

### 7.1 获取当前用户信息
```http
GET /user/profile
Authorization: Bearer <token>
```

响应（示例）：
```json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "username": "myusername",
    "role": "user"
  }
}
```

### 7.2 更新用户信息
```http
PUT /user/profile
Authorization: Bearer <token>
Content-Type: application/json
```

### 7.3 修改密码
```http
PUT /user/password
Authorization: Bearer <token>
Content-Type: application/json
```

### 7.4 获取压缩历史
```http
GET /user/history?page=1&limit=20
Authorization: Bearer <token>
```

---

## 8. API Key 管理

### 8.1 获取 API Key 列表
```http
GET /user/api-keys
Authorization: Bearer <token>
```

### 8.2 创建 API Key
```http
POST /user/api-keys
Authorization: Bearer <token>
Content-Type: application/json
```

请求体：
```json
{ "name": "Production Server", "permissions": ["compress", "batch_compress"] }
```

响应：
```json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440300",
    "name": "Production Server",
    "key": "if_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "message": "请保存此 Key，它只会显示一次"
  }
}
```

### 8.3 轮换 API Key（可选）
```http
POST /user/api-keys/{key_id}/rotate
Authorization: Bearer <token>
```

### 8.4 删除/禁用 API Key
```http
DELETE /user/api-keys/{key_id}
Authorization: Bearer <token>
```

---

## 9. 计费与用量（Billing）

### 9.1 获取套餐列表（公开）
```http
GET /billing/plans
```

响应（示例）：
```json
{
  "success": true,
  "data": {
    "plans": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440900",
        "code": "pro_monthly",
        "name": "Pro（月付）",
        "currency": "CNY",
        "amount_cents": 1999,
        "interval": "monthly",
        "included_units_per_period": 10000,
        "max_file_size_mb": 20,
        "max_files_per_batch": 50,
        "retention_days": 7,
        "features": { "webhook": true }
      }
    ]
  }
}
```

### 9.2 获取当前订阅
```http
GET /billing/subscription
Authorization: Bearer <token>
```

### 9.3 获取当期用量
```http
GET /billing/usage
Authorization: Bearer <token>
```

响应：
```json
{
  "success": true,
  "data": {
    "period_start": "2025-01-01T00:00:00Z",
    "period_end": "2025-02-01T00:00:00Z",
    "used_units": 120,
    "included_units": 10000,
    "bonus_units": 500,
    "total_units": 10500,
    "remaining_units": 10380
  }
}
```

### 9.4 创建 Checkout（订阅/升级）
```http
POST /billing/checkout
Authorization: Bearer <token>
Content-Type: application/json
Idempotency-Key: <key>
```

请求体：
```json
{ "plan_id": "550e8400-e29b-41d4-a716-446655440900" }
```

响应：
```json
{ "success": true, "data": { "checkout_url": "https://pay.example.com/..." } }
```

### 9.5 打开客户 Portal（管理支付方式/取消订阅）
```http
POST /billing/portal
Authorization: Bearer <token>
```

### 9.6 发票列表
```http
GET /billing/invoices?page=1&limit=20
Authorization: Bearer <token>
```

---

## 10. Webhooks（支付回调）

> 无需登录；必须验签与幂等处理，详见 `docs/billing.md` 与 `docs/security.md`。

### 10.1 Stripe 回调（示例）
```http
POST /webhooks/stripe
Content-Type: application/json
Stripe-Signature: t=...,v1=...
```

---

## 11. 管理员接口

> 需要管理员权限（`role: admin`）

### 11.1 获取系统统计
```http
GET /admin/stats
Authorization: Bearer <admin_token>
```

### 11.2 用户管理（示例）
```http
GET /admin/users?page=1&limit=20&search=keyword
Authorization: Bearer <admin_token>
```

### 11.3 系统配置
```http
GET /admin/config
Authorization: Bearer <admin_token>
```

```http
PUT /admin/config
Authorization: Bearer <admin_token>
Content-Type: application/json
```

### 11.4 任务管理
```http
GET /admin/tasks?status=processing&page=1
Authorization: Bearer <admin_token>
```

```http
POST /admin/tasks/{task_id}/cancel
Authorization: Bearer <admin_token>
```

### 11.5 计费管理（建议）
```http
GET /admin/billing/subscriptions?page=1&limit=20
Authorization: Bearer <admin_token>
```

```http
POST /admin/billing/credits
Authorization: Bearer <admin_token>
Content-Type: application/json
```

---

## 12. WebSocket（网站任务进度）

网站侧可用 WebSocket 或 SSE（SSE 更易穿透代理）。当前先保留 WebSocket 方案：

```
ws://your-domain.com/ws/tasks/{task_id}?token=<jwt_token>
```

消息（示例）：
```json
{ "type": "progress", "data": { "task_id": "550e8400-e29b-41d4-a716-446655440200", "progress": 50, "completed_files": 5 } }
```