feat: add docker capacity benchmark mode

docs/refactor/performance-benchmark-runbook.md

@@ -19,6 +19,16 @@ npm run perf:api:local
 - 默认不创建练习 session，不写业务数据。
 - 输出 JSON 和 Markdown 报告到 `docs/refactor/performance-reports/`。该目录已被 `.gitignore` 忽略，不应提交。
 
+默认本地兼容模式使用 `x-user-id` 作为压测身份，只适合开发机。更接近 Taro/Supabase 接入方式的压测应启用迁移期 Bearer session：
+
+```powershell
+$env:PERF_AUTH_MODE="app_session"
+npm run perf:api:local
+Remove-Item Env:\PERF_AUTH_MODE
+```
+
+`app_session` 模式会在测试库中为压测学生创建 2 小时 `tk_` 会话，然后用 `Authorization: Bearer <tk_...>` 请求业务接口；API 可以关闭 `ALLOW_LEGACY_AUTH_HEADERS`。生产远程压测如果已经有真实 Supabase access token，也可以用 `PERF_AUTH_MODE=bearer` 和 `PERF_BEARER_TOKEN`。
+
 PostgreSQL 调参与运行证据：
 
 ```bash
@@ -83,6 +93,8 @@ npm run perf:api:local
 | `PERF_INCLUDE_LEADERBOARD` | `false` | 是否加入排行榜接口；排行榜租户默认关闭，仅在租户明确开启并需要专项压测时打开 |
 | `PERF_OUTPUT_DIR` | `docs/refactor/performance-reports` | 报告输出目录 |
 | `PERF_REQUEST_TIMEOUT_MS` | `15000` | 单请求超时 |
+| `PERF_AUTH_MODE` | `legacy` | `legacy` 使用本地 `x-user-id`；`app_session` 创建 `tk_` Bearer session；`bearer` 使用 `PERF_BEARER_TOKEN`；`none` 只适合公开接口 |
+| `PERF_BEARER_TOKEN` | 空 | `PERF_AUTH_MODE=bearer` 时使用 |
 
 ## 默认工作负载
 
@@ -138,6 +150,37 @@ npm run perf:api:local
 
 本地 Docker Desktop 可以先用同一矩阵做跑分，但只能证明代码、索引和本机 Docker 环境的趋势。正式容量承诺必须以目标云服务器、生产 PostgreSQL 参数、生产 API/worker 连接池、对象存储/CDN 和真实网络重新跑。
 
+## 本地 Docker 4c16g 模拟入口
+
+仓库提供一个 Docker API 受限资源压测入口：
+
+```powershell
+$env:DATABASE_URL="postgresql://postgres:postgres@127.0.0.1:54322/postgres"
+$env:BENCHMARK_API_CPUS="2.0"
+$env:BENCHMARK_API_MEMORY="4g"
+$env:DB_POOL_MAX="10"
+npm run perf:api:docker-4c16g
+Remove-Item Env:\BENCHMARK_API_CPUS
+Remove-Item Env:\BENCHMARK_API_MEMORY
+Remove-Item Env:\DB_POOL_MAX
+```
+
+它会使用 `docker-compose.api.yml` + `docker-compose.api.benchmark.yml` 构建并启动 API 容器，默认限制 API 容器为 2 CPU/4G，关闭 `ALLOW_LEGACY_AUTH_HEADERS`，然后用 `PERF_AUTH_MODE=app_session` 跑：
+
+- 30 worker / 120s / 只读上线门禁。
+- 50 worker / 60s / 10% 刷题闭环写入。
+- 100 worker / 60s / 8% 刷题闭环写入。
+
+这个入口模拟的是“4 核 16G shared-host 中 API 容器的资源约束”，不是完整云服务器复刻。当前本地 Supabase/PostgreSQL 仍跑在 Docker Desktop 的 Supabase stack 中，除非额外手工限制 DB 容器资源，否则数据库容器仍可能使用 Docker Desktop 的全局资源。正式容量承诺必须在目标 4 核 16G 云服务器、生产 PostgreSQL shared-host 参数、真实对象存储/CDN 和真实网络下复跑。
+
+如需保留 API 容器便于排查：
+
+```powershell
+$env:PERF_KEEP_DOCKER_API="true"
+npm run perf:api:docker-4c16g
+Remove-Item Env:\PERF_KEEP_DOCKER_API
+```
+
 PowerShell 示例：
 
 ```powershell