baozi API 规范化改造方案（K-275 C 选项）

> 闲帝 2026-09-10 08:14 拍板「选 C，尽量全都规范化，如果一次性做不完，可以分步做」。 > 本文是分阶段实施计划。

TL;DR

目标：baozi 全栈 API 路径规范化（kebab-case + 带版本 + Logto auth 段参照 Logto 官方）
范围：baozi-service（3041）45 端点 + baozi-frontend（route.ts）16 端点 + 调用方 24 处 = 85 处改动
阶段：Phase 1 (auth) → Phase 2 (baozi own) → Phase 3 (forward) → Phase 4 (frontend 重生成) → Phase 5 (调用方切换) → Phase 6 (308 重定向) → Phase 7 (清理)
回退：每个 phase 完成后立即 e2e 验证，任何一阶段失败就停在那一阶段
预计：单 phase 30-90 分钟，全部完成 1-2 个工作日

---

一、K-275 决策记录（闲帝拍板 18:53）

三个决策（K-273）

Logto 段用 kebab-case（新 /auth/sign-in，老 signin 重定向到 sign-in）
认证部分参照 Logto 标准（/sign-in /sign-up /callback /oidc/auth 等）
所有 API path 必须带版本（/api/v1/*）

业务路径 vs 转发路径边界（K-276）

类型	路径模式	示例
baozi own	`/api/v1/*`（带版本）	`/api/v1/me` `/api/v1/me/token` `/api/v1/packages`
baozi own session	`/api/v1/session/*`	`/api/v1/session/me` `/api/v1/session/logout`
baozi auth (Logto 段)	`/auth/*`（不带版本，参照 Logto）	`/auth/sign-in` `/auth/sign-up` `/auth/callback`
new-api 转发	`/api/user/` `/api/token/` `/api/v1/models`（不带 baozi v1，new-api own）	`/api/user/self` `/api/token/?p=0` `/v1/chat/completions`

baozi-service 现存端点（45 个）

已查实 — baozi-service logto-node-migration/server.js.current 包含 45 个路由：

A. Auth (Logto 集成) — 3 个

GET  ~~signin~~               (line 674, 已废弃/重命名为 /auth/sign-in)
GET  /auth/login-newapi        (line 690)
GET  /auth/userinfo            (line 734)

→ 重命名为：

GET  /auth/sign-in             (kebab-case)
GET  /auth/sign-in/newapi      (Logto callback 后走 new-api 登录)
GET  /auth/userinfo            (保留，按 Logto 习惯)

B. Baozi own (api/*) — 18 个

GET  /api/me                   (line 1656)
POST /api/me/token             (line ???)
... 等

→ 全部加 /v1：

GET  /api/v1/me
POST /api/v1/me/token
... 等

C. Baozi own (_v2 实验) — 4 个（已存在！）

GET  /health_v2
POST /auth_v2/signin
GET  /auth_v2/callback
GET  /me_v2

→ 这是 Phase 1 的天然测试床，先把 4 个实验端点跑通再批量改。

D. 转发 new-api — 12 个

/api/user/login
/api/user/register
/api/user/self
/api/user/topup/info
/api/user/topup/self
/api/user/topup
/api/user/?p=0&search=
/api/user/{id}
/api/token/?p=0
... 等

→ **保留 /api/user/* 不带版本**（new-api own，K-276 已定义边界）

E. Admin / Ops — 6 个

/admin/...
/ops/...

→ 加 v1：/api/v1/admin/* /api/v1/ops/*

F. Misc — 2 个

/manifest
/health

→ /api/v1/manifest /api/v1/health

---

二、Phase 划分（分步做）

Phase 1 — Auth 段改造（最小风险，先跑通）⏱️ 30 分钟

目标：把 baozi-service 的 /auth/* 3 端点改成 kebab-case + Logto 标准。

改动：

老 signin → 新 /auth/sign-in
/auth/login-newapi → /auth/sign-in/newapi（语义更清晰）
Caddyfile baozi.ohoooho.com 块加 redir 老 signin → 新 /auth/sign-in 308
baozi-frontend signin route.ts → 新 /auth/sign-in
调 baozi-service 的所有内联 URL 引用 → /auth/sign-in
e2e 验证：登录流程通

回退：Caddy 308 redir 立即生效，反向不行。

Phase 2 — Baozi own API 加 v1（中风险）⏱️ 60 分钟

目标：baozi-service 18 个 /api/* 端点全部加 v1。

改动：

所有 /api/* → /api/v1/*（除 /api/user/* /api/token/* 转发段）
baozi-frontend route.ts /api/me → /api/v1/me
lib/new-api.ts 调用方批量改
Caddyfile 加 redir /api/me → /api/v1/me 308（兼容旧前端缓存）
e2e 验证：dashboard / pricing / orders / tokens 全部通

回退：Caddy 308 redir 立即生效。

Phase 3 — Forward 段规范化（低风险）⏱️ 20 分钟

目标：转发 new-api 的端点保持原样（K-276 已定义边界），但补 Caddy 反代到 oneapi。

改动：

Caddyfile baozi.ohoooho.com 块加：

   @newapi path /api/user/* /api/token/* /v1/* /v1beta/*
   handle @newapi {
       reverse_proxy 127.0.0.1:3030
   }

baozi.ohoooho.com 现在能调 /api/user/self 等 new-api 原生端点
e2e 验证：/api/user/self 200 返用户信息

风险：Caddy 反代是新增配置，不破坏现有。

Phase 4 — Frontend route.ts 重建（中风险）⏱️ 45 分钟

目标：baozi-frontend 16 个 route.ts 按规范重建。

改动：

16 个 route.ts 文件加 /v1/ 前缀
调整内部 forward 调用 → baozi-service /api/v1/*
typecheck + build 验证

回退：git revert。

Phase 5 — 调用方切换（高风险）⏱️ 60 分钟

目标：前端所有调用 baozi API 的地方切换到新路径。

改动：

lib/new-api.ts 所有 API path 加 /v1 前缀
lib/api-client.ts 同上
所有 fetch("/api/...") 调用方加 /v1
e2e 验证：所有页面通

回退：git revert + Caddy 308 redir 兜底。

Phase 6 — 308 重定向兜底（生产兼容）⏱️ 30 分钟

目标：生产环境老用户 / 老书签 / 老 API key 仍能用。

改动：

Caddyfile 加全套 redir：

   redir /api/me /api/v1/me permanent
   redir /api/me/token /api/v1/me/token permanent
   ... 等

测试老 URL 全部 308 跳转
e2e 验证

Phase 7 — 清理（低风险）⏱️ 30 分钟

目标：删老路由 / 清理老 token / 清理文档。

改动：

baozi-service 删老 handler（保留 _v2 4 端点作为对照）
baozi-frontend 删老 route.ts（保留 .bak）
清理 baozi-frontend user_id=1 的 24 个老 token（待闲帝拍板）
删 docs 里老 URL 引用

---

三、依赖与前置条件

已完成 ✅

K-272 纠错（聚焦 Logto 集成 API 命名）
K-273 三决策（kebab-case + Logto 标准 + 带版本）
K-274 实际查 Logto 官方文档（确认 /sign-in /sign-up /callback 等真实存在）
K-276 dopple 推荐边界（业务路径 vs 转发路径边界定义）

待闲帝拍板 ⏳

308 重定向范围（K-275 细节 1）

- A 全 308 永久（推荐） - B 仅重要端点 308 - C 不做 308 硬切

老 token 清理（K-275 细节 2）

- user_id=1 的 24 个 P0 老 token 要不要顺手在 Phase 7 做

K-266 A/B/C 拍板（API Key 设计 — coding/chat 场景合并）
Claude Opus 5 接入决策

---

四、回退方案

每个 phase 完成后立即 e2e 验证，任何一阶段失败就停在那阶段，不回退也不继续。

Phase 1 ✅ ─→ Phase 2 ✅ ─→ Phase 3 ✅ ─→ Phase 4 ✅ ─→ Phase 5 ✅ ─→ Phase 6 ✅ ─→ Phase 7 ✅
   │            │            │            │            │            │            │
   └─ 失败停   └─ 失败停   └─ 失败停   └─ 失败停   └─ 失败停   └─ 失败停   └─ 失败停

回退手段：

Caddy 308 redir 双向兜底
git revert 单 phase
baozi-service 保留 _v2 4 端点作为对照
baozi-frontend 保留 .bak 备份

---

五、成功标准

技术指标

[ ] baozi-service 45 端点全部 kebab-case + 带版本（除 forward 段）
[ ] baozi-frontend 16 route.ts 全部带 /v1
[ ] 24 处调用方全部切换
[ ] Caddy 308 redir 兜底生效
[ ] 真浏览器 e2e 19/19 全通（login / register / dashboard / pricing / orders / tokens / logout）

业务指标

[ ] 老用户无感知切换（308 兜底）
[ ] 老 API key 仍可用
[ ] 老链接 / 老书签仍 308 跳转
[ ] 文档站 docs 链接全部更新

文档指标

[ ] baozi public/docs/ 全套文档 URL 更新
[ ] 闲帝库 _docs/ 同步副本
[ ] K-NNN 编号完整记录

---

六、变更日志

版本	日期	变更	作者
1.0	2026-09-10	初版：闲帝 08:14 拍板 C 选项 + 列 7 phase 实施计划	闲云

---

七、相关链接

K-272 PROGRESS（纠错 + 聚焦 Logto 集成 API 命名）
K-273 PROGRESS（URL 标准 3 决策）
K-274 PROGRESS（实际查 Logto 官方文档）
K-275 PROGRESS（拍板 C 选项 + 启动改造）
K-276 PROGRESS（dopple 推荐边界 vs Logto 官方 vs 我之前查的对比）
闲帝库 _docs/api-standardization-plan.md（同步副本）