docs: add ai development guardrails

docs/refactor/api-structure.md

@@ -1,6 +1,6 @@
 # API 目录规范
 
-`apps/api` 是 Web、Taro 小程序、管理后台共用的业务 API。所有复杂业务写入都进入这里，前端不直接写 Supabase 表。
+`apps/api` 是 Web、Taro 小程序、管理后台共用的业务命令 API。项目采用 Supabase-first 架构：简单安全的数据访问可以走 Supabase table/view/RPC + RLS；复杂业务写入、第三方 provider、密钥、webhook、导入、支付、权益、审计进入 `apps/api`、Edge Functions 或 worker。
 
 ## 当前结构
 
@@ -59,6 +59,7 @@ types.ts                   仅本领域使用的类型
 - `repository.ts` 才写 SQL，所有 SQL 必须带明确租户边界。
 - 可预期错误用 `HttpError`，生产环境不向前端暴露内部异常。
 - 写接口必须考虑幂等、审计和租户隔离；支付 webhook 必须先设计幂等键。
+- 不要为了少写 API 而让前端直写复杂业务表。新增前端直连 table/view/RPC 必须先满足 RLS、最小 grant、跨租户测试、权限测试和索引要求。
 - 迁移期接口可用 `x-user-id` 标识学生用户；接 Supabase Auth 后统一替换为 JWT 解析。
 - 登录类接口先使用 `Authorization: Bearer tk_*` 迁移期 session；session 明文只返回客户端，数据库只保存 hash。
 - 平台运营接口使用 `x-platform-admin-key` 作为临时保护；正式上线前要迁到平台管理员 JWT 和审计日志。
@@ -68,5 +69,5 @@ types.ts                   仅本领域使用的类型
 - `referral` 是增长/客资业务域，负责邀请码、扫码事件、首绑保护、销售/代理团队归属和 CRM 入队；真实 CRM webhook 发送应由 worker 处理，API 只负责幂等入队。
 - 题库前端入口不再只依赖旧 `module_nodes/subjects/categories`；新业务主模型是 `content_entries/content_nodes/question_collections/practice_blueprints`，用于表达可视化入口、多级分类、考试意向标记、题目列表和顺序/随机/全真模拟规则。
 - `learning` 创建练习 session 时必须保存 `question_ids` 快照，避免随机刷题和模考过程中题目集合变化导致答题记录无法复盘。
-- 资料、PDF、视频等对象存储资源必须先进入 `content_assets` 台账，再通过 API 做权限校验和签名 URL 下发；前端不能直接拼 OSS/COS/Supabase Storage 地址。
+- 资料、PDF、视频等对象存储资源必须先进入 `content_assets` 台账，再通过 API/Edge Function 做权限校验和签名 URL 下发；前端不能直接拼 OSS/COS/Supabase Storage 私有地址。
 - 批量导入必须先写 `content_import_jobs/items/issues`，保留原始 payload、规范化 payload、逐行问题和审计记录；同步 API 当前支持题目 JSON，Excel/CSV 和其它内容类型应接入同一管线。