docs(test): 去掉 permission.go:112 这个**同一提交内就失效**的行号引用(pi 2026-09-25)

pi 那条"引用位置要用**唯一标识**,行号只作辅助"我收 —— 而它在**我自己的提交**里
就有一个现成的反例:

    34a15dc^  : permission.go **112** = Error(w, …, "Invalid session_id")   ← 引用写下时是对的
    34a15dc   : 同一提交给它**前面**插了 16 行注释 ⇒ 真调用移到 **128**
                (而新注释自己占了 113 行,所以 112 现在落在注释文本里)
    HEAD      : 112 = 注释文本;真调用 = 128、另一处提到它的注释 = 113

⇒ **引用与使它失效的改动在同一个提交里** —— 这不是"时间久了漂移",
  是"写下时就错了",而且**任何 review 都看不出来**(数字看着很具体、很像核过)。
  判据也抓不到:112/301/39 全都在文件行数界内(弱形式"越界检查"无效)。

改法(按 pi 的写法):唯一标识用**函数名 + 错误字符串字面量**
(`RequestPermission` + `Error(w, http.StatusBadRequest, "Invalid session_id")`),
行号删除;并把"为什么故意不写行号"记在注释里,免得下一个人"顺手补回去"。

★ 顺带核实(**只核实、未改动**)另一处同类引用:
  `docs/HARMONY-ALIGN-PLAN.md:225` 引 `permission.go:301`,声称是 `DecidePermission`。
  实测: e07e3bf(引用写下时)301 = 该函数的文档注释、函数体在 302;
        现在函数体在 **318** ⇒ 该行号也已漂移 17 行,落在 `RequestPermission` 里。
  未改它(属于另一个 writer 的文档,且是否要改成"唯一标识"由那条线决定)。

验证: `go test ./internal/handler/` 通过。
This commit is contained in:
2026-09-25 06:35:53 +08:00
parent b5989a94a1
commit 5753169077

View File

@ -23,11 +23,17 @@ import (
// created_at = 2026-09-12 06:06:13
//
// 该键的 session 位不是 UUID,于是 `RequestPermission` 走到
// `uuid.Parse` 失败那条 `Invalid session_id`(permission.go:112)时直接 return,
// **没有调用 ReleaseRelay**。键因此永久留在表里:之后任何用同一个
// `uuid.Parse` 失败那条 `Error(w, http.StatusBadRequest, "Invalid session_id")`
// 时直接 return,**没有调用 ReleaseRelay**。键因此永久留在表里:之后任何用同一个
// (agent_name, relay_key) 的重试都会拿到 `ErrRelayDuplicate`(→ 200
// duplicate_relay),而那次询问其实**从未发出去**。
//
// ⚠️ 这里**故意不写行号**(pi 2026-09-25 那条:引用位置要用唯一标识,行号只作辅助)。
// 原始版本写的是 `permission.go:112` —— 而 `7589f0a` 自己插入的注释把那条 return
// 推到了 **128 行**,于是**同一个提交里**引用就失效了(实测:112 行现在是本注释的
// 上游注释文本,`Invalid session_id` 在 128)。⇒ 唯一标识是那句**错误字符串**与
// 函数名(`RequestPermission`),它们在重构中比行号稳。
//
// 为什么必须是两个独立的测试:这两件事在**早退路径**上观测等价。
// 早退时正确实现与"把 ClaimRelay 换成空操作"的坏实现**都**在表里留下一个空键,
// 所以任何单条用例都无法同时钉住"该退的时候退"和"该占的时候占"。