From a8e0ac78be97e80bfec73d27ebdc81086d7961d4 Mon Sep 17 00:00:00 2001 From: Codex Date: Sun, 28 Jun 2026 21:00:55 +0800 Subject: [PATCH] docs: add ai development guardrails --- README.md | 1 + docs/refactor/README.md | 1 + docs/refactor/ai-development-guardrails.md | 209 ++++++++++++++++++ docs/refactor/api-structure.md | 5 +- docs/refactor/architecture.md | 13 +- docs/refactor/frontend-handoff-index.md | 16 +- .../supabase-frontend-access-strategy.md | 37 +++- docs/refactor/taro-frontend-integration.md | 2 +- 8 files changed, 257 insertions(+), 27 deletions(-) create mode 100644 docs/refactor/ai-development-guardrails.md diff --git a/README.md b/README.md index fcaa84c5..ebfe728c 100644 --- a/README.md +++ b/README.md @@ -34,6 +34,7 @@ - `docs/refactor/implementation-status.md` - `docs/refactor/backend-progress.md` - `docs/refactor/backend-handoff-roadmap.md` +- `docs/refactor/ai-development-guardrails.md` - `docs/refactor/content-import-contract.md` - `docs/refactor/object-storage.md` - `docs/refactor/project-structure.md` diff --git a/docs/refactor/README.md b/docs/refactor/README.md index d85419f5..bc0e2c32 100644 --- a/docs/refactor/README.md +++ b/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 前端前的后端进度同步、缺口清单和接入路线图。 diff --git a/docs/refactor/ai-development-guardrails.md b/docs/refactor/ai-development-guardrails.md new file mode 100644 index 00000000..30323ba6 --- /dev/null +++ b/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` + +如果需求与这些文档冲突，先更新架构文档并说明原因，再改代码。 + diff --git a/docs/refactor/api-structure.md b/docs/refactor/api-structure.md index c5b7c633..a90bd0b5 100644 --- a/docs/refactor/api-structure.md +++ b/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 和其它内容类型应接入同一管线。 diff --git a/docs/refactor/architecture.md b/docs/refactor/architecture.md index b8f61dad..27564999 100644 --- a/docs/refactor/architecture.md +++ b/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，不单独维护另一套后端逻辑。 diff --git a/docs/refactor/frontend-handoff-index.md b/docs/refactor/frontend-handoff-index.md index e53c5578..baa71585 100644 --- a/docs/refactor/frontend-handoff-index.md +++ b/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 还未完成。 diff --git a/docs/refactor/supabase-frontend-access-strategy.md b/docs/refactor/supabase-frontend-access-strategy.md index 8c034337..74a68de9 100644 --- a/docs/refactor/supabase-frontend-access-strategy.md +++ b/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 ` | -| 低风险公开只读数据 | 可选 | 仅限 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 ## 对后续 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。 diff --git a/docs/refactor/taro-frontend-integration.md b/docs/refactor/taro-frontend-integration.md index 6e5b89bb..125bd2b2 100644 --- a/docs/refactor/taro-frontend-integration.md +++ b/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 的范围：