docs: update production launch handoff

README.md

@@ -8,6 +8,17 @@
 
 更新时间：2026-07-01
 
+## 最新交付快照
+
+截至 2026-07-01，当前 `main` 已推送到 Gitea，可进入云服务器部署和生产测试阶段。这里的“生产测试”指在真实云服务器、真实域名、真实对象存储和真实 provider 配置下做灰度/演练验证；正式对 C 端或合作商放量前，仍必须通过本文的生产上线证据门禁。
+
+- 后端核心业务已经覆盖旧题库主链路：刷题、背单词、知识手册、分数线、错题本、收藏夹、资料下载、题目视频、会员/订单/优惠券/激活码、个人中心、站内通知、勋章、租户后台、平台 SaaS 管理、公共题库授权/采纳/同步、CRM/销售/代理/分佣、财务对账和 worker 任务。
+- 多租户安全底座已经具备商用联调条件：平台/租户/学生三类身份边界、Supabase Auth JWT、迁移期 `tk_` session、RLS 测试、租户角色模板、成员权限、班级/教师/学生范围、字段脱敏、审计日志、私有资源短签名、导入/导出 job 审计均已落地。
+- H5/Taro 第一版已经具备前后端联调入口：学生端、租户后台、平台后台三套 H5 构建入口、统一 API client、Supabase client 初始化、运行时公开配置、H5 静态烟测和 32 项真实浏览器交互 smoke 已接入。
+- `smoke:launch-persona` 已升级为默认 `LAUNCH_SMOKE_AUTH_MODE=app_session`，可用 `--write` / `--write-md` 生成稳定上线证据文件，覆盖普通学生、租户管理员、平台管理员三类真实 API 角色旅程和越权拒绝。
+- 本地真实迁移库最新规模约为 19 个租户、74,131 道题、3,722 个平台用户、3,712 个学生资料、81,160 个练习 session、327,925 条答题记录、38,207 条错题、1,501 个内容资源和 474 条权益。
+- 2026-07-01 08:41 本地真实数据压测通过：30 并发只读 37,520 请求、0 错误、310.34 req/s、P95 251.08ms；50 并发混合读写 25,047 请求、0 错误、410.49 req/s、P95 237.41ms；100 并发混合读写 24,116 请求、0 错误、393.56 req/s、P95 437.37ms；150 并发混合读写 22,864 请求、0 错误、371.29 req/s、P95 633.46ms。该结果只能作为本机真实数据观察，正式容量必须在目标 4 核 16G 云服务器复跑。
+
 目前已经完成并在本地验证通过的内容：
 
 - Supabase/PostgreSQL 多租户数据库 schema、RLS、索引、触发器。
@@ -53,7 +64,7 @@
 | 对象存储/资料安全 | √ 可联调，待生产 AV/CDN | OSS/COS/Supabase Storage 签名、上传确认、短签名预览下载、水印 traceId、复检和安全扫描地基已完成；生产配置会拒绝 local_dev、非 HTTPS 公开 URL、非官方阿里云 OSS endpoint、阿里云 OSS 内网直签和未接外部扫描服务 |
 | PocketBase 真实数据迁移 | √ 本地跑通，待人工复核 blocker | SQLite 导出、标准化导入、校验和抽样脚本已跑通；正式切换前处理缺用户订单和缺归属手册章节 |
 | Taro H5 三端前端 | √ 第一版可构建 | 学生端、租户后台、平台后台均有真实 API 页面；已补 H5 `index.html` 模板和发布产物守卫；后续继续补小程序兼容、视觉精修、状态管理、包体优化和端到端测试 |
-| 生产安全/压测交付 | △ 本地真实数据压测已跑，云端待复测 | 本地 Docker/Supabase 已完成真实迁移数据 30/50/100/150 并发只读和混合读写压测；最新 Docker API 受限资源复核为 30 并发只读 0 错误、305.59 req/s、P95 241.46ms，50 并发混合读写 0 错误、398.79 req/s、P95 231.28ms，100 并发混合读写 0 错误、370.86 req/s、P95 445.26ms，150 并发混合读写 0 错误、340.74 req/s、P95 689.67ms。进一步显式限制 DB 容器为 2 CPU/8G 后，30 只读和 50 混合读写均 0 错误但 P95 分别升至 1183.29ms/996.01ms，未通过上线延迟门禁。上云后必须执行生产 readiness、PostgreSQL shared-host 调优、远程 Auth/RLS、4C16G 复测、`security:repo`、真实 `@codex-security` 扫描和上线证据门禁。 |
+| 生产安全/压测交付 | △ 本地真实数据压测已跑，云端待复测 | 2026-07-01 08:41 本地真实迁移库 API 进程压测：30 并发只读 0 错误、310.34 req/s、P95 251.08ms；50 并发混合读写 0 错误、410.49 req/s、P95 237.41ms；100 并发混合读写 0 错误、393.56 req/s、P95 437.37ms；150 并发混合读写 0 错误、371.29 req/s、P95 633.46ms。Docker API 2C/4G 受限复核和 DB 2C/8G 未调参悲观复核已留档。上云后必须执行生产 readiness、PostgreSQL shared-host 调优、远程 Auth/RLS、4C16G 复测、`security:repo`、真实 `@codex-security` 扫描和上线证据门禁。 |
 
 更完整的进度看这些文档：
 
@@ -416,6 +427,23 @@ npm run test:worker:student-supervision
 npm run test:rls
 ```
 
+## 云服务器部署与生产测试顺序
+
+接下来在新云服务器上建议按下面顺序推进。不要跳过证据门禁；它是后续给合作商交付 SaaS 时的安全底线。
+
+1. 准备服务器基础环境：安装 Docker、Node.js 20+、Supabase CLI、Nginx/Caddy、进程管理或容器编排工具；拉取本仓库 `main`，以 Gitea 最新提交为准。
+2. 启动 Supabase/PostgreSQL，执行全部 migrations 和最小 seed；确认 `DATABASE_URL` 指向云端数据库。
+3. 按 `docs/refactor/postgresql-4c16g-tuning.md` 应用 4 核 16G `shared-host` 起步参数，启用 `pg_stat_statements`，重启 PostgreSQL 后跑 `PG_TUNING_PROFILE=shared-host npm run perf:postgres:evidence -- --strict --json`。
+4. 配置生产 `.env`：关闭 legacy 身份头和平台本地 key，配置 HTTPS CORS 白名单、强随机 session/JWT secret、对象存储 provider、短信/OAuth/支付 provider、worker provider 和 webhook 域名。生产环境禁止 `CORS=*`、mock/未知短信 provider、local_dev 存储、localhost webhook、非 HTTPS 回调。
+5. 导入旧 PocketBase 数据：先跑 production dry-run 和 sample，确认 7 个已支付缺用户订单、22 个缺所属手册章节等旧数据人工复核项有明确处理结论，再执行正式导入演练。
+6. 构建并部署 API/worker：API 对外只开放 HTTPS；worker 按本文的计费、用量、催缴、审计、资源复检、导入、导出、公共题库同步等任务设置 cron 或队列。
+7. 构建三套 H5：`build:taro:h5:student`、`build:taro:h5:tenant`、`build:taro:h5:platform`，分别部署到学生端、租户后台、平台后台域名。每个发布目录根部放置真实公开 `runtime-config.json`，只允许公开字段。
+8. 执行生产验收：`readiness:production`、`readiness:production:db`、`smoke:auth:remote`、`test:rls`、`smoke:launch-persona -- --write ...`、Taro H5 静态/交互 smoke、API/worker 构建检查、`security:repo`、真实 `@codex-security` 扫描。
+9. 执行云端真实数据压测：按 runbook 跑 6/30/50/100 阶梯，只读和混合读写各一组；把摘要写入 `production-launch-evidence.json`，不要把原始压测报告提交 Git。
+10. 通过 `npm run launch:gate -- --evidence docs/refactor/production-launch-evidence.json` 后，再进入灰度生产测试。灰度期间继续观察 CPU、内存、慢 SQL、连接数、错误率、P95/P99、对象存储签名、支付回调、短信/OAuth 登录、订单权益开通和 worker 失败告警。
+
+当前可上线生产测试的边界：后端主链路和 H5 第一版已具备联调条件；真实生产账号、真实支付/短信/OAuth 回调、对象存储 AV/CDN、水印策略、4C16G 云端容量和真实迁移数据人工复核仍是上线前必须验收项。学生头像只支持男女预设，不做上传；排行榜默认不开启，只有租户明确购买/开启活动并完成专项压测后再进入独立功能。
+
 ## 生产就绪检查
 
 填好生产 `.env` 后，先跑环境变量级检查：
@@ -738,6 +766,15 @@ API 身份上下文：
 最近本地验证命令：
 
 ```text
+node --check scripts/launch-persona-smoke.js
+npm run test:readiness
+npm run security:repo
+npm run check:taro
+LAUNCH_SMOKE_AUTH_MODE=app_session npm run smoke:launch-persona -- --write docs/refactor/launch-artifacts/launch-persona-smoke.json --write-md docs/refactor/launch-artifacts/launch-persona-smoke.md
+PERF_AUTH_MODE=app_session PERF_DURATION_SECONDS=120 PERF_CONCURRENCY=30 PERF_RAMP_SECONDS=15 PERF_INCLUDE_WRITES=false npm run perf:api:local
+PERF_AUTH_MODE=app_session PERF_DURATION_SECONDS=60 PERF_CONCURRENCY=50 PERF_RAMP_SECONDS=10 PERF_INCLUDE_WRITES=true PERF_PRACTICE_FLOW_RATIO=0.1 npm run perf:api:local
+PERF_AUTH_MODE=app_session PERF_DURATION_SECONDS=60 PERF_CONCURRENCY=100 PERF_RAMP_SECONDS=10 PERF_INCLUDE_WRITES=true PERF_PRACTICE_FLOW_RATIO=0.08 npm run perf:api:local
+PERF_AUTH_MODE=app_session PERF_DURATION_SECONDS=60 PERF_CONCURRENCY=150 PERF_RAMP_SECONDS=10 PERF_INCLUDE_WRITES=true PERF_PRACTICE_FLOW_RATIO=0.06 npm run perf:api:local
 npx supabase db reset
 npm run check:api
 npm run check:worker
@@ -759,7 +796,11 @@ npm run audit:runtime
 git diff --check
 ```
 
-结果：通过。最近一轮真实迁移专项验证已通过 `npx supabase db reset`、`npm run pb:import:json`、`npm run pb:import:validate`、`npm run pb:import:sample` 和 `npm run check:importer`；`pb:import:sample` 当前为 0 failures、6 warnings、1 skipped、39 passed；production dry-run 仍按预期返回非 0，因为旧数据本身还剩订单缺用户和手册章节缺归属两个 blocker。`npm run test:auth:remote-smoke` 覆盖远程 Auth/JWKS 验收脚本自身。`npm run test:rls` 覆盖 75 条运行时 RLS 断言，包含主租户、合作商租户、无租户 claim、平台管理员旁路和跨租户写入拒绝。`npm run test:api` 覆盖平台细粒度权限、公共题库跨租户同步运营状态、资源访问事件、锁定 CDN 资源拒绝、provider-managed CDN 显式放行、学生短 TTL 下载/预览、访问记录查询、安全扫描门禁、官方账单下载任务权限和脱敏响应、异常订单运营台、人工调整凭证提交/复核/事件/报表、销售/代理转化报表本人/全局权限、平台账单逾期 dry-run/催缴记录、平台审计告警查询/状态更新/越权拒绝/敏感 details 脱敏、平台审计告警通知渠道/事件查询和密钥不回显、平台催缴通知渠道/事件查询和密钥不回显、租户隔离，以及凭证审批不修改订单/支付/权益。`npm run test:worker:commerce` 覆盖支付/退款补偿、微信/支付宝官方账单下载、账单 hash 校验、导入 `provider_download` 对账批次和密钥不泄露。`npm run test:worker:platform-billing` 覆盖平台 SaaS 订阅自动计费、重复开票保护、账单明细和审计。`npm run test:worker:platform-usage` 覆盖平台 SaaS 月度用量自动采集、11 类指标、手工调整记录不覆盖和重复运行幂等。`npm run test:worker:platform-usage-overage` 覆盖平台 SaaS 超额账单明细、重复开票保护、非法账期失败审计、审计告警生成和敏感错误信息脱敏。`npm run test:worker:platform-dunning` 覆盖平台 SaaS 逾期账单标记、内部催缴记录、租户 `past_due` 状态和每日催缴幂等。`npm run test:worker:platform-dunning-notifications` 覆盖平台 SaaS 催缴外部通知入队、generic webhook 发送、幂等、防重复、联系方式掩码、签名密钥不泄露和请求 payload 脱敏。`npm run test:worker:platform-audit-alerts` 覆盖平台审计告警生成、规则匹配、幂等、防重复和告警 details 脱敏。`npm run test:worker:platform-audit-notifications` 覆盖平台审计告警外部通知入队、generic webhook 发送、幂等、防重复、签名密钥不泄露和请求 payload 脱敏。`npm run test:worker:assets` 覆盖托管资源复检、内置安全扫描、外部 HTTP scanner 通过/失败/不可用 fail-closed、扫描失败/跳过事件和异常资源自动下架。`npm run test:worker:public-banks` 覆盖公共题库自动同步、失败通知和恢复自动关闭。`npm run test:worker:exports` 覆盖导出 worker 生成可信资源并标记 `securityScanStatus=passed`。`npm run audit:runtime` 当前为 0 vulnerabilities；Excel 解析已从 `exceljs` 切换为 `read-excel-file`，避免生产运行时携带 `exceljs -> uuid` 的已知中危依赖。
+结果：通过。最近一轮上线前本地复核已通过 `npm run test:readiness`、`npm run security:repo`、`npm run check:taro`、`node --check scripts/launch-persona-smoke.js`、`node scripts/production-launch-gate-test.js` 和 `git diff --check`；`security:repo` 为 0 finding，`test:readiness` 已包含生产配置 fail-fast、Taro runtime/API/persona/route contract、H5 发布守卫、自动勋章并发、PostgreSQL 调参证据 helper、Docker 压测资源证据、远程 Auth smoke 脚本、launch persona 稳定证据 CLI 和上线门禁测试。`LAUNCH_SMOKE_AUTH_MODE=app_session npm run smoke:launch-persona -- --write ...` 已通过，生成带时间戳报告和稳定 `launch-persona-smoke.json/md`，覆盖普通学生 SVIP 后刷题、收藏、错题/收藏复习入口，租户管理员 dashboard/主题/学生/销售转化入口，平台管理员租户/套餐/审计入口，以及学生越权后台和跨租户访问拒绝。
+
+真实迁移库本地 API 压测已跑 30/50/100/150 阶梯，均 0 错误；50 并发混合读写为 410.49 req/s、P95 237.41ms，100 并发混合读写为 393.56 req/s、P95 437.37ms，150 并发进入压力观察区。该结果用于证明当前后端代码和索引在本机真实数据下可跑通高并发刷题读写链路，不作为云服务器 SLA。
+
+最近一轮真实迁移专项验证已通过 `npx supabase db reset`、`npm run pb:import:json`、`npm run pb:import:validate`、`npm run pb:import:sample` 和 `npm run check:importer`；`pb:import:sample` 当前为 0 failures、6 warnings、1 skipped、39 passed；production dry-run 仍按预期返回非 0，因为旧数据本身还剩订单缺用户和手册章节缺归属两个 blocker。`npm run test:auth:remote-smoke` 覆盖远程 Auth/JWKS 验收脚本自身。`npm run test:rls` 覆盖 75 条运行时 RLS 断言，包含主租户、合作商租户、无租户 claim、平台管理员旁路和跨租户写入拒绝。`npm run test:api` 覆盖平台细粒度权限、公共题库跨租户同步运营状态、资源访问事件、锁定 CDN 资源拒绝、provider-managed CDN 显式放行、学生短 TTL 下载/预览、访问记录查询、安全扫描门禁、官方账单下载任务权限和脱敏响应、异常订单运营台、人工调整凭证提交/复核/事件/报表、销售/代理转化报表本人/全局权限、平台账单逾期 dry-run/催缴记录、平台审计告警查询/状态更新/越权拒绝/敏感 details 脱敏、平台审计告警通知渠道/事件查询和密钥不回显、平台催缴通知渠道/事件查询和密钥不回显、租户隔离，以及凭证审批不修改订单/支付/权益。`npm run test:worker:commerce` 覆盖支付/退款补偿、微信/支付宝官方账单下载、账单 hash 校验、导入 `provider_download` 对账批次和密钥不泄露。`npm run test:worker:platform-billing` 覆盖平台 SaaS 订阅自动计费、重复开票保护、账单明细和审计。`npm run test:worker:platform-usage` 覆盖平台 SaaS 月度用量自动采集、11 类指标、手工调整记录不覆盖和重复运行幂等。`npm run test:worker:platform-usage-overage` 覆盖平台 SaaS 超额账单明细、重复开票保护、非法账期失败审计、审计告警生成和敏感错误信息脱敏。`npm run test:worker:platform-dunning` 覆盖平台 SaaS 逾期账单标记、内部催缴记录、租户 `past_due` 状态和每日催缴幂等。`npm run test:worker:platform-dunning-notifications` 覆盖平台 SaaS 催缴外部通知入队、generic webhook 发送、幂等、防重复、联系方式掩码、签名密钥不泄露和请求 payload 脱敏。`npm run test:worker:platform-audit-alerts` 覆盖平台审计告警生成、规则匹配、幂等、防重复和告警 details 脱敏。`npm run test:worker:platform-audit-notifications` 覆盖平台审计告警外部通知入队、generic webhook 发送、幂等、防重复、签名密钥不泄露和请求 payload 脱敏。`npm run test:worker:assets` 覆盖托管资源复检、内置安全扫描、外部 HTTP scanner 通过/失败/不可用 fail-closed、扫描失败/跳过事件和异常资源自动下架。`npm run test:worker:public-banks` 覆盖公共题库自动同步、失败通知和恢复自动关闭。`npm run test:worker:exports` 覆盖导出 worker 生成可信资源并标记 `securityScanStatus=passed`。`npm run audit:runtime` 当前为 0 vulnerabilities；Excel 解析已从 `exceljs` 切换为 `read-excel-file`，避免生产运行时携带 `exceljs -> uuid` 的已知中危依赖。
 
 注意：`apps/taro` 是静态构建工程，线上发布 `apps/taro/dist/**`，不发布 `node_modules`。Taro 4.2.0 当前构建工具链仍会触发 `npm run audit:taro:toolchain` 的上游 high/critical 提示，不能用 `npm audit fix --force` 降级到 Taro 3 破坏构建；上线验收时以 `audit:runtime`、构建产物、前端密钥检查和静态服务器配置为准，并持续跟进 Taro 官方修复。