docs: add ai development guardrails

docs/refactor/supabase-frontend-access-strategy.md

@@ -4,7 +4,7 @@
 
 这份文档用于回答一个关键架构问题：Taro/H5/小程序前端到底应该直接调用 Supabase，还是调用我们自己的 `apps/api` 后端？
 
-结论：采用“Supabase Auth/JWT + 业务 API 优先 + 有边界的 Supabase Client 直连”的混合架构。
+结论：采用 Supabase-first 的混合架构。优先使用 Supabase Auth、RLS、视图、RPC、Storage 等原生能力；涉及密钥、跨表事务、支付、导入、对象存储签名、CRM、AI 和复杂权限的业务命令，放到 Edge Functions、`apps/api` 或 worker。
 
 ## 官方依据
 
@@ -46,9 +46,10 @@ Taro/H5/小程序
   ├─ Supabase client
   │   ├─ Auth session/JWT
   │   ├─ 可选：Realtime
-  │   └─ 可选：严格 RLS 下的低风险只读数据
+  │   ├─ 可选：严格 RLS 下的 table/view 只读或低风险自助写入
+  │   └─ 可选：RPC 调用短事务业务函数
   │
-  └─ apps/api 业务 API
+  └─ apps/api / Edge Functions 业务命令层
       ├─ 校验 Supabase JWT/session
       ├─ 解析 tenant
       ├─ 校验角色和 permissions
@@ -60,17 +61,32 @@ Taro/H5/小程序
 
 `apps/api` 可以部署为我们自己的 Node.js API，也可以在部分云原生场景下拆为 Supabase Edge Functions。对当前项目而言，保留 `apps/api` 更适合复杂业务、国内 provider、自托管和后续 worker。
 
+## 功能落位选择
+
+| 场景 | 首选方案 | 说明 |
+| --- | --- | --- |
+| 公开只读数据 | view/table + RLS | 例如公开 Banner、FAQ、主题配置 |
+| 当前用户简单自助读写 | table/view + RLS | 必须有最小 policy 和越权测试 |
+| 原子状态变化 | Postgres RPC | 例如激活码兑换、计数扣减、幂等状态流转 |
+| 跨表聚合读取 | view/RPC 或 `apps/api` | 简单聚合可用 view，复杂权限用 API |
+| 支付/短信/OAuth/CRM/AI | Edge Function 或 `apps/api` | 需要密钥和外部 HTTP 调用 |
+| 大批量导入/重试/定时任务 | worker | API 只提交 job 和查询状态 |
+| 私有对象存储签名 | Edge Function 或 `apps/api` | 必须先校验 `content_assets` 和权益 |
+
+选择原则：能用 RLS/view/RPC 安全解决的，就不要写一堆重复后端代码；需要密钥、副作用、审计、幂等和第三方 provider 的，就不要放到前端直连表。
+
 ## 前端直连 Supabase 的适用范围
 
 | 能力 | 是否建议前端直连 Supabase | 说明 |
 | --- | --- | --- |
 | Supabase Auth session | 建议 | H5 可直接用 `@supabase/supabase-js`；小程序需先验证运行时兼容性 |
 | 获取当前用户 JWT | 建议 | API 请求统一带 `Authorization: Bearer <access_token>` |
-| 低风险公开只读数据 | 可选 | 仅限 RLS、grant、索引都成熟后；当前默认仍走 `apps/api` |
+| 低风险公开只读数据 | 可选 | 仅限 RLS、grant、索引都成熟后 |
+| 原子业务 RPC | 可选 | 仅限函数内部完成 tenant/user/permission 校验 |
 | Realtime 通知 | 可选 | 非敏感通知、学习状态刷新可考虑；后台敏感队列不建议前端订阅 |
 | Public Storage 公开资源 | 可选 | 真正公开的 Logo、主题图可直连 CDN/公开 bucket |
 | 私有资料/PDF/视频 | 不建议 | 必须通过 `content_assets` 权限校验和后端签名 |
-| 学习记录/答题/错题/收藏 | 不建议 | 涉及权益、统计、审计、题目快照，应走 API |
+| 学习记录/答题/错题/收藏 | 不建议直接写表 | 可通过后端 API 或经过安全评审的 RPC |
 | 订单/支付/激活码/优惠券 | 禁止 | 必须走后端事务、验签和幂等 |
 | 租户后台配置 | 禁止 | 涉及权限、密钥、审计 |
 | 内容导入/题库维护 | 禁止 | 必须走 preview/import/job/issues 管线 |
@@ -92,7 +108,7 @@ Taro 要同时支持 H5 和微信小程序。Supabase 官方 JavaScript client
    - 前端把微信 `code` 或手机号验证码发给后端。
    - 后端调用 Supabase Auth/Admin 或自有 session 逻辑换取可信 session。
    - 前端保存后端返回的 access token/session。
-4. 无论 H5 还是小程序，业务数据默认调用 `apps/api`，不直接写 Supabase 表。
+4. 无论 H5 还是小程序，复杂业务数据默认调用 `apps/api`、Edge Function 或 RPC，不直接写 Supabase 表。
 
 ## 推荐前端环境变量
 
@@ -147,15 +163,14 @@ Authorization: Bearer <supabase_access_token_or_server_session>
 
 ## 对后续 AI/开发者的硬性约束
 
-- 不要把 `apps/api` 删除或绕过。
-- 不要让 Taro 直接写订单、支付、权益、内容、租户配置、CRM、导入相关表。
+- 不要把 Supabase-first 误解成前端直写所有表。
+- 不要让 Taro 直接写订单、支付、权益、租户配置、CRM、导入相关表。
 - 不要把 service role/secret key 放进 Taro。
 - 不要为了少写接口而放宽 RLS。
-- 新增前端直连 Supabase 表之前，必须先补：
+- 新增前端直连 Supabase table/view/RPC 之前，必须先补：
   - 明确 RLS policy。
   - 最小 grant。
   - 跨租户测试。
   - 权限测试。
   - 性能索引。
-- 若某个功能需要密钥、跨表事务、webhook、审计、幂等或第三方 provider，一律放到 `apps/api` 或 worker/Edge Function。
-
+- 若某个功能需要密钥、webhook、审计、幂等、长任务或第三方 provider，一律放到 `apps/api`、Edge Function 或 worker。