chore: add launch readiness smoke and tuning evidence

docs/refactor/performance-benchmark-runbook.md

@@ -19,6 +19,22 @@ npm run perf:api:local
 - 默认不创建练习 session，不写业务数据。
 - 输出 JSON 和 Markdown 报告到 `docs/refactor/performance-reports/`。该目录已被 `.gitignore` 忽略，不应提交。
 
+PostgreSQL 调参与运行证据：
+
+```bash
+npm run perf:postgres:evidence
+```
+
+该脚本会把关键 `pg_settings`、连接等待、缓存命中、大表大小和可选 `pg_stat_statements` Top SQL 输出到 `docs/refactor/launch-artifacts/`。调参前后各跑一次，配合 API 压测报告判断是否真正改善。
+
+角色旅程烟测：
+
+```bash
+npm run smoke:launch-persona
+```
+
+该脚本从普通学生、租户管理员、平台管理员三个视角调用真实 API，覆盖 SVIP 后刷题、收藏、错题复习入口、租户 dashboard/主题/学生/销售转化、平台租户/套餐/审计入口和越权拒绝。它会写入少量 `launch_persona_smoke` 测试练习与收藏记录，只建议在本地、预生产或灰度租户运行。
+
 ## 前置条件
 
 本地真实迁移库压测：
@@ -120,6 +136,8 @@ npm run perf:api:local
 | spike-100 | 100 | 2min | 否 | 短峰值和缓存命中观察 |
 | spike-100-write | 100 | 2min | 是 | 短峰值刷题闭环，找 P95/P99 拐点 |
 
+本地 Docker Desktop 可以先用同一矩阵做跑分，但只能证明代码、索引和本机 Docker 环境的趋势。正式容量承诺必须以目标云服务器、生产 PostgreSQL 参数、生产 API/worker 连接池、对象存储/CDN 和真实网络重新跑。
+
 PowerShell 示例：
 
 ```powershell
@@ -203,6 +221,14 @@ npm run perf:summary -- --input docs/refactor/performance-reports/api-benchmark-
 
 工具会从 `summary.errors`、`summary.errorRate`、`summary.latencyOk.p95Ms`、`summary.latencyOk.p99Ms`、`config.concurrency`、`config.durationSeconds`、`config.includeWrites` 生成 `launchGateCheck.summary`，并按上线门禁阈值返回退出码。通过后，把 `launchGateCheck.summary` 转写到 `production-launch-evidence.json`；`artifact` 保留对应日志或报告路径。
 
+写入混合场景默认不会通过只读门禁。如果只是做容量观察，可以显式允许写入并使用写入场景阈值：
+
+```powershell
+npm run perf:summary -- --input docs/refactor/performance-reports/api-benchmark-20260630-xxxxxx.json --json --allow-writes --min-duration-seconds=60 --min-concurrency=50 --max-p95-ms=500 --max-p99-ms=1200
+```
+
+使用 `--allow-writes` 时，摘要工具输出 `capacityObservation`，不输出 `launchGateCheck`；不要把写入场景误填进生产上线门禁的 `performance.api-real-data-read`。
+
 更高的 50/100 并发、写入混合场景和容量结论仍应作为人工容量报告归档；门禁只负责挡住明显不达标的基础读路径。
 
 证据中只记录报告路径、并发矩阵、P95/P99、错误率和结论，不保存真实 token、支付密钥、用户隐私或完整响应。