docs: add ai development guardrails

docs/refactor/README.md

@@ -18,6 +18,7 @@
 - `scripts/import-pocketbase`：PocketBase schema/数据导入工具。
 - `docker-compose.api.yml`、`apps/api/Dockerfile`：本地 Docker API 运行入口。
 - `docs/refactor/architecture.md`：新重构目录边界和工程规范。
+- `docs/refactor/ai-development-guardrails.md`：后续 AI/开发者必须遵守的 Supabase-first 架构和安全守则。
 - `docs/refactor/content-import-contract.md`：题目、单词、知识手册导入契约，明确后端校验、旧格式转换和前端职责。
 - `docs/refactor/next-development-todo.md`：后端剩余缺口、Taro 前端接入顺序、上云测试前待办。
 - `docs/refactor/backend-handoff-roadmap.md`：进入 Taro 前端前的后端进度同步、缺口清单和接入路线图。

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`
+
+如果需求与这些文档冲突，先更新架构文档并说明原因，再改代码。
+

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 和其它内容类型应接入同一管线。

docs/refactor/architecture.md

@@ -6,7 +6,7 @@
 
 ```text
 apps/
-  api/                    新业务 API，前端和小程序都通过它访问业务数据
+  api/                    业务命令 API，承接复杂事务、第三方 provider、密钥和审计
     src/core/             配置、HTTP、错误响应、路由注册、数据库访问等基础层
     src/features/         领域模块，按 catalog、tenant、health 等拆分
     src/features/platform-admin/
@@ -26,14 +26,15 @@ scripts/
   import-pocketbase/      PocketBase schema 风险分析、JSON 导入、导入后校验
   smoke-seed.js           本地 reset 后的最小业务烟测数据
 
-src/
-  services/supabaseApi.ts 旧 Web 前端迁向新 API 的兼容客户端
-  tenant.config.ts        租户解析配置，优先读新 API
+docs/refactor/
+  ai-development-guardrails.md
+                            后续 AI/开发者必须遵守的架构和安全守则
 ```
 
 ## 设计原则
 
-- `apps/api` 是业务 API 层，复杂交易、支付、权益、租户解析都应该在这里做，不让前端直接操作表。
+- 本项目采用 Supabase-first 架构。简单安全的数据访问优先使用 RLS、视图、RPC 等 Supabase/PostgreSQL 原生能力；复杂交易、支付、权益、租户解析、密钥、webhook、异步任务和审计放在 `apps/api`、Edge Functions 或 worker。
+- 前端可以使用 Supabase client 管理 Auth/JWT，也可以在严格 RLS 下访问低风险 table/view/RPC；但不得直接写订单、支付、权益、租户密钥、CRM、导入等复杂业务表。
 - 平台方与合作商之间的 SaaS 收费，使用 `platform_saas_plans`、`tenant_subscriptions`、`tenant_invoices`、`tenant_invoice_payments`；学生 C 端会员订单仍使用 `orders/payments/entitlements`。
 - `apps/api/src/server.ts` 只负责 HTTP 生命周期；业务路由统一放在 `features/*`，由 `core/router.ts` 汇总注册。
 - API 对外错误必须走 `HttpError` 或统一错误响应，生产环境不向前端泄露数据库异常和内部栈信息。
@@ -94,4 +95,4 @@ npm run pb:import:validate
 - `apps/api/src/features` 继续按业务域扩展：真实支付 provider、真实 OAuth provider、平台审计和 worker。
 - `src/services/supabaseApi.ts` 逐页替换旧 PB 只读接口，优先学生端和小程序共用页面。
 - 新增 `apps/worker` 承接 CRM webhook、支付补偿、日报统计、导入后异步检查。
-- 新增 `apps/taro` 后，所有租户解析和公开业务读取都复用 API，不单独维护另一套后端逻辑。
+- 新增 `apps/taro` 后，Auth/JWT 优先复用 Supabase client；复杂业务命令复用 `apps/api`/RPC/Edge Functions，不单独维护另一套后端逻辑。

docs/refactor/frontend-handoff-index.md

@@ -8,17 +8,19 @@
 
 1. `docs/refactor/project-structure.md`
    - 先确认新项目目录边界，避免把 `参考/旧题库项目` 当成新源码。
-2. `docs/refactor/backend-capability-status.md`
+2. `docs/refactor/ai-development-guardrails.md`
+   - 先看后续 AI/开发者必须遵守的 Supabase-first 架构、安全红线和功能落位判断树。
+3. `docs/refactor/backend-capability-status.md`
    - 看哪些后端能力已经能联调，哪些只是迁移期可用。
-3. `docs/refactor/legacy-feature-gap-matrix.md`
+4. `docs/refactor/legacy-feature-gap-matrix.md`
    - 对照旧题库功能，确认哪些页面能按新 API 重做，哪些后端还要补。
-4. `docs/refactor/supabase-frontend-access-strategy.md`
+5. `docs/refactor/supabase-frontend-access-strategy.md`
    - 明确 Taro 什么时候可以用 Supabase client，什么时候必须走 `apps/api`。
-5. `docs/refactor/taro-frontend-integration.md`
+6. `docs/refactor/taro-frontend-integration.md`
    - Taro 启动、租户解析、请求封装、页面/API 映射、跨端注意事项。
-6. `docs/refactor/multitenant-auth-security-contract.md`
+7. `docs/refactor/multitenant-auth-security-contract.md`
    - 多租户、鉴权、权限、资源签名和生产安全红线。
-7. `docs/refactor/content-import-contract.md`
+8. `docs/refactor/content-import-contract.md`
    - 后台内容导入、题目 JSON、单词、知识手册的后端校验契约。
 
 ## 当前可进入的前端工作
@@ -37,7 +39,7 @@
 ## 不能误认为已商用完成的部分
 
 - 生产鉴权尚未完成：当前很多接口仍用 `x-tenant-id`、`x-user-id`、`x-platform-admin-key` 作为迁移期上下文。
-- 不要把“Supabase 支持前端 Data API”误解为“本项目所有业务表都由 Taro 直写”；订单、支付、权益、租户后台、导入、CRM、私有资源必须走后端。
+- 不要把“Supabase 支持前端 Data API”误解为“本项目所有业务表都由 Taro 直写”；订单、支付、权益、租户后台、导入、CRM、私有资源必须走 RPC、`apps/api`、Edge Function 或 worker 这类后端命令层。
 - 真实短信、微信登录、QQ 登录、微信支付、支付宝支付 provider 还未正式接完。
 - 对象存储已完成签名 provider，但 PDF 预览、防盗链、视频水印、上传后校验还要补。
 - 大批量 Excel/CSV、分数线、视频导入和异步 worker 还未完成。

docs/refactor/supabase-frontend-access-strategy.md

@@ -4,7 +4,7 @@
 
 这份文档用于回答一个关键架构问题：Taro/H5/小程序前端到底应该直接调用 Supabase，还是调用我们自己的 `apps/api` 后端？
 
-结论：采用“Supabase Auth/JWT + 业务 API 优先 + 有边界的 Supabase Client 直连”的混合架构。
+结论：采用 Supabase-first 的混合架构。优先使用 Supabase Auth、RLS、视图、RPC、Storage 等原生能力；涉及密钥、跨表事务、支付、导入、对象存储签名、CRM、AI 和复杂权限的业务命令，放到 Edge Functions、`apps/api` 或 worker。
 
 ## 官方依据
 
@@ -46,9 +46,10 @@ Taro/H5/小程序
   ├─ Supabase client
   │   ├─ Auth session/JWT
   │   ├─ 可选：Realtime
-  │   └─ 可选：严格 RLS 下的低风险只读数据
+  │   ├─ 可选：严格 RLS 下的 table/view 只读或低风险自助写入
+  │   └─ 可选：RPC 调用短事务业务函数
   │
-  └─ apps/api 业务 API
+  └─ apps/api / Edge Functions 业务命令层
       ├─ 校验 Supabase JWT/session
       ├─ 解析 tenant
       ├─ 校验角色和 permissions
@@ -60,17 +61,32 @@ Taro/H5/小程序
 
 `apps/api` 可以部署为我们自己的 Node.js API，也可以在部分云原生场景下拆为 Supabase Edge Functions。对当前项目而言，保留 `apps/api` 更适合复杂业务、国内 provider、自托管和后续 worker。
 
+## 功能落位选择
+
+| 场景 | 首选方案 | 说明 |
+| --- | --- | --- |
+| 公开只读数据 | view/table + RLS | 例如公开 Banner、FAQ、主题配置 |
+| 当前用户简单自助读写 | table/view + RLS | 必须有最小 policy 和越权测试 |
+| 原子状态变化 | Postgres RPC | 例如激活码兑换、计数扣减、幂等状态流转 |
+| 跨表聚合读取 | view/RPC 或 `apps/api` | 简单聚合可用 view，复杂权限用 API |
+| 支付/短信/OAuth/CRM/AI | Edge Function 或 `apps/api` | 需要密钥和外部 HTTP 调用 |
+| 大批量导入/重试/定时任务 | worker | API 只提交 job 和查询状态 |
+| 私有对象存储签名 | Edge Function 或 `apps/api` | 必须先校验 `content_assets` 和权益 |
+
+选择原则：能用 RLS/view/RPC 安全解决的，就不要写一堆重复后端代码；需要密钥、副作用、审计、幂等和第三方 provider 的，就不要放到前端直连表。
+
 ## 前端直连 Supabase 的适用范围
 
 | 能力 | 是否建议前端直连 Supabase | 说明 |
 | --- | --- | --- |
 | Supabase Auth session | 建议 | H5 可直接用 `@supabase/supabase-js`；小程序需先验证运行时兼容性 |
 | 获取当前用户 JWT | 建议 | API 请求统一带 `Authorization: Bearer <access_token>` |
-| 低风险公开只读数据 | 可选 | 仅限 RLS、grant、索引都成熟后；当前默认仍走 `apps/api` |
+| 低风险公开只读数据 | 可选 | 仅限 RLS、grant、索引都成熟后 |
+| 原子业务 RPC | 可选 | 仅限函数内部完成 tenant/user/permission 校验 |
 | Realtime 通知 | 可选 | 非敏感通知、学习状态刷新可考虑；后台敏感队列不建议前端订阅 |
 | Public Storage 公开资源 | 可选 | 真正公开的 Logo、主题图可直连 CDN/公开 bucket |
 | 私有资料/PDF/视频 | 不建议 | 必须通过 `content_assets` 权限校验和后端签名 |
-| 学习记录/答题/错题/收藏 | 不建议 | 涉及权益、统计、审计、题目快照，应走 API |
+| 学习记录/答题/错题/收藏 | 不建议直接写表 | 可通过后端 API 或经过安全评审的 RPC |
 | 订单/支付/激活码/优惠券 | 禁止 | 必须走后端事务、验签和幂等 |
 | 租户后台配置 | 禁止 | 涉及权限、密钥、审计 |
 | 内容导入/题库维护 | 禁止 | 必须走 preview/import/job/issues 管线 |
@@ -92,7 +108,7 @@ Taro 要同时支持 H5 和微信小程序。Supabase 官方 JavaScript client
    - 前端把微信 `code` 或手机号验证码发给后端。
    - 后端调用 Supabase Auth/Admin 或自有 session 逻辑换取可信 session。
    - 前端保存后端返回的 access token/session。
-4. 无论 H5 还是小程序，业务数据默认调用 `apps/api`，不直接写 Supabase 表。
+4. 无论 H5 还是小程序，复杂业务数据默认调用 `apps/api`、Edge Function 或 RPC，不直接写 Supabase 表。
 
 ## 推荐前端环境变量
 
@@ -147,15 +163,14 @@ Authorization: Bearer <supabase_access_token_or_server_session>
 
 ## 对后续 AI/开发者的硬性约束
 
-- 不要把 `apps/api` 删除或绕过。
-- 不要让 Taro 直接写订单、支付、权益、内容、租户配置、CRM、导入相关表。
+- 不要把 Supabase-first 误解成前端直写所有表。
+- 不要让 Taro 直接写订单、支付、权益、租户配置、CRM、导入相关表。
 - 不要把 service role/secret key 放进 Taro。
 - 不要为了少写接口而放宽 RLS。
-- 新增前端直连 Supabase 表之前，必须先补：
+- 新增前端直连 Supabase table/view/RPC 之前，必须先补：
   - 明确 RLS policy。
   - 最小 grant。
   - 跨租户测试。
   - 权限测试。
   - 性能索引。
-- 若某个功能需要密钥、跨表事务、webhook、审计、幂等或第三方 provider，一律放到 `apps/api` 或 worker/Edge Function。
-
+- 若某个功能需要密钥、webhook、审计、幂等、长任务或第三方 provider，一律放到 `apps/api`、Edge Function 或 worker。

docs/refactor/taro-frontend-integration.md

@@ -37,7 +37,7 @@ F:\project\参考\旧题库项目\src
 
 ## 请求封装
 
-本项目不采用“前端直接写 Supabase 表替代后端”的模式。Supabase 官方允许前端在 RLS 和最小权限下使用 Data API，但本系统的订单、支付、权益、租户后台、内容导入、CRM、对象存储签名等都需要服务端事务、密钥、审计和幂等，所以业务数据默认调用 `apps/api`。
+本项目不采用“前端直接写 Supabase 表替代业务命令层”的模式。Supabase 官方允许前端在 RLS 和最小权限下使用 Data API，但本系统的订单、支付、权益、租户后台、内容导入、CRM、对象存储签名等都需要服务端事务、密钥、审计和幂等，所以复杂业务命令默认调用 RPC、`apps/api`、Edge Function 或 worker。
 
 前端可以使用 Supabase client 的范围：