# 重构工程结构

新系统按 SaaS 商用架构组织，不再把 PocketBase 旧项目作为长期主结构。旧 React/PocketBase 代码先保留为兼容层，新的后端、数据库、导入器和共享包独立放置。

## 目录边界

```text
apps/
  api/                    业务命令 API，承接复杂事务、第三方 provider、密钥和审计
    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 后的最小业务烟测数据

docs/refactor/
  ai-development-guardrails.md
                            后续 AI/开发者必须遵守的架构和安全守则
```

## 设计原则

- 本项目采用 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` 或统一错误响应，生产环境不向前端泄露数据库异常和内部栈信息。
- `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 -- --confirm=SMOKE_SEED_LOCAL_OR_CI_ONLY
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
```

API Dockerfile 锁定 `node:20.20.2-alpine3.23` 多架构 manifest，最终镜像以 `node` 用户运行，只复制生产依赖和编译产物。若 Docker Hub 超时，先配置受信镜像源/代理并确认拉取到相同 digest，再重试 `npm run docker:api:build`，不要移除 digest 锁定。

本地容量预演可以使用专门的 benchmark override：

```bash
npm run perf:api:docker-4c16g
```

该命令会使用 `docker-compose.api.yml` + `docker-compose.api.benchmark.yml` 启动受限 API 容器，默认限制 API 为 2 CPU/4G、`DB_POOL_MAX=10`，关闭 `ALLOW_LEGACY_AUTH_HEADERS`，并用 Bearer `tk_` 会话跑压测。它只用于本地模拟和跑分，不是生产 compose 文件。

验证 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 本地容器可启动。
- API Dockerfile 已验证可构建；最终镜像约 `53 MB`、生产 `node_modules` 约 `24.3 MB`，不含 TypeScript/tsx，UID 为 `1000(node)`，连接隔离测试库通过 `/health`；benchmark override 可启动受限 API 容器并通过短压测 smoke。
- `supabase db reset` 可完整执行三份 migration 和 seed。
- `supabase db reset` 可完整执行全部 migration 和 seed。
- `npm run db:smoke-seed -- --confirm=SMOKE_SEED_LOCAL_OR_CI_ONLY` 只能在已标记为 `local/test/ci` 的隔离库恢复最小业务烟测数据。
- `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` 继续按业务域扩展：退款对账、真实 OAuth provider、平台审计和更多后台任务。
- `src/services/supabaseApi.ts` 逐页替换旧 PB 只读接口，优先学生端和小程序共用页面。
- 扩展 `apps/worker`：CRM webhook、支付/退款补偿、资源复检、异步导入、公共题库同步和公共题库同步通知已落地；后续继续补日报统计、失败告警和更完整运营台。
- 新增 `apps/taro` 后，Auth/JWT 优先复用 Supabase client；复杂业务命令复用 `apps/api`/RPC/Edge Functions，不单独维护另一套后端逻辑。