# 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 或平台主角色字段。
- 严禁在学生端默认请求或展示排行榜；排行榜接口只作为租户显式开启后的活动能力，默认学习激励以后台配置的勋章自动发放为主。

## 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`

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