chore: gate production postgres tuning and taro handoff

docs/refactor/taro-production-integration-checklist.md

@@ -0,0 +1,108 @@
+# Taro 生产接入检查清单
+
+更新时间：2026-07-01
+
+这份清单给前端同事和后续 AI 使用。目标是让 `apps/taro` 的 H5 学生端、租户后台、平台后台按当前 Supabase/PostgreSQL 新后端上线，后续再扩展微信小程序。旧小程序前端文件在 `F:\project\参考\旧题库小程序前端文件`，只作为视觉、交互状态和微信平台能力参考，不继承旧 PocketBase 直连、旧 token、旧安全假设。
+
+## 总原则
+
+- Taro 负责 UI、路由、交互、公开 runtime config 和 Supabase Auth session。
+- 复杂业务默认调用 `apps/api`，不要让页面直接写 Supabase 业务表。
+- Supabase client 可用于 Auth session、可选 Realtime、公开只读 view/table 或经过 RLS/RPC 评审的低风险功能。
+- 支付、短信、微信/QQ OAuth、订单、权益、激活码、优惠券、CRM、AI、导入、私有对象存储签名必须走 `apps/api`、Edge Function 或 worker。
+- 页面代码不得覆盖 `Authorization`、`x-tenant-id`，不得发送 `x-user-id`。
+- 前端只做可见性优化，权限最终以后端/RLS/RPC 校验为准。
+
+## 三套 H5 发布目录
+
+建议三套 H5 分域部署，不共用 web root：
+
+| 门户 | 推荐域名 | 构建命令 | runtime-config |
+| --- | --- | --- | --- |
+| 学生端 | `https://www.example.com` 或租户自定义域名 | `npm run build:taro:h5:student` | `apps/taro/deploy/h5-student.runtime-config.example.json` |
+| 租户后台 | `https://admin.example.com` | `npm run build:taro:h5:tenant` | `apps/taro/deploy/h5-tenant-admin.runtime-config.example.json` |
+| 平台后台 | `https://console.example.com` | `npm run build:taro:h5:platform` | `apps/taro/deploy/h5-platform-admin.runtime-config.example.json` |
+
+每个发布目录根部必须放置独立的 `runtime-config.json`，只允许公开字段：
+
+```json
+{
+  "portal": "student",
+  "apiBaseUrl": "https://api.example.com",
+  "supabaseUrl": "https://supabase.example.com",
+  "supabasePublishableKey": "sb_publishable_xxx",
+  "tenantCode": "optional-tenant-slug"
+}
+```
+
+禁止出现在 `runtime-config.json`、Taro 环境变量、源码和构建产物中的内容：
+
+- Supabase service role / secret key。
+- 数据库连接串。
+- 短信、OAuth、支付、对象存储、CRM、AI 的 secret/private key。
+- 真实用户 token、测试 access token、平台本地管理 key。
+
+## 生产接入步骤
+
+1. 配好三套 H5 的 `runtime-config.json`，确认 `apiBaseUrl`、`supabaseUrl` 都是 HTTPS。
+2. H5 登录优先使用 Supabase Auth access token；迁移期 `tk_` session 只用于本地或内网联调。
+3. 学生端先走完整路径：解析租户、登录、选择地区、进入题库、创建练习、答题、收藏、交卷、查看报告、错题/收藏复习、背单词、知识手册、资料预览/下载、视频授权、会员下单、订单轮询。
+4. 租户后台先走完整路径：权限加载、学生运营、题库导入/任务/问题行、公共题库采纳、营销中心、财务运营、主题发布、角色模板和成员绑定。
+5. 平台后台先走完整路径：平台权限加载、创建租户、租户详情、账务资料、订阅/账单/用量、公共题库授权、平台员工、审计和告警。
+6. 所有真实 provider 密钥只配置在后端 `.env`、`app_private.tenant_secrets`、`app_private.platform_secrets` 或生产 KMS/Vault，不进入 Taro。
+7. 对象存储私有资源必须通过 `content_assets` 台账和后端短签名；前端只展示签名 URL、过期时间、`watermark.traceId` 和水印容器。
+8. 支付页面只展示后端返回的支付参数、订单状态和权益结果；金额、套餐、优惠、权益最终以后端返回为准。
+
+## 必跑检查
+
+页面、API service、路由、runtime config 或发布目录有任何变化时，至少运行：
+
+```bash
+npm run check:taro
+npm run test:readiness
+npm run smoke:taro:h5
+npm run smoke:taro:h5:interaction
+node scripts/taro-h5-release-guardrails-test.js --require-dist --require-runtime-config
+```
+
+后端、RLS、provider、对象存储或生产配置有变化时，还要运行：
+
+```bash
+npm run readiness:production
+npm run readiness:production:db
+npm run smoke:auth:remote
+npm run test:rls
+npm run audit:runtime
+```
+
+正式上线前，三套 H5 严格发布证据、真实 Auth/RLS、真实 provider 抽样、对象存储控制、支付对账、PostgreSQL 严格调参证据和真实数据压测都要写入本地 `docs/refactor/production-launch-evidence.json`，再运行：
+
+```bash
+npm run launch:gate -- --evidence docs/refactor/production-launch-evidence.json
+```
+
+## 小程序后续兼容重点
+
+小程序不能直接照搬 H5 假设，进入真机前要单独验收：
+
+- `@supabase/supabase-js` 的 fetch、storage、URL、token refresh 兼容性。
+- 如果兼容成本高，小程序登录只调用 `apps/api/auth/*`，由后端换取可信 session。
+- 微信支付容器、订阅消息、分享参数、小程序码 tenant/referral 场景。
+- KaTeX/公式渲染替代方案、题图资源字段化、PDF 预览能力和下载限制。
+- 网络错误、弱网续练、本地缓存恢复、切后台/回前台 token 刷新。
+
+## 旧前端参考边界
+
+可以参考旧项目：
+
+- 学生端刷题流程、答题卡、题型展示、背单词卡片、知识手册阅读、个人中心视觉。
+- 微信小程序分享、支付、授权和登录交互经验。
+- 租户后台/运营后台字段含义和常用工作流。
+
+不能继承旧项目：
+
+- PocketBase SDK 直连和旧 collection 命名。
+- 前端保存或拼接用户 id、租户 id 来绕过后端鉴权。
+- 前端直接写订单、权益、学习记录、错题、收藏、导入任务。
+- 旧头像上传/第三方头像同步；学生头像只保留男女预设。
+- 默认排行榜请求；排行榜只作为租户显式开启后的活动能力。