docs(召回): 全量重算耗时归因 —— 68% 在逐行 gap 子查询,两个方案已实测否定

2026-08-29 用 dump 开关 + pg_stat_activity 采样 + EXPLAIN ANALYZE 测出来的,
结论与直觉相反,写进代码免得后来人重走弯路:

① 11 个子场景只有 2 个慢(K05 牙周 9m13s / K01 阻生牙 13m+),其余 9 个秒回;
   且与结果集大小无关 —— K02 理由数最多(49,382)却秒回。
② 11 条 SQL 逐字节相同,只有绑定参数不同 → 是数据分布 + 执行计划,不是 SQL 写法。
③ 真实热点:Append(resolvedTeeth 的 UNION) loops=117,256 × 1.71ms ≈ 201 秒,
   占 K01 单条 301 秒的 68% —— 每候选行跑一次的 gap 相关子查询。

⛔ 已实测否定,别再试:
 · 子场景并发=3:24.1 分钟 vs 串行 23.3。瓶颈是共享磁盘 I/O,并行只抢同一批 page。
 · 信号码部分索引:EXPLAIN 估算成本降 13×(122 万行 → 5,593 行),
   墙钟 24.5 vs 23.3 —— 无效。教训:别拿估算成本当依据,要看 EXPLAIN ANALYZE 的实际时间。
   (该索引的迁移已撤回,不上生产。)

✅ 真正的方向(独立项目,未做):resolvedTeethSql 从逐行相关子查询改集合式。
   它是召回与画像共用的单一真理源,重写必须配等价性验证,否则是拿静默少召赌运气。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

apps/pac-service/src/modules/plan/engine/scenarios/treatment-initiation-recall.scenario.ts

@@ -466,6 +466,40 @@ export class TreatmentInitiationRecallScenario implements PlanScenarioPlugin {
         )
     `;
 
+    // ══════════════════════════════════════════════════════════════════
+    // 📊 2026-08-29 全量重算耗时归因(测试服 585K 患者 / 87,661 命中,空闲机)
+    //
+    // 用下面这个 dump 开关 + pg_stat_activity 采样测出来的,结论与直觉相反,记在这里
+    // 免得后来人重走弯路:
+    //
+    // ① **11 个子场景里只有 2 个慢**,其余 9 个全部秒回:
+    //      K05 牙周    9 分 13 秒
+    //      K01 阻生牙  13 分钟+
+    //    且**与结果集大小无关** —— K02 龋齿理由数最多(49,382)却秒回。
+    //
+    // ② **11 条子场景 SQL 逐字节相同**,只有绑定参数(诊断码 / resolver 类目)不同。
+    //    所以慢是数据分布 + 执行计划的事,不是 SQL 写法的事。
+    //
+    // ③ 真实热点(EXPLAIN ANALYZE,K01 单条 301 秒):
+    //      Append(resolvedTeeth 的 UNION) loops=117,256 × 1.71ms ≈ 201 秒
+    //      → **68% 的时间花在「每候选行跑一次」的 gap 相关子查询上**
+    //      5.8 万个 (患者×信号) 候选,每行跑两个子查询。
+    //
+    // ⛔ 已实测**否定**的两个方案,别再试:
+    //    · 子场景并发(PAC_RECALL_SUBSCENARIO_CONCURRENCY=3):24.1 分钟 vs 串行 23.3 —— 无效。
+    //      瓶颈是共享磁盘 I/O(全程 DataFileRead),并行只是抢同一批 page,总读取量不变。
+    //    · 给信号码建部分索引(((content->>'code')) WHERE type IN (...) AND status='active'):
+    //      EXPLAIN 估算成本 1,837,125 → 139,816(13×),信号扫描 122 万行 → 5,593 行,
+    //      **但墙钟 24.5 分钟 vs 23.3 —— 无效**。教训:别拿 EXPLAIN 的估算成本当依据,
+    //      成本模型改善不等于实际耗时改善;要 EXPLAIN (ANALYZE) 看真实的 actual time。
+    //
+    // ✅ 真正能解决的方向(尚未做,是个独立项目):
+    //    把 buildGapCore 的 resolvedTeethSql 从**逐行相关子查询**改成**集合式**
+    //    (一次算出全部患者的 resolved 牙位再做连接)。理论上能降一到两个数量级。
+    //    ⚠️ 但它是召回与画像共用的单一真理源,重写必须配等价性验证
+    //    (改写前后逐患者逐牙位比对),否则就是拿静默少召赌运气。
+    // ══════════════════════════════════════════════════════════════════
+
     // ⚡ 调试开关:PAC_RECALL_DUMP_SQL=1 时把本子场景的完整 SQL 打出来。
     //   为什么需要:pg_stat_activity.query 被 track_activity_query_size(默认 1024 字节)截断,
     //   而本查询远超这个长度 —— 线上抓到"某条子场景查询跑了 6.7 分钟"却拿不到全文做 EXPLAIN,