From ac60b2426739c728c5943fe6881d81063ec37157 Mon Sep 17 00:00:00 2001 From: bchanot Date: Sun, 25 Oct 2026 17:12:37 +0100 Subject: [PATCH] docs(docs): realign active docs on develop for P0 Roadmap section and step statuses in the plan, D-R9 Rust services in place of Edge Functions and a Node worker, platform roles per BDR-026, equine sheet draft-only, curation-only authoring until Step 17, OPEN_QUESTIONS statuses and conflict resolutions, dated snapshot notices on the Step 0 documents. --- CLAUDE.md | 4 + docs/design/README.md | 5 +- docs/development/ANATOMICAL_SHEET_MODEL.md | 2 +- docs/development/BACKEND_ARCHITECTURE.md | 97 ++++++++------ docs/development/DOMAIN_MAP.md | 23 ++-- docs/development/FRONTEND_ARCHITECTURE.md | 8 ++ docs/development/IMPLEMENTATION_PLAN.md | 127 +++++++++++++------ docs/development/MIGRATION_STRATEGY.md | 6 + docs/development/OPEN_QUESTIONS.md | 60 +++++++++ docs/development/PDF_IMPORT_HARDENING.md | 6 +- docs/development/REPOSITORY_MIGRATION_MAP.md | 5 + docs/development/TEST_STRATEGY.md | 9 ++ 12 files changed, 260 insertions(+), 92 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 3900c68e..4c137f25 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -46,6 +46,10 @@ importer, curation, migration map, review files, seed SQL, upload tool) into the R5.7 deleted `packages/anatomy` and `packages/domain` (`RUST.md` §11.23, test ledger `crates/core/tests/curation/LEDGER.tsv`). MVP species: equine only. Open-source MIT. +Product roadmap (owner, 2026-10-25): P0 docs, then V1-1 clients and animals, V1-2 sheets from Supabase, +V1-3 cloud bilans, V1-4 stored PDF and sharing, V1-5 mobile and accessibility pass +(`docs/development/IMPLEMENTATION_PLAN.md` §0; V1-1 contract `docs/development/V1-1_OWNERS_ANIMALS.md`: +owner orientations proposed, awaiting ratification; nothing built). --- diff --git a/docs/design/README.md b/docs/design/README.md index 51869928..1cce98d6 100644 --- a/docs/design/README.md +++ b/docs/design/README.md @@ -30,7 +30,10 @@ step has built yet, with the step that owns them: | Element | Owner | |---|---| -| Bilans, Clients, Animaux, Agenda, Fiches anatomiques entries and screens | Steps 9 to 16 (clients/animals, cloud reports, agenda) | +| Clients and Animaux entries and screens | roadmap V1-1 (plan Step 12 reduced, `docs/development/V1-1_OWNERS_ANIMALS.md`) | +| Fiches anatomiques entry and screen | roadmap V1-2 (plan Step 13 reduced) | +| Bilans entry and screens | roadmap V1-3 (plan Step 14) | +| Agenda entry and screens | plan Step 20 | | Stat tiles (bilans créés, clients, animaux, rendez-vous) and "Derniers bilans" | once the reports and agenda tables exist; never invented numbers | | Notification bell | notifications step | | Avatar photo and "Modifier la photo" | built in Step 8 (2026-10-13): circle + "Modifier la photo" in Informations personnelles, photo in the sidebar / drawer badge and in the top bar with the name on desktop (link to Mon compte, no dropdown) | diff --git a/docs/development/ANATOMICAL_SHEET_MODEL.md b/docs/development/ANATOMICAL_SHEET_MODEL.md index 00930217..8dcc4730 100644 --- a/docs/development/ANATOMICAL_SHEET_MODEL.md +++ b/docs/development/ANATOMICAL_SHEET_MODEL.md @@ -298,7 +298,7 @@ the decision lands; only the naming one is implemented in this document. | 3 | A new publication becomes the current version; older versions are **not deprecated automatically** and stay readable under the access rules. | Already the behaviour of `publish_sheet_version`; deprecation stays a manual act. | | 4 | Official sheets are **platform-owned**, administered by authorised accounts. | Already the model: `creator_user_id = null`, `is_official = true`, platform admins edit. | | 5 | Name anatomical findings apart from the observations typed during a report. | Finding category kind `observation` renamed **`consultation_reason`** (`dysfunction` / `consultation_reason` / `anamnesis` / `custom`). The report-side object keeps the name Observation. | -| 6 | Server-side validation and integrity for every publication; the frontend is never a security boundary. | SQL already re-checks references, sizes and species. The full shape check (Zod) moves server-side before community publication: plpgsql shape rules or an Edge Function gate, decided at the community step. | +| 6 | Server-side validation and integrity for every publication; the frontend is never a security boundary. | SQL already re-checks references, sizes and species. The full shape check (the Rust core's `sheet.check` since R2) moves server-side before community publication: plpgsql shape rules or a Rust service gate (Edge Functions retired, D-R9), decided at the community step. | | 7 | Account deletion handles dependencies and transfers explicitly (RGPD); no dependency may block the erasure of personal data forever. | Retention step (§16): published versions get their `created_by` / `published_by` anonymised through a dedicated system path (the immutability guard will allow that single transition), personal sheets are transferred or archived, `creator_user_id` keeps `on delete restrict` only as the backstop that forces the explicit path. | ## 6. Official equine sheet: import (Step 4b) and curation (Step 4c) diff --git a/docs/development/BACKEND_ARCHITECTURE.md b/docs/development/BACKEND_ARCHITECTURE.md index e14d931a..8f581756 100644 --- a/docs/development/BACKEND_ARCHITECTURE.md +++ b/docs/development/BACKEND_ARCHITECTURE.md @@ -3,25 +3,32 @@ Status: Step 0 deliverable, 2026-10-08. Conceptual only. No migration, table, policy or function is created by this document. Table and function names follow `faunosteo-business-architecture.md` §4–§20. +Revised 2026-10-25 (P0): Edge Functions retired (D-R9, BDR-045), worker = +`crates/worker` in Rust, data contracts in `crates/core` (R2), bucket list and +signed-URL rule as built at Step 8 (`STORAGE.md`). Hosting stays open +(`OPEN_QUESTIONS.md` Q2). ## 1. Components and what runs where ```text -Browser (apps/app, anon key + user JWT) - │ tables via RLS, RPC (security definer), Storage signed URLs +Browser (apps/app, anon key + user JWT, Rust core as WebAssembly) + │ tables via RLS, RPC (security definer), Storage under storage.objects policies ▼ -Supabase (self-hosted on Scaleway at launch, §31) - ├─ Auth (GoTrue): email/password, Google, Apple, OTP, phone +Supabase (self-hosted on Scaleway at launch, §31; hosting open, Q2) + ├─ Auth (GoTrue): email/password, OAuth providers (Google, Apple), OTP, phone; keeps the OAuth flows (D-R9) ├─ PostgreSQL: schemas public / private / audit, RLS, functions, pg_cron - ├─ Storage: private buckets, storage.objects policies - ├─ Edge Functions (Deno): public endpoints, webhooks, signed-URL issuance - └─ Realtime (optional): report sync state -Worker (apps/worker, service key, same host) - └─ jobs table in PostgreSQL, no Redis -public-web (anon key, SSR) + └─ Storage: private buckets, storage.objects policies evaluated on public.assets +Rust worker (crates/worker, container faunosteo_worker, service key, same host) + └─ jobs claimed from PostgreSQL through RPCs (lease token), no Redis; decode child sandboxed +Rust HTTP services (same image, other subcommands, own secrets; from the first inbound need) + └─ webhooks (Stripe), OAuth callbacks of external calendars, public endpoints that SQL cannot serve +public-web (Astro, D-R8; anon key) └─ public views / RPCs only ``` +Edge Functions are not used (D-R9): limits on the self-hosted edge runtime, hand +deployment, and one Rust runtime for every server process. + The browser never holds a service-role key, admin credential, storage master key or third-party refresh token (§17.1). @@ -33,8 +40,8 @@ key or third-party refresh token (§17.1). | Google, Apple | GoTrue OAuth providers | Apple requires a paid developer account and a services id: dependency to confirm | | Phone verification | GoTrue phone OTP needs an SMS provider (Twilio, MessageBird, Vonage) | cost and EU processing to confirm; see `OPEN_QUESTIONS.md` Q7 | | Email verification | GoTrue, mandatory before professional features | | -| MFA | GoTrue TOTP; mandatory for owner/admin/moderator/support roles, enforced by RLS helper `has_mfa()` on admin tables | | -| Roles | `profile_roles` table, never JWT custom claims as the only source (claims can lag) | helpers read the table | +| MFA | GoTrue TOTP; mandatory for owner/admin/moderator/support roles, enforced by RLS helper `has_mfa()` on admin tables | TOTP enabled server-side; `has_mfa()`, enrolment and enforcement not built (`IDENTITY.md` §4, TODO RR-3) | +| Roles | `profile_roles` table with the `platform_role` enum (owner, admin, moderator, support: BDR-026), never JWT custom claims as the only source (claims can lag) | helpers read the table; professional statuses (practitioner, student, professor) come from verification, cabinet roles from membership, never from this enum | | Impersonation | dedicated RPC issuing a short-lived scoped session, audited, banner in UI (§17.5) | after MVP core | `profiles.id = auth.users.id`, created by a trigger on `auth.users` insert. @@ -51,7 +58,7 @@ Conventions fixed now so every step follows them: - UUID primary keys (`gen_random_uuid()`), `created_at` / `updated_at` with a shared trigger, soft delete `deleted_at` where the architecture names it. - Enums as PostgreSQL `enum` types when the value set is closed by the business (report status, appointment status), `text` + CHECK when the set is expected to grow (document types). -- JSONB documents (`reports.current_document`, `anatomical_sheet_versions.content_jsonb`) carry their own `schema_version` and are validated by the matching Zod schema at the application boundary and by a CHECK on `schema_version` in SQL. SQL does not re-implement Zod. +- JSONB documents (`reports.current_document`, `anatomical_sheet_versions.content`) carry their own `schema_version` and are validated by the Rust core's contracts (`crates/core/src/domain`, since R2) at the application boundary and by a CHECK on `schema_version` in SQL. SQL re-checks only what publication needs (`private.sheet_document_issues`, BDR-032), with the same rule codes as the core. - Every table exposed to the browser: RLS enabled, no `USING (true)` policy for `authenticated`, no anonymous policy on core tables (§17.4). ## 4. RLS strategy @@ -102,40 +109,42 @@ EXECUTE on those functions and nothing else. ## 5. Storage -Buckets, all private: `avatars`, `logos`, `professional-documents`, -`client-files`, `animal-files`, `report-files`, `anatomical-sheets`, `imports`. +Buckets, all private, as built (`STORAGE.md`): `avatars` (the only one with +policies), `logos`, `professional-documents`, `client-files`, `animal-files`, +`report-files`, `imports` (closed until their step writes the rules), and +`anatomical-sheet-assets` (sheet drawings, its own policy). -Object key: `///`. The -`assets` table is authoritative; `storage.objects` policies call the owning -helper (`can_view_report` for `report-files/...`). Reads go through signed -URLs issued by an RPC/Edge Function after the same check. +Object keys are built by the server from uuids +(`profiles///avatar.webp`, `quarantine///upload`). The +`assets` table is authoritative; `storage.objects` policies compare whole keys +through `assets`. Owner-only files are downloaded under the SELECT policy with +no signed URL (BDR-048); a shared kind may use a short-lived signed URL issued +by the Storage API after the same policy. There is no `issue_signed_url` RPC. -SVG pipeline (§15.3): upload lands in a quarantine prefix with -`assets.sanitization_status = pending`; a server sanitizer (Edge Function or -worker) rewrites the file (strip `