docs(docs): SUPABASE.md runbook + CLAUDE/README/DEPLOY/WORKSPACE updated for the Supabase foundation
This commit is contained in:
1 parent
5511a2158a
commit
1dd45a3109
7 files changed
+267
-26
No files matched your search
@@ -11,7 +11,9 @@ Single-praticien French web app for veterinary osteopathy bilans on animal anato
|
||||
Practitioner clicks anatomical zones, builds observations with pathologies/severity,
|
||||
writes conclusion, and exports an A4 PDF. PDF carries the full JSON state as a native
|
||||
attachment so importing it restores the session for a follow-up.
|
||||
Static SPA, no backend, no auth. Deployed via Docker + nginx on Scaleway VPS.
|
||||
SPA deployed via Docker + nginx on Scaleway VPS. Backend foundation on Supabase
|
||||
(PostgreSQL + Auth + RLS) since Step 3 of the SaaS plan: profiles, platform roles and
|
||||
audit log exist; the UI does not use the client yet (local-only flows unchanged).
|
||||
MVP species: equine only. Open-source MIT.
|
||||
|
||||
---
|
||||
@@ -32,15 +34,18 @@ MVP species: equine only. Open-source MIT.
|
||||
| SVG raster | native Image/canvas (no dependency) | — |
|
||||
| Animation | motion | 11 |
|
||||
| Tests | vitest + happy-dom + @testing-library/react | 3.x |
|
||||
| Backend | Supabase (PostgreSQL 17, GoTrue, PostgREST) — CLI pinned as root devDependency | CLI 2.120 |
|
||||
| DB client | @supabase/supabase-js (packages/supabase) | 2.x |
|
||||
| SQL tests | pgTAP under supabase/tests, run by `supabase test db` and by PGlite (Dockerless) | PGlite 0.3 |
|
||||
| Deploy | Docker multi-stage → nginx:alpine | — |
|
||||
|
||||
---
|
||||
|
||||
## Build commands
|
||||
|
||||
pnpm workspace: `apps/app` = the private application, `packages/` empty for
|
||||
now (see `docs/development/WORKSPACE.md`). Every command below runs from the
|
||||
repository root and delegates to the packages.
|
||||
pnpm workspace: `apps/app` = the private application, `packages/supabase` =
|
||||
Supabase access layer (see `docs/development/WORKSPACE.md`). Every command
|
||||
below runs from the repository root and delegates to the packages.
|
||||
|
||||
```bash
|
||||
# Development
|
||||
@@ -66,6 +71,13 @@ pnpm lint
|
||||
|
||||
# Format
|
||||
pnpm format
|
||||
|
||||
# Supabase local stack (Docker) — docs/development/SUPABASE.md
|
||||
pnpm db:start # start stack, apply migrations + seed
|
||||
pnpm db:reset # replay from zero
|
||||
pnpm db:test # pgTAP on the real stack
|
||||
pnpm db:types # regenerate packages/supabase/src/database.types.ts
|
||||
pnpm db:types:check # CI diff
|
||||
```
|
||||
|
||||
## Docker commands
|
||||
@@ -96,6 +108,8 @@ pnpm test # vitest watch — dev loop
|
||||
Test files live in `apps/app/tests/unit/*.test.ts(x)`; golden fixtures in
|
||||
`apps/app/tests/fixtures/`. Setup: `apps/app/tests/setup.ts` imports
|
||||
@testing-library/jest-dom. Characterisation suite: files prefixed `char.`.
|
||||
SQL: `supabase/tests/*.sql` (pgTAP) run by `packages/supabase/tests/db/pgtap.test.ts`
|
||||
on PGlite (part of `pnpm test:run`) and by `pnpm db:test` on the real stack.
|
||||
|
||||
---
|
||||
|
||||
@@ -159,7 +173,7 @@ faunosteo/
|
||||
│ ├─ pdf/
|
||||
│ │ ├─ export.ts + import.ts + attachment.ts + fonts.ts
|
||||
│ │ └─ render/{header,footer,observationPage,conclusionPage,svgToPng,text,logo,linkAnnotation}.ts
|
||||
│ ├─ lib/{dates,id,assert,zoneMatch,spineZones}.ts
|
||||
│ ├─ lib/{dates,id,assert,zoneMatch,spineZones,supabase}.ts ← supabase.ts: getSupabaseClient() | null
|
||||
│ ├─ styles/{index,tokens,svg-editor}.css ← Tailwind v4 CSS-first + SVG editor styles
|
||||
│ └─ main.tsx
|
||||
├─ tests/
|
||||
@@ -178,7 +192,14 @@ faunosteo/
|
||||
├─ eslint.config.js, index.html, package.json (@faunosteo/app)
|
||||
├─ tsconfig*.json, vite.config.ts, vitest.config.ts
|
||||
│ (end of apps/app)
|
||||
├─ packages/README.md ← future shared packages (none yet)
|
||||
├─ packages/supabase/ ← @faunosteo/supabase
|
||||
│ ├─ src/{index,client,database.types}.ts ← typed browser client + generated types
|
||||
│ └─ tests/{client.test.ts,db/} ← PGlite harness, shim, pgTAP runner, schema↔types test
|
||||
├─ supabase/
|
||||
│ ├─ config.toml, seed.sql ← CLI config (public schema only), local dev accounts
|
||||
│ ├─ migrations/*.sql ← forward-only; foundation, profiles, platform_roles
|
||||
│ └─ tests/*.sql ← pgTAP: allowed + denied paths per policy
|
||||
├─ packages/README.md ← shared packages index
|
||||
├─ .gitea/workflows/ci.yml ← CI: install, typecheck, test, lint, build, docker
|
||||
├─ .claude/{tasks/TODO.md,memory/,audits/}
|
||||
├─ Dockerfile, docker-compose.yml, docker/
|
||||
@@ -224,6 +245,14 @@ Runtime config
|
||||
→ index.html loads env.js before bundle
|
||||
→ src/config/env.ts reads window.__APP_CONFIG__ → VITE_APP_* → defaults
|
||||
→ ConfigProvider exposes via React context
|
||||
→ appConfig.supabase (url + anon key) or null → lib/supabase.ts lazy client
|
||||
|
||||
Database (Supabase)
|
||||
→ schemas: public (exposed, RLS on every table) / private (helpers, triggers) / audit (append-only)
|
||||
→ auth.users insert → private.handle_new_auth_user() → public.profiles row
|
||||
→ platform roles: public.profile_roles written only by grant_platform_role / revoke_platform_role
|
||||
(security definer, actor checked via private.is_platform_*; every call logged by private.log_event)
|
||||
→ tests: supabase/tests/*.sql (pgTAP) via PGlite in CI check job and `supabase test db`
|
||||
```
|
||||
|
||||
---
|
||||
@@ -278,6 +307,20 @@ Runtime config
|
||||
- boneIds: [] = all zones; speciesIds: [] = all species
|
||||
- Source types: manual | journal | database | web
|
||||
|
||||
### Database (Supabase)
|
||||
- Platform roles (`platform_role`: owner/admin/moderator/support) are NOT professional
|
||||
statuses (practitioner/student/professor come from verification, cabinet roles from
|
||||
organization_members). Never add a professional status to `platform_role`.
|
||||
- Every `public` table: RLS enabled, `revoke all` from API roles then exact grants,
|
||||
separate policies per command, no `using (true)` for anon/authenticated (test-enforced).
|
||||
- Writes that change privileges or sensitive state go through a security-definer RPC
|
||||
that checks `auth.uid()` and calls `private.log_event()`. Never a direct table policy.
|
||||
- Helpers in `private` are `security definer`, `set search_path = ''`, EXECUTE revoked
|
||||
from public and granted only to the roles that evaluate them.
|
||||
- A migration is never edited once applied. Each migration ships its pgTAP file with
|
||||
allowed AND denied cases, and a regenerated `database.types.ts`.
|
||||
- The browser holds the anon key only. `service_role` never appears in env.js, .env.example or code.
|
||||
|
||||
### Component stubs
|
||||
- Scaffold stubs render <div>ComponentName placeholder</div>
|
||||
- Replace stub body entirely when implementing — no partial edits on stubs
|
||||
@@ -288,7 +331,8 @@ Runtime config
|
||||
|
||||
- **React SPA**: explicit exception — this is a practitioner tool, not a public website.
|
||||
No indexing needed. SPA is correct. (See BDR-001)
|
||||
- **No API versioning**: no backend, no API routes. Section N/A.
|
||||
- **No API versioning**: no hand-written HTTP API. Supabase exposes tables/RPC through
|
||||
PostgREST; breaking changes are handled by new migrations and RPC names, not URL versions.
|
||||
- **80-char line limit**: relaxed to 100 for TypeScript generics and long Zod chains.
|
||||
|
||||
---
|
||||
@@ -313,6 +357,9 @@ Runtime config
|
||||
| @testing-library/react | Component testing utilities |
|
||||
| @testing-library/jest-dom | Custom DOM matchers |
|
||||
| eslint 9 | Linting (flat config) |
|
||||
| @supabase/supabase-js 2 | Typed client (packages/supabase) |
|
||||
| supabase (CLI) 2.120 | Local stack, migrations, pgTAP runner, type generation |
|
||||
| @electric-sql/pglite 0.3 | PostgreSQL 17 in WASM: runs the pgTAP suite without Docker |
|
||||
| prettier 3 | Code formatting |
|
||||
|
||||
---
|
||||
@@ -327,11 +374,13 @@ Runtime config
|
||||
- Ask before any change to importReportFromPdf or extractReportJson — these handle user data.
|
||||
- After PDF roundtrip tests fail: check attachment bytes, then Zod validation, then DecompressionStream inflation.
|
||||
- Node 24 / pnpm 10.13.1: `corepack enable` or `corepack pnpm`; never a global install.
|
||||
- SQL change: `pnpm --filter @faunosteo/supabase test:run` (PGlite) before commit; `pnpm db:reset && pnpm db:test`
|
||||
on the real stack when Docker is available; regenerate types (`pnpm db:types`).
|
||||
|
||||
## Commit message convention
|
||||
|
||||
Conventional Commits format. Subject ≤72 chars, imperative mood, no trailing period.
|
||||
Allowed scopes: `schema`, `store`, `anatomy`, `pdf`, `editor`, `home`, `new`, `ui`, `config`, `species`, `i18n`, `docker`, `docs`, `tests`, `chore`, `app`, `workspace`, `ci`.
|
||||
Allowed scopes: `schema`, `store`, `anatomy`, `pdf`, `editor`, `home`, `new`, `ui`, `config`, `species`, `i18n`, `docker`, `docs`, `tests`, `chore`, `app`, `workspace`, `ci`, `supabase`, `domain`, `worker`, `public-web`.
|
||||
|
||||
Examples:
|
||||
- `test(schema): cover Report version literal`
|
||||
|
||||
Reference in new issue
Block a user