81 · 刷新失败不误判登出
性质:方案(已落地)。把
/api/auth/refresh拿到响应后的判定从「非 2xx 即登出」改成三态:只有「HTTP 401 且响应是引擎信封」才清登录态;5xx、dev 下 Vite 代理在重启窗口回的 500、非信封的 401 都是暂时性故障,静默保留 token 等下一拍。 状态:✅ 2026-11-14 落地(未 commit,等验收)。客户端判定:npm test35/35 绿(含本方案新增 8 条)、npm run typecheck/npm run build通过;两个 check 脚本退出 0。端到端「重启后仍保持登录」与反向「伪造 refresh 值后确实回登录页」是人工浏览器走查项,由用户验收时跑(见 §4)。 代码落点:web/src/auth.ts(RefreshOutcome/readRefreshOutcome/isEnvelope、doRefresh按三态分支)、web/test/authrefresh.test.ts(新增回归网)。无后端改动、无契约字节变化。 前置真源:doc/40(响应信封{code,message,data}固定序与业务码表)、doc/46(SSE 事件流,是这次刷新请求的触发方)、doc/36 §34(登录态统一在auth.ts)。 边界:不改后端 Go 代码;不改scripts/acceptance/、vite.config.ts;不改 SSE 重连节奏;不把 token 从sessionStorage挪到localStorage;不放宽真失效判定(真 401 + 信封仍必须登出)。
1 病灶:把「拿到非 2xx」等同于「登录失效」
1.1 一场真实发生的戏
dev 环境里把引擎重启一次(改了后端代码要让新二进制生效)。浏览器上开着的那个标签页——一直挂在 http://127.0.0.1:5173/,没换地址、没换标签页、没退出——自己退回了登录页,表单上写着「登录已过期,请重新登录」。用户什么都没做。
这不是「登录真的过期了」。服务端从没拒绝过这个人:dev 的 TAKO_JWT_SECRET 是固定默认值、重启前后一致;refresh token 存在 Postgres 的 refresh_tokens 表里、重启不丢;重启窗口前后的 refresh 请求没有一条 401。
1.2 链条在哪一步断了(四步,全部可复核)
- 重启窗口里,引擎还没 bound,Vite 还在。
dev.sh日志:[vite] http proxy error: /api/auth/refresh→Error: connect ECONNREFUSED 127.0.0.1:8901。引擎晚约 44 秒才Listening and serving,中间是「前端在、引擎不在」。 - Vite 对普通 HTTP 请求代理出错,写死回 500(
web/node_modules/vite/dist/node/chunks/config.js:res.writeHead(500, { "Content-Type": "text/plain" }).end())。 - 前端把这个 500 当成登录失效。 旧
doRefresh():if (!res.ok || !body || body.code !== 0 || !body.data?.accessToken) { clearAuth('expired') return false }fetch没有抛异常(拿到的是一个正常的 500 响应),所以「网络错误保留 token」的分支根本没走到,直接落到!res.ok→clearAuth('expired')→ 登录表单。 - 这个 refresh 是谁打的:SSE 重连。
web/src/mutation.ts里引擎一停,事件流断开 →es.onerror→ 重连前先自己refreshAccessToken()→ 打到 Vite → 代理到已停的引擎 → 500。
1.3 严重性
确定性、每次必现:只要重启引擎时浏览器有标签页开着,这个标签页就会被登出一次。同类误判的后果不止重启——引擎内部错误(codeInternal)回 500 时,同样会把一个合法的登录清掉。
1.4 这不是「设计错了」,是同一条规则漏写了一处
同一份文件里另外三处判定其实是对的:switchTenant / settleSwitch 只有 res.status === 401 才 clearAuth();authFetch 只在「连 refresh token 都没有」时才 clearAuth('expired');loginWithPassword 失败只返回错误、不动登录态。漏的就是 doRefresh 这一处。
2 完整业务链路(谁 → 谁 → 谁)
用户在页面登录
→ saveAuth 把 access/refresh 写进 sessionStorage
→ 页面静止(没人调 api)时,只有 SSE 事件流在维持
→ 引擎重启 → SSE 断开 → es.onerror
→ 重连前先 refreshAccessToken():POST /api/auth/refresh ← 本方案动的是这一环的判定
→ 引擎回什么决定走哪条路:
200 信封 code=0 → updateTokens(新 token 对) → 重建 SSE,用户无感
401 + 引擎信封 → 真的失效 → clearAuth('expired') → 登录表单(应该保留)
5xx / 代理 500 → 暂时性故障 → 保留 token,下一拍再试(今天错走成了「失效」)
本方案动的唯一一环:/api/auth/refresh 拿到响应之后的三态判定。上游是引擎的响应,下游是 clearAuth 与 SSE 重建。不改谁去刷新、不改刷新节奏、不改任何后端。
3 判定口径:必须是引擎信封形状才判失效
POST /api/auth/refresh 的响应口径(后端真源 internal/runengine/auth.go):
| 情形 | HTTP | 业务码 | 该不该登出 |
|---|---|---|---|
| 成功 | 200 | 0 + data.accessToken |
不登出,换 token |
| refresh token 无效 / 用户被停用 / 无可用租户 | 401 | 111105 |
登出 |
| 请求体格式不对(不该发生) | 400 | 111101 |
不登出 |
| 内部错误(DB 抖动等) | 500 | codeInternal |
不登出 |
| 引擎没起(dev 下 Vite 代理兜底) | 500 | 无(text/plain) |
不登出 |
三态判定(导出为纯函数 readRefreshOutcome(status, body)):
export type RefreshOutcome = 'ok' | 'expired' | 'transient'
// ok = 2xx 且响应是引擎信封、code=0、data.accessToken 是字符串
// expired = HTTP 401 且响应是引擎信封且 code≠0 ← 唯一会清登录态的一态
// transient = 其余全部(5xx、代理 500、400、非 JSON 的 HTML、401 但非信封……)「是引擎信封」的判据(isEnvelope):body 是非 null 对象、typeof body.code === 'number'、typeof body.message === 'string'。
为什么 expired 还要 code≠0:401 却自称 code=0(成功)是矛盾体,无法确证是引擎在拒绝,按保守处理归 transient、不登出——「引擎明确拒绝」必须是「信封 + 非零业务码」,不是光看 HTTP 状态。
没这么做会怎样:只按 HTTP 状态分(例如「401 就登出」)在今天也能跑,但把判断绑在了「引擎恰好用 401 表达失效」这个巧合上——信封规则(doc/40)才是真源,业务码才是页面分叉的依据。
transient 这一态静默保留 token:只 return false,不改 authState、不弹提示、不打日志(重启期每几秒一次,打日志会刷屏);下一次调用自然会重试。这不等于绕过鉴权——服务端该 401 还是 401,下一次带旧 access token 的请求仍会被拒并再触发刷新。
4 测试与验收
4.1 机器测试(已入库,cd yk-tako-eino/web && npm test)
web/test/authrefresh.test.ts,逐条用例与期望:
| # | 输入(status, body) | 期望 readRefreshOutcome |
为什么 |
|---|---|---|---|
| 1 | 200, {code:0,message:'',data:{accessToken:'a',refreshToken:'b'}} |
ok |
正常续期 |
| 2 | 401, {code:111105,message:'登录已失效,请重新登录',data:null} |
expired |
真失效 |
| 3 | 500, null(Vite 代理 500,text/plain 解析失败) |
transient |
本次病灶 |
| 4 | 500, {code:111408,message:'服务暂时不可用,请再试一次',data:null} |
transient |
引擎内部错误 |
| 5 | 400, {code:111101,message:'请求格式不对',data:null} |
transient |
客户端 bug,不该踢人 |
| 6 | 401, null(网关 HTML 401) |
transient |
非信封不判失效 |
| 7 | 401, {code:0,message:'',data:null} |
transient |
矛盾体,保守 |
| 8 | 200, '<!doctype html>'(被代理到别的服务) |
transient |
非信封 |
用例 1 与 2 是「既有行为不许破」的守卫;3、4、5、6、7、8 是本次修复的新网。
4.2 活体验收(人工浏览器走查,由用户执行)
- 正向:重启引擎 → 浏览器
http://127.0.0.1:5173/保持登录(不出现登录页);引擎回来后事件流自动重连、任务/会话列表恢复。 - 反向(证明真失效仍然会登出):浏览器控制台把
sessionStorage['tako.configure.refresh']改成一个垃圾值 → 触发一次刷新(等 SSE 重连,或切一次工作区)→ 应回到登录页并显示「登录已过期,请重新登录」。
机器能验的是判定函数(§4.1);「重启不再踢人」这条端到端行为需要真浏览器,登记为人工项,不写成「已自动验证」。
5 顺带记录:一处与本方案无关的独立盲区
scripts/check-master-plan.sh 的 awk 只认 | N | 形式的表格行,而 doc/README.md §1 现行真源是 - **NN** [标题](...) 的列表 → 该检查目前对任何编号都匹配不到、恒返回 OK(空跑)。也就是说它今天并不真守卫「doc/16 有没有漏引 docs/README §1 的现行真源」。
本方案不修它(不在范围内),只留记录给后续接手:以后改动 doc/README.md §1 之后,不能只靠这条脚本判定 doc/16 有没有跟上,得人工核。