docs: 记录"窗口当索引"陷阱与本次改动
build / build (push) Successful in 1m26s

trap-17:分页窗口当索引 —— "当前生效版本"不能按最近 N 条找。它比 trap-14 更
隐蔽:读成"没有"不报错,只是让错误的选择看起来合理(重写已上线的目标、给已有
权威版本的目标再建基线)。写清判据(250 条历史 + 窗口里看不到 + 精确查询仍命中)
与修法(身份/当前状态一律精确查,窗口只用于列表)。AGENTS.md 的陷阱索引同步加
一行;CHANGELOG 记录当前生效版本查询修复与固定同步屏障;test-scope 声明新增的
真实 PG 用例为"可选未运行"并写清理由(未声明 skip 判红)。
This commit is contained in:
姚章浩
2026-10-30 03:09:37 +08:00
parent ed307f3c20
commit 465cae80bd
4 changed files with 68 additions and 0 deletions
+32
View File
@@ -410,3 +410,35 @@ scheme)。`validObjectKey` 认这种形状并把它拆成裸 key,`ValidObjec
证据单独落盘在 `reuse/<digest>.json`,摘要在写集合行里 —— 不冒充历史台账。
**反例**:为了"让同步能过"把"不在预备份范围"直接放行,或者恢复时按"没被引用就删"清理。
## trap-17:分页窗口当索引 —— "当前生效版本"不能按最近 N 条找
**症状**(比 trap-14 更隐蔽:它不报错,只是判错):
- 接管时把一个"其实已经生效"的作业判成 `fresh`,于是把已经上线的目标**重写一遍**;
- 基线入口为一个已经有权威版本的目标放行"建基线"(会覆盖别人的版本);
- 页面上"生产当前版本"显示成"没有生效版本记录",同步闸口据此要求先建基线;
- 只有把窗口 N 从 50 调到 100/200 才"暂时好一点",再长一点又复发。
**根因**:`LibraryVersions(scope, N)` 是**分页展示**用的窗口(真实上限 1..100),
它按 `created_at DESC` 截断。可"当前生效版本"是每 scope 唯一一行、可能很久以前
登记的事实;"本快照是否生效过"更是身份查询。用窗口当索引,历史一长就把**存在**
读成**不存在**——而且读成"没有"不会报错,只会让错误的选择看起来合理。
**判据**:把生效版本登记在 48 小时前、再灌 250 条更新的版本记录,然后:
- `LibraryVersions(scope, 100)` 里**看不到**它(用例先断言这一点,否则夹具失效);
- `LibraryCurrentVersion`(`kind='production_effective' AND superseded_at IS NULL`)
仍精确命中,接管判定是 `pending_final` 而不是 `fresh`;
- 换个更新的快照生效后,旧快照 `LibraryVersionOfSnapshot` 仍取回并带
`superseded_at`,接管判定 `superseded`(拒绝用旧快照覆盖);
- 台账被写坏(同一身份两行、未顶替却不是当前生效、已顶替却是当前生效)⇒
**拒绝挑选** / 判 `unknown`,不许挑一条"看起来对"的继续写。
**修法**:身份/当前状态一律走精确查询(`LibraryCurrentVersion`、
`LibraryVersionOfSnapshot`、`LibraryVersionByRef`),窗口只用于列表展示;
同一含义的判定(worker 接管、基线、同步闸口的创建判据、归档保留的保护标记)
共用同一份实现,别各写一份"取最近几条再筛"。
**反例**:把窗口上限调大、或在内存里 `for` 一遍再 `break`——那是换了个数字,
不是换了判据。