# 接口文档

基础地址示例：

```text
本地：http://127.0.0.1:3002
线上：https://你的Worker域名
```

线上示例：

```text
https://cloud-mail-api-service.zixiaohan.workers.dev
```

## 1. 通用规则

### 1.0 Cloud-Mail 同步状态说明

创建注册码返回或列表里出现：

```json
{
  "sync_status": "local_only"
}
```

或页面显示“仅本地”，表示 api-service 已经写入本地 D1，但当次请求没有拿到 Cloud-Mail 同步连接，所以没有调用 Cloud-Mail 创建注册码。

常见原因：

- 管理后台还没有保存 Cloud-Mail 连接配置。
- Cloud-Mail Token 已过期，需要重新保存连接。
- Cloudflare 变量 `cloud_mail_url` 留空，且旧版本代码没有读取后台保存的 Cloud-Mail 地址。

处理方式：

1. 打开后台 `/`。
2. 进入 Cloud-Mail 连接配置，填写 Cloud-Mail 地址、管理员邮箱和密码或 Token。
3. 保存后确认状态显示“Cloud-Mail 已连接”。
4. 重新创建注册码；新创建记录应显示 `synced` / `未使用`，并能在 Cloud-Mail 中看到。

### 1.1 返回结构

JSON 成功返回：

```json
{
  "code": 200,
  "message": "success",
  "data": {}
}
```

JSON 错误返回：

```json
{
  "code": 401,
  "message": "未授权：请使用管理后台创建的 API 调用密钥"
}
```

TXT 返回：接口支持 `format=txt` 或 `response_type=txt` 时，会直接返回 `text/plain`。

### 1.2 鉴权方式

业务接口需要先在管理后台创建“API 调用密钥”，并给密钥开放对应权限。

推荐方式，请求头传递：

```http
X-API-Key: 你的API调用密钥
```

兼容方式：

```http
Authorization: Key 你的API调用密钥
Authorization: ApiKey 你的API调用密钥
Authorization: Bearer 你的API调用密钥
```

浏览器地址栏直访方式：

```text
?api_key=你的API调用密钥
```

也兼容：

```text
?access_key=你的API调用密钥
```

示例：

```text
https://你的Worker域名/api/text/random?api_key=你的API调用密钥&type=txt&response_type=txt
```

注意：地址栏传密钥更方便测试，但密钥可能进入浏览器历史、代理日志、访问日志。正式业务调用仍建议用 `X-API-Key` 请求头。

### 1.3 通用可选参数

以下参数仅适用于使用统一响应工具的接口：账号、注册码、文本管理、API 调用密钥管理等。

| 参数 | 必传 | 位置 | 默认值 | 说明 |
|---|---|---|---|---|
| `format` | 否 | Query 或 Body | `json` | `json`、`txt`、`text` |
| `response_type` | 否 | Query 或 Body | `json` | `json`、`txt`、`text`；`/api/text/random` 额外支持 `xml` |
| `api_key` | 否 | Query | 无 | API 调用密钥，方便浏览器地址栏测试 |
| `access_key` | 否 | Query | 无 | `api_key` 的别名 |

### 1.4 权限列表

```json
[
  "account:create",
  "account:delete",
  "account:list",
  "key:create",
  "key:delete",
  "key:list",
  "text:random",
  "text:add",
  "text:list",
  "text:delete",
  "text:toggle",
  "cloud:status",
  "cloud:configure"
]
```

`all` 表示开放全部业务权限。管理员 JWT 不受权限列表限制，但不建议分发给外部系统。

## 2. 健康检查

`GET /api/health`

鉴权：无需。

请求参数：无。

返回参数：

```json
{
  "code": 200,
  "message": "API Service is running",
  "timestamp": "2026-05-17T12:00:00.000Z"
}
```

## 3. 初始化数据库

`GET /api/init`

鉴权：无需。

请求参数：无。

用途：创建或迁移 D1 表结构。首次部署后访问一次。

返回参数：

```json
{
  "code": 200,
  "message": "DB initialized",
  "data": [
    {
      "table": "api_key",
      "created": true
    }
  ]
}
```

## 4. 管理员登录

`POST /api/auth/admin`

鉴权：无需。

Body 参数：

| 参数 | 必传 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| `username` | 是 | string | 无 | Cloudflare 变量 `admin_user` |
| `password` | 是 | string | 无 | 管理后台明文登录密码，服务端会比对 `admin_pass_hash` |
| `cloud_mail_url` | 否 | string | 环境变量 `cloud_mail_url` | Cloud-Mail 地址；如果同时连接 Cloud-Mail 且环境变量为空，则需要传 |
| `cloud_email` | 否 | string | 无 | Cloud-Mail 管理员邮箱；和 `cloud_password` 成对使用 |
| `cloud_password` | 否 | string | 无 | Cloud-Mail 管理员密码；和 `cloud_email` 成对使用 |
| `cloud_token` | 否 | string | 无 | 已有 Cloud-Mail Token；可替代 `cloud_email` + `cloud_password` |

请求示例：

```json
{
  "username": "admin",
  "password": "你的后台密码"
}
```

返回参数：

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "token": "管理员JWT",
    "cloud_connected": true
  }
}
```

## 5. Cloud-Mail Token 换取 JWT

`POST /api/auth/token`

鉴权：无需。

说明：历史兼容接口，用于把 Cloud-Mail 登录凭据或 Token 换成 api-service JWT。当前业务接口推荐使用“API 调用密钥”，不要把这个 JWT 当作外部业务鉴权密钥。

Body 参数：

| 参数 | 必传 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| `token` | 条件必传 | string | 无 | 已有 Cloud-Mail Token；和 `email/password` 二选一 |
| `email` | 条件必传 | string | 无 | Cloud-Mail 登录邮箱；没有 `token` 时必传 |
| `password` | 条件必传 | string | 无 | Cloud-Mail 登录密码；没有 `token` 时必传 |
| `cloud_mail_url` | 否 | string | 环境变量 `cloud_mail_url` | Cloud-Mail 地址；环境变量为空且使用邮箱密码登录时必传 |

返回参数：

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "token": "JWT"
  }
}
```

## 6. Cloud-Mail 状态

`GET /api/auth/cloud/status`

鉴权：管理员 JWT 或 API 调用密钥权限 `cloud:status`。

Query 参数：

| 参数 | 必传 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| `api_key` | 否 | string | 无 | 浏览器直访时传 API 调用密钥 |
| `access_key` | 否 | string | 无 | `api_key` 别名 |

返回参数：

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "url": "https://你的Cloud-Mail站点",
    "email": "管理员邮箱",
    "connected_at": "2026-05-17T12:00:00.000Z",
    "token_expires_at": "2026-06-15T12:00:00.000Z",
    "connected": true,
    "mode": "cloud"
  }
}
```

## 7. Cloud-Mail 角色列表

`GET /api/auth/cloud/roles`

鉴权：管理员 JWT 或 API 调用密钥权限 `cloud:status`。

Query 参数：

| 参数 | 必传 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| `api_key` | 否 | string | 无 | 浏览器直访时传 API 调用密钥 |
| `access_key` | 否 | string | 无 | `api_key` 别名 |

返回参数：

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "list": [
      {
        "role_id": 1,
        "name": "普通用户",
        "is_default": false
      }
    ]
  }
}
```

## 8. Cloud-Mail 邮箱域名列表

`GET /api/auth/cloud/domains`

鉴权：管理员 JWT 或 API 调用密钥权限 `cloud:status`。

用途：从 Cloud-Mail 的 `/api/setting/websiteConfig` 读取网站邮箱域名，管理页面会用它生成“创建账号”的邮箱后缀下拉框。

Query 参数：

| 参数 | 必传 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| `api_key` | 否 | string | 无 | 浏览器直访时传 API 调用密钥 |
| `access_key` | 否 | string | 无 | `api_key` 别名 |

返回参数：

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "list": ["example.com"],
    "raw_list": ["@example.com"]
  }
}
```

字段说明：

| 字段 | 类型 | 说明 |
|---|---|---|
| `list` | string[] | 已去掉开头 `@` 的域名，可直接作为 `email_suffix` |
| `raw_list` | string[] | Cloud-Mail 原始 `domainList` |

## 9. 配置 Cloud-Mail 连接

`POST /api/auth/cloud/configure`

鉴权：管理员 JWT 或 API 调用密钥权限 `cloud:configure`。

Body 参数：

| 参数 | 必传 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| `cloud_mail_url` | 条件必传 | string | 环境变量 `cloud_mail_url` | Cloud-Mail 地址；也可传 `url` |
| `url` | 条件必传 | string | 环境变量 `cloud_mail_url` | `cloud_mail_url` 别名 |
| `cloud_token` | 条件必传 | string | 无 | 已有 Cloud-Mail Token；也可传 `token` |
| `token` | 条件必传 | string | 无 | `cloud_token` 别名 |
| `cloud_email` | 条件必传 | string | 无 | 使用账号密码连接时必传；也可传 `email` |
| `email` | 条件必传 | string | 无 | `cloud_email` 别名 |
| `cloud_password` | 条件必传 | string | 无 | 使用账号密码连接时必传；也可传 `password` |
| `password` | 条件必传 | string | 无 | `cloud_password` 别名 |
| `api_key` | 否 | string | 无 | Query 参数，浏览器测试用 |

必传规则：`cloud_token/token` 和 `cloud_email/email + cloud_password/password` 二选一。Cloud-Mail 地址如果环境变量为空则必须提供。

返回参数：

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "source": "login",
    "connected": true,
    "url": "https://你的Cloud-Mail站点",
    "email": "Cloud-Mail管理员邮箱",
    "connected_at": "2026-05-17T12:00:00.000Z",
    "token_expires_at": "2026-06-15T12:00:00.000Z"
  }
}
```

## 10. 断开 Cloud-Mail 连接

`DELETE /api/auth/cloud/configure`

鉴权：管理员 JWT 或 API 调用密钥权限 `cloud:configure`。

Query 参数：

| 参数 | 必传 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| `api_key` | 否 | string | 无 | 浏览器直访时传 API 调用密钥 |
| `access_key` | 否 | string | 无 | `api_key` 别名 |

返回参数：

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "connected": false
  }
}
```

## 11. 创建 API 调用密钥

`POST /api/access-key/create`

鉴权：管理员 JWT。API 调用密钥不能创建新的 API 调用密钥。

Body 参数：

| 参数 | 必传 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| `name` | 否 | string | `API 调用密钥` | 后台显示名称 |
| `prefix` | 否 | string | `ak-` | 密钥前缀 |
| `length` | 否 | number | `48` | 密钥总长度，包含前缀 |
| `permissions` | 否 | string 或 string[] | `all` | 权限，支持 `all`、`*`、具体权限、`account:*` 这类通配 |
| `max_uses` | 否 | number | `0` | 最大调用次数，`0` 不限制 |
| `expire_days` | 否 | number | `0` | 有效期天数，`0` 不限制 |
| `inactive_days` | 否 | number | `0` | 不活跃失效天数，`0` 不限制 |
| `quantity` | 否 | number | `1` | 批量创建数量，最大 100 |
| `format` | 否 | string | `json` | `json` 或 `txt` |
| `response_type` | 否 | string | `json` | `json` 或 `txt` |

请求示例：

```json
{
  "name": "文本读取密钥",
  "permissions": ["text:random"],
  "expire_days": 30,
  "quantity": 1
}
```

返回参数：

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "quantity": 1,
    "keys": [
      {
        "access_key_id": 1,
        "name": "文本读取密钥",
        "key": "ak-xxxxxxxxxxxxxxxx",
        "prefix": "ak-",
        "permissions": "text:random",
        "max_uses": 0,
        "expire_days": 30,
        "inactive_days": 0
      }
    ]
  }
}
```

## 12. API 调用密钥列表

`GET /api/access-key/list`

鉴权：管理员 JWT。

Query 参数：

| 参数 | 必传 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| `page` | 否 | number | `1` | 页码 |
| `size` | 否 | number | `20` | 每页数量，最大 200 |
| `status_val` | 否 | number | 无 | 本地状态：`0` 正常，`1` 禁用，`2` 失效 |
| `format` | 否 | string | `json` | `json` 或 `txt` |
| `response_type` | 否 | string | `json` | `json` 或 `txt` |

返回参数：

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "list": [
      {
        "access_key_id": 1,
        "name": "文本读取密钥",
        "key_value": "ak-xxxxxxxx",
        "prefix": "ak-",
        "status": 0,
        "permissions": "text:random",
        "max_uses": 0,
        "used_count": 3,
        "expire_days": 30,
        "inactive_days": 0,
        "last_used_at": "2026-05-17 12:00:00",
        "created_by": "admin",
        "create_time": "2026-05-17 12:00:00",
        "update_time": "2026-05-17 12:00:00"
      }
    ],
    "total": 1,
    "page": 1,
    "size": 20
  }
}
```

## 13. 删除 API 调用密钥

`POST /api/access-key/delete`

`DELETE /api/access-key/delete`

鉴权：管理员 JWT。

Body 或 Query 参数：

| 参数 | 必传 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| `access_key_ids` | 条件必传 | number[] 或逗号字符串 | 无 | API 调用密钥 ID；和 `key_values` 至少传一个 |
| `key_values` | 条件必传 | string[] 或逗号字符串 | 无 | API 调用密钥明文；和 `access_key_ids` 至少传一个 |
| `format` | 否 | string | `json` | `json` 或 `txt` |
| `response_type` | 否 | string | `json` | `json` 或 `txt` |

返回参数：

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "results": [
      {
        "access_key_id": 1,
        "key_prefix": "ak-xxxxx...",
        "deleted": true
      }
    ]
  }
}
```

## 14. 创建账号

`POST /api/account/create`

鉴权：API 调用密钥权限 `account:create`，或管理员 JWT。

Body 参数：

| 参数 | 必传 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| `role_id` | 是 | number | 无 | Cloud-Mail 角色 ID |
| `email_suffix` | 条件必传 | string | 无 | 邮箱后缀；随机生成或批量行没有 `@` 时必传，可通过 `/api/auth/cloud/domains` 获取 |
| `quantity` | 否 | number | `1` | 随机创建数量，最大 500 |
| `email_prefix` | 否 | string | 随机字符串 | 邮箱账号名前缀；传入后仍会按 `email_prefix_len` 补齐随机字符 |
| `email_prefix_len` | 否 | number | `8` | 邮箱账号名前缀总长度，传了 `email_prefix` 时也生效；例如 `test` + `8` 会生成 `test` 后再补 4 位随机字符 |
| `default_password` | 否 | string | 随机密码 | 默认密码 |
| `order_id` | 否 | string | 无 | 订单号 |
| `max_uses` | 否 | number | `0` | 兼容旧请求的本地记录字段；Cloud-Mail 创建账号接口不接收该字段，不会限制账号使用次数 |
| `expire_days` | 否 | number | `0` | 兼容旧请求的本地记录字段；Cloud-Mail 创建账号接口不接收该字段，不会设置账号有效期 |
| `remark` | 否 | string | 空 | 备注 |
| `accounts` | 否 | object[] | 无 | 批量指定账号；传了以后优先于随机生成 |
| `batch_text` | 否 | string | 空 | 批量文本，一行一个：`账号,密码,备注` |
| `format` | 否 | string | `json` | `json` 或 `txt` |
| `response_type` | 否 | string | `json` | `json` 或 `txt` |
| `api_key` | 否 | string | 无 | Query 参数，浏览器测试用 |

`accounts[]` 项参数：

| 参数 | 必传 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| `email` | 是 | string | 无 | 完整邮箱，或不带后缀的账号名前缀 |
| `password` | 否 | string | `default_password` 或随机密码 | 密码 |
| `role_id` | 否 | number | 外层 `role_id` | 单条覆盖角色 |
| `order_id` | 否 | string | 外层 `order_id` | 单条覆盖订单 |
| `max_uses` | 否 | number | 外层 `max_uses` | 兼容旧请求的本地记录字段，云端账号不使用 |
| `expire_days` | 否 | number | 外层 `expire_days` | 兼容旧请求的本地记录字段，云端账号不使用 |
| `remark` | 否 | string | 外层 `remark` | 单条备注 |

请求示例：

```json
{
  "email_prefix": "test",
  "email_prefix_len": 8,
  "email_suffix": "example.com",
  "quantity": 3,
  "default_password": "Password123",
  "role_id": 1,
  "order_id": "order-001",
  "remark": "测试批量创建"
}
```

返回参数：

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "quantity": 1,
    "created": [
      {
        "email": "test@example.com",
        "password": "Password123",
        "role_id": 1,
        "role_name": "普通用户",
        "max_uses": 0,
        "expire_days": 0,
        "remark": "测试批量创建",
        "status": "created"
      }
    ],
    "summary": {
      "total": 1,
      "success": 1,
      "failed": 0
    }
  }
}
```

TXT 返回：

```text
账号：test@example.com 密码：Password123
```

## 15. 删除账号

`POST /api/account/delete`

鉴权：API 调用密钥权限 `account:delete`，或管理员 JWT。

Body 参数：

| 参数 | 必传 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| `emails` | 是 | string[] | 无 | 要删除的账号邮箱 |
| `delete_scope` | 否 | string | `cloud` | `cloud` 只删 Cloud-Mail；`both` 两边一起删 |
| `scope` | 否 | string | `cloud` | `delete_scope` 别名 |
| `format` | 否 | string | `json` | `json` 或 `txt` |
| `response_type` | 否 | string | `json` | `json` 或 `txt` |
| `api_key` | 否 | string | 无 | Query 参数，浏览器测试用 |

返回参数：

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "results": [
      {
        "email": "test@example.com",
        "status": "deleted",
        "delete_scope": "cloud",
        "local_deleted": false
      }
    ]
  }
}
```

## 16. 账号列表

`GET /api/account/list`

鉴权：API 调用密钥权限 `account:list`，或管理员 JWT。

Query 参数：

| 参数 | 必传 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| `page` | 否 | number | `1` | 页码 |
| `size` | 否 | number | `20` | 每页数量，最大 1000 |
| `status` | 否 | string | 无 | 本地状态筛选，如 `created`、`cloud_deleted`、`failed` |
| `email` | 否 | string | 无 | 邮箱模糊查询 |
| `sort_by` | 否 | string | `account_id` | 排序字段：`account_id`、`email`、`role_id`、`role_name`、`status`、`create_time`、`update_time`、`created_by` |
| `sort_order` | 否 | string | `desc` | `asc` 或 `desc` |
| `format` | 否 | string | `json` | `json` 或 `txt` |
| `response_type` | 否 | string | `json` | `json` 或 `txt` |
| `api_key` | 否 | string | 无 | 浏览器直访时传 API 调用密钥 |

返回参数：

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "list": [
      {
        "account_id": 1,
        "email": "test@example.com",
        "password": "Password123",
        "role_id": 1,
        "role_name": "普通用户",
        "status": "created",
        "cloud_status": "normal",
        "cloud_status_label": "正常",
        "order_id": "order-001",
        "created_by": "admin",
        "remark": "备注",
        "create_time": "2026-05-17 12:00:00",
        "update_time": "2026-05-17 12:00:00"
      }
    ],
    "total": 1,
    "page": 1,
    "size": 20
  }
}
```

TXT 导出：

```text
账号：test@example.com----密码：Password123----状态：正常
```

## 17. 创建注册码

`POST /api/key/create`

鉴权：API 调用密钥权限 `key:create`，或管理员 JWT。

Body 参数：

| 参数 | 必传 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| `role_id` | 是 | number | 无 | Cloud-Mail 角色 ID |
| `prefix` | 否 | string | 空 | 注册码前缀 |
| `length` | 否 | number | `5` | 注册码总长度，包含前缀 |
| `quantity` | 否 | number | `1` | 随机创建数量，最大 500 |
| `max_uses` | 否 | number | `0` | 可用次数；`0` 会按长期可用处理 |
| `expire_days` | 否 | number | `0` | 过期天数；`0` 约等于长期有效 |
| `order_id` | 否 | string | 无 | 订单号 |
| `remark` | 否 | string | 空 | 备注 |
| `inactive_days` | 否 | number/string | 空 | 兼容旧字段，现在会写入 `remark` |
| `keys` | 否 | object[] | 无 | 批量指定注册码；传了以后优先于随机生成 |
| `batch_text` | 否 | string | 空 | 批量文本，一行一个：`注册码,备注` |
| `format` | 否 | string | `json` | `json` 或 `txt` |
| `response_type` | 否 | string | `json` | `json` 或 `txt` |
| `api_key` | 否 | string | 无 | Query 参数，浏览器测试用 |

`keys[]` 项参数：

| 参数 | 必传 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| `key_value` | 是 | string | 无 | 注册码内容；也兼容 `key`、`code`、`value` |
| `role_id` | 否 | number | 外层 `role_id` | 单条覆盖角色 |
| `max_uses` | 否 | number | 外层 `max_uses` | 单条覆盖次数 |
| `expire_days` | 否 | number | 外层 `expire_days` | 单条覆盖过期天数 |
| `order_id` | 否 | string | 外层 `order_id` | 单条覆盖订单 |
| `remark` | 否 | string | 外层 `remark` | 单条备注 |

返回参数：

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "quantity": 1,
    "keys": [
      {
        "key": "ABCDE",
        "key_value": "ABCDE",
        "prefix": "",
        "length": 5,
        "role_id": 1,
        "role_name": "普通用户",
        "max_uses": 1,
        "available_count": 1,
        "expire_days": 30,
        "expire_time": "2026-06-16 00:00:00",
        "order_id": "order-002",
        "remark": "备注",
        "sync_status": "synced",
        "sync_error": null
      }
    ],
    "synced_to_cloud": 1,
    "local_only": 0,
    "failed": 0
  }
}
```

TXT 返回只显示注册码：

```text
ABCDE
```

## 18. 注销注册码

`POST /api/key/revoke`

鉴权：API 调用密钥权限 `key:delete`，或管理员 JWT。

说明：尝试删除 Cloud-Mail 注册码，并把本地记录标记为禁用，不删除本地行。

Body 参数：

| 参数 | 必传 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| `key_values` | 是 | string[] | 无 | 注册码内容数组 |
| `format` | 否 | string | `json` | `json` 或 `txt` |
| `response_type` | 否 | string | `json` | `json` 或 `txt` |
| `api_key` | 否 | string | 无 | Query 参数，浏览器测试用 |

返回参数：

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "results": [
      {
        "key_prefix": "ABCDE...",
        "revoked": true,
        "cloud_status": "deleted",
        "cloud_deleted": 1,
        "cloud_error": null
      }
    ]
  }
}
```

## 19. 删除注册码

`POST /api/key/delete`

`DELETE /api/key/delete`

鉴权：API 调用密钥权限 `key:delete`，或管理员 JWT。

Body 或 Query 参数：

| 参数 | 必传 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| `key_values` | 条件必传 | string[] 或逗号/换行字符串 | 无 | 注册码内容；和 `key_ids` 至少传一个 |
| `key_ids` | 条件必传 | number[] 或逗号字符串 | 无 | 本地注册码 ID；和 `key_values` 至少传一个 |
| `delete_scope` | 否 | string | `both` | `cloud` 只删 Cloud-Mail；`both` 两边一起删 |
| `scope` | 否 | string | `both` | `delete_scope` 别名 |
| `format` | 否 | string | `json` | `json` 或 `txt` |
| `response_type` | 否 | string | `json` | `json` 或 `txt` |
| `api_key` | 否 | string | 无 | 浏览器直访时传 API 调用密钥 |

返回参数：

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "results": [
      {
        "key_id": null,
        "key_prefix": "ABCDE...",
        "delete_scope": "both",
        "deleted": true,
        "local_deleted": true,
        "local_updated": false,
        "cloud_status": "deleted",
        "cloud_deleted": 1,
        "cloud_error": null
      }
    ]
  }
}
```

## 20. 注册码列表

`GET /api/key/list`

鉴权：API 调用密钥权限 `key:list`，或管理员 JWT。

Query 参数：

| 参数 | 必传 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| `page` | 否 | number | `1` | 页码 |
| `size` | 否 | number | `20` | 每页数量，最大 1000 |
| `status_val` | 否 | number | 无 | 本地状态：`0` 正常，`1` 禁用，`2` 失效 |
| `sort_by` | 否 | string | `key_id` | 排序字段：`key_id`、`key_value`、`status`、`role_id`、`role_name`、`used_count`、`max_uses`、`expire_days`、`expire_time`、`available_count`、`order_id`、`created_by`、`create_time` |
| `sort_order` | 否 | string | `desc` | `asc` 或 `desc` |
| `format` | 否 | string | `json` | `json` 或 `txt` |
| `response_type` | 否 | string | `json` | `json` 或 `txt` |
| `api_key` | 否 | string | 无 | 浏览器直访时传 API 调用密钥 |

返回参数：

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "list": [
      {
        "key_id": 1,
        "key_value": "ABCDE",
        "status": 0,
        "role_id": 1,
        "role_name": "普通用户",
        "used_count": 0,
        "available_count": 1,
        "expire_days": 30,
        "expire_time": "2026-06-16 00:00:00",
        "order_id": "order-002",
        "created_by": "admin",
        "cloud_status": "unused",
        "cloud_status_label": "未使用",
        "remark": "备注",
        "create_time": "2026-05-17 12:00:00"
      }
    ],
    "total": 1,
    "page": 1,
    "size": 20
  }
}
```

TXT 导出：

```text
注册码：ABCDE----到期时间：2026-06-16 00:00:00----可用次数：1
```

## 21. 添加文本

`POST /api/text/add`

鉴权：API 调用密钥权限 `text:add`，或管理员 JWT。

Body 参数：

| 参数 | 必传 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| `content` | 是 | string | 无 | 文本内容 |
| `type` | 否 | string | `txt` | `txt`、`json`、`xml` |
| `format` | 否 | string | `json` | `json` 或 `txt` |
| `response_type` | 否 | string | `json` | `json` 或 `txt` |
| `api_key` | 否 | string | 无 | Query 参数，浏览器测试用 |

返回参数：

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "status": "added"
  }
}
```

## 22. 随机文本

`GET /api/text/random`

鉴权：API 调用密钥权限 `text:random`，或管理员 JWT。

Query 参数：

| 参数 | 必传 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| `api_key` | 否 | string | 无 | 浏览器直访时传 API 调用密钥 |
| `access_key` | 否 | string | 无 | `api_key` 别名 |
| `type` | 否 | string | 无 | 文本类型筛选：`txt`、`json`、`xml`；不传则全部类型随机 |
| `response_type` | 否 | string | `txt` | 返回格式：`txt`、`json`、`xml` |

浏览器直访示例：

```text
https://你的Worker域名/api/text/random?api_key=你的API调用密钥&type=txt&response_type=txt
```

返回 TXT：

```text
随机输出内容
```

返回 JSON：

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "content": "随机输出内容",
    "type": "txt"
  }
}
```

返回 XML：

```xml
<response><text>随机输出内容</text></response>
```

## 23. 文本列表

`GET /api/text/list`

鉴权：API 调用密钥权限 `text:list`，或管理员 JWT。

Query 参数：

| 参数 | 必传 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| `page` | 否 | number | `1` | 页码 |
| `size` | 否 | number | `20` | 每页数量，最大 200 |
| `type` | 否 | string | 无 | 类型筛选：`txt`、`json`、`xml` |
| `sort_by` | 否 | string | `text_id` | 排序字段：`text_id`、`type`、`status`、`content`、`create_time` |
| `sort_order` | 否 | string | `desc` | `asc` 或 `desc` |
| `format` | 否 | string | `json` | `json` 或 `txt` |
| `response_type` | 否 | string | `json` | `json` 或 `txt` |
| `api_key` | 否 | string | 无 | 浏览器直访时传 API 调用密钥 |

返回参数：

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "list": [
      {
        "text_id": 1,
        "content": "随机输出内容",
        "type": "txt",
        "status": 0,
        "create_time": "2026-05-17 12:00:00"
      }
    ],
    "total": 1,
    "page": 1,
    "size": 20
  }
}
```

## 24. 删除文本

`DELETE /api/text/delete`

鉴权：API 调用密钥权限 `text:delete`，或管理员 JWT。

Body 或 Query 参数：

| 参数 | 必传 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| `text_id` | 条件必传 | number | 无 | 文本 ID；和 `id` 二选一 |
| `id` | 条件必传 | number | 无 | `text_id` 别名 |
| `format` | 否 | string | `json` | `json` 或 `txt` |
| `response_type` | 否 | string | `json` | `json` 或 `txt` |
| `api_key` | 否 | string | 无 | 浏览器直访时传 API 调用密钥 |

返回参数：

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "status": "deleted"
  }
}
```

## 25. 启用或禁用文本

`PUT /api/text/toggle`

鉴权：API 调用密钥权限 `text:toggle`，或管理员 JWT。

Body 参数：

| 参数 | 必传 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| `text_id` | 条件必传 | number | 无 | 文本 ID；和 `id` 二选一 |
| `id` | 条件必传 | number | 无 | `text_id` 别名 |
| `status` | 是 | number | 无 | `0` 启用，`1` 禁用 |
| `format` | 否 | string | `json` | `json` 或 `txt` |
| `response_type` | 否 | string | `json` | `json` 或 `txt` |
| `api_key` | 否 | string | 无 | Query 参数，浏览器测试用 |

返回参数：

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "status": "updated"
  }
}
```