# 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 字段结构作为新系统长期事实来源。 - 严禁为学生头像新增上传链路、对象存储签名、第三方头像落库或后台批量导入字段；学生头像只允许 `avatarPreset=male/female` 默认资源，租户后台学生接口也不能写头像 URL 或平台主角色字段。 - 严禁在学生端默认请求或展示排行榜；排行榜接口只作为租户显式开启后的活动能力，默认学习激励以后台配置的勋章自动发放为主。 - 严禁新增 Taro 页面后不注册路由、不更新启动页/静态烟测入口或不更新前端交接清单；页面变更后必须运行 `node scripts/taro-route-contract-test.js`，确保 `app.config.ts`、`pages/**/index.tsx`、启动页跳转和交接文档一致。 ## 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 ``` CSV/Excel 导入属于后端规范化能力，`.xlsx` 解析统一走 `read-excel-file`。不要把 `exceljs` 重新加入生产运行时；确需替换解析库时，必须同时证明 `npm run audit:runtime` 通过，并用 API 集成测试覆盖多 Sheet 分数线、题目、单词、知识手册和视频导入。 导入不得直接从前端写正式业务表。迁移脚本若因一次性内控需要直写数据库，必须： - 保留原始 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` 如果需求与这些文档冲突，先更新架构文档并说明原因，再改代码。