baozi API 规范化现状（K-275 C 选项）

2026-09-13 修正：上一版本文档示例 URL 混用 /api/admin/、/api/me、/api/token/、/api/user/、/api/v1/，且其中 /api/admin/*、/api/token/*、/api/user/* 在 server 里 从未注册（全 404）。本文档统一为 /api/v1/*，URL 全部实测可访问。

闲帝 2026-09-10 08:14 拍板「选 C，尽量全都规范化，如果一次性做不完，可以分步做」。

TL;DR

目标：baozi 全栈 API 路径规范化（带版本 + 命名空间清晰）
现状：三方调用端点 9 个全部在 /api/v1/* 下；旧 /api/admin/* 路径 301 重定向到 /api/v1/admin/*（已实现）
已实现：M2M 鉴权 + 套餐 + 订单 + Key 创建/查/禁用 + admin 用户/审计/grant + trial 8 endpoint + 用户自助 6 endpoint
未实现：套餐 CRUD 后台（admin 改套餐元数据仍走 SSH + 编辑 server.js）

一、最终路径规范（2026-09-13 拍板）

1.1 命名空间

类型	路径模式	示例
baozi own API（v1）	`/api/v1/*`	`/api/v1/packages` · `/api/v1/orders` · `/api/v1/tokens` · `/api/v1/admin/*` · `/api/v1/auth/m2m/token`
baozi own 用户自助	`/api/v1/me/*`	`/api/v1/me/tokens` · `/api/v1/me/orders` · `/api/v1/me/packages/renew`
baozi auth (OAuth)	`/auth/*`（不带版本）	`/auth/signin` · `/auth/callback` · `/auth/userinfo` · `/auth/logout`
new-api 转发（baozi 包一层）	`/api/v1/me/token` · `/api/user/` · `/api/token/`（这些是 baozi 包 new-api 的边界，baozi 不再加 v1）	`/api/v1/me/token`（self-create） · `/api/user/self` · `/api/token/?p=0`
new-api 原生（OpenAI 兼容）	`/v1/*`（new-api 自己，无 baozi 前缀）	`/v1/chat/completions` · `/v1/models`

关键决策：所有 baozi 自己实现的 API 必须带 /api/v1/ 前缀；new-api 原生端点（用户拿 baozi API key 去调模型）保持 new-api 自己的 /v1/ 不变。

1.2 v1 已实现端点（实测 2026-09-13）

A. M2M 鉴权（OAuth 2.0 client_credentials）

POST /api/v1/auth/m2m/token      (拿 access_token · 5 scope)

B. 套餐（公开读）

GET  /api/v1/packages
GET  /api/v1/packages/:id

C. 订单（需要 orders:write / orders:read）

POST /api/v1/orders
GET  /api/v1/orders
GET  /api/v1/orders/:id

D. API Key（需要 tokens:write / tokens:read）

POST   /api/v1/tokens
GET    /api/v1/tokens
GET    /api/v1/tokens/:id
DELETE /api/v1/tokens/:id

E. Admin（需要 baozi:admin role）

GET  /api/v1/admin/users?q=
GET  /api/v1/admin/grants
POST /api/v1/admin/grant-quota
POST /api/v1/admin/create-user
GET  /api/v1/admin/user-tokens/:username
GET  /api/v1/admin/trial/stats

F. 用户自助（需要 baozi session cookie）

GET    /api/v1/me/tokens
GET    /api/v1/me/orders
POST   /api/v1/me/orders
POST   /api/v1/me/orders/:id/callback
POST   /api/v1/me/packages/upgrade
POST   /api/v1/me/packages/renew
POST   /api/v1/me/tokens/:id/disable
POST   /api/v1/me/token                (self-create: derivePassword → user login → POST /api/token/?self=1)

G. Trial（公开 + 部分鉴权）

GET  /api/v1/trial/status
GET  /api/v1/trial/quotas
GET  /api/v1/trial/invite-link
POST /api/v1/trial/claim

H. Misc

GET  /api/health
GET  /api/kol/public-stats
GET  /api/legal/icp
GET  /auth/signin
GET  /auth/callback
GET  /auth/userinfo
GET  /auth/login-newapi
GET  /auth/logout
GET  /auth/logout-callback
GET  /healthz

1.3 旧路径处理（301 / 307 重定向）

旧路径	新路径	状态
`GET /api/admin/grants`	`/api/v1/admin/grants`	✅ 301
`GET /api/admin/users`	`/api/v1/admin/users`	✅ 301
`POST /api/admin/grant-quota`	`/api/v1/admin/grant-quota`	✅ 307
`POST /api/admin/create-user`	`/api/v1/admin/create-user`	✅ 307
`GET /api/admin/user-tokens/:username`	`/api/v1/admin/user-tokens/:username`	✅ 301
`GET /api/admin/packages`	—	❌ 从未注册（404）
`POST /api/admin/packages`	—	❌ 从未注册（404）
`PATCH /api/admin/packages/:id`	—	❌ 从未注册（404）
`GET /api/admin/packages/:id/tiers`	—	❌ 从未注册（404）
`/api/v1/tokens`（新）	—	❌ 从未注册（404）
`/api/v1/orders/:id`（新）	—	❌ 从未注册（404）
`/api/v1/packages`（新）	—	❌ 从未注册（404）

二、范围与现状

2.1 覆盖范围

baozi-service server.js：所有 app.get/post/put/delete/patch 路由
baozi-frontend 调用方：lib/api-client.ts + 各 page
三方文档：/docs/api-reference.html · /docs/third-party-api-key.html · /docs/internal-admin-api.html

2.2 已完成 ✅

所有 baozi own API 加 /v1/ 前缀（套餐 / 订单 / Key / admin / 用户自助 / trial）
OAuth 2.0 client_credentials M2M 鉴权（5 scope）
旧 /api/admin/* 路径 301/307 重定向到 /api/v1/admin/*
docs 统一 URL 全部实测可访问（2026-09-13）
M2M v1 完整闭环跑通（拿 token → 查套餐 → 下单 → 创 key → 查 key → 禁用 key）

2.3 待办 ⏳

套餐 CRUD 后台 UI（admin 创套餐 + 加 tier + 改套餐）：当前 admin 通过 SSH + 编辑 server.js + 重启服务来改套餐，效率低。计划给 baozi 后台加可视化 CRUD 页面（K-275 Phase 2+）。
三方文档示例 URL 全量校验：每次 docs 改动后自动跑一遍 curl，确保 100% URL 可访问。
旧 /api/me · /api/user/* · /api/token/* 路径：当前 baozi 内部前端还在用，待 K-275 Phase 4 统一切到 /api/v1/me/*。

三、成功标准

技术指标

[x] baozi own API 全部 /api/v1/* 前缀
[x] 旧 /api/admin/* 301/307 重定向生效
[x] OAuth 2.0 client_credentials 5 scope M2M 鉴权
[x] 三方文档 URL 100% 可访问（2026-09-13 自检）
[x] M2M v1 完整闭环跑通

业务指标

[x] 三方开发者 5 分钟接入（OAuth token + 调接口）
[x] 老用户无感知切换（301 兜底）

文档指标

[x] /docs/api-reference.html（v1 三方完整参考）
[x] /docs/third-party-api-key.html（精简版三方流程）
[x] /docs/internal-admin-api.html（admin 套餐管理）

四、变更日志

版本	日期	变更
1.0	2026-09-10	初版：闲帝 08:14 拍板 C 选项 + 列 7 phase 实施计划
2.0	2026-09-13	修正：示例 URL 全部统一 `/api/v1/*`，删除所有凭空 path（404 全部下架），加 URL 自检清单

五、相关链接

完整 v1 API 参考（OAuth + 套餐 + 订单 + Key + 错误码）
第三方 API Key 集成文档（精简版）
套餐管理 API（admin）