Skip to content

feat: 预览页读者标注——页边批注 + 抽屉汇总 + Markdown 存档 - #107

Merged
Svtter merged 5 commits into
mainfrom
proto/annotation-ui
Nov 19, 2026
Merged

Svtter merged 5 commits into
mainfrom
proto/annotation-ui

Conversation

@Svtter

@Svtter Svtter commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Closes #106

实现

后端

  • session_annotations 表(SQLite,外键挂 sessions、级联删除;软删除保留数据),owner_id 按读者隔离,时间戳纳秒保证插入序 = 阅读序
  • API:GET/POST /api/sessions/{id}/annotations、DELETE /api/sessions/{id}/annotations/{aid};读 requireViewer、删除限本人(auth 关闭时归公共池)

注入件(internal/live/annotations.go)

  • ✎ 圆钮(amber,:144px,数量角标)融入右下角既有按钮堆;选字气泡「划线 / 批注」;批注编辑器(想法 + 标签)
  • 页边编号卡片随高亮首行定位(宽屏;≤1180px 隐藏);抽屉汇总支持定位 / 删除 / 导出
  • 高亮渲染 CSS Custom Highlight API,零 DOM 改动;加载时按「摘录 + 前后文」模糊重锚,锚不上标记「未在当前页面找到原文」
  • 存档导出:Markdown(标题 / 来源 / 摘录 / 想法 / 标签 / 时间),复制(clipboard + execCommand 降级)与 .md 下载
  • 样式 sth-ann-* 前缀 + !important,与 inject.go 抽屉/按钮约定一致

附带修复(decdd2d)

  • 单版本会话版本圆钮残留 "v?" 占位:抽屉样式表的 display:flex!important 会覆盖 JS 的普通 inline display 切换。所有脚本侧 display 切换改用 setProperty(..., 'important'),版本徽标初始态与单版本探测路径改为 display:none!important——同时修好了「抽屉打开时按钮不隐藏」。单版本隐藏 / 多版本显示 v2 / 面板打开隐藏三种场景已在临时实例实测。

验证

  • go build ./... + go test ./internal/... 五包全绿(新增存储层 / API / 注入三组测试)
  • 独立数据目录临时实例端到端:上传笔记 → 选中批注 → 落库确认 → 刷新后高亮重锚恢复 → 页边卡与抽屉联动 → 导出弹层 → UI 删除落库,全程浏览器截图自检通过

已知边界 / 后续

  • 编辑已有标注暂未做(先删再标)
  • 版本时间线的「每版本标注数」徽标未做(API 已有 Count 支撑,UI 后续加)

- session_annotations table (SQLite, FK cascade, owner-scoped)
- REST API: GET/POST/DELETE /api/sessions/{id}/annotations
- injected UI: floating button, selection bubble, margin cards,
  summary drawer, Markdown export
- highlights via CSS Custom Highlight API (zero DOM mutation),
  re-anchored on load using quote + surrounding text

@Svtter Svtter left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

自动代码评审 (review-server-neo)

⚠️ CONDITIONAL MERGE

📋 未清账单(跨轮跟踪)

本轮新增(10):

  • Blocking internal/server/annotations.go:62 — / :91 与 internal/server/auth.go:69-79:启用 --auth 后,所有 mutating 方法(POST/DELETE)走 s.requireBearer,**只认 Bearer key、刻…
  • Blocking …/annotations:0 — 同一问题的可见后果:protectPreviews 关闭(即「发链接给人看」的常规流程)时,匿名读者加载预览页 → GET …/annotations 401 → 每次打开页面都弹「标注加载失败」并显示重试按钮。修复上面那条后建议一…
  • Should-fix internal/live/annotations.go:158 — norm 是把 idx.text 的空白压缩后的字符串,但匹配出的 start/end 又交给 offsetToPoint(:145)去查 未压缩 的 idx.offsets。只要页面里有换行/多空格(未压缩…
  • Should-fix internal/live/annotations.go:227 — lastBottom = top + card.offsetHeight + 12 在 box.appendChild(card)(:228)之前执行,detach 元素的 offsetHeight 恒为 0,防重叠逻辑失效…
  • Should-fix internal/session/annotations.go:9 — 注释明说「each session row owns its own set, so switching versions switches annotation sets with it」,而版本链里每个版本是独立 session(见 `…
  • Should-fix internal/server/annotations_test.go:0 — 测试缺口:internal/server/annotations_test.go 全部用 auth 关闭的 New(..., "", 0, "") 起服务,所以上面那条 401 无法被发现。建议照 shares_test.go …
  • Nit internal/session/annotations.go:180 — CountAnnotations 注释写「Used by the version timeline to badge each version」,但全仓库 grep CountAnnotations 只有定义本身,没有任何调用点;要…
  • Nit internal/server/annotations.go:107 — 删除处理器内联的路径切分与 isAnnotationTargetPath(:144)重复,建议复用同一个解析函数(并让它和 parseShareTargetPath 一样返回 (sessionID, aid, ok))。
  • Nit internal/live/annotations.go:199 — 附近 eachRange 的 a._ranges 分支永远走不到(全流程只写 _range),可删。
  • Nit internal/server/annotations.go:76 — 请求体未限长:internal/server/annotations.go:76 直接 json.NewDecoder(r.Body),服务端是在完整解码后才 clamp 的;参照 server.go:2555 的 `http.…

修复后推送即逐项核销;未修项会带着连续未修轮数一直列在这里。
提交前自检:下次修改和提交前,请务必确定已经将内容改正;否则请不要提交新的 commit。

评审详情

Blocking

  • internal/server/annotations.go:62 / :91 与 internal/server/auth.go:69-79:启用 --auth 后,所有 mutating 方法(POST/DELETE)走 s.requireBearer,只认 Bearer key、刻意不认登录 cookie;唯一例外是 isShareManagementPath(auth.go:126)——分享面板那种浏览器写操作。注入的标注 JS(internal/live/annotations.go:381 创建、~405 删除)用 fetch(..., {credentials:'same-origin'}) 且不带 Authorization,所以在 auth 开启的部署里这两条写路径必然 401,前端只弹出「标注保存失败:服务暂不可用」。而「按读者隔离(每人只看/删自己的)」这条需求恰恰只在 auth 开启时有意义。改法:仿 isShareManagementPath 增加 isAnnotationMutationPath(POST …/annotations、DELETE …/annotations/{aid})并走 requireBearerOrCookie,复用其 sameOrigin(r) 的 Origin 校验,保持 CSRF 安全。
  • 同一问题的可见后果:protectPreviews 关闭(即「发链接给人看」的常规流程)时,匿名读者加载预览页 → GET …/annotations 401 → 每次打开页面都弹「标注加载失败」并显示重试按钮。修复上面那条后建议一并决定匿名读者在 auth 模式下是否该看到该入口。

Should-fix

  • internal/live/annotations.go:158:norm 是把 idx.text 的空白压缩后的字符串,但匹配出的 start/end 又交给 offsetToPoint(:145)去查 未压缩 的 idx.offsets。只要页面里有换行/多空格(未压缩的 HTML 到处都有),偏移就会整体左移,重锚会高亮到错误位置甚至整段错位。改法:要么在 buildIndex 里就产出压缩后的文本与逐节点压缩后的 offset 表,要么用原文文本做匹配(只在比较时做空白归一)。
  • internal/live/annotations.go:227:lastBottom = top + card.offsetHeight + 12 在 box.appendChild(card)(:228)之前执行,detach 元素的 offsetHeight 恒为 0,防重叠逻辑失效,相邻页边卡片会互相盖住。先 append 再量高度、再写 top/lastBottom。
  • internal/session/annotations.go:9-13:注释明说「each session row owns its own set, so switching versions switches annotation sets with it」,而版本链里每个版本是独立 session(见 internal/live/inject.go:274 每版本各自的 sessionId 与 /s/{id}/ 链接),因此新上传一版 → 新 session → 标注清零,与需求「跨版本存活」不符。若要满足需求,列表/计数需按链(root 或整条 chain 的 session 集合)聚合;若产品上决定不跨版本,请把需求改掉,别只留在代码注释里。
  • 测试缺口:internal/server/annotations_test.go 全部用 auth 关闭的 New(..., "", 0, "") 起服务,所以上面那条 401 无法被发现。建议照 shares_test.go 里 doReqWithCookie 的写法补一个 auth 开启 + cookie 的 POST/DELETE 用例。

Nits

  • internal/session/annotations.go:180-188:CountAnnotations 注释写「Used by the version timeline to badge each version」,但全仓库 grep CountAnnotations 只有定义本身,没有任何调用点;要么接上调用,要么删掉避免死代码。
  • internal/server/annotations.go:107-118:删除处理器内联的路径切分与 isAnnotationTargetPath(:144)重复,建议复用同一个解析函数(并让它和 parseShareTargetPath 一样返回 (sessionID, aid, ok))。
  • internal/live/annotations.go:199 附近 eachRange 的 a._ranges 分支永远走不到(全流程只写 _range),可删。
  • 请求体未限长:internal/server/annotations.go:76 直接 json.NewDecoder(r.Body),服务端是在完整解码后才 clamp 的;参照 server.go:2555 的 http.MaxBytesReader 加个上限更稳。

已核对无问题的点

  • 路由无冲突:GET/POST 用 hasPrefixSuffix,DELETE 用 isAnnotationTargetPath,且 extractSessionIDFromMetaPath 会拒绝含 / 的中间段(server.go:1978),annotations/{aid} 不会误入列表接口。
  • 所有权隔离到位:存储层 DeleteAnnotation 用 annotation_id + session_id + owner_id 三条件删除(internal/session/annotations.go:157),越权删除返回 ErrAnnotationNotFound;requireViewer(shares.go:393)允许 owner 与 sharee,auth 关闭时放行,符合「公共池」约定。
  • 表结构正确:session_annotations.session_id REFERENCES sessions(session_id) ON DELETE CASCADE 与 sessions 主键列名一致,PRAGMA foreign_keys = ON 在 store.go:228 已开启,initAnnotations 挂在 init 链上是安全的。
  • XSS 面干净:所有回显(quote/comment/tag/时间/标题)都过 esc(),innerHTML 拼接部分是常量与已转义值;clampString 的字节早退 + 按 rune 截断不会切坏多字节字符。

由 review-server-neo 自动生成。新 push 会重新评审。

Details


func (s *Server) handleCreateAnnotation(w http.ResponseWriter, r *http.Request) {
defer r.Body.Close()
sessionID, ok := extractSessionIDFromMetaPath(r.URL.Path, "/api/sessions/", "/annotations")

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[blocking] internal/server/annotations.go:62 / :91 与 internal/server/auth.go:69-79:启用 --auth 后,所有 mutating 方法(POST/DELETE)走 s.requireBearer,只认 Bearer key、刻意不认登录 cookie;唯一例外是 isShareManagementPath(auth.go:126)——分享面板那种浏览器写操作。注入的标注 JS(internal/live/annotations.go:381 创建、~405 删除)用 `fetch(...,…

Comment thread internal/live/annotations.go Outdated
function locateQuote(a){
var idx = buildIndex();
var q = a.quote.replace(/\s+/g,' ').trim();
var norm = idx.text.replace(/[ \t\r\n\f]+/g,' ');

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[should-fix] internal/live/annotations.go:158:norm 是把 idx.text 的空白压缩后的字符串,但匹配出的 start/end 又交给 offsetToPoint(:145)去查 未压缩 的 idx.offsets。只要页面里有换行/多空格(未压缩的 HTML 到处都有),偏移就会整体左移,重锚会高亮到错误位置甚至整段错位。改法:要么在 buildIndex 里就产出压缩后的文本与逐节点压缩后的 offset 表,要么用原文文本做匹配(只在比较时做空白归一)。

Comment thread internal/live/annotations.go Outdated
'<span class="sth-ann-macts"><button data-act="go">定位</button><button data-act="del">删除</button></span>' +
'<div class="sth-ann-mtext">' + (a.comment ? esc(a.comment) : '<i style="color:#9ca3af">(仅划线)</i>') + '</div>';
card.style.top = top + 'px';
lastBottom = top + card.offsetHeight + 12;

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[should-fix] internal/live/annotations.go:227:lastBottom = top + card.offsetHeight + 12 在 box.appendChild(card)(:228)之前执行,detach 元素的 offsetHeight 恒为 0,防重叠逻辑失效,相邻页边卡片会互相盖住。先 append 再量高度、再写 top/lastBottom。

"strings"
"time"
)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[should-fix] internal/session/annotations.go:9-13:注释明说「each session row owns its own set, so switching versions switches annotation sets with it」,而版本链里每个版本是独立 session(见 internal/live/inject.go:274 每版本各自的 sessionId 与 /s/{id}/ 链接),因此新上传一版 → 新 session → 标注清零,与需求「跨版本存活」不符。若要满足需求,列表/计数需按链(root 或整条 chain 的 ses…

…tant CSS

The drawer stylesheet sets display:flex!important on the floating buttons,
which overrode the plain inline style toggles used by the scripts: the
version badge showed a stray 'v?' on single-version chains and buttons
never hid while their panel was open. All script-side display toggles now
use setProperty(..., 'important'), the version badge starts hidden with
display:none!important, and the single-version probe path explicitly
hides it.

@Svtter Svtter left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

自动代码评审 (review-server-neo)

🚫 blocking issues, do not ship — --auth 下标注写路径 401 未修复,且重锚偏移、页边卡片重叠两项仍需处理;新 push 只修了 display 切换。

评审详情

本次 push(decdd2d)只做了一件事:修 display 切换

  • internal/live/inject.go:84,92,215,219,222,229 与 internal/live/annotations.go:openDrawer/closeDrawer:把 style.display='...' 换成 style.setProperty('display','...','important'),并给 versionDrawerHTML 的初始内联样式补上 display:none!important。这个修复是必要且正确的:#sth-drawer-btn(inject.go:40)、#sth-version-btn(inject.go:148)、#sth-ann-fab(annotations.go CSS 首行)都在样式表里写了 display:flex!important,普通内联赋值赢不过它,所以旧代码里「打开抽屉时按钮不消失」是真实存在的 bug;内联 !important 的优先级高于作者样式表的 !important,修复后三条线的显示状态一致。
  • 顺带提醒(Nits):.sth-ann-badge 仍用普通 b.style.display = ...(annotations.go 的 renderBadge),目前无碍(该选择器没声明 display),但同一文件里 now 混用两种写法,后续若给 badge 加 display!important 会复现同类 bug。

上一轮结论逐条状态

  • Blocking(未修,仍然存在):internal/server/annotations.go:62(POST)/:91(DELETE)在 --auth 下会被 auth.go:69-79 的「mutating 只认 Bearer」拦成 401,唯一例外仍是 isShareManagementPath(auth.go:126)。注入的标注 JS(internal/live/annotations.go:381、删除处)用 credentials:'same-origin' 且不带 Authorization,所以「按读者隔离」这条需求唯一有意义的部署形态下写操作全挂,前端只弹「标注保存失败」。仍需仿 isShareManagementPath 加 isAnnotationMutationPath 走 requireBearerOrCookie(含 sameOrigin 校验)。
  • Should-fix(未修):locateQuote 用压缩空白后的 norm 下标去查未压缩的 idx.offsets(internal/live/annotations.go:158 + :145),带换行/多空格的页面会整体偏移、高亮错位。
  • Should-fix(未修):renderMargin 在 appendChild 之前取 card.offsetHeight(internal/live/annotations.go:227),恒为 0,防重叠失效,页边卡片会互相盖住。
  • Should-fix(未修):标注按 session_id 存储,而版本链里每个版本是独立 session(internal/live/inject.go:274),新上传一版标注即清零,与需求「跨版本存活」不符;代码注释(internal/session/annotations.go:9-13)已自认这点。
  • 测试缺口(未修):internal/server/annotations_test.go 全部起 auth 关闭的服务,正好盖不住上面的 401;建议按 shares_test.go 的 doReqWithCookie 补一个 auth 开启的 POST/DELETE 用例。
  • Nits(未修):CountAnnotations(internal/session/annotations.go:182)全仓库无调用点;handleDeleteAnnotation 内联路径切分与 isAnnotationTargetPath(:144)重复;eachRange 的 _ranges 死分支;POST 未加 http.MaxBytesReader。

blocking issues, do not ship — --auth 下标注写路径 401 未修复,且重锚偏移、页边卡片重叠两项仍需处理;新 push 只修了 display 切换。


由 review-server-neo 自动生成。新 push 会重新评审。

Details

- auth: annotation mutations authenticate via Bearer or login cookie
  (sameOrigin-checked), like share management — browser UI no longer 401s
  under --auth; reads follow the normal cookie/bearer path and the
  injected UI degrades to a 'log in to annotate' hint on 401
- anchoring: text index maps every normalized character back to its
  original node+offset, fixing offset drift on pages with newlines or
  repeated spaces
- margin cards: append to the DOM before measuring offsetHeight so the
  overlap guard actually works
- scoping: annotations attach to the version chain (chain_id), so all
  versions of a document share one annotation set; chainless sessions
  fall back to per-session rows
- nits: drop unused CountAnnotations, share one path parser between
  route guard and delete handler, remove dead _ranges branch, cap
  annotation POST bodies at 64 KiB, consistent setProperty usage for
  badge visibility

@Svtter Svtter left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

自动代码评审 (review-server-neo)

⚠️ minor nits, OK to ship after — buildIndex 每次 locateQuote 重建的开销、以及 cookie 路径缺测试建议补上;其余为 nit。

评审详情

本轮(a08a4ac)修好了什么

  • Blocking 已修:internal/server/auth.go:69 的 mutating 分支新增 isAnnotationMutationPath(auth.go:129),标注 POST/DELETE 现在走 requireBearerOrCookie,即登录 cookie + sameOrigin(r) 校验,与分享面板同一条 CSRF-safe 路径;浏览器写操作在 --auth 下可用,owner_id 隔离随之生效。前端也补了 401 文案(internal/live/annotations.go loadAnnotations/persist),匿名读者看到的是「需要登录」而不是红色报错。新增 internal/server/annotations_auth_test.go 覆盖匿名 401 / owner Bearer 201。
  • 锚点偏移已修:buildIndex 现在产出 norm + 逐字符 map(node+offset),locateQuote 全程只用 idx.norm,pointAt 直接取原节点偏移 —— 旧的「压缩下标查未压缩表」错位问题消失。
  • 页边卡片重叠已修:renderMargin 改成 appendChild 之后再量 offsetHeight 再写 top,防重叠逻辑真正生效。
  • 跨版本存活已实现:新增 chain_id 列 + chainIDOfSession,ListAnnotations 按 chain 聚合、无链时回退 chain_id='' 按 session,TestAnnotationsCrossVersionVisibility 覆盖。需求「跨版本存活」这条对上。
  • 小项也顺手清了:MaxBytesReader(64<<10)、parseAnnotationTargetPath 去重(internal/server/annotations.go:135)、eachRange 去掉死分支、badge 改 setProperty(...,'important')、无调用者的 CountAnnotations 删除。

仍建议处理

  • Should-fix(性能) internal/live/annotations.go:buildIndex() 在 locateQuote 内部,而 loadAnnotations 是 anns.forEach(a => locateQuote(a)) —— N 条标注就整页重建 N 次字符级 map(每个字符一个对象)。大文档 + 十几条标注会在首屏卡顿。建议 loadAnnotations 里 var idx = buildIndex() 只建一次传进去。
  • Should-fix(测试缺口) internal/server/annotations_auth_test.go:只测了 Bearer 与匿名 401,没测本轮修复的正主——登录 cookie 路径。请补:cookie POST 得 201(owner)、非 sharee 的 cookie POST 得 403、带跨站 Origin 的 cookie POST 得 403(复用 shares_test.go 的 doReqWithCookie)。
  • Nits
    • internal/server/annotations.go:117:DELETE 现在只按 (annotation_id, owner_id) 删除,路径里的 session 仅用于 viewer 校验;虽然只能删自己的数据、ID 不可猜,但语义上失去了作用域,建议 WHERE 加上 chain(或 session_id IN (链内 session))以免「用 A 会话的链接删掉别处标注」这种反直觉行为。
    • internal/live/annotations.go 的 renderList:判定文案仍写 !a._range && !a._ranges,_ranges 已不存在,属残留。
    • pointAt 的末端钳制:当引文正好结束在全文最后一位时 end 会被钳到最后一个字符,高亮少最后一个字(且不会报「未找到」,属静默偏差)。
    • chainIDOfSession 在软删除/缺失时返回 ErrSessionNotFound,AddAnnotation 会把它变成 400 "session not found"、ListAnnotations 变 500(正常流程已被 requireSession 拦在前面,属兜底不一致)。
    • 标注锚点不含页面路径,而 chain 是按文档聚合的:多页站点的同一会话下,A 页的标注会在 B 页显示为「未找到原文」。若要支持多页,锚点里加 pagePath 更妥。

结论

上一轮的 Blocking 已随本轮修复关闭,剩下的是性能与测试覆盖两项 Should-fix 加若干 nit,无安全或数据正确性阻碍。

minor nits, OK to ship after — buildIndex 每次 locateQuote 重建的开销、以及 cookie 路径缺测试建议补上;其余为 nit。


由 review-server-neo 自动生成。新 push 会重新评审。

Details

- locateQuote now takes the shared text index instead of rebuilding it
  per annotation (rs review round 2 nit)
- doAnnotationJSON distinguishes a login cookie pair from a Bearer key,
  and the cookie test registers the session owner through the web flow
  so ownership matches the cookie identity (was 401/403 by test bug,
  not a server defect)

@Svtter Svtter left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

自动代码评审 (review-server-neo)

⚠️ minor nits, OK to ship after — 建议顺手把删除用例里的内联闭包拆开,其余 nit 可留待后续。

评审详情

本轮(194ddc0)改动

  • 性能 Should-fix 已修:buildIndex 提到 loadAnnotations 里构建一次,locateQuote(a, idx) 复用同一索引(internal/live/annotations.go:530-531),全文只有这一个调用点(已全文件核对 locateQuote/buildIndex 的出现位置),不再 N 条标注重建 N 次字符级 map。
  • cookie 路径测试已补:doAnnotationJSON 现在按前缀区分 Bearer 与 sth_session= cookie(internal/server/annotations_auth_test.go:29-35);TestAnnotationsAuthOn 用 registerAndLogin 拿到真实登录 cookie,断言 cookie POST → 201、cookie DELETE → 200。相关符号均存在且语义对得上(sessionCookieName internal/server/loginauth.go:12、registerAndLogin 返回 sth_session=<value> loginauth_test.go:53、SetAllowRegistration server.go:803、FindUserByUsername session/auth.go:131);cookie 请求不带 Origin,sameOrigin 放行,链路正确。

仍在的小问题(都不阻塞)

  • Nits annotations_auth_test.go:112-125:删除请求的 URL 里塞了一个当场解码 rec.Body 的闭包,同时又在同一语句给 rec 赋值。Go 的求值顺序保证闭包读到的是上一条 POST 的 recorder,所以能跑通,但太隐晦、易被后人改坏——建议先把 ID 解到局部变量再拼 DELETE 路径。
  • Nits annotations_auth_test.go:只测了 cookie 正向路径,负向(非 sharee 的 cookie → 403、跨站 Origin 的 cookie → 403)仍未覆盖;机制与分享面板共用,风险不高,但补两条更稳。
  • Nits internal/server/annotations.go:117(沿用上轮):DELETE 仅按 (annotation_id, owner_id),路径里的 session 只做 viewer 校验,建议 WHERE 上补 chain 作用域。
  • Nits internal/live/annotations.go:renderList 的 !a._range && !a._ranges 残留 _ranges;pointAt 末端钳制会在「引文结束于全文最后一位」时少高亮最后一字(静默、不报未找到)。
  • Nits internal/session/annotations.go 的 chainIDOfSession:session 缺失/软删除时返回 ErrSessionNotFound,在 AddAnnotation 会变成 400、在 ListAnnotations 会变成 500,与上游 404 语义不一致(正常流程已被 requireSession 挡在前面)。

累计状态

上一轮的 Blocking(auth 下写路径 401)与两项 Should-fix(锚点偏移、页边卡片重叠)均已在 a08a4ac 关闭,本轮又把索引复用的性能项和 cookie 测试补齐;功能上「选中即标注 / 页边卡片 / 抽屉汇总 / Markdown 存档 / 按读者隔离 + 跨版本」均已落地并有测试覆盖。剩下的只是测试可读性与若干边界 nit。

minor nits, OK to ship after — 建议顺手把删除用例里的内联闭包拆开,其余 nit 可留待后续。


由 review-server-neo 自动生成。新 push 会重新评审。

Details

- DeleteAnnotation is scoped to the path session's chain (or the session
  itself for legacy no-chain rows), not just owner+id
- ErrSessionNotFound maps to 404 in create/list/delete handlers when it
  races past requireSession, instead of 400/500
- endPointAt extends the highlight to one past the last character when a
  quote ends at the end of the document (was silently dropping it)
- renderList drops the never-set _ranges residue
- annotation auth test: decode the created id into a local variable, add
  negative paths (non-owner cookie 403, cross-origin cookie 403)

@Svtter Svtter left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

自动代码评审 (review-server-neo)

✅ ship as-is — 累计无遗留阻塞项,可选补充:跨链删除用例与 endPointAt 的空索引守卫。

评审详情

本轮(85122f0)改动核对

  • endPointAt(internal/live/annotations.go:158-166)正确:normOff >= map.length 时取最后一个映射字符的 node/off+1,off 是该字符在节点内的下标,off+1 必然 ≤ nodeValue.length,setEnd 合法;真正落在全文末尾的引文不再少高亮一个字。空索引时 map[-1] 会抛异常但被 locateQuote 的 try/catch 兜住,且空索引下 candidates 本就为空,走不到这一步。
  • renderList 残留 _ranges 已清(:266),判定回到只看 _range。
  • 删除作用域已收紧:Store.DeleteAnnotation 改为 (sessionID, ownerID, annotationID)(internal/session/annotations.go:205),先 chainIDOfSession 再按 chain_id(无链时 session_id + chain_id='')匹配——上轮「用 A 会话链接删别处标注」的反直觉行为关闭。签名变更的全部调用点已同步:全仓库 grep DeleteAnnotation( 只有 internal/server/annotations.go:141 与两条 session 测试,均已改成三参形式,无遗漏调用者。
  • 错误映射已顺:ErrSessionNotFound 在 list/create/delete 三处都映射成 404(internal/server/annotations.go:50,104,144),不再出现「400 或 500 说 session 不存在」的兜底不一致。
  • 新增测试有效:doAnnotationJSON 支持附加头后,TestAnnotationsAuthOn 补了三条真正有意义的断言——非属主 cookie POST → 403(requireViewer 拦住)、属主 cookie + 跨站 Origin: https://evil.example → 403(sameOrigin 拦截,httptest 的 Host 与之不符)、cookie 正向 201/200。删除用例的内联闭包也拆成了局部变量,可读性问题消失。

累积状态

四轮下来:auth 下写路径 401(Blocking)、锚点压缩偏移、页边卡片重叠、跨版本存活、索引复用性能、cookie 路径与负向测试,均已关闭;功能面(选中即标注 / 页边编号卡片 / 抽屉汇总与角标 / Markdown 存档 / 按读者隔离 + 公共池 / 跨版本 chain 作用域)与需求逐条对得上,且各有测试。

仅剩两点可选建议,不影响合并:endPointAt 可加一句 if (!idx.map.length) return null; 让空索引语义显式;本轮新增的「跨链删除」作用域行为还没有专门用例(chain A 的标注用 chain B 的会话删 → 应 404),补一条能把这条新约束钉住。

ship as-is — 累计无遗留阻塞项,可选补充:跨链删除用例与 endPointAt 的空索引守卫。


由 review-server-neo 自动生成。新 push 会重新评审。

Details

@Svtter
Svtter merged commit 7f8c00f into main Nov 19, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

预览页支持读者标注与笔记存档(页边批注 + 抽屉汇总)

1 participant