gongxue-base/docs/refactor/README.md

# SaaS 重构工作区

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

当前阶段目标：

- 新 Supabase/PostgreSQL 多租户后端继续支撑 Taro H5/小程序、租户后台和平台后台全面联调。
- 使用真实 PocketBase 导出数据反复演练导入、抽样和容量压测。
- 上云前补齐生产 provider、对象存储安全、Auth/RLS、备份恢复、日志告警和上线证据门禁。
- 旧 PocketBase/React 项目只作为功能、样式和迁移参考，不再作为新项目源码入口。

关键文件：

- `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`、`docker-compose.api.benchmark.yml`、`apps/api/Dockerfile`：本地 Docker API 和受限资源压测入口。
- `scripts/deploy/README.md`：云服务器部署 runbook，覆盖 `tjszsb.com` 六域名规划、服务器目录、Gitea 安全部署、Nginx、systemd 和更新脚本。
- `scripts/deploy/bin/deploy.sh`：服务器端发布脚本模板，负责拉取 Gitea、构建 API/worker/Taro H5、发布静态文件和重启服务；真实密钥只从 `/etc/tiku-saas/*.env` 读取。
- `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 阶梯并发矩阵、Docker 受限资源预演和报告归档方式。
- `docs/refactor/performance-benchmark-summary-20260630.md`：真实迁移数据压测脱敏摘要。
- `docs/refactor/backend-open-items-and-capacity-20260701.md`：后端剩余功能、已定稿产品口径和最新在线容量估算。
- `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`、`docs/refactor/production-launch-evidence.template.json` 执行生产配置、Auth/JWKS、RLS、备份恢复和上线证据门禁。
2. 继续按 `docs/refactor/pocketbase-real-data-migration-runbook.md` 处理真实旧数据人工复核项；当前重点是已支付缺用户订单和缺所属手册章节。
3. 在目标 4 核 16G 云服务器按 `docs/refactor/postgresql-4c16g-tuning.md` 调参，再按 `docs/refactor/performance-benchmark-runbook.md` 复跑只读和混合读写压测。
4. 接真实短信、微信/QQ 登录、微信支付/支付宝、对象存储 AV/内容安全、CDN 防盗链和支付账单抽样验收。
5. Taro 继续补小程序真机、公式图片混排、状态管理、包体优化、前端端到端测试和租户/平台后台体验细节。学生头像上传不做，排行榜默认不启用。