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，只允许公开字段：

{
  "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。

生产接入步骤

配好三套 H5 的 runtime-config.json，确认 apiBaseUrl、supabaseUrl 都是 HTTPS。
H5 登录优先使用 Supabase Auth access token；迁移期 tk_ session 只用于本地或内网联调。
学生端先走完整路径：解析租户、登录、选择地区、进入题库、创建练习、答题、收藏、交卷、查看报告、错题/收藏复习、背单词、知识手册、资料预览/下载、视频授权、会员下单、订单轮询。
租户后台先走完整路径：权限加载、学生运营、题库导入/任务/问题行、公共题库采纳、营销中心、财务运营、主题发布、角色模板和成员绑定。
平台后台先走完整路径：平台权限加载、创建租户、租户详情、账务资料、订阅/账单/用量、公共题库授权、平台员工、审计和告警。
所有真实 provider 密钥只配置在后端 .env、app_private.tenant_secrets、app_private.platform_secrets 或生产 KMS/Vault，不进入 Taro。
对象存储私有资源必须通过 content_assets 台账和后端短签名；前端只展示签名 URL、过期时间、watermark.traceId 和水印容器。
支付页面只展示后端返回的支付参数、订单状态和权益结果；金额、套餐、优惠、权益最终以后端返回为准。

必跑检查

页面、API service、路由、runtime config 或发布目录有任何变化时，至少运行：

npm run check:taro
npm run test:readiness
npm run guard:taro:visual
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、对象存储或生产配置有变化时，还要运行：

npm run readiness:production
npm run readiness:production:db
npm run smoke:auth:remote
npm run test:rls
npm run audit:runtime
npm run security:repo

正式上线前，三套 H5 严格发布证据、真实 Auth/RLS、真实 provider 抽样、对象存储控制、支付对账、PostgreSQL 严格调参证据、security:repo 和真实数据压测都要写入本地 docs/refactor/production-launch-evidence.json，再运行：

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 来绕过后端鉴权。
前端直接写订单、权益、学习记录、错题、收藏、导入任务。
旧头像上传/第三方头像同步；学生头像只保留男女预设。
默认排行榜请求；排行榜只作为租户显式开启后的活动能力。

5.8 KiB Raw Blame History Unescape Escape