gongxue-base/docs/refactor/ai-development-guardrails.md

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 才是最终裁决。

导入与迁移规范

所有题目、单词、知识手册、分数线、视频等批量导入必须走：

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。
• 视频应补防盗链、水印、播放日志和次数扣减。

测试与提交规范

涉及业务逻辑、安全边界、权限、支付、导入、资源访问的改动，提交前至少运行：

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

如果需求与这些文档冲突，先更新架构文档并说明原因，再改代码。