# 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.