feat: scaffold supabase multi-tenant backend

docs/refactor/architecture.md

@@ -0,0 +1,97 @@
+# 重构工程结构
+
+新系统按 SaaS 商用架构组织，不再把 PocketBase 旧项目作为长期主结构。旧 React/PocketBase 代码先保留为兼容层，新的后端、数据库、导入器和共享包独立放置。
+
+## 目录边界
+
+```text
+apps/
+  api/                    新业务 API，前端和小程序都通过它访问业务数据
+    src/core/             配置、HTTP、错误响应、路由注册、数据库访问等基础层
+    src/features/         领域模块，按 catalog、tenant、health 等拆分
+    src/features/platform-admin/
+                            平台方管理合作商租户、订阅、账单和使用量
+
+packages/
+  config/                 环境变量、默认租户、默认数据库连接等共享配置
+  db/                     PostgreSQL 连接池和 query/queryOne
+  domain/                 租户角色、订单状态、权益范围等领域常量
+
+supabase/
+  config.toml             本地 Supabase 配置
+  migrations/             PostgreSQL schema、RLS、触发器、索引
+  seed.sql                本地主租户 seed
+
+scripts/
+  import-pocketbase/      PocketBase schema 风险分析、JSON 导入、导入后校验
+  smoke-seed.js           本地 reset 后的最小业务烟测数据
+
+src/
+  services/supabaseApi.ts 旧 Web 前端迁向新 API 的兼容客户端
+  tenant.config.ts        租户解析配置，优先读新 API
+```
+
+## 设计原则
+
+- `apps/api` 是业务 API 层，复杂交易、支付、权益、租户解析都应该在这里做，不让前端直接操作表。
+- 平台方与合作商之间的 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` 或统一错误响应，生产环境不向前端泄露数据库异常和内部栈信息。
+- `packages/*` 放可复用基础能力，后续 Taro 小程序、管理后台 API、异步 worker 都复用这里。
+- `supabase/migrations` 是数据库事实来源，旧 PB 字段不能绕过迁移规范直接进正式表。
+- `scripts/import-pocketbase` 是一次性和可重复迁移工具，必须保持幂等，导入后必须跑验证。
+- `src/services/pocketbase.ts` 和 `src/services/mockBackend.ts` 属于旧兼容层，后续按页面逐步替换到 `src/services/supabaseApi.ts`。
+
+## 本地开发顺序
+
+```bash
+npm run supabase:start
+npm run supabase:reset
+npm run db:smoke-seed
+npm run dev:api
+```
+
+也可以只把 API 放进 Docker 容器运行。Supabase 仍由 Supabase CLI 管理，API 容器通过宿主机端口连接本地 PostgreSQL：
+
+```bash
+npm run supabase:start
+npm run docker:api:build
+npm run docker:api:up
+```
+
+如果 Docker 拉取 `node:20-alpine` 超时，先配置 Docker Desktop 镜像源或代理，再重试 `npm run docker:api:build`。
+
+验证 API：
+
+```bash
+curl http://127.0.0.1:8787/health
+curl "http://127.0.0.1:8787/api/tenant/resolve?host=localhost"
+curl "http://127.0.0.1:8787/api/catalog/regions?tenantId=00000000-0000-0000-0000-000000000001"
+```
+
+导入旧数据：
+
+```bash
+npm run pb:import:json
+npm run pb:import:validate
+```
+
+## 当前已验证
+
+- Docker Desktop 可用。
+- Supabase 本地容器可启动。
+- `supabase db reset` 可完整执行三份 migration 和 seed。
+- `supabase db reset` 可完整执行全部 migration 和 seed。
+- `npm run db:smoke-seed` 可恢复最小业务烟测数据。
+- `platform-admin` 可完成平台概览、租户创建、订阅、账单生成、人工收款确认、使用量记录。
+- API `/health` 可连 PostgreSQL 并返回 `db: ok`。
+- API `/api/tenant/resolve?host=localhost` 可解析主租户。
+- API 构建产物入口 `apps/api/dist/apps/api/src/server.js` 已验证可启动。
+- 空库执行 `pb:import:validate` 为 0 failures、0 warnings。
+
+## 下一阶段拆分
+
+- `apps/api/src/features` 继续按业务域扩展：真实支付 provider、真实 OAuth provider、平台审计和 worker。
+- `src/services/supabaseApi.ts` 逐页替换旧 PB 只读接口，优先学生端和小程序共用页面。
+- 新增 `apps/worker` 承接 CRM webhook、支付补偿、日报统计、导入后异步检查。
+- 新增 `apps/taro` 后，所有租户解析和公开业务读取都复用 API，不单独维护另一套后端逻辑。