feat: scaffold supabase multi-tenant backend

2026-06-21 21:54:43 +08:00
commit c9c767c7bd
99 changed files with 36660 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,154 @@
+# tiku-supabase
+
+PocketBase/SQLite question-bank product rebuilt as a Supabase/PostgreSQL multi-tenant SaaS backend.
+
+This repository is the new reconstruction workspace for the commercial SaaS version. The old PocketBase/React project remains as the migration reference in the original workspace, but this Git repository should focus on the new backend, database schema, importer, and delivery documentation.
+
+## Current Status
+
+Updated: 2026-06-21
+
+Implemented and locally verified:
+
+- Supabase/PostgreSQL multi-tenant schema, RLS policies, indexes, and triggers.
+- Node.js business API under `apps/api`, shared by future H5, Taro mini program, and admin clients.
+- Tenant admin APIs for branding, domain, settings, payment accounts, login providers, secrets, marketing content, activation codes, coupons, members, permissions, and audit logs.
+- Tenant content APIs for questions, videos, scorelines, vocabulary, handbook content, content assets, and question JSON import.
+- Student APIs for catalog, practice sessions, answers, wrong questions, favorites, vocabulary progress, profile, scorelines, question videos, orders, entitlements, activation-code redemption, and content asset download.
+- Platform admin APIs for tenants, SaaS plans, subscriptions, invoices, payments, usage records, and billing profiles.
+- Referral/CRM growth APIs for invite codes, first-binding lead protection, sales/agent teams, CRM config, and CRM queue.
+- PocketBase schema/data importer scaffold with validation.
+- Local Supabase reset, smoke seed, API integration tests, and refactor check command.
+
+Still not production complete:
+
+- Supabase Auth/JWT and full production RLS validation must replace migration-period headers.
+- Real SMS/OAuth/payment provider adapters are still pending.
+- Real OSS/COS/Supabase Storage signed upload/download adapters are still pending.
+- Excel/CSV import, vocabulary/handbook/scoreline/video import, and async import worker are pending.
+- Taro frontend scaffold is pending.
+
+See:
+
+- `docs/refactor/implementation-status.md`
+- `docs/refactor/backend-progress.md`
+- `docs/refactor/blueprint-coverage.md`
+- `docs/refactor/api-structure.md`
+
+## Repository Layout
+
+```text
+apps/api/                   Node.js business API
+packages/config/            Shared config defaults
+packages/db/                PostgreSQL pool/query helpers
+packages/domain/            Domain constants and shared types
+supabase/migrations/        PostgreSQL schema, RLS, indexes, triggers
+supabase/seed.sql           Minimal tenant seed
+scripts/import-pocketbase/  PocketBase schema/data importer and validator
+scripts/smoke-seed.js       Local integration-test seed data
+scripts/api-integration-test.js
+docs/refactor/              Reconstruction architecture and progress docs
+docker-compose.api.yml      API container compose file
+```
+
+## Local Development
+
+Prerequisites:
+
+- Node.js 20+
+- Docker Desktop
+- Supabase CLI
+
+```bash
+npm install
+npm run supabase:start
+npm run supabase:reset
+npm run db:smoke-seed
+npm run dev:api
+```
+
+Default local database:
+
+```text
+postgresql://postgres:postgres@127.0.0.1:54322/postgres
+```
+
+API defaults to:
+
+```text
+http://127.0.0.1:8787
+```
+
+## Verification
+
+Run the full backend reconstruction check:
+
+```bash
+npm run check:refactor
+```
+
+This runs:
+
+- API TypeScript check
+- PocketBase importer TypeScript check
+- PocketBase import validation
+- smoke seed
+- API build
+- local API integration test
+
+Useful individual commands:
+
+```bash
+npm run check:api
+npm run check:importer
+npm run pb:import:validate
+npm run test:api
+```
+
+## API Modules
+
+Current API feature folders:
+
+```text
+apps/api/src/features/
+  auth/
+  catalog/
+  commerce/
+  health/
+  learning/
+  platform-admin/
+  profile/
+  referral/
+  scoreline/
+  tenant/
+  tenant-admin/
+  tenant-content/
+  video/
+```
+
+Migration-period API context:
+
+- `x-tenant-id`
+- `x-user-id`
+- `x-platform-admin-key`
+
+Production must replace these with Supabase Auth/JWT/server-side sessions.
+
+## Security Notes
+
+- Tenant public payment/login config must not contain secrets.
+- Secrets go to `app_private.tenant_secrets` or future production KMS/Vault.
+- Asset download must go through API authorization and signed URL generation.
+- Content import must write job/item/issue records before final import.
+- Payment webhooks must be idempotent before production use.
+
+## Latest Verified Check
+
+Last local verification:
+
+```text
+npm run supabase:reset
+npm run check:refactor
+```
+
+Result: passed.