admin-packages

2026-09-13 修正：所有路径统一 /api/v1/*（不再有 /api/admin/*）。本文档所列端点 100% 与 server 一致，URL 实测全部可访问。

核心场景：管理员在 baozi 后台创套餐 → 加 tier（不同价格/配额组合）→ 用户在前台购买。

鉴权

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

💡 三方接入方：本文档的 admin 端点不是三方调用入口。三方必须用 M2M OAuth 2.0 client_credentials 鉴权（5 scope），详见 v1 API 参考 §1.3 Scope 列表或精简版三方接入文档。
获取固定测试 client：联系 trust@ohoooho.com，使用 baozi-e2e-fixed-2026（scopes 全开，note 标 FIXED 不轮换）。

范围：本文档只列 /api/v1/admin/* 端点（5 个）。查询套餐 GET /api/v1/packages 是公开接口，不在本文档范围，详见 v1 API 参考。

调用方式：

curl https://baozi.ohoooho.com/api/v1/admin/users \
  -H "Cookie: baozi_token=<your_session_cookie>"

已实现端点（2026-09-13 现状）

`GET /api/v1/admin/users?q=<keyword>`

查 baozi 用户（用于 admin 前端选择目标用户）。

查询参数：

参数	类型	必填	说明
`q`	string	否	按 username / name / email 模糊匹配
`limit`	number	否	默认 50，最大 200
`offset`	number	否	默认 0

响应 200：

{
  "success": true,
  "api_version": "v1",
  "data": [
    {
      "id": 1,
      "idp": "logto",
      "sub": "ceiu3ijbigus...",
      "newapi_uid": 17,
      "username": "baozi-1",
      "name": "闲云",
      "email": "xianyun@ohoooho.com",
      "last_login_at": 1723723456789,
      "created_at": 1723000000000
    }
  ],
  "total": 1,
  "_meta": { "q": "", "limit": 50, "offset": 0 }
}

`GET /api/v1/admin/grants`

列所有管理员发起的配额变更记录（审计用）。

响应 200：

{
  "success": true,
  "api_version": "v1",
  "data": [
    {
      "id": 1,
      "admin_idp": "logto",
      "admin_sub": "ceiu3ijbigus...",
      "admin_name": "闲云",
      "target_username": "baozi-2",
      "target_newapi_uid": 18,
      "pre_quota": 0,
      "quota_delta": 500000,
      "post_quota": 500000,
      "plan_name": "trial",
      "note": "测试种子用户",
      "order_ref": "",
      "created_at": 1723723456789
    }
  ],
  "total": 1,
  "_meta": { "source": "admin_grants", "version": "v1" }
}

`POST /api/v1/admin/grant-quota`

管理员给 baozi 用户加配额（不发订单，直接记 audit 流水）。

请求 body：

字段	类型	必填	说明
`username`	string	是	目标 baozi 用户名
`quota_delta`	number	是	本次发放配额（tokens）
`plan_name`	string	否	套餐名（默认 `lite`）
`note`	string	否	审计备注
`order_ref`	string	否	关联订单号

响应 201：

{
  "success": true,
  "api_version": "v1",
  "data": { "id": 2, "username": "baozi-2", "quota_delta": 500000, "plan_name": "lite" }
}

错误码：

HTTP	code	含义
401	`auth_required`	未登录
403	`admin_required`	非管理员
404	`user_not_found`	目标用户不存在

`POST /api/v1/admin/create-user`

管理员手动建 baozi 用户（不走 OIDC，运营专用）。

请求 body：

字段	类型	必填	说明
`idp`	string	是	身份提供方（如 `logto`、`manual`）
`sub`	string	是	idp 唯一标识
`username`	string	是	baozi 用户名（全局唯一）
`name`	string	否	显示名
`email`	string	否	邮箱
`role`	enum	否	`user` / `admin`（默认 `user`）

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

查指定 baozi 用户的所有 token（含 active / disabled / expired）。

响应 200：

{
  "success": true,
  "api_version": "v1",
  "data": [
    {
      "id": 1,
      "package_id": "pkg-daily-chat",
      "scene": "chat",
      "tier": "lite",
      "period": "月",
      "status": "active",
      "new_api_token_id": 285,
      "token_name": "bz-coding-lite-z6bn84",
      "quota": 4000,
      "used": 0,
      "expires_at": 1791857235000
    }
  ],
  "total": 1
}

URL 自检清单

本文档列出的所有 URL，2026-09-13 实测结果：

URL	状态	说明
`GET /api/v1/admin/users`	✅ 200	已实现
`GET /api/v1/admin/grants`	✅ 200	已实现
`POST /api/v1/admin/grant-quota`	✅ 403/201	已实现
`POST /api/v1/admin/create-user`	✅ 403/201	已实现
`GET /api/v1/admin/user-tokens/:username`	✅ 403/200	已实现
`GET /api/v1/packages`	✅ 200	公开接口（不在本文档范围）
`GET /api/v1/packages/:id`	✅ 200/404	公开接口（不在本文档范围）
`GET /api/admin/packages`	❌ 已下架	从未注册（老文档凭空写）
`POST /api/admin/packages`	❌ 已下架	从未注册（老文档凭空写）
`PATCH /api/admin/packages/:id`	❌ 已下架	从未注册（老文档凭空写）
`GET /api/admin/packages/:id/tiers`	❌ 已下架	从未注册（老文档凭空写）

联系 baozi

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

发现文档与 server 不一致？直接打回本文档（看 git log「docs-fix-2026-09-13」commit），闲云立刻跟进。