docs(gap): 测试机切 setbased + 记录手搓 compose 踩的两个坑(容器名/DB口令)

docs/design/gap-set-based-rewrite-plan.md

@@ -427,3 +427,25 @@ reason 行级 diff(323,796 条):A↔B 10 行 / B↔C 3 行 / C↔D 2 行 / A↔D
 方案 §0.1 预估「全轮改善 35~40%,不足以单独装进 2 小时」——**实测 22~31%,预估方向对、幅度偏乐观**。
 生产场景段 3h11m 按此推算 → 约 2h11m,整轮 3h41m → 约 2h50m,**仍然超 2 小时**。
 要进窗口还得叠加 §9(全口码那条独立线)或别的手段。
+
+## 12. 测试机切到集合式(2026-08-30 03:2x)
+
+`apps/pac-service/.env` 加 `PAC_GAP_VARIANT=setbased`,重启 pac-service。
+**生产未动,仍是 legacy**(该变量在生产 .env 里不存在 → `gapVariant()` 返回 legacy)。
+
+回退:把该行改回 `legacy`(或删掉),`bash deploy/deploy-prod.sh --no-pull`。**不需要改代码、不需要发版。**
+
+### ⛔ 切换时踩的坑:别手搓 docker compose
+
+我为了省一次构建,手动跑了
+`docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d --no-deps --force-recreate pac-service`,
+结果:
+
+1. **compose 文件组合错了** —— deploy-prod.sh 用的是 `-f docker-compose.prod.yml`(+ managed override),
+   我多带了一个 `docker-compose.yml`,容器名从 `pac-pac-service-1` 变成 `pac-service`,端口冲突起不来
+2. 删掉重来后又撞上**已知的 DB 口令坑**([[pac-prod-compose-db-cred-landmine]]):
+   手动 compose 不 source `.env`,`DATABASE_URL` 里的口令回落 → **P1000 认证失败 → crash-loop**
+3. 测试服务挂了约 5 分钟,靠 `bash deploy/deploy-prod.sh --no-pull` 恢复(三项验证全过,数据完好)
+
+deploy-prod.sh 的文件头注释本来就写着"不信 compose 的 diff 启发式"、整套逻辑就是为了避开这些。
+**改环境变量也要走部署脚本** —— 它多花的那几分钟构建时间,买的是不出这种事。