docs: add ai development guardrails

docs/refactor/ai-development-guardrails.md

@@ -0,0 +1,209 @@
+# AI 开发守则与安全基线
+
+更新时间：2026-06-28
+
+这份文档是后续 AI、后端、前端、运维共同遵守的最高优先级开发规范。项目可以逐步演进，但不能破坏这里定义的安全边界和架构方向。
+
+## 总原则
+
+本项目采用 Supabase-first 架构：
+
+- PostgreSQL/Supabase 是数据和权限事实来源。
+- Supabase Auth/JWT 是用户身份的主方向。
+- RLS、视图、函数、触发器、约束和索引优先承担数据层安全。
+- `apps/api`、Edge Functions、worker 承担复杂业务命令、密钥、第三方 provider、异步任务和审计。
+- Taro/H5/小程序可以使用 Supabase client，但不能直接改写复杂业务表。
+
+一句话：优先使用 Supabase 原生能力，但不要把业务规则散落到前端页面里。
+
+## 新功能落位判断树
+
+新增功能时按下面顺序判断：
+
+1. 只是公开、低风险、只读数据？
+   - 优先使用 view + RLS + Supabase Data API。
+   - 例如公开 Banner、公开 FAQ、公开主题资源。
+
+2. 是当前用户自己的简单数据，且没有复杂副作用？
+   - 可以考虑 table/view + RLS。
+   - 必须有跨租户测试、越权测试、最小 grant。
+   - 例如个人公开资料读取、只读学习统计快照。
+
+3. 是一个跨表业务动作，但全部在数据库内可安全完成？
+   - 优先 Postgres function/RPC。
+   - 必须 `security definer`/`security invoker` 选择清楚，函数内部显式校验 tenant/user/role。
+   - 例如激活码原子兑换、简单计数扣减、幂等状态流转。
+
+4. 需要第三方密钥、HTTP 调用、webhook、文件签名、AI、支付、短信、微信/QQ？
+   - 使用 Edge Function、`apps/api` 或 worker。
+   - 密钥只在服务端环境变量/KMS/Vault。
+
+5. 需要长任务、重试、队列、定时统计、导入后校验？
+   - 使用 worker。
+   - API 只负责提交 job 和查询 job 状态。
+
+## 严禁事项
+
+- 严禁在 Taro/H5/小程序中放入 Supabase secret key、service role key、数据库连接串、支付私钥、短信密钥、对象存储密钥。
+- 严禁前端直接写订单、支付、权益、激活码使用状态、租户密钥、平台账单、CRM 队列、内容导入结果。
+- 严禁为了快速开发关闭 RLS 或写宽泛 policy。
+- 严禁只靠前端隐藏按钮实现权限控制。
+- 严禁绕过 `content_assets` 台账直接拼接私有 OSS/COS/Supabase Storage URL。
+- 严禁在日志、导入 issue、审计日志中写入明文验证码、商户密钥、OAuth secret、支付私钥。
+- 严禁把旧 PocketBase 字段结构作为新系统长期事实来源。
+
+## Supabase 直连表的准入条件
+
+任何前端直连 Supabase table/view 之前，必须满足：
+
+- 已启用 RLS。
+- 已有最小权限 policy。
+- 不暴露跨租户数据。
+- 不暴露未开通权益的数据。
+- 不包含密钥、手机号批量列表、支付流水、后台配置等敏感信息。
+- 已有跨租户测试。
+- 已有角色越权测试。
+- 已有索引和分页限制。
+- 读写语义不会绕过业务审计。
+
+不满足任一条件，就不能前端直连，必须走 RPC、Edge Function、`apps/api` 或 worker。
+
+## RPC/数据库函数规范
+
+适合 RPC：
+
+- 原子事务。
+- 简短业务命令。
+- 强一致状态变化。
+- 不需要外部 HTTP provider。
+- 可以完全在数据库内校验权限。
+
+RPC 必须：
+
+- 参数包含或可推导 tenant 上下文。
+- 使用 `auth.uid()`、JWT claim 或服务端传入的可信 userId。
+- 函数内显式校验 membership/role/permission。
+- 返回稳定、前端友好的 JSON。
+- 对并发场景使用唯一约束、`for update`、幂等键或事务。
+- 写关键操作审计。
+
+不适合 RPC：
+
+- 支付平台验签。
+- 发送短信。
+- 微信/QQ OAuth 换取用户信息。
+- CRM webhook 推送。
+- OSS/COS 私有签名。
+- 大文件处理。
+- AI 报告生成。
+
+这些应放在 Edge Function、`apps/api` 或 worker。
+
+## `apps/api` 使用原则
+
+`apps/api` 不是为了替代 Supabase，而是作为业务命令层：
+
+- 验证 Supabase JWT/session。
+- 解析租户。
+- 聚合多表数据。
+- 校验角色和 permissions。
+- 调用 RPC 或执行事务。
+- 调用第三方 provider。
+- 处理 webhook 验签和幂等。
+- 签发私有资源 URL。
+- 提交/查询异步 job。
+- 写审计日志。
+
+后续如果某个模块更适合 Edge Functions，可以迁移过去，但必须保持统一的鉴权、审计、错误码和测试标准。
+
+## 多租户安全规范
+
+每个业务表默认必须有：
+
+- `tenant_id`
+- 必要唯一约束包含 `tenant_id`
+- 必要索引包含 `tenant_id`
+- RLS policy
+- API/RPC SQL 显式 tenant 过滤
+
+例外情况必须在 migration 中注释说明，例如平台全局字典、公开主题模板。
+
+公共题库也不能天然跨租户可见。必须通过授权、采纳、复制或订阅关系授予租户使用权。
+
+## 权限规范
+
+权限判断顺序：
+
+1. 平台超级管理员。
+2. 租户 membership。
+3. 租户角色默认权限。
+4. 租户自定义 permissions 覆盖。
+5. 资源范围权限，例如本人客资、班级学生、地区授权、题库授权。
+6. 权益权限，例如 SVIP、视频次数、资料下载权限。
+
+前端只负责 UI 可见性，后端/RPC/RLS 才是最终裁决。
+
+## 导入与迁移规范
+
+所有题目、单词、知识手册、分数线、视频等批量导入必须走：
+
+```text
+preview -> job -> items -> issues -> import -> audit -> validate
+```
+
+导入不得直接从前端写正式业务表。迁移脚本若因一次性内控需要直写数据库，必须：
+
+- 保留原始 payload。
+- 生成迁移报告。
+- 跑 `pb:import:validate`。
+- 跑 `check:refactor`。
+- 人工抽样验收。
+
+## 支付与权益规范
+
+支付相关必须满足：
+
+- 订单金额以后端套餐/商品价格为准。
+- 前端传来的金额只能作为展示或校验参考。
+- webhook 必须验签。
+- webhook 必须有 provider event id 幂等。
+- 支付成功、权益开通必须在事务中完成。
+- 激活码兑换必须防并发。
+- 退款/撤销必须生成可审计事件。
+
+## 对象存储规范
+
+- 公开品牌图可以放公开 bucket/CDN。
+- 私有 PDF、资料、视频必须进入 `content_assets`。
+- 下载/播放必须由后端或 Edge Function 校验权限后签发短期 URL。
+- 上传后必须校验对象存在性、size、mime、hash。
+- 视频应补防盗链、水印、播放日志和次数扣减。
+
+## 测试与提交规范
+
+涉及业务逻辑、安全边界、权限、支付、导入、资源访问的改动，提交前至少运行：
+
+```bash
+npm run check:refactor
+```
+
+新增直连 Supabase 表、RPC、RLS policy、权限点时，必须增加或更新测试覆盖：
+
+- 同租户允许。
+- 跨租户拒绝。
+- 低权限拒绝。
+- 未登录拒绝。
+- 并发/幂等。
+
+## 给后续 AI 的开发提示
+
+实现代码前先查：
+
+1. `docs/refactor/ai-development-guardrails.md`
+2. `docs/refactor/supabase-frontend-access-strategy.md`
+3. `docs/refactor/multitenant-auth-security-contract.md`
+4. `docs/refactor/backend-capability-status.md`
+5. `docs/refactor/legacy-feature-gap-matrix.md`
+
+如果需求与这些文档冲突，先更新架构文档并说明原因，再改代码。
+