docs(perf): 更正 ② 连接池那条的证据 —— 我把测试服的观测当成了池上限

原注释写「生产实测 --concurrency=8 时进程恰好只有 9 条连接」,不准确。核对两台机器的
.env 之后:

  测试服 47.251.104.47  URL 显式 `connection_limit=30` → withCohortDerivedPool 提前返回,
                        池=30。**我观测到的那 9 条其实是 8 个 worker + 1 空闲,不是池上限。**
  生产   47.99.62.30    URL 没写 connection_limit → Prisma 默认 核数×2+1,4 核机 = 9

所以:
  · ② 这个缺陷本身成立(函数只认 PAC_COHORT_CONCURRENCY,CLI 旋钮不驱动池)
  · 但它是**潜在**的,只在没显式配 limit 的机器上咬人
  · 且按计划的 --concurrency=8 跑生产时 9 条刚好够 —— **本修复对今晚的回填零收益**,
    价值只在解锁更高并发

代码/测试注释同步改对,别让后人照着一个错的观测去推断。实现与单测未动(行为本来就是对的)。

apps/pac-service/src/cli/recompute-persona.cli.ts

@@ -50,9 +50,10 @@ function parseArgs(argv: string[]): Args {
 async function bootstrap() {
   const args = parseArgs(process.argv.slice(2));
   const logger = new Logger('recompute-persona');
-  // ⭐ 必须在 NestFactory 之前设:PrismaService 在容器初始化时就按这个值算 connection_limit。
-  //   不设的话池是 Prisma 默认的「核数×2+1」(4 核机 = 9),--concurrency 超过它就静默失效
-  //   —— 多出来的 worker 全卡在连接池排队,提并发一点不快(2026-07-26 生产实测)。
+  // ⭐ 必须在 NestFactory 之前设:PrismaService 在容器初始化时就按这个值算 connection_limit,晚了没用。
+  //   不设的话池是 Prisma 默认的「核数×2+1」—— 生产 4 核机 = 9,--concurrency 超过 8 就会被卡住,
+  //   多出来的 worker 全在排队等连接。详见 prisma.service.ts 里 withCohortDerivedPool 的注释
+  //   (含两台机器的实际 .env 差异;测试服 URL 里显式写了 connection_limit=30,那里不受影响)。
   //   只在用户显式给了 --concurrency 时设,不覆盖外部已有的环境变量。
   if (args.concurrency > 1 && !process.env.PAC_DB_CONCURRENCY) {
     process.env.PAC_DB_CONCURRENCY = String(args.concurrency);

apps/pac-service/src/prisma/prisma.service.ts

@@ -12,11 +12,17 @@ import { tenantGuardExtension } from './tenant-guard.extension';
  *   - URL 里已显式写了 connection_limit → 尊重,不覆盖(逃生口)。
  * CLI 是独立进程,只有它拿大池,常驻服务仍是小池,天然隔离。
  *
- * ⭐ 2026-07-26 修:原来只认 `PAC_COHORT_CONCURRENCY`(摄入的旋钮),于是
- * `recompute-persona --concurrency=N` 这类 CLI 的旋钮**根本没放大池** —— 生产实测
- * 跑 `--concurrency=8` 时进程恰好只有 9 条连接(= 4核×2+1 的 Prisma 默认值),
- * 也就是说 `--concurrency` 一旦超过 9 就是个静默失效的假旋钮,多出来的 worker 全卡在池上排队。
- * 现在改成读**通用**的 PAC_DB_CONCURRENCY,由各 CLI 在 Nest 启动前按自己的 --concurrency 设进来;
+ * ⭐ 2026-07-26 修:原来只认 `PAC_COHORT_CONCURRENCY`(**摄入**的旋钮),于是
+ * `recompute-persona --concurrency=N` 这类 CLI 的旋钮**不会放大池**。
+ *
+ * ⚠️ 这是**潜在**缺陷,咬不咬人取决于该机 .env 有没有显式写 connection_limit(核对过两台):
+ *   测试服 47.251.104.47  URL 里显式 `connection_limit=30` → 本函数提前返回,池=30,不是瓶颈
+ *                          (那里观测到的 9 条连接 = 8 个 worker + 1 空闲,不是池上限 —— 别再据此推断)
+ *   生产   47.99.62.30    URL **没写** → 走 Prisma 默认 `核数×2+1`,4 核机 = **9**
+ *                          → `--concurrency` 超过 8 就会被卡在 9,多出来的 worker 排队等连接
+ * 也就是说:按 --concurrency=8 跑生产,9 条刚好够,本修复不产生收益;它的价值是**解锁更高并发**。
+ *
+ * 改成读**通用**的 PAC_DB_CONCURRENCY,由各 CLI 在 Nest 启动前按自己的 --concurrency 设进来;
  * PAC_COHORT_CONCURRENCY 保留为向后兼容的别名,两者取大。
  */
 export function withCohortDerivedPool(rawUrl: string | undefined): string | undefined {

apps/pac-service/tests/persona-recompute-perf.spec.ts

@@ -9,8 +9,10 @@ import { withCohortDerivedPool } from '../src/prisma/prisma.service';
  *
  *   ① 批次栅栏 → worker pool:缺口正好是 E[8 次抽样最大值](≈p90)与均值之比;
  *      那个 75.7 秒的患者会把同批 7 个 worker 一起冻住。
- *   ② --concurrency 没放大连接池:实测跑 --concurrency=8 时进程恰好 9 条连接
- *      (= 4核×2+1 的 Prisma 默认值),超过 9 的并发全卡在池上排队,旋钮静默失效。
+ *   ② --concurrency 没放大连接池 —— **潜在**缺陷,咬不咬人看该机 .env:
+ *        测试服 URL 显式 `connection_limit=30` → 不受影响
+ *        生产   URL 没写 → Prisma 默认 核数×2+1,4 核机 = 9 → --concurrency>8 会被卡住
+ *      所以按 --concurrency=8 跑生产时本修复无收益,价值在于解锁更高并发。
  */
 
 describe('runPool —— 连续调度,不做批次栅栏', () => {