docs(bugs): BUG-1254 gate flake — PostgreSQL fixture slot wait times out

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017eEAG8HD3mm8gsKXgk8uU8

docs/BUG_HISTORY.md

@@ -16778,3 +16778,19 @@
 - 防复发：测试锁清单不含旧层名（心动接触 / 关系成对 / 社会法律落地 / 分三层说 / 压力窗 / 恢复窗）、每份清单以用途说明开头、白话对照与括号上限存在。
 - 相关记录：BUG-1148（名词只用中文；本次补上没有中文叫法时怎么说）、BUG-1244、BUG-1160～1163（通用读法与精简清单）。
 - 修复版本：待发布
+
+## BUG-1254 | staging 门禁偶发红：数据库测试排队等 PostgreSQL 槽位超时
+
+- 状态：investigating（已定位原因，未修）
+- 首次发现 / 最近更新：2026-10-06 / 2026-10-06
+- 来源：门禁 run 1746（`171a3f25`）「Frontend and database tests」红；同日 run 1742（`da226db1`）同一步红，随后同代码的 run 1743（`e62d0a32`）通过。
+- 影响面：Gitea `backend-quality-gate.yml` 的 `npm test --prefix frontend`；`frontend/tests/helpers/postgres-fixture.ts`。与被测提交的改动无关时也会红，阻断部署。
+- 现象：`not ok - corrective migration clears untrusted clocks and serializes concurrent fourth/fifth people`，原文 `timed out waiting for a PostgreSQL fixture slot (2 concurrent compose networks). Docker address pools cannot host one network per parallel test file.`，`ERR_TEST_FAILURE`。
+- 触发条件：全量并行 `npm test` 时，使用 `startPostgresFixture()` 的测试文件（2026-10-06 共 46 个）同时排队抢 2 个槽位，每个文件最多等 `FIXTURE_SLOT_WAIT_MS` = 5 分钟；排在后面的文件等满 5 分钟即失败，谁失败取决于调度，所以同一代码时红时绿。
+- 根因：BUG-281 为防 Docker 地址池耗尽把并发限到 2 个槽位，但等待上限是固定 5 分钟；数据库测试文件从当时约 20 个增长到 46 个，排队总时长已超过 5 分钟。属于 BUG-281 修复的容量假设失效，不是新代码引入。
+- 修复：未做。候选（待决定）：①等待上限改为「只要持槽进程还活着就继续等」或按排队文件数放大；②`run-tests.mjs` 把 `database-*` 等用 fixture 的文件拆到单独一轮串行跑（与 `test:db` 同口径），其余仍并行。不改 `.gitea/workflows/**`。
+- 验证：本机无可用 Docker，未复现；依据为门禁日志原文与 `postgres-fixture.ts` 的槽位 / 等待常量。
+- 防复发：待修复时补：fixture 数量增长不应让门禁变成随机红。
+- 相关记录：BUG-281（槽位上限的来源）、BUG-266（runner 资源回收）。
+- 复发自：BUG-281（同一机制的容量问题以另一种形式出现）。
+- 修复版本：—