# SaaS 重构工作区

这个目录记录从 PocketBase 单体项目迁移到 Supabase/PostgreSQL + 新 API + Taro 学生端的重构过程。

当前第一阶段目标：

- 本地 Supabase 能启动并创建多租户 PostgreSQL schema。
- 新 API 能连接数据库并解析租户。
- PocketBase 的 `docs/pb_schema.json` 能被解析，后续真实数据导出后可导入到新库。
- 先保留旧 React Web 项目，逐步把学生端和后台接到新 API。

关键文件：

- `supabase/config.toml`：本地 Supabase 配置。
- `supabase/migrations/202606210001_core_multitenant_schema.sql`：第一版商用级多租户 schema。
- `apps/api`：新业务 API 服务，内部按 `src/core` 和 `src/features` 分层。
- `packages/config`、`packages/db`、`packages/domain`：新系统共享基础包。
- `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/frontend-handoff-index.md`：交给前端同事的阅读入口和当前可开工范围。
- `docs/refactor/backend-capability-status.md`：后端已覆盖、迁移期、待补齐能力盘点。
- `docs/refactor/legacy-feature-gap-matrix.md`：对照旧题库功能的新后端差距矩阵。
- `docs/refactor/supabase-frontend-access-strategy.md`：Supabase 官方推荐能力与本项目业务 API 边界。
- `docs/refactor/taro-frontend-integration.md`：Taro/H5/小程序启动、请求封装、页面/API 映射。
- `docs/refactor/taro-h5-deployment.md`：Taro H5 三域名部署、运行时配置、Nginx、CSP、缓存和 CORS 边界。
- `docs/refactor/postgresql-4c16g-tuning.md`：4 核 16G 自托管 PostgreSQL 起步调参、观察 SQL 和回滚方式。
- `docs/refactor/performance-benchmark-runbook.md`：本地/云端 API 压测、4 核 16G 阶梯并发矩阵和报告归档方式。
- `docs/refactor/multitenant-auth-security-contract.md`：多租户隔离、鉴权、权限和资源安全红线。
- `docs/refactor/production-launch-evidence.template.json`：生产上线证据模板；真实证据填入本地 `production-launch-evidence.json` 后运行 `npm run launch:gate`。

下一步优先级：

1. 先按 `docs/refactor/multitenant-auth-security-contract.md` 的 P0 清单补齐鉴权、生产配置和租户隔离测试，并在上云前运行 `npm run readiness:production` / `npm run readiness:production:db`。
2. 新建 `apps/taro`，按 `docs/refactor/taro-frontend-integration.md` 优先接租户解析、首页、题库练习、背单词、知识手册、个人中心。
3. 继续按 `docs/refactor/pocketbase-real-data-migration-runbook.md` 处理真实旧数据人工复核项；当前真实导入已能生成新架构题库入口、分类、合集和练习蓝图。
4. 上云前按 `docs/refactor/postgresql-4c16g-tuning.md` 准备 4 核 16G PostgreSQL 起步参数，再按 `docs/refactor/performance-benchmark-runbook.md` 跑 smoke、30/50 并发和少量写入压测。
5. 接真实短信、微信/QQ 登录、微信支付/支付宝，继续增强 CRM worker 和其它异步任务，进入商用验收。
