管理员运营 API

管理员日常运营工具：用户管理、渠道健康监控、审计日志查询、草稿保存等。

---

鉴权

所有接口都需要 baozi 管理员身份（OIDC 登录 + admin role）。

---

1. 查询用户列表

`GET /api/admin/users`

查询参数：

参数	类型	默认	说明
`limit`	number	20	最多返回条数
`offset`	number	0	跳过条数
`search`	string	-	按 username / email 模糊搜索

响应 200：

{
  "success": true,
  "data": {
    "items": [
      {
        "id": 42,
        "username": "zhangsan",
        "email": "zhangsan@example.com",
        "tier": "pro",
        "quota_remaining": 18500,
        "created_at": 1730000000000,
        "last_login_at": 1730000000000
      }
    ],
    "total": 1
  }
}

---

2. 查询某用户的所有 Token

`GET /api/admin/user-tokens/:username`

响应 200：

{
  "success": true,
  "data": {
    "user": { "id": 42, "username": "zhangsan" },
    "tokens": [
      {
        "id": 123,
        "name": "my-app-key",
        "key_preview": "sk-baozi-xxxxxx...xxxx",
        "status": 1,
        "created_at": 1730000000000
      }
    ]
  }
}

---

3. 渠道健康检查

`GET /api/admin/channels`

列出 baozi 后端对接的所有 LLM 渠道（OpenAI / Anthropic / 国产模型等）。

响应 200：

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "OpenAI 官方",
      "base_url": "https://api.openai.com/v1",
      "enabled": true,
      "model_count": 12,
      "last_health_check_at": 1730000000000,
      "last_health_status": "ok"
    }
  ]
}

`POST /api/admin/channels/test`

测试某渠道连通性（只发 1 个轻量请求，不会消耗生产 quota）。

请求 body：

字段	类型	必填	说明
`channel_id`	number	是	渠道 ID

响应 200：

{
  "success": true,
  "data": {
    "channel_id": 1,
    "status": "ok",
    "latency_ms": 234,
    "tested_at": 1730000000000
  }
}

错误码：

HTTP	code	含义
502	`CHANNEL_UNREACHABLE`	渠道不可达
504	`CHANNEL_TIMEOUT`	渠道超时

---

4. 审计日志

`GET /api/admin/audit-logs`

查询管理员操作审计记录。

查询参数：

参数	类型	默认	说明
`limit`	number	50	最多返回条数
`offset`	number	0	跳过条数
`action`	string	-	过滤：`grant_quota` / `refund_purchase` / `create_user` / ...
`admin_user_id`	number	-	过滤特定管理员
`target_user_id`	number	-	过滤被操作的用户

响应 200：

{
  "success": true,
  "data": {
    "items": [
      {
        "id": 9876,
        "admin_user_id": 1,
        "admin_username": "admin",
        "action": "grant_quota",
        "target_user_id": 42,
        "payload": { "quota": 10000, "reason": "客服补偿" },
        "request_ip": "1.2.3.4",
        "created_at": 1730000000000
      }
    ],
    "total": 1
  }
}

---

5. 健康检查

`GET /api/admin/health`

baozi 内部依赖（DB / Redis / 上游）的综合健康状态。

响应 200：

{
  "success": true,
  "data": {
    "status": "ok",
    "components": {
      "database": "ok",
      "cache": "ok",
      "upstream_default": "ok"
    },
    "checked_at": 1730000000000
  }
}

---

6. 场景映射

`GET /api/admin/scene-mapping`

查询"用户场景 → 推荐套餐"的映射规则（用于前端智能推荐）。

`POST /api/admin/scene-mapping`

创场景映射规则。

请求 body：

字段	类型	必填	说明
`scene`	string	是	场景 ID（如 `daily_chat` / `code_plan`）
`package_id`	string	是	推荐套餐 ID
`priority`	number	否	推荐优先级（数字大=优先）

---

7. 草稿

用于前端临时保存"创建套餐 / 创建兑换码"等表单内容，避免误关丢失。

`POST /api/admin/drafts`

存草稿。

请求 body：

字段	类型	必填	说明
`kind`	string	是	草稿类型：`package` / `tier` / `redemption` / `redemption_batch`
`payload`	object	是	草稿内容

`GET /api/admin/drafts`

列出我的草稿。

`PUT /api/admin/drafts/:id`

更新草稿。

`DELETE /api/admin/drafts/:id`

删草稿。

---

8. 管理员手动建用户

`POST /api/admin/create-user`

请求 body：

字段	类型	必填	说明
`username`	string	是	用户名
`email`	string	否	邮箱
`tier`	string	否	初始 tier：`free` / `pro` / `enterprise`

---

联系 baozi

文档不全？发邮件到 support@ohoooho.com 或在飞书群里 @ 闲云。