chore: add launch readiness smoke and tuning evidence

docs/refactor/web-launch-acceptance-checklist.md

@@ -0,0 +1,117 @@
+# Web 版上线前验收清单
+
+更新时间：2026-06-30
+
+这份清单用于先上线 H5 Web 题库。Taro 仍然是前端工程，后端以 Supabase Auth/JWT、PostgreSQL/RLS、`apps/api`、worker 为主。前端视觉和交互可以参考 `F:\project\参考\旧题库小程序前端文件` 和旧 Web 版，但不能继承旧 PocketBase 直连、旧鉴权或旧字段模型。
+
+## 前端接入原则
+
+- H5 登录态优先使用 Supabase Auth access token。
+- 复杂业务统一调用 `apps/api`，不要让页面直接写 Supabase 表。
+- `runtime-config.json` 只能放 `portal`、`apiBaseUrl`、`supabaseUrl`、`supabasePublishableKey`、`tenantCode`。
+- 前端禁止出现 service role key、secret key、数据库连接串、OSS/COS 密钥、支付私钥、短信密钥。
+- 页面层禁止手写 `x-user-id`、`Authorization`、`x-tenant-id`，统一使用 `apps/taro/src/services/api.ts`。
+- 私有图片、PDF、视频只消费后端短签名和 `content_assets` 权限结果，不能拼对象存储 URL。
+- 学生头像只做男女预设，不做上传、裁剪或第三方头像同步。
+- 排行榜默认不请求、不展示；只有租户购买/开启活动且完成专项压测后再接独立页面。
+
+## 学生端验收旅程
+
+用普通学生账号在 H5 走一遍：
+
+1. 进入域名后能解析租户品牌、主题、公开配置。
+2. 登录后 `GET /api/profile/me` 返回当前用户，不能靠页面传 userId。
+3. 查看题库入口、地区、分类树、合集和练习蓝图。
+4. 开通或确认 SVIP 权益后创建顺序/随机/模考 session。
+5. 拉取 session detail，刷新页面后仍能按后端 session 续练。
+6. 提交答案、交卷、查看报告、逐题复盘。
+7. 收藏题目，在个人中心或复习页进入收藏练习。
+8. 产生错题后查看错题本、复习计划和错题复习 session。
+9. 背单词：今日计划、单元学习、收藏练习、发音、进度上报。
+10. 知识手册：章节、搜索、公式/图片/RichContent 安全渲染。
+11. 分数线：地区、院校、专业、年份和动态字段筛选。
+12. 资料下载：预览/下载前必须看到短签名、水印 traceId 或权限提示。
+13. 视频解析：未授权提示、授权后短签名播放、水印上下文、次数扣减。
+14. 订单：套餐、优惠券、下单、支付参数、订单详情、状态轮询、售后入口。
+15. 个人中心：权益、学习统计、勋章、积分任务、兑换、站内通知。
+
+自动烟测命令：
+
+```bash
+npm run smoke:launch-persona
+```
+
+该命令会写入少量测试练习和收藏记录，生产只在灰度/演练租户执行。
+
+## 租户后台验收旅程
+
+用租户管理员账号在 H5 走一遍：
+
+1. 工作台模块按权限显示，学生账号访问后台必须 403。
+2. 数据看板能按 7/30/90 天、地区读取收益、注册、学习、内容、活跃、反馈、激活码。
+3. 学生运营：列表、状态、批量导入、分班、备注、跟进任务、督导规则、CRM 推送。
+4. 题库内容：入口、分类、题目集合、蓝图、题目/单词/手册/分数线/视频导入预览、异步 job、复检。
+5. 营销中心：激活码、优惠券规则、核销报表、积分任务、兑换、勋章、用户通知。
+6. CRM/分佣：CRM 配置、队列、失败池、日志脱敏、重试/忽略、结算、凭证复核、销售转化报表。
+7. 财务运营：退款、官方账单下载任务、对账异常、差错工单、人工调整凭证。
+8. 设置：品牌、主题模板/草稿/发布、域名、支付账户、登录 provider、角色模板、成员绑定。
+9. 跨租户访问必须拒绝，字段权限如手机号脱敏要按角色生效。
+
+## 平台后台验收旅程
+
+用平台管理员账号在 H5 走一遍：
+
+1. 工作台、租户列表、租户详情、状态变更、账务资料维护。
+2. SaaS 套餐、订阅、订阅账单候选、批量开票、收款、逾期催缴。
+3. 用量记录、用量超额候选、超额账单生成。
+4. 公共题库授权、租户可见范围、采纳/同步/冲突运营摘要。
+5. 平台员工、权限点、禁用/恢复、受限员工越权拒绝。
+6. 审计日志、CSV/JSON 导出、审计告警、外部通知渠道。
+7. 学生或租户管理员访问平台后台必须 403。
+
+## 安全与配置门禁
+
+上线前至少执行：
+
+```bash
+npm run test:readiness
+npm run test:rls
+npm run audit:runtime
+npm run check:api
+npm run check:worker
+npm run check:taro
+npm run smoke:launch-persona
+```
+
+如 `@codex-security` 插件在当前 Codex 环境暴露扫描工具，再补插件扫描结果。若工具不可用，不能把该项标记为已完成，只能在上线证据里标记为待补。
+
+生产 API 推荐：
+
+```text
+ALLOW_LEGACY_AUTH_HEADERS=false
+ALLOW_PLATFORM_ADMIN_KEY=false
+CORS_ORIGIN=https://student.example.com,https://tenant-admin.example.com,https://platform-admin.example.com
+```
+
+生产 worker 推荐：
+
+```text
+WORKER_ASSET_SECURITY_SCANNER=metadata_rules,http
+WORKER_ASSET_SECURITY_SCAN_FAIL_OPEN=false
+STORAGE_DEFAULT_PROVIDER=aliyun_oss 或 tencent_cos 或 supabase_storage
+STORAGE_REQUIRE_TENANT_PREFIX=true
+```
+
+## 性能与数据库
+
+本地真实迁移库已能跑题库读写压测，但正式容量必须在目标 4 核 16G 云服务器复测。
+
+推荐顺序：
+
+1. `npm run perf:postgres:evidence` 采集默认 PostgreSQL 参数。
+2. 按 `docs/refactor/postgresql-4c16g-tuning.md` 应用 shared-host 起步值。
+3. 重启 PostgreSQL 后再次 `npm run perf:postgres:evidence`。
+4. 跑 `npm run perf:api:local` 的 6/30/50/100 阶梯，只读和少量写入各一组。
+5. 把摘要写入本地 `production-launch-evidence.json`，执行 `npm run launch:gate`。
+
+容量折算不要直接把压测 worker 当在线人数。真实学生有读题和思考时间，应结合 H5 埋点估算单人平均 RPS，再按成功 RPS 折算在线容量。