# 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 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、对象存储或生产配置有变化时，还要运行：

```bash
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`，再运行：

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