docs: clarify supabase frontend access strategy

docs/refactor/taro-frontend-integration.md

@@ -2,7 +2,7 @@
 
 更新时间：2026-06-28
 
-目标：用一套 Taro 工程同时服务微信小程序和 H5 Web 题库，统一调用 `apps/api`，并支持多租户、品牌主题、地区题库、会员权益、销售追踪和对象存储资源。
+目标：用一套 Taro 工程同时服务微信小程序和 H5 Web 题库，并采用“Supabase Auth/JWT + `apps/api` 业务 API 优先”的混合架构，支持多租户、品牌主题、地区题库、会员权益、销售追踪和对象存储资源。
 
 建议新建：
 
@@ -37,6 +37,22 @@ F:\project\参考\旧题库项目\src
 
 ## 请求封装
 
+本项目不采用“前端直接写 Supabase 表替代后端”的模式。Supabase 官方允许前端在 RLS 和最小权限下使用 Data API，但本系统的订单、支付、权益、租户后台、内容导入、CRM、对象存储签名等都需要服务端事务、密钥、审计和幂等，所以业务数据默认调用 `apps/api`。
+
+前端可以使用 Supabase client 的范围：
+
+- H5 Auth session/JWT。
+- 小程序端在兼容性验证通过后的 Auth session/JWT。
+- 低风险公开只读数据，且必须已经有 RLS、grant、跨租户测试。
+- Realtime 非敏感通知。
+
+前端必须调用 `apps/api` 的范围：
+
+- 题库练习、答题、错题、收藏。
+- 订单、支付、激活码、优惠券、权益。
+- 私有 PDF、资料、视频、对象存储签名。
+- 租户后台、平台后台、内容导入、CRM、销售/代理。
+
 前端应封装一个统一 API client，所有页面禁止直接散写 `Taro.request`。
 
 迁移期请求头：
@@ -50,11 +66,21 @@ x-user-id: <userId>
 生产目标：
 
 ```text
-Authorization: Bearer <jwt_or_session>
+Authorization: Bearer <supabase_access_token_or_server_session>
 ```
 
 生产后不应再由前端传 `x-user-id`。租户可以由可信 JWT claim、服务端 session、域名解析结果共同确定；前端传入的租户参数只能作为路由/展示上下文，不能作为安全依据。
 
+前端环境变量只允许包含：
+
+```text
+TARO_APP_API_BASE_URL
+TARO_APP_SUPABASE_URL
+TARO_APP_SUPABASE_PUBLISHABLE_KEY
+```
+
+禁止把 Supabase secret key、service role key、数据库连接串、对象存储密钥、支付私钥放进 Taro。
+
 统一错误处理：
 
 | HTTP | 前端动作 |
@@ -200,3 +226,13 @@ content_entries
 9. 租户后台内容维护和导入。
 10. 正式鉴权、真实支付、对象存储生产联调。
 
+## Supabase Client 验证任务
+
+前端 scaffold 后先做一个最小兼容性验证：
+
+- H5：`@supabase/supabase-js` 初始化、session 持久化、token refresh、logout。
+- 微信小程序：验证自定义 storage/fetch/URL polyfill 是否稳定。
+- API：用 Supabase access token 调 `apps/api`，后端解析出可信用户。
+- 安全：确认前端 bundle 中不存在 secret/service role/database/payment/storage 私钥。
+
+如果微信小程序端 `supabase-js` 兼容性不稳定，小程序端改走 `apps/api/auth/*` 登录适配层，H5 继续使用 Supabase client 管理 Auth。