# 注册机接入与邮箱池 API 文档

## 📖 概览 Overview

本文档描述邮箱池管理系统的公开 API，供注册机业务方、脚本接入方使用。

**服务定位**：为注册机提供邮箱领取、状态回传、池管理等功能。

**数据格式**：所有请求和响应均使用 JSON 格式。

**支持 CORS**：支持跨域请求。

---

## 🔐 鉴权与通用规则

### API Key 获取

联系系统管理员获取 API Key，在请求头中携带：

```
Authorization: Bearer YOUR_API_KEY
```

**测试环境**：联系管理员获取测试 Key（调用限制：100 次/分钟）

### 统一响应格式

所有接口遵循统一的响应格式：

```json
{
  "success": true,
  "data": { ... },
  "message": "操作成功"
}
```

失败时：

```json
{
  "success": false,
  "error": "error_code",
  "message": "错误描述"
}
```

### 时间字段约定

所有时间字段使用 ISO 8601 格式：`YYYY-MM-DDTHH:MM:SSZ`

---

## 📋 API 端点列表

### 快速开始

注册机接入只需关注以下 3 个核心接口：

| 接口 | 用途 | 必要性 |
|------|------|--------|
| `POST /api/pool/claim-random` | 领取邮箱 | 必需 |
| `POST /api/pool/claim-complete` | 完成任务回传 | 必需 |
| `POST /api/pool/claim-release` | 释放邮箱 | 必需 |
| `GET /api/pool/stats` | 查看池状态 | 可选 |

---

## 1️⃣ 领取邮箱

### 基本信息

```
POST /api/pool/claim-random
需要鉴权：是
```

### 请求示例

```bash
curl -X POST https://api.example.com/api/pool/claim-random \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "caller_id": "register-worker-1",
    "task_id": "job-20260317-0001",
    "provider": "outlook"
  }'
```

### 参数说明

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `caller_id` | string | 是 | 调用方标识，建议使用固定的业务方标识或机器标识，如：`register-worker-1`、`register-cluster-a` |
| `task_id` | string | 是 | 当前注册任务的唯一 ID，如：`job-20260317-0001`、`order-928371` |
| `provider` | string | 否 | 邮箱提供商筛选，传 `outlook` 则只领取 Outlook 邮箱 |

### 成功响应示例

```json
{
  "success": true,
  "data": {
    "account_id": 12,
    "email": "demo@outlook.com",
    "claim_token": "clm_xxxxx",
    "lease_expires_at": "2026-03-17T10:00:00Z"
  },
  "message": "邮箱领取成功"
}
```

### 响应字段说明

| 字段名 | 类型 | 说明 |
|--------|------|------|
| `account_id` | integer | 账号 ID，回传时必需 |
| `email` | string | 邮箱地址 |
| `claim_token` | string | 领取令牌，回传时必需 |
| `lease_expires_at` | string | 租约过期时间，过期前需完成回传或释放 |

### 失败响应示例

```json
{
  "success": false,
  "error": "no_available_account",
  "message": "池中没有符合条件的可用邮箱"
}
```

---

## 2️⃣ 完成任务并回传结果

### 基本信息

```
POST /api/pool/claim-complete
需要鉴权：是
```

### 请求示例

```bash
curl -X POST https://api.example.com/api/pool/claim-complete \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": 12,
    "claim_token": "clm_xxxxx",
    "caller_id": "register-worker-1",
    "task_id": "job-20260317-0001",
    "result": "success",
    "detail": "注册成功"
  }'
```

### 参数说明

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `account_id` | integer | 是 | 领取时返回的账号 ID |
| `claim_token` | string | 是 | 领取时返回的令牌 |
| `caller_id` | string | 是 | 必须与领取时的 `caller_id` 一致 |
| `task_id` | string | 是 | 必须与领取时的 `task_id` 一致 |
| `result` | string | 是 | 任务结果，见下方【result 可选值】 |
| `detail` | string | 否 | 详细说明，建议填写失败原因、目标站名称、风控现象等 |

### result 可选值及对应状态

| result 值 | 说明 | 邮箱最终状态 | 使用场景 |
|-----------|------|--------------|----------|
| `success` | 注册成功，账号已消耗 | `used` | 成功完成注册任务 |
| `verification_timeout` | 未收到验证码 | `cooldown` | 长时间未收到验证码，建议冷却后再试 |
| `provider_blocked` | 被供应商风控 | `frozen` | 供应商风控、被封、被限制 |
| `credential_invalid` | 凭据失效 | `retired` | 邮箱密码或凭据已失效 |
| `network_error` | 网络故障 | `available` | 网络问题、临时故障，可立即重试 |

### 成功响应示例

```json
{
  "success": true,
  "data": {
    "account_id": 12,
    "pool_status": "used"
  },
  "message": "结果回传成功"
}
```

### 失败响应示例

```json
{
  "success": false,
  "error": "invalid_claim",
  "message": "claim_token 已失效或与 account_id 不匹配"
}
```

---

## 3️⃣ 释放邮箱

### 基本信息

```
POST /api/pool/claim-release
需要鉴权：是
```

### 请求示例

```bash
curl -X POST https://api.example.com/api/pool/claim-release \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": 12,
    "claim_token": "clm_xxxxx",
    "caller_id": "register-worker-1",
    "task_id": "job-20260317-0001",
    "reason": "任务取消"
  }'
```

### 参数说明

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `account_id` | integer | 是 | 领取时返回的账号 ID |
| `claim_token` | string | 是 | 领取时返回的令牌 |
| `caller_id` | string | 是 | 必须与领取时一致 |
| `task_id` | string | 是 | 必须与领取时一致 |
| `reason` | string | 否 | 释放原因 |

### 成功响应示例

```json
{
  "success": true,
  "data": {
    "account_id": 12,
    "pool_status": "available"
  },
  "message": "邮箱已释放回池"
}
```

---

## 4️⃣ 查看池状态

### 基本信息

```
GET /api/pool/stats
需要鉴权：是
```

### 请求示例

```bash
curl -X GET https://api.example.com/api/pool/stats \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### 成功响应示例

```json
{
  "success": true,
  "data": {
    "total": 1000,
    "available": 850,
    "claimed": 120,
    "used": 20,
    "cooldown": 5,
    "frozen": 3,
    "retired": 2
  },
  "message": "查询成功"
}
```

---

## ⚠️ 错误处理

### HTTP 状态码一览

| 状态码 | 说明 |
|--------|------|
| 200 | 请求成功 |
| 400 | 请求参数错误 |
| 401 | 未授权（缺少或无效的 API Key） |
| 403 | 禁止访问 |
| 404 | 资源不存在 |
| 429 | 请求频率超限 |
| 500 | 服务器内部错误 |

### 常见错误响应

#### 缺少 API Key

```json
{
  "success": false,
  "error": "missing_api_key",
  "message": "请在请求头中携带 Authorization: Bearer YOUR_API_KEY"
}
```

#### 请求频率超限

```json
{
  "success": false,
  "error": "rate_limit_exceeded",
  "message": "请求频率超限，请稍后重试"
}
```

#### 无可用邮箱

```json
{
  "success": false,
  "error": "no_available_account",
  "message": "池中没有符合条件的可用邮箱"
}
```

#### claim_token 不匹配

```json
{
  "success": false,
  "error": "invalid_claim",
  "message": "claim_token 已失效或与 account_id 不匹配"
}
```

---

## 📝 使用限制

### 频率限制

- 领取邮箱：60 次/分钟
- 回传结果：120 次/分钟
- 查询状态：300 次/分钟

### 租约超时

领取邮箱后，必须在 `lease_expires_at` 前完成回传或释放。超时未处理的邮箱将自动释放回池。

### 建议重试策略

- 遇到 `429` 错误时，等待 1 秒后重试
- 遇到 `no_available_account` 时，等待 5-10 秒后重试
- 建议使用指数退避算法

---

## 🔄 业务流程图

```
导入邮箱（add_to_pool=true）
         ↓
邮箱进入池子（status=available）
         ↓
注册机调用 claim-random 领取邮箱
         ↓
注册机执行注册任务
         ↓
    ┌────┴────┐
    ↓         ↓
 成功/失败   中途放弃
    ↓         ↓
claim-complete  claim-release
    ↓         ↓
邮箱状态更新   邮箱返回池子
```

---

## 🎯 常见问题

### Q1: 账号导入了，但注册机领不到？

**原因**：
1. 导入时没有设置 `add_to_pool=true`
2. 账号状态不是 `active` 或不在 `available`

**解决**：检查导入参数，确保账号正确入池。

### Q2: 回传时提示参数不匹配？

**原因**：`account_id`、`claim_token`、`caller_id`、`task_id` 四个字段必须与领取时完全一致。

**解决**：注册机必须保存领取时的原始参数，不能自行修改。

### Q3: 领取后忘记回传会怎样？

**后果**：邮箱会停留在 `claimed` 状态，影响后续分配。

**建议**：
- 成功或失败都调用 `claim-complete`
- 中途放弃调用 `claim-release`

### Q4: 所有失败都回传 `network_error` 会怎样？

**后果**：已失效的邮箱会继续回池，被重复分配，浪费资源。

**建议**：根据实际失败原因选择正确的 `result` 值。

---

## 📞 联系方式

- 问题反馈：[提交 Issue]
---

## 📅 更新日志

### v1.0.0 (2026-03-17)
- 初始版本发布
- 支持邮箱领取、回传、释放、查询功能

---

## 外部接口路径

如果通过外部受控接口调用，路径对应为：

- `/api/external/pool/claim-random`
- `/api/external/pool/claim-complete`
- `/api/external/pool/claim-release`
- `/api/external/pool/stats`

业务含义与内部接口完全一致。