# Gmail 单次注册 API

版本：1.1.0。更新日期：2026-11-21。

前端只需要让用户填写 Gmail 邮箱和邮件中的六位验证码。后端负责选择已配置的代理节点、生成日文姓名和 1980–2005 年的随机生日、注册、激活及兑换邀请码。

## 1. 接入地址与最短流程

| 环境 | Base URL |
| --- | --- |
| 线上 API（卡网后端正式调用） | `https://muse.yufan88.top` |
| 本地服务 | `http://127.0.0.1:8766` |
| 现有 SSH/Tailscale 隧道转发的服务器服务 | `http://127.0.0.1:18766` |
| 在线服务器本机访问注册服务 | `http://127.0.0.1:8766`（须在服务器宿主机上调用） |

**线上正式提交地址：**`https://muse.yufan88.top/api/gmail/registrations`。卡网后端使用该 HTTPS 域名和 Bearer 密钥，无需依赖当前电脑的 SSH 隧道。域名只代理 `/api/gmail/`，HTTP 请求会跳转 HTTPS；带密钥的业务请求应直接使用 HTTPS。

**当前在线部署位置：**服务器 `3.137.204.200`，项目目录 `/opt/muse-protocol`，服务 `muse-jp-reg.service`，实际监听 `127.0.0.1:8766`。现有 Nginx 网关将上述域名转发到注册服务。`http://3.137.204.200:8766` 仍不是已开放的调用地址。

当前电脑通过已有 SSH 隧道访问线上服务时，完整的邮箱提交地址是 `http://127.0.0.1:18766/api/gmail/registrations`。本机测试应使用 `http://127.0.0.1:8766/api/gmail/registrations`，两者对应不同数据库。

在已配置本项目 SSH 别名与密钥的机器上，可用以下命令建立转发；其他机器需要先配置相应的 SSH 连接方式：

```bash
ssh -N -L 18766:127.0.0.1:8766 muse-protocol
```

卡网如果运行在 Docker 容器中，直接使用 `https://muse.yufan88.top`。容器的 `127.0.0.1` 不是宿主机，不要使用容器内的 `127.0.0.1:8766`。本次仅配置域名网关与内部转发，未修改卡网业务源码。

`18766` 需要现有服务器转发隧道保持连接。其他机器通过其实际可达的服务地址调用。注册 API 使用 Bearer 密钥鉴权，由卡网等可信后端调用；浏览器用户只向卡网提交邮箱和验证码。当前没有新增跨域 CORS 放行。

### 卡网后端鉴权与权限

所有 `/api/gmail/registrations` 及其任务、验证码、日志和凭证接口，均须在请求头携带：

```http
Authorization: Bearer <服务密钥>
```

密钥拥有该注册服务的创建任务、查询所有任务、提交验证码、读取任务日志和账号凭证权限。目前是单个服务调用者密钥，没有多租户/用户权限划分，也不能仅凭 `run_id` 当作用户身份凭证。卡网应在自己的后端验证登录或订单权限，并绑定用户与任务 ID；不要把服务密钥、完整账号凭证或任意任务查询入口直接交给浏览器。

| 请求条件 | HTTP | 错误码 |
| --- | --- | --- |
| 缺少、错误或非 Bearer 密钥 | 401 | `unauthorized`，响应带 `WWW-Authenticate: Bearer` |
| 注册服务未配置有效密钥 | 503 | `api_auth_not_configured` |
| 正确密钥 | 按接口业务返回 | 不代表任务一定成功 |

服务读取密钥优先级：环境变量 `MUSE_REG_API_KEY` → `MUSE_REG_API_KEY_FILE` 指定文件 → 项目 `private/gmail-api-key`。密钥文件不进入 Git；不在文档、日志或错误响应中返回密钥。文件每次请求读取，替换文件即可轮换密钥；使用环境变量配置时，需要更新服务环境并重启。卡网自行保存对应密钥，或从受限文件读取。

`GET /api/gmail/docs`、`GET /api/gmail/openapi.json`、`GET /api/gmail/errors` 为公开的文档/字典接口，不返回账号数据。OpenAPI 已声明 HTTP Bearer 鉴权。

**网络发布范围：**鉴权只覆盖新注册业务 API。原 WebUI 使用的 `/api/register`、`/api/runs`、`/api/registered`、代理配置等管理接口保持本地兼容，不在本次服务密钥保护范围。`muse.yufan88.top` 只发布 `/api/gmail/`，访问其他管理路径返回 404。原控制台仍通过本地或 SSH/Tailscale 隧道访问。

卡网正式对接统一配置 `https://muse.yufan88.top`；`127.0.0.1` 始终表示调用方所在机器或容器，不能把本机的 `18766` 转发地址原样当作另一台服务器的地址。密钥保持原值，不会因为增加域名而自动更换。

1. `POST /api/gmail/registrations`，提交 `{"email":"你的邮箱@gmail.com"}`，取得 `run_id`。
2. 每秒 `GET /api/gmail/registrations/{run_id}`，直到 `can_submit_otp=true`。
3. 用户收到邮件后，`POST /api/gmail/registrations/{run_id}/otp`，提交 `{"code":"六位数字"}`。
4. 继续轮询同一个任务，直到 `finished=true`，显示 `feedback`、`warnings` 和 `result`。

**HTTP 202 只代表请求已接收；HTTP 200 只代表查询成功。任务是否完成、账号是否可用，必须判断 `state`、`feedback.code`、`registered` 和 `account_status`。**

六位验证码被上游拒绝时，本轮任务会结束；当前不支持在同一任务中重发邮件或反复尝试不同验证码。仅请求格式错误（例如少于六位）不会结束任务，可以修正后再次提交。请只提交本轮发码收到的验证码。

### 并发与部署限制

不同 Gmail 邮箱支持同时发起注册。每个任务独立运行线程、注册会话及验证码队列，必须使用对应的 `run_id` 提交验证码和查询结果，不能共用某个全局“当前任务 ID”。

- 已通过 4 路并发离线模拟测试：四个任务同时等待验证码，逆序提交不同验证码，均归入各自任务。该测试不代表真实上游允许同出口大量注册，也不代表已测得最大承载量。
- 当前 Gmail API 没有设置并发数量上限或排队机制；调用方应自行限制同时运行的任务数量。
- 并发任务均使用代理池第一个非空节点，共享同一出口；本接口没有按任务分配不同代理，也不执行批量调度器的单 IP 上限轮换策略。
- 同邮箱已有进行中任务时通常返回 `registration_in_progress`，但检查与新建不是原子去重。调用方应防止同一邮箱同时重复创建任务，不能把该检查当作严格幂等保证。
- 验证码队列保存在当前服务进程内。当前使用单进程、多线程支持并发，不支持直接通过多个 Uvicorn worker 或多实例负载均衡扩容。创建与提交验证码必须到达持有该会话的服务进程；跨进程可能收到 `worker_restarted`。

### 验证码超时、填错与重新提交

| 场景 | 当前任务是否结束 | API 行为与前端处理 |
| --- | --- | --- |
| 尚未发码成功就提交 | 否 | HTTP 409 `otp_not_ready`，继续轮询 |
| 不足六位、含非数字或不是字符串 | 否 | HTTP 422 `invalid_otp`；修正格式后可在同一任务重新提交 |
| 提交六位数字，后台正在校验 | 否 | 首次返回 HTTP 202；继续轮询，不能据此认定验证码正确 |
| 处理中重复提交验证码 | 否 | HTTP 409 `otp_already_submitted`；若任务已经结束则为 `run_finished`，若已超时则为 `otp_expired` |
| 六位验证码被上游拒绝 | 是 | 查询反馈 `otp_rejected`，通常 `state=failed`、`finished=true`；核对 detail，不支持原任务换码重试 |
| 已因验证码错误结束后再提交 | 已结束 | HTTP 409 `run_finished`；重新创建任务并使用新一轮邮件验证码 |
| 发码成功后一直未提交，到达等待上限 | 是 | 后台自动结束任务，最终反馈 `otp_timeout`、`finished=true`，清理验证码等待队列，不需要前端轮询触发 |
| 等待超时后才提交 | 已结束或正在完成超时清理 | HTTP 410 `otp_expired`；创建新任务 |
| 正常注册结束后再次提交 | 已结束 | HTTP 409 `run_finished`；读取原任务结果 |

等待上限由 `otp_timeout` 决定，默认 300 秒，可配置 15–900 秒，从发码成功进入等待阶段开始计算。截止时轮询可能先观察到 `state=expired`、反馈 `otp_expired`，随后后台落盘为 `state=failed`、反馈 `otp_timeout`；两种情况均为 `finished=true`，前端都应停止本轮提交。

已经通过真实计时的 15 秒离线超时测试：不查询任务，后台仍会自行结束、移除验证码队列，并拒绝迟到的提交。测试中的邮件发送与上游注册请求使用模拟客户端，不会真实发送邮件或新建账号。

## 2. 接口列表

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| POST | `/api/gmail/registrations` | 创建 Gmail 注册任务 |
| GET | `/api/gmail/registrations/{run_id}` | 查询当前阶段、反馈、截止时间及最终结果 |
| POST | `/api/gmail/registrations/{run_id}/otp` | 提交六位验证码 |
| GET | `/api/gmail/registrations/{run_id}/logs` | 按行分页获取日志，可重复读取 |
| GET | `/api/gmail/errors` | 获取完整错误码、中文反馈、后续操作及阶段字典 |
| GET | `/api/gmail/openapi.json` | 获取这组接口的 OpenAPI 文档，可导入接口工具 |
| GET | `/api/gmail/docs` | 获取本文 Markdown |
| GET | `/api/gmail/registrations/{run_id}/credentials` | 带 Bearer 密钥获取该任务已保存账号的完整凭证 |

原有 `/api/register`、`/api/runs/{run_id}/otp` 和 WebUI 保持兼容。新前端建议统一使用 `/api/gmail/`，以获得稳定的结构化错误响应。

## 3. 创建任务

`POST /api/gmail/registrations`，Content-Type 为 `application/json`。

| 字段 | 类型 | 必填 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| `email` | string | 是 | 无 | `@gmail.com` 或 `@googlemail.com`，自动去首尾空格并转小写 |
| `otp_timeout` | integer | 否 | 300 | 发码成功后的输入等待秒数，范围 15–900 |
| `invite_code` | string | 否 | 空字符串 | 非空时兑换指定码；不填时从现有邀请码池领取 |

请求只支持表中字段，拼错字段会返回 422。后端使用当前持久化代理池中第一个非空节点，整次任务保持同一个代理；本接口不会在流程中途轮换节点，也不根据批量任务的 `max_per_ip` 自动切换。未配置代理不会直接无代理注册，返回 503。

代理池是否为日本出口仍取决于实际配置和出口服务；接口不会仅凭代理地址宣称其地区。姓名、生日、语言等由后端自动填写，不需要前端提交。此接口不修改全局邮箱来源设置。

```bash
curl -X POST https://muse.yufan88.top/api/gmail/registrations \
  -H "Authorization: Bearer $MUSE_REG_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"email":"your.address@gmail.com","invite_code":"JP3P6J","otp_timeout":300}'
```

Windows PowerShell 可使用以下形式；请把示例地址替换为实际授权邮箱：

```powershell
$base = 'https://muse.yufan88.top'
$apiKey = (Get-Content -Raw -LiteralPath 'F:/muse protocol/private/gmail-api-key').Trim()
$headers = @{ Authorization = "Bearer $apiKey" }
$body = @{ email = 'your.address@gmail.com'; invite_code = 'JP3P6J' } | ConvertTo-Json
$task = Invoke-RestMethod "$base/api/gmail/registrations" -Headers $headers -Method Post -ContentType 'application/json' -Body $body
$task.run_id
```

成功 HTTP 202。响应与任务查询使用同一个结构，最初通常为 `state=processing`、`stage=initialized/starting`。**创建接口返回时，邮件可能尚未发送成功。**

同一邮箱已有进行中任务，返回 409 `registration_in_progress`，并在 `error.run_id`、`error.status_url` 中返回现有任务。邮箱已有本项目保存的注册结果，返回 409 `already_registered`；调用方应保存先前任务 ID，再通过带鉴权的任务凭证接口读取。无法识别其他设备或其他项目注册过的所有账号。

## 4. 查询任务与结果

`GET /api/gmail/registrations/{run_id}`。已知任务返回 HTTP 200；不存在返回 HTTP 404。

等待用户验证码时的响应结构示例；时间字段实际为 Unix 秒时间戳：

```json
{
  "ok": true,
  "run_id": "a1b2c3d4e5f6",
  "email": "your.address@gmail.com",
  "state": "waiting_otp",
  "finished": false,
  "stage": "wait_otp",
  "stage_label": "等待验证码",
  "feedback": {
    "code": "otp_required",
    "level": "info",
    "message": "验证码邮件已发送，请提交六位验证码",
    "detail": "[5/10] 等待邮箱 6 位验证码 (超时 300s)...",
    "next_action": "submit_otp"
  },
  "warnings": [],
  "error_category": "",
  "registered": false,
  "account_status": "pending",
  "can_submit_otp": true,
  "otp_expires_at": 1795248300,
  "otp_seconds_remaining": 299,
  "started_at": 1795247990,
  "updated_at": 1795248000,
  "finished_at": null,
  "result": null,
  "links": {
    "status": "/api/gmail/registrations/a1b2c3d4e5f6",
    "otp": "/api/gmail/registrations/a1b2c3d4e5f6/otp",
    "logs": "/api/gmail/registrations/a1b2c3d4e5f6/logs",
    "credentials": null
  }
}
```

| 字段 | 含义 |
| --- | --- |
| `state` | 面向前端的任务状态，见下表 |
| `finished` | 本轮任务是否终止；为 true 时停止轮询、禁止继续提交验证码 |
| `stage` / `stage_label` | 当前执行阶段标识和中文名称 |
| `feedback.code` | 稳定反馈码；不要依赖中文文本进行逻辑判断 |
| `feedback.level` | `info`、`success`、`warning` 或 `error` |
| `feedback.message` | 可直接展示给用户的中文提示 |
| `feedback.detail` | 原始流程反馈或上游错误片段；上游响应可能被底层客户端截断，不保证是完整响应体 |
| `feedback.upstream_http_status` | 可选；底层错误明确带有 HTTP 状态时返回，例如 400、403、429，与本接口的 HTTP 状态分开判断 |
| `feedback.next_action` | 建议下一步操作标识，含义见反馈表 |
| `warnings` | 额外提醒，例如兑换成功但自有邀请码仍待分配 |
| `error_category` | 底层历史分类；终态时通常有值，优先使用 `feedback.code` |
| `registered` | 账号是否已创建并保存；为 true 时不要因后续受限而把账号当作未注册 |
| `account_status` | 账号业务状态，与任务是否结束分开判断 |
| `can_submit_otp` | 只有为 true 才启用验证码输入和提交按钮 |
| `otp_expires_at` | 等待验证码截止时间；非等待阶段通常为 null |
| `otp_seconds_remaining` | 服务端计算的剩余秒数；不保证等于邮件验证码在上游的有效期 |
| `started_at` / `updated_at` / `finished_at` | Unix 秒时间戳，可含小数；未结束时 `finished_at=null` |
| `result` | 已保存账号的摘要；未创建账号时为 null |
| `links` | 后续查询、提交、日志和完整凭证的相对 URL |

| `state` | 含义 | 前端行为 |
| --- | --- | --- |
| `processing` | 正在发码或处理后续步骤 | 显示反馈，继续轮询 |
| `waiting_otp` | 发码成功，等待用户输入 | 启用验证码输入框 |
| `completed` | 本轮处理结束 | 停止轮询；还要检查是否存在 warning |
| `failed` | 本轮处理失败 | 停止轮询，展示错误及账号是否已保留 |
| `action_required` | 需要年龄验证或进入地区候补 | 停止轮询，提示到官方流程处理 |
| `interrupted` | 服务重启导致原任务会话中断 | 检查保存结果，再决定是否创建新任务 |
| `expired` | 验证码输入等待已超时 | 停止提交，创建新任务 |

| `account_status` | 含义 |
| --- | --- |
| `pending` | 账号尚未创建 |
| `registered_unactivated` | 已创建并保存，但尚未完成激活或需要年龄验证 |
| `registered_waitlist` | 已创建并保存，进入候补/地区限制 |
| `registered_pending_redemption` | 已保留账号，邀请码兑换或权限仍待处理 |
| `activated` | 已注册并激活，没有完成邀请码兑换 |
| `redeemed` | 邀请码兑换完成 |

`result` 包括 `account_id`、`status`、`stage`、`own_code`、`used_invite_code`、`ip`、`first_name`、`last_name`、`date_of_birth`、`is_live`、`own_code_status`、`redeem_reason`、`last_error` 和 `session_token_len`。部分上游未返回的字段可能为空字符串或 null。

完整的 `access_token`、`session_token`、`cookie_header` 等由带 Bearer 鉴权的 `GET /api/gmail/registrations/{run_id}/credentials` 返回，响应为 `{"ok":true,"data":{...}}`；直接使用 `links.credentials`。账号尚未保存时返回 HTTP 409 `account_not_ready`。前端通常不需要把完整凭证展示给最终用户。

任务阶段及最终反馈持久化到 SQLite，不依赖 SSE 是否连接。可以多次轮询同一任务，也可以多个客户端查询。服务重启后仍可读取已保存反馈与结果，但不会恢复原来的内存注册会话；进行中任务会以 `interrupted` 反馈。更新前的历史任务只能提供原先保存的阶段/错误信息，无法补出过去未记录的实时阶段。

## 5. 提交验证码

`POST /api/gmail/registrations/{run_id}/otp`。

```json
{"code":"123456"}
```

验证码必须是**字符串**，长度恰好 6 位且只含 ASCII 数字，以保留前导零。格式不正确返回 422；尚未发码、已经提交或任务已结束时不会再次投递验证码。

成功 HTTP 202：

```json
{
  "ok": true,
  "run_id": "a1b2c3d4e5f6",
  "feedback": {
    "code": "otp_submitted",
    "level": "info",
    "message": "验证码已接收，正在继续注册",
    "detail": "",
    "next_action": "poll_run"
  },
  "status_url": "/api/gmail/registrations/a1b2c3d4e5f6"
}
```

这只表示后台接受了验证码；验证码是否通过由后续查询结果给出。上游拒绝时返回业务反馈 `otp_rejected`，不保证能区分“输入错误”和“上游已过期”。当前不会自动重试错误验证码。

## 6. 读取日志

`GET /api/gmail/registrations/{run_id}/logs?offset=0&limit=100`。

`offset` 是从 0 开始的行偏移，必须 ≥0；`limit` 为 1–500，默认 100。

```json
{
  "ok": true,
  "run_id": "a1b2c3d4e5f6",
  "offset": 0,
  "next_offset": 2,
  "has_more": false,
  "lines": ["00:10:00 [INFO] registrar: 开始注册", "00:10:01 [INFO] muse.flow: 等待验证码"]
}
```

下次带上 `next_offset`；`has_more=false` 仅表示读取时没有更多日志，任务仍可能继续追加。日志不被读取操作消耗。新任务不再把六位验证码明文写入普通流程日志；更新前的历史文件不做改写。日志中的时间是执行服务所在机器的日志时间；前端跨时区显示应优先使用任务中的 Unix 时间戳。

旧接口 `GET /api/runs/{run_id}/stream` 仍提供 SSE，但它消费同一任务队列，断开后不保证可重连补发。新接入以本组轮询和日志分页接口为准。

## 7. 请求错误与反馈码

请求被拒绝时，HTTP 为 4xx/5xx，响应统一为：

```json
{
  "ok": false,
  "error": {
    "code": "invalid_otp",
    "level": "error",
    "message": "验证码必须是六位数字字符串",
    "detail": "",
    "next_action": "correct_otp"
  }
}
```

422 还会附带 `error.fields`，各项包含 `field`、`message`、`type`。接口工具应读取 `error.code`，不解析 `message`。错误发生在异步注册流程时，查询仍返回 HTTP 200，通过 `feedback` 表达失败。

### 请求阶段

| HTTP | 错误码 | 含义及处理 |
| --- | --- | --- |
| 422 | `invalid_request` | 请求字段缺失、类型/范围错误或存在不支持的字段；修正请求 |
| 401 | `unauthorized` | 缺少或错误的 Bearer 密钥；由卡网后端修正配置 |
| 503 | `api_auth_not_configured` | 注册服务没有配置有效密钥 |
| 409 | `account_not_ready` | 该任务尚未保存账号，继续查询任务状态 |
| 400 | `invalid_email` | 邮箱为空或格式不合法 |
| 400 | `unsupported_email_domain` | 不是 Gmail/Googlemail 地址 |
| 409 | `already_registered` | 本项目已有保存结果，使用之前保存的任务 ID 获取账号凭证 |
| 409 | `registration_in_progress` | 已有进行中任务，改查 `error.run_id` / `error.status_url` |
| 503 | `proxy_not_configured` | 配置代理池后再发起任务 |
| 503 | `proxy_config_invalid` | 代理池 JSON、类型、协议或地址不合法 |
| 404 | `run_not_found` | 检查任务 ID 和当前调用的是本地还是服务器服务 |
| 404 | `endpoint_not_found` | API 路径错误 |
| 405 | `method_not_allowed` | HTTP 方法错误 |
| 422 | `invalid_otp` | 验证码字段缺失、不是字符串或不是六位数字 |
| 409 | `otp_not_ready` | 发码尚未完成，继续查询任务 |
| 409 | `otp_already_submitted` | 本轮已经提交验证码，不要重复提交 |
| 410 | `otp_expired` | 输入等待时间已过，重新创建任务 |
| 409 | `run_finished` | 任务已结束，查看结果 |
| 409 | `worker_restarted` | 服务已重启，检查已保存账号后再决定重试 |
| 500 | `internal_error` | 服务内部异常，检查服务器日志 |

### 异步业务反馈

下表通过任务查询的 `feedback.code` 返回，查询 HTTP 均为 200。

| 反馈码 | 说明 | 下一步 |
| --- | --- | --- |
| `processing` | 正在处理 | 继续轮询 |
| `otp_required` | 邮件已发送，等待验证码 | 用户输入并提交验证码 |
| `otp_submitted` | 验证码已接收 | 继续轮询 |
| `account_registered` | 账号已创建，后续激活进行中 | 不再重复注册，继续查询 |
| `redeemed` | 注册、激活及邀请码兑换完成 | 展示结果 |
| `activated` | 已注册并激活 | 展示结果 |
| `otp_timeout` | 等待用户验证码超时 | 创建新任务 |
| `otp_rejected` | 上游拒绝验证码 | 核对最新邮件，再创建新任务 |
| `otp_send_failed` | 上游发送邮件失败，例如限流 | 查看 detail 后处理 |
| `session_init_failed` | 上游初始化会话失败 | 查看 detail 后处理 |
| `registration_rejected` | 上游拒绝注册资料，例如 register-completion 403 | 查看 detail；不代表账号一定已创建 |
| `age_verification_required` | **需要进行年龄验证** | 已保存账号，进入官方验证流程 |
| `region_waitlist` | 进入候补或地区受限 | 已保存账号，查看结果及官方状态 |
| `disclosure_unresolved` | 无法解析上游条款确认页 | 检查已保存账号，避免重复注册 |
| `pre_send_network` | 发码前网络/代理失败 | 检查代理后创建新任务 |
| `post_send_network` | 发码后网络失败 | 先检查 registered 和保存结果 |
| `activation_failed` | 条款确认/激活被拒绝 | 检查保存结果和 detail |
| `protocol_error` | 上游接口或页面返回异常 | 查看 detail |
| `account_error` | 邮箱来源处理失败 | 查看 detail |
| `registration_failed` | 其他业务失败 | 查看 detail、registered |
| `invite_unavailable` | 账号保留，池中没有可用邀请码 | 对保存的账号补兑 |
| `invite_rejected` | 账号保留，但指定/池内邀请码未兑换成功 | 查看 result.redeem_reason，补兑 |
| `invite_retries_exhausted` | 账号保留，邀请码重试已耗尽 | 补充邀请码后补兑 |
| `own_code_pending` | 已兑码，自有邀请码暂未分配，位于 warnings | 稍后查询保存账号 |
| `pending_redemption` | 账号保留，兑换或权限待确认 | 查看保存结果 |
| `internal_error` | 后台未预期异常 | 查看 detail 与服务器日志 |
| `worker_restarted` | 原会话随服务重启而中断 | 检查已保存账号 |
| `otp_expired` | 等待输入截止时间已过 | 创建新任务 |

`GET /api/gmail/errors` 实时返回与运行代码相同的字典，包括 `message`、`level`、`next_action` 和阶段中文名。其 `errors[].http_status` 为拒绝同步请求时使用的 HTTP 状态；纯异步业务项为 200。同一个 `worker_restarted` 或 `otp_expired` 出现在查询反馈时，查询本身仍为 200。

`next_action` 是界面操作提示，例如 `poll_run`=继续查询、`submit_otp`=输入验证码、`view_saved_account`/`check_saved_account`=查看保存结果、`complete_official_age_verification`=完成官方年龄验证、`redeem_saved_account`=对已保存账号补兑。它不会自动执行对应动作。

## 8. JavaScript 与命令行接入

可直接复用 [examples/gmail-api.mjs](../examples/gmail-api.mjs)，在 Node.js 18+ 可信后端中调用。浏览器通过卡网自己的业务接口间接调用，不直接持有服务密钥：

```javascript
import { createGmailApi } from './examples/gmail-api.mjs'

const api = createGmailApi('https://muse.yufan88.top', process.env.MUSE_REG_API_KEY)
// 由邮箱表单的提交按钮调用：
const task = await api.start('your.address@gmail.com', { invite_code: 'JP3P6J' })
// 后端将 task.run_id 与当前卡网用户/订单关联并保存。
// 定时查询并把反馈展示到界面：
const status = await api.status(task.run_id)
console.log(status.feedback.message, status.can_submit_otp)
// 仅当 can_submit_otp=true 时，由验证码提交按钮调用：
// await api.submitOtp(task.run_id, 用户输入的六位数字字符串)
// 继续 api.status(task.run_id)，finished=true 时停止查询。
```

页面刷新后由卡网后端按当前用户/订单返回其绑定任务的状态。请用串行查询或在上一次请求完成后再设置下一次计时，避免网络较慢时叠加请求。

完整交互命令行示例（会真实发起注册，仅在需要实际测试时执行）：

```bash
node examples/gmail-register.mjs your.address@gmail.com https://muse.yufan88.top JP3P6J
```

脚本自动轮询，发码成功后提示输入验证码，并输出最终结构化结果。发生请求错误时，客户端抛出的异常包含 `error.status` 和 `error.feedback`。

命令行脚本会从 `MUSE_REG_API_KEY`、`MUSE_REG_API_KEY_FILE` 或当前工作目录下的 `private/gmail-api-key` 读取调用密钥，不需要把密钥放到命令行参数中。

## 9. 实现与验证对应

| 可验证证据 | 结论 | 接入方式 |
| --- | --- | --- |
| `webui/gmail_api.py` 与 `test_gmail_api.py` | 邮箱创建、验证码投递、任务查询和日志可通过 HTTP 获取 | 使用第 1 节流程 |
| `webui/registration_feedback.py` | 错误与中文反馈共享同一字典 | 调用 `/api/gmail/errors` |
| `webui/db.py` 的 `feedback_json` 与 `webui/registrar.py` | 阶段反馈先保存再推送，不依赖 SSE 消费 | 轮询任务详情 |
| `test_gmail_api.py` 的网络客户端替换 | 可离线验证验证码拒绝、年龄验证、候补、代理失败、兑码失败等路径 | `python test_gmail_api.py` |
| `test_gmail_concurrency.py` 的独立任务和真实超时等待 | 可验证四路并发验证码隔离、格式修正、重复提交、错误后新建任务及无人提交时自动结束 | `python test_gmail_concurrency.py` |
| `test_gmail_auth.py` | 可验证未配置密钥时拒绝、缺失/错误密钥 401、文件轮换、凭证读取鉴权及 OpenAPI 声明 | `python test_gmail_auth.py` |

这些测试验证本项目接口和流程分支，第三方网络响应采用模拟，不表示第三方服务始终允许注册或保证任意真实邮箱注册成功。
