diff --git a/CHANGELOG.md b/CHANGELOG.md index 9ee66cb9..6587c4cf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,11 @@ Versions follow [Semantic Versioning](https://semver.org/). ## [Unreleased] +### Added (SaaS migration, plan Steps 3–4) + +- **Supabase foundation** — local stack (`supabase/config.toml`), migrations (schemas `private` / `audit`, `profiles`, platform roles with audited RPCs), pgTAP suite run on PGlite (`pnpm test:run`) and on the real stack (`pnpm db:test`), `@faunosteo/supabase` typed client + generated types. No UI change. +- **Anatomical sheet model** — `@faunosteo/domain`: canonical sheet document (views tree, annotations with stable ids and explicit laterality, ordered vertebral regions, typed finding categories, explicit annotation → finding zone links, FR/EN labels) with integrity validation; tables `species`, `anatomical_sheets`, `anatomical_sheet_versions` (published rows immutable, one draft per sheet, deletion preconditions), `anatomical_sheet_assets`; lifecycle RPCs (create, draft, publish, deprecate, delete, fork with provenance, archive, assets) audited and under RLS. Spec: `docs/development/ANATOMICAL_SHEET_MODEL.md`. + ### Changed (SaaS migration, plan Step 2) - **pnpm workspace** — the application moved to `apps/app` (`@faunosteo/app`) with `git mv`; root commands (`pnpm typecheck|test:run|lint|build|dev`) delegate to the packages. `packages/` reserved, empty. CI workflow added (`.gitea/workflows/ci.yml`). diff --git a/CLAUDE.md b/CLAUDE.md index a00b3656..af91cb4e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -13,7 +13,9 @@ writes conclusion, and exports an A4 PDF. PDF carries the full JSON state as a n attachment so importing it restores the session for a follow-up. 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). +audit log exist; Step 4 added the canonical anatomical sheet model (`packages/domain`, +tables `species`, `anatomical_sheets` / `_versions` / `_assets`). The UI does not use +the client yet (local-only flows unchanged). MVP species: equine only. Open-source MIT. --- @@ -43,8 +45,9 @@ MVP species: equine only. Open-source MIT. ## Build commands -pnpm workspace: `apps/app` = the private application, `packages/supabase` = -Supabase access layer (see `docs/development/WORKSPACE.md`). Every command +pnpm workspace: `apps/app` = the private application, `packages/domain` = pure +Zod domain model (anatomical sheet document), `packages/supabase` = Supabase +access layer (see `docs/development/WORKSPACE.md`). Every command below runs from the repository root and delegates to the packages. ```bash @@ -192,12 +195,15 @@ faunosteo/ ├─ eslint.config.js, index.html, package.json (@faunosteo/app) ├─ tsconfig*.json, vite.config.ts, vitest.config.ts │ (end of apps/app) +├─ packages/domain/ ← @faunosteo/domain (pure, no DOM, zod only) +│ ├─ src/anatomical-sheet/{schema,validate,create}.ts ← canonical sheet document + integrity rules +│ └─ tests/{fixtures/horse-slice.ts,*.test.ts} ├─ 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 +│ ├─ src/{index,client,database.types,anatomical-sheets}.ts ← typed client, generated types, publish gate +│ └─ tests/{client,anatomical-sheets}.test.ts, tests/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 +│ ├─ migrations/*.sql ← forward-only; foundation, profiles, platform_roles, anatomical_sheets │ └─ 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 @@ -320,6 +326,16 @@ Database (Supabase) - 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. +- pgTAP files run on PGlite and on the real image: scope counts to fixture ids, pin `collate "C"` on text ordering. + +### Anatomical sheet model (packages/domain + migration 20261008110000) +- `docs/development/ANATOMICAL_SHEET_MODEL.md` is the source of truth: document shape, issue codes, tables, RPCs. +- Ids are stable slugs never derived from labels; labels are `{ fr, en }` objects. Annotation → findings is the + explicit `finding_zone_id`; vertebral regions are ordered data with free codes. No label matching at runtime. +- A published version is immutable (trigger, every role). Change = new draft (`create_sheet_draft`) then + `publish_sheet_version`. Integrity rule codes are shared by `validateSheetDocument` (TS) and + `private.sheet_document_issues` (SQL); add a rule on both sides and in the spec table. +- Document schema change → bump `SHEET_DOCUMENT_SCHEMA_VERSION`, extend the SQL CHECK on `document_schema_version`. ### Component stubs - Scaffold stubs render
ComponentName placeholder
diff --git a/README.md b/README.md index 835cddb9..9a196ae2 100644 --- a/README.md +++ b/README.md @@ -129,6 +129,7 @@ faunosteo/ pnpm workspace (see docs/development/WORKSPACE.md) ├─ src/lib/ id, dates, assert utilities ├─ src/styles/ Tailwind v4 CSS + design tokens ├─ tests/unit/ vitest tests (apps/app/tests, incl. characterisation suite) +├─ packages/domain/ @faunosteo/domain: canonical anatomical sheet document (Zod) + integrity rules ├─ packages/supabase/ @faunosteo/supabase: typed client, generated types, PGlite SQL test harness ├─ supabase/ CLI config, SQL migrations, local seed, pgTAP tests ├─ docker/ entrypoint.sh + nginx.conf diff --git a/docs/development/IMPLEMENTATION_PLAN.md b/docs/development/IMPLEMENTATION_PLAN.md index fcea9907..9e8a62e8 100644 --- a/docs/development/IMPLEMENTATION_PLAN.md +++ b/docs/development/IMPLEMENTATION_PLAN.md @@ -138,6 +138,12 @@ Tests: importer reproduces the Step 1 mapping table exactly; every audit 07 spec Manual validation: open IMPORT-REPORT.md: 27 annotations, 26 mapped, 1 detail trigger, 5 spine zones with region codes C/T/L/S/Cd, 9 bilateral, 2 views; diff document.json against docs/faunosteo-audit/anatomical-sheet-example.json for sanity. Definition of Done: seed document committed; packages/domain and packages/anatomy have no DOM import outside anatomy/dom/*; no runtime code imports zoneMatch outside legacy/. Risks: subtle divergences between parser and importer on the detail trigger (no name, category kept); Horse_head.svg id space overlaps if a future file reuses ids (mitigated by per-view id scoping in the importer). + Adjustment 2026-10-08 (user brief for Step 4): the step is split. Step 4 = model, validation, + persistence foundations and tests (packages/domain, migration 20261008110000_anatomical_sheets, + pgTAP 005, docs/development/ANATOMICAL_SHEET_MODEL.md). Step 4b = legacy importer producing the + official equine sheet as a DRAFT with an import report, published only after business review. + packages/anatomy is created at Step 4b. Labels use `{ fr, en }` objects, annotation→findings is + `finding_zone_id`, finding categories carry a `kind`; see the spec for the final field names. ``` ```text diff --git a/docs/development/SUPABASE.md b/docs/development/SUPABASE.md index ae9b6312..29ab6bdb 100644 --- a/docs/development/SUPABASE.md +++ b/docs/development/SUPABASE.md @@ -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, _.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 diff --git a/docs/development/WORKSPACE.md b/docs/development/WORKSPACE.md index 0d2e68a3..7a17f3f3 100644 --- a/docs/development/WORKSPACE.md +++ b/docs/development/WORKSPACE.md @@ -13,6 +13,7 @@ faunosteo/ │ ├─ src/ public/ tests/ scripts/ index.html │ ├─ vite.config.ts vitest.config.ts tsconfig*.json eslint.config.js │ └─ package.json app dependencies and scripts +├─ packages/domain/ @faunosteo/domain: canonical anatomical sheet document (Zod) + integrity rules ├─ packages/supabase/ @faunosteo/supabase: typed client, generated types, PGlite SQL tests ├─ supabase/ Supabase CLI config, migrations, seed, pgTAP tests (docs/development/SUPABASE.md) ├─ docker/ nginx.conf, entrypoint.sh (unchanged) diff --git a/packages/README.md b/packages/README.md index e03e1ceb..7055acc2 100644 --- a/packages/README.md +++ b/packages/README.md @@ -8,11 +8,11 @@ Planned packages and the step that creates each one: | Package | Content | Created at | |---|---|---| -| `@faunosteo/domain` | Zod schemas: report document, anatomical sheet document, species, entitlement capabilities | Step 4 (sheet model) | -| `@faunosteo/anatomy` | SVG convention parser, legacy importer, renderer helpers, spine logic | Step 4 | +| `@faunosteo/domain` | Zod schemas: anatomical sheet document + integrity rules (**created**, Step 4); report document, entitlement capabilities later | Step 4 (sheet model) | +| `@faunosteo/anatomy` | SVG convention parser, legacy importer, renderer helpers, spine logic | Step 4b (importer) | | `@faunosteo/pdf` | export / import / attachment, render helpers | Step 6 (PDF v3) | | `@faunosteo/i18n` | FR/EN dictionaries (no React) + `useT` | first second consumer (public-web or worker) | -| `@faunosteo/supabase` | browser client factory, generated database types, PGlite harness running the pgTAP suite | **created**, Step 3 | +| `@faunosteo/supabase` | browser client factory, generated database types, PGlite harness running the pgTAP suite, sheet publish gate | **created**, Step 3 | | `@faunosteo/config` | runtime config resolution shared by app, public-web, worker | with public-web | | `@faunosteo/ui` | UI primitives and design tokens | only when public-web reuses them |