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

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

npm install
npm run supabase:start
npm run supabase:reset
npm run db:smoke-seed
npm run dev:api

Default local database:

postgresql://postgres:postgres@127.0.0.1:54322/postgres

API defaults to:

http://127.0.0.1:8787

Verification

Run the full backend reconstruction check:

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:

npm run check:api
npm run check:importer
npm run pb:import:validate
npm run test:api

API Modules

Current API feature folders:

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:

npm run supabase:reset
npm run check:refactor

Result: passed.