docs(docs): Step 4 sheet model in CLAUDE.md, SUPABASE.md, WORKSPACE, README, plan note, changelog

This commit is contained in:
bchanot committed 2026-10-08 23:45:01 +02:00
1 parent 8cac8b1a68
commit 6966c54a2e
7 files changed
+51 -13

No files matched your search

+13 -4
View File
@@ -1,7 +1,8 @@
# Supabase: local stack, migrations, tests
Status: Step 3 deliverable, 2026-10-08. Covers the foundation only (profiles,
platform roles, audit log). Conventions: `BACKEND_ARCHITECTURE.md` §3–§9.
Status: Step 3 deliverable, extended at Step 4 (2026-10-08). Covers the
foundation (profiles, platform roles, audit log) and the anatomical sheet
tables (`ANATOMICAL_SHEET_MODEL.md`). Conventions: `BACKEND_ARCHITECTURE.md` §3–§9.
## 1. Layout
@@ -11,13 +12,17 @@ supabase/
├─ migrations/ forward-only SQL, <timestamp>_<name>.sql
│ ├─ 20261008100000_foundation.sql schemas private/audit, updated_at, audit log
│ ├─ 20261008100100_profiles.sql profiles + auth.users trigger + RLS
│ └─ 20261008100200_platform_roles.sql platform_role, profile_roles, helpers, RPCs
│ ├─ 20261008100200_platform_roles.sql platform_role, profile_roles, helpers, RPCs
│ └─ 20261008110000_anatomical_sheets.sql species, sheets, immutable versions, assets, lifecycle RPCs
├─ seed.sql LOCAL dev accounts + first owner (never run in prod)
└─ tests/ pgTAP, one file per concern, allowed AND denied paths
packages/supabase/
├─ src/client.ts createBrowserClient() (anon key, PKCE)
├─ src/database.types.ts `supabase gen types` output
├─ src/anatomical-sheets.ts publishSheetVersion(): Zod + integrity gate before the RPC
└─ tests/db/ PGlite harness: runs the pgTAP files without Docker
packages/domain/
└─ src/anatomical-sheet/ canonical sheet document (Zod), validateSheetDocument, createEmptySheetDocument
```
## 2. Prerequisites
@@ -89,7 +94,7 @@ Two runners, one SQL source of truth (`supabase/tests/*.sql`, pgTAP):
| Command | Engine | Needs Docker | What runs |
|---|---|---|---|
| `pnpm --filter @faunosteo/supabase test:run` | PGlite (PostgreSQL 17 in WASM) | no | shim of the Supabase base schema + all migrations + every pgTAP file; schema ↔ types check; client factory |
| `pnpm --filter @faunosteo/supabase test:run` | PGlite (PostgreSQL 17 in WASM) | no | shim of the Supabase base schema + all migrations + every pgTAP file; schema ↔ types check; client factory; publish gate |
| `pnpm db:test` | `supabase test db` (pg_prove in the local stack) | yes | the same pgTAP files against the real Supabase image |
`pnpm test:run` at the root runs the PGlite suite together with the app
@@ -97,6 +102,10 @@ suite. The shim (`packages/supabase/tests/db/supabase-shim.sql`) recreates
the API roles, `auth.users`, `auth.uid()` and the permissive default
privileges of Supabase so that a forgotten `revoke` fails a test.
Two parity traps met so far: counts must be scoped to fixture ids (the real
stack carries `seed.sql` rows), and `order by` on text must pin
`collate "C"` (the real image sorts with a locale collation, PGlite with C).
How a test impersonates a user (same technique in both runners):
```sql