feat: scaffold supabase multi-tenant backend

docs/refactor/local-supabase.md

@@ -0,0 +1,127 @@
+# 本地 Supabase 开发环境
+
+## 前置依赖
+
+Supabase 本地开发需要：
+
+- Docker Desktop
+- Supabase CLI
+- Node.js 20+
+
+当前机器如果出现下面错误，说明 Docker Desktop 未启动或 Docker daemon 不可访问：
+
+```text
+failed to inspect container health
+open //./pipe/docker_engine: The system cannot find the file specified
+```
+
+先启动 Docker Desktop，再执行 Supabase 命令。
+
+当前仓库已经加入 `supabase/config.toml` 和第一版 migration。安装依赖后执行：
+
+```bash
+npm run supabase:start
+npm run supabase:status
+```
+
+本地默认端口：
+
+```text
+API:      http://127.0.0.1:54321
+DB:       postgresql://postgres:postgres@127.0.0.1:54322/postgres
+Studio:   http://127.0.0.1:54323
+Inbucket: http://127.0.0.1:54324
+```
+
+重置数据库：
+
+```bash
+npm run supabase:reset
+npm run db:smoke-seed
+```
+
+## API 服务
+
+```bash
+npm run dev:api
+```
+
+健康检查：
+
+```bash
+curl http://127.0.0.1:8787/health
+```
+
+租户解析：
+
+```bash
+curl "http://127.0.0.1:8787/api/tenant/resolve?host=localhost"
+curl "http://127.0.0.1:8787/api/tenant/resolve?tenantCode=master"
+```
+
+公开题库数据接口示例：
+
+```bash
+curl "http://127.0.0.1:8787/api/catalog/regions?tenantId=00000000-0000-0000-0000-000000000001"
+curl "http://127.0.0.1:8787/api/catalog/questions?tenantId=00000000-0000-0000-0000-000000000001&limit=20"
+```
+
+本地短信登录 smoke 可用 mock provider。开发环境接口会返回 `debugCode`：
+
+```bash
+curl -X POST "http://127.0.0.1:8787/api/auth/sms/send" \
+  -H "content-type: application/json" \
+  -H "x-tenant-id: 00000000-0000-0000-0000-000000000001" \
+  -d "{\"phone\":\"13900000001\",\"purpose\":\"login\"}"
+```
+
+平台运营接口迁移期使用 `x-platform-admin-key`。本地默认值来自 `PLATFORM_ADMIN_API_KEY`，未设置时为 `local-platform-admin-key`：
+
+```bash
+curl "http://127.0.0.1:8787/api/platform-admin/overview" \
+  -H "x-platform-admin-key: local-platform-admin-key"
+
+curl "http://127.0.0.1:8787/api/platform-admin/tenants?limit=20" \
+  -H "x-platform-admin-key: local-platform-admin-key"
+```
+
+## Docker 运行 API
+
+本地 Supabase 继续由 Supabase CLI 启动，API 可以单独进入 Docker 容器：
+
+```bash
+npm run supabase:start
+npm run docker:api:build
+npm run docker:api:up
+```
+
+Compose 文件是 `docker-compose.api.yml`。API 容器默认使用：
+
+```text
+DATABASE_URL=postgresql://postgres:postgres@host.docker.internal:54322/postgres
+PORT=8787
+```
+
+如果本机已有非容器 API 占用 `8787`，先关闭旧进程或临时修改 `docker-compose.api.yml` 的端口映射。当前机器 Docker Desktop 可用，Supabase 容器已可运行；若构建 API 镜像时报 Docker Hub 或 ECR 拉取超时，需要先处理 Docker 镜像源或网络代理。
+
+## PocketBase JSON 导入
+
+把 PocketBase 导出的集合 JSON 放到仓库根目录的 `pb_export` 文件夹后执行：
+
+```bash
+npm run pb:import:json
+npm run pb:import:validate
+```
+
+导入真实密钥时必须明确打开开关，且只允许进入 `app_private.tenant_secrets`：
+
+```bash
+set IMPORT_SECRET_VALUES=true
+npm run pb:import:json
+```
+
+上线前 `pb:import:validate` 不能有 `FAIL`。`WARN` 通常代表旧数据缺失关联，需要业务确认后记录处理结论。
+
+## 说明
+
+Supabase Custom Domain 不用于合作商多域名绑定。合作商域名在你们自己的 Web/API 网关层解析，然后从 `tenant_domains` 表得到 `tenant_id`。