# API 更新日志

本文档记录 EaseBG API 的所有版本变更，包括新增接口、废弃接口、行为变更和修复。

---

## v2.0.0 — 2025-07-17

### 重大变更 (Breaking Changes)

- **统一 API 路径前缀**：所有接口统一使用 `/api/v1` 前缀
  - 旧版 `/v1/tasks` → 新版 `/api/v1/open/developer/tasks`
  - 旧版 `/v1/batch` → 新版 `/api/v1/open/developer/batch-tasks`
- **认证方式统一**：
  - 开发者 API 使用 `X-API-Key` Header
  - App/Web API 使用 `Authorization: Bearer <JWT>`
  - Admin API 使用 `Authorization: Bearer <JWT>` + 2FA
  - Internal API 使用 `X-Internal-Token` Header
- **错误响应格式统一**：所有错误响应采用 `{ request_id, error: { code, message, details } }` 格式
- **SSE 连接方式变更**：从 `EventSource` + `withCredentials` 改为 `?token=` query 参数认证

### 新增接口

- `POST /api/v1/open/developer/tasks` — 创建抠图任务
- `GET /api/v1/open/developer/tasks` — 查询任务列表（支持分页、状态筛选）
- `GET /api/v1/open/developer/tasks/{taskId}` — 查询单个任务
- `DELETE /api/v1/open/developer/tasks/{taskId}` — 取消任务
- `POST /api/v1/open/developer/tasks/{taskId}/retry` — 重试任务
- `POST /api/v1/open/developer/batch-tasks` — 创建批量任务
- `GET /api/v1/open/developer/batch-tasks` — 查询批量任务列表
- `GET /api/v1/open/developer/batch-tasks/{batchId}` — 查询单个批量任务
- `GET /api/v1/open/developer/webhooks` — 查询 Webhook 端点
- `POST /api/v1/open/developer/webhooks` — 创建 Webhook 端点
- `GET /api/v1/open/developer/api-keys` — 查询 API Key 列表
- `GET /api/v1/open/developer/usage` — 查询用量统计
- `POST /api/v1/app/auth/register` — 用户注册
- `POST /api/v1/app/auth/login` — 用户登录
- `POST /api/v1/app/auth/google` — Google OAuth 登录
- `POST /api/v1/app/auth/refresh` — 刷新令牌
- `POST /api/v1/app/auth/logout` — 退出登录
- `GET /api/v1/app/users/profile` — 获取用户资料
- `PUT /api/v1/app/users/profile` — 更新用户资料
- `GET /api/v1/app/users/subscription` — 获取当前订阅
- `GET /api/v1/app/users/login-events` — 获取登录历史
- `GET /api/v1/app/credits/balance` — 获取积分余额
- `GET /api/v1/app/credits/ledger` — 获取积分流水
- `GET /api/v1/app/notifications` — 获取通知列表
- `POST /api/v1/app/notifications/{id}/read` — 标记通知已读
- `GET /api/v1/app/referral/info` — 获取推荐信息
- `GET /api/v1/app/teams` — 获取团队信息
- `POST /api/v1/app/teams` — 创建团队
- `POST /api/v1/admin/auth/login` — 管理员登录（支持 2FA）
- `GET /api/v1/admin/dashboard` — 获取仪表盘数据
- `GET /api/v1/admin/users` — 获取用户列表
- `PATCH /api/v1/admin/users/{userId}/status` — 变更用户状态
- `POST /api/v1/admin/users/{userId}/reset-password` — 重置用户密码
- `GET /api/v1/admin/tasks` — 获取任务列表
- `POST /api/v1/admin/tasks/{taskId}/retry` — 重试任务
- `GET /api/v1/admin/tasks/nodes` — 获取工作节点列表
- `GET /api/v1/admin/payments/orders` — 获取订单列表
- `GET /api/v1/admin/payments/refunds` — 获取退款列表
- `POST /api/v1/admin/payments/refunds/{refundId}/approve` — 批准退款
- `GET /api/v1/admin/credits/adjustments` — 获取积分调整列表（别名）
- `POST /api/v1/admin/credit-adjustments` — 创建积分调整
- `POST /api/v1/internal/tasks/{jobId}/status` — 更新任务状态
- `POST /api/v1/internal/tasks/{jobId}/progress` — 更新任务进度
- `POST /api/v1/internal/tasks/callback` — 推理服务任务完成回调
- `POST /api/v1/internal/worker/register` — 注册工作节点
- `POST /api/v1/internal/worker/{nodeId}/heartbeat` — 工作节点心跳（旧版）
- `POST /api/v1/internal/nodes/heartbeat` — 推理节点心跳上报（新版）
- `POST /api/v1/internal/nodes/metrics` — 推理节点指标上报
- `GET /api/v1/internal/config/{key}` — 读取系统配置
- `POST /api/v1/internal/payments/{orderId}/success` — 支付成功回调
- `POST /api/v1/internal/refunds/{refundId}/completed` — 退款完成回调

### 废弃接口

- `GET /v1/tasks` — 废弃，请使用 `GET /api/v1/open/developer/tasks`
- `POST /v1/tasks` — 废弃，请使用 `POST /api/v1/open/developer/tasks`
- `GET /v1/tasks/{id}` — 废弃，请使用 `GET /api/v1/open/developer/tasks/{taskId}`
- `DELETE /v1/tasks/{id}` — 废弃，请使用 `DELETE /api/v1/open/developer/tasks/{taskId}`

### 行为变更

- **速率限制**：按套餐分级限制（Free: 10/min, Pro: 60/min, Team: 200/min, Enterprise: 1000/min）
- **批量任务上限**：单次最多 50 张图片
- **Webhook 签名**：统一使用 HMAC-SHA256，Header 为 `X-EaseBG-Signature`
- **任务超时**：单任务最长处理时间 120 秒，超时自动标记为 failed
- **结果 URL 有效期**：处理结果 URL 有效期 7 天，过期后需重新生成

### 修复

- 修复了批量任务中部分任务失败时整体状态不正确的问题
- 修复了 Webhook 重试可能导致重复推送的问题（增加幂等性检查）
- 修复了积分扣减在高并发场景下的竞态条件

---

## v1.5.0 — 2025-03-15（已废弃）

### 新增

- 新增 Google OAuth 登录支持
- 新增团队协作功能
- 新增批量处理接口

### 废弃

- 旧版 `/v1/tasks` 系列接口标记为 deprecated

---

## v1.0.0 — 2024-09-01（已废弃）

### 初始发布

- 基础抠图任务 API
- API Key 鉴权
- Webhook 回调
- cURL / JavaScript / Python 示例