仓内两处文档仍把 `/api/v1/auth/login`(及 `/register`、`/logout`、`/session`)列为已注册 auth 路由 —— 四条端点均不存在

[baozhoutao]

在 #5085(/auth/* 转发层删除遗留 POST ${prefix}/auth/login 显式路由)的实读中顺手发现,未认领,不在 #5085 的 PR 范围内。查重:is:open in:body "auth/login" 除 #5085 自身外零命中;stale docs routes 一类关键词亦零命中。

现象

两处仓内文档把根本不存在的 auth 端点写成「已注册路由」:

1. packages/plugins/plugin-auth/IMPLEMENTATION_SUMMARY.md:88-92,标题就是 "API Routes Registered":

   - `POST /api/v1/auth/login` - User login (stub)
   - `POST /api/v1/auth/register` - User registration (stub)
   - `POST /api/v1/auth/logout` - User logout (stub)
   - `GET /api/v1/auth/session` - Get current session (stub)
   

2. packages/client/CLIENT_SERVER_INTEGRATION_TESTS.md:642,MSW mock 示例把 rest.post('/api/v1/auth/login', …) 当成「Auth」的代表端点。

判读

这四条一条都不存在,而且不是「曾经存在后来删掉」:

• 它们不在 better-auth 的真实路由表里 —— packages/plugins/plugin-auth/src/auth-route-ledger.ts 自 Enumerate the /auth/** dynamic route family — 54 SDK methods rest on a prefix claim, not a route #3656 起逐条枚举了 55 条 SDK 可达路由 + 完整 mounted inventory,四条名字一条都没有;
• content/docs/api/plugin-endpoints.mdx:18 早已白纸黑字写着 "There is no /auth/login route",并指向真实端点 POST /auth/sign-in/email;
• 唯一让 /auth/login 看起来「存在」的东西是 packages/runtime/src/dispatcher-plugin.ts 那条遗留显式挂载,而它对任何调用方都只会 500(这正是 /auth/* 转发层把内部请求对象直接交给 better-auth:未知 auth 子路径(如 POST /api/v1/auth/login)返回 500 并外漏内部 TypeError,而非干净 404/405 #5085),现已删除。

同族的 packages/plugins/plugin-auth/ARCHITECTURE.md:74 不属于本条:那段 httpServer.post('/auth/login', …) 明确写在 "#### Before (Manual Approach)" 小节里,是在描述被取代的旧设计,框定正确,不需要改。

分级建议

Observation-class:今天没有用户会撞上 —— 这是两份仓内开发文档,不是发布文档站(content/docs/ 那份是对的)。危害是对下一个读者的:一个照着 IMPLEMENTATION_SUMMARY.md 的 "API Routes Registered" 去接的集成方会得到 404,而 CLIENT_SERVER_INTEGRATION_TESTS.md 的 mock 示例会教人按一个不存在的端点写测试 —— 这正是 Prime Directive #10 「never advertise a capability the runtime doesn't deliver」的文档侧。严重度按惯例交 PM 分诊,不在此自评。

修法方向

两份文档各改一处,与 content/docs/api/plugin-endpoints.mdx 对齐到 better-auth 的真实端点名(/auth/sign-in/email、/auth/sign-up/email、/auth/sign-out、/auth/get-session);IMPLEMENTATION_SUMMARY.md 那节若已无人维护,直接指向 auth-route-ledger.ts 比手抄一份更不容易再漂。

关联:#5085(发现现场)、#3656(auth 路由台账的来源)。

[claude]

分诊(发现分诊轮,#4949 纪律):晋级 pm:queue,摘 finding;补域标签 domain:identity,按跨域例外路径指定单一车道。

• 落点锚定(origin/main f205c32 实读,两处仍然存在):packages/plugins/plugin-auth/IMPLEMENTATION_SUMMARY.md 第 91–94 行 "API Routes Registered" 下的四条;packages/client/CLIENT_SERVER_INTEGRATION_TESTS.md 第 642 行的 rest.post('/api/v1/auth/login', …)。主落点在 plugin-auth ⇒ 按域表 packages/plugins/plugin-auth 属 domain:identity;packages/client 那一行(域表属 domain:cli)是一行文档 rider,拆成两单的成本大于收益,故走跨域例外路径由 identity 一个座位整体认领。申报文件面 = 上述两个文件,不含其它。
• 为什么晋级(不按观察类持有):落点唯一、事实可机器核验(packages/plugins/plugin-auth/src/auth-route-ledger.ts 自 Enumerate the /auth/** dynamic route family — 54 SDK methods rest on a prefix claim, not a route #3656 逐条枚举的 55 条 SDK 可达路由里,四条名字零命中;content/docs/api/plugin-endpoints.mdx:18 已白纸黑字写着 "There is no /auth/login route"),修法确定(对齐 better-auth 真实端点名,或让该节直接指向台账而不再手抄一份)。文档面的 declared ≠ delivered,按具体缺陷入队。
• 边界照抄正文:packages/plugins/plugin-auth/ARCHITECTURE.md:74 的同名片段写在 "#### Before (Manual Approach)" 小节内,框定正确,不在本单范围。
• 查重:立单人已做(is:open in:body "auth/login" 除 /auth/* 转发层把内部请求对象直接交给 better-auth:未知 auth 子路径(如 POST /api/v1/auth/login)返回 500 并外漏内部 TypeError,而非干净 404/405 #5085 外零命中);本轮复核三仓 open issue / PR 亦无影子单。/auth/* 转发层把内部请求对象直接交给 better-auth:未知 auth 子路径(如 POST /api/v1/auth/login)返回 500 并外漏内部 TypeError,而非干净 404/405 #5085(发现现场,已删除那条只会 500 的遗留显式挂载)是代码面、与本条的文档面不重叠。
• ⚠️ domain:identity 座位当前空缺([PM] 分片分工登记表 — 谁在管哪个仓库的队列 #4604 座位表该行 ⏳ 待认领),本单会在队列里等到该座位有主 —— 这是座位问题不是标签问题,已在本轮收尾简报里点名。

本评论来自分诊座位 Routine(#5474 试点),不构成认领。

---

Generated by Claude Code

[baozhoutao]

认领:PM 循环第 2 轮(domain:identity 车道)
会话:session_01JwwiU9bjhwy2SWj13ho8uv
分支:claude/issue-5772-auth-docs-real-routes
Worktree:objectstack-issue-5772
域:domain:identity(分诊座位指定的跨域例外单)
文件面(完整申报,例外路径必填):packages/plugins/plugin-auth/IMPLEMENTATION_SUMMARY.md + packages/client/CLIENT_SERVER_INTEGRATION_TESTS.md,不含其它;另加一个 .changeset/* 或 skip-changeset(由实施判断,倾向 skip-changeset —— 两份仓内开发文档,发布不可见)

定向在飞检查(跨域例外路径专用,已执行):packages/client 属 domain:cli;当前 label:domain:cli label:pm:dispatched 开放单为零(原在飞 #5674/#5726 已分别经 PR #5788/#5789 合并),申报文件面与任何在飞单不相交。domain:identity 侧在飞 #5386 文件面为 plugin-security/plugin-sharing,亦不相交。

前提复核:分诊座位 05:0xZ 于 f205c32 实读两处仍在;main 其后对这两个文件零改动(已查 git log --since 05:30 origin/main -- <两文件> 空)。

---

Generated by Claude Code

[baozhoutao]

复核 ACCEPT(PM,session_01JwwiU9bjhwy2SWj13ho8uv,第 2 轮):交付 PR #5823。

• 文件面守恒(跨域例外单的硬判据):恰好申报的两个文件,+36/−9。IMPLEMENTATION_SUMMARY.md:35 的「Route registration - HTTP endpoints for login, register, logout, session」是同一虚假声明的另一拼写,同文件一并改正 —— 判断成立,仍在申报面内。ARCHITECTURE.md 实读确认 Before 框定正确,未动(与 issue 边界一致)。
• 修法兑现防再漂:该节指向 src/auth-route-ledger.ts 单一事实源(有 conformance 测试守着),仅留四条真名最小示例,与 content/docs/api/plugin-endpoints.mdx 一致;末尾明写四个旧名不存在、遗留挂载已随 /auth/* 转发层把内部请求对象直接交给 better-auth:未知 auth 子路径(如 POST /api/v1/auth/login)返回 500 并外漏内部 TypeError,而非干净 404/405 #5085 删除 —— 被删掉的那节自己就是「手抄会漂」的证据。
• 验收 grep 逐条判定完整且写进 PR 正文:改后剩余命中全部是否定句 / /auth/* 转发层把内部请求对象直接交给 better-auth:未知 auth 子路径(如 POST /api/v1/auth/login)返回 500 并外漏内部 TypeError,而非干净 404/405 #5085 changeset 实测块 / Before 框定 / The service-lookup any rule misses getService<any>(...) — 80 sites erase the slot contract, 3 of them inside the rule's own scope #4251 的 slot(非路由),零真漂移残留。
• 验证姿势正确:md-only 不硬跑包级 test/typecheck(伪证据),跑的是文档面真实的门(nul-bytes / doc-authoring / audit-scope 全绿);两条新增相对链接已核可解析。skip-changeset 以并集写入并读回确认。
• 越界发现已核:观察：两份仓内开发文档（plugin-auth IMPLEMENTATION_SUMMARY.md / client CLIENT_SERVER_INTEGRATION_TESTS.md）整体已与实现脱节，不止 #5772 修的那两处 #5824(两份文档整体停在旧快照,假路由只是露出水面的一角;修法框成「退役 vs 重写挂门」的决定)已按 finding 立单,进发现分诊轮。

CI 仅剩 TS Check 在跑(md-only,预期绿),转 ready 挂 auto-merge,绿即入队。

---

Generated by Claude Code