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.
This commit is contained in:
bchanot committed 2026-10-25 17:12:37 +01:00
1 parent c71fafa3c5
commit ac60b24267
12 files changed
+260 -92

No files matched your search

+4
View File
@@ -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).
---
+4 -1
View File
@@ -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) |
+1 -1
View File
@@ -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)
+55 -42
View File
@@ -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: `<resource-type>/<resource-id>/<asset-id>/<safe-filename>`. 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/<owner>/<id>/avatar.webp`, `quarantine/<owner>/<id>/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 `<script>`, `<foreignObject>`, `on*`,
`javascript:`/external hrefs, `<use>` to external documents, CSS `url()`),
stores the clean bytes under the final key and sets `status = clean`. Policies
only allow reading `clean` assets to anyone other than the uploader. The
current 10-line client sanitizer stays as a pre-check in the editor, not as
the boundary.
Untrusted uploads (§15.3) land under a quarantine key; the Rust worker's
sandboxed child decodes them and writes the clean object; a quarantine object
is never readable by an API role. User SVG uploads arrive with Step 13 and go
through the Rust core's one SVG reader (prescan caps, allowlist, reference
graph), never a browser sanitiser as the boundary.
Archive (§15.4, §16): S3-compatible cold storage with lifecycle rules, no
Object Lock by default. Out of MVP core; designed at the data-lifecycle step.
## 6. Edge Functions vs PostgreSQL functions vs worker
## 6. PostgreSQL functions vs Rust worker vs Rust HTTP services
Decision rule for each server-side behaviour:
Decision rule for each server-side behaviour (D-R9 replaced the Edge
Functions row):
| Put it in | When |
|---|---|
| PostgreSQL function / trigger (RPC) | Needs transactional guarantees with the data: report numbering, completion + quota, booking slot lock, grant evaluation, version publication, GC preconditions |
| Edge Function | Needs HTTP from outside or secrets: Stripe webhooks, public widget endpoints, signed-URL issuance, calendar OAuth callbacks, email send trigger, SVG sanitization (small files), import preflight (small files) |
| Worker | Long or scheduled: reminders, expiry sweeps (unless `pg_cron`), calendar sync, route cache, long imports, archive, GC sweeps, server PDF (later) |
| Rust HTTP service (`crates/worker` image, `serve` subcommand behind the reverse proxy) | Needs inbound HTTP from outside or third-party secrets: Stripe webhooks, public widget endpoints SQL cannot serve, external calendar OAuth callbacks; each service holds only its own secrets |
| Rust worker (`crates/worker`, job loop) | Long, scheduled or untrusted-bytes work: file decoding (avatar since Step 8), reminders and email sending, expiry sweeps (unless `pg_cron`), calendar sync, route cache, long imports, archive, GC sweeps, server PDF (later) |
Self-hosted note: Edge Functions on a self-hosted stack run in the
`edge-runtime` container and must be deployed by hand. The first steps lean
on PostgreSQL functions, which the CLI migrates and tests natively. See
`OPEN_QUESTIONS.md` Q2 on VPS sizing.
Supabase Auth keeps the OAuth sign-in flows it already handles. Shared rules
come from `crates/core`; the worker and the HTTP services are distinct
processes with their own least privilege. See `OPEN_QUESTIONS.md` Q2 on VPS
sizing.
## 7. Migrations
@@ -146,9 +155,12 @@ on PostgreSQL functions, which the CLI migrates and tests natively. See
listed in §32 of the architecture, pgTAP tests, and regenerated types.
- `supabase db reset` must succeed from zero on CI, then `supabase test db`,
then the app test suite (§36).
- Seed data (`supabase/seed/`): species list, plans, the official equine sheet
v1 produced by the importer from the two SVGs and the catalog. Seeds are
idempotent and versioned like migrations.
- Seed data (`supabase/seed/`): the official equine sheet as a DRAFT,
generated by the Rust pipeline (`pnpm import:equine`) from the legacy
sources and the curation changeset; it is published only by a platform admin
after business review (BDR-034, BDR-037). Reference lists (species, later
plans) are written by migrations. Seeds are idempotent and versioned like
migrations.
- Production changes follow expand/contract when a column is renamed or
dropped (the `deprecation-and-migration` skill applies).
@@ -167,9 +179,10 @@ Representative cross-tenant cases are a release gate (§30).
## 9. Generated types
`supabase gen types typescript --local > packages/supabase/src/database.types.ts`
after every migration. CI regenerates and fails on diff. Zod schemas in
`packages/domain` remain the contract for JSONB documents; generated types
`pnpm db:types` regenerates `packages/supabase/src/database.types.ts` after
every migration; `pnpm db:types:check` diffs it (no CI runs on the forge,
BDR-047). The Rust contracts of `crates/core/src/domain`, exported to
TypeScript by ts-rs, are the contract for JSONB documents; generated types
cover columns and RPC signatures.
## 10. What must stay server-side (brief §19, architecture principles 6–13)
@@ -182,7 +195,7 @@ cover columns and RPC signatures.
6. Entitlement computation and Stripe state.
7. Referral eligibility and caps.
8. Client candidate matching and sharing consent flows.
9. SVG sanitization and signed URL issuance.
9. Untrusted file decoding (worker child), SVG reading by the core on every product drawing, Storage access through policies.
10. Import preflight, quota check and atomic commit.
11. Audit logging, impersonation, moderation.
12. Archive and deletion workflows.
+15 -8
View File
@@ -5,6 +5,13 @@ Status: Step 0 deliverable, 2026-10-08. Derived from
current code (`docs/faunosteo-audit/`). No SQL here: entity names are the
conceptual tables of the architecture document, listed so that each
implementation step knows which domain it touches.
Revised 2026-10-25 (P0): platform roles (BDR-026), sheet document fields
(BDR-031), Storage as built (`STORAGE.md`). The "Reuse" rows and §19 describe
the code of 2026-10-08: the TypeScript modules they name have since moved into
`crates/core` or been deleted (Steps 5 to 8, R2 to R5); `CLAUDE.md` holds the
current map. Clients and Animals (§4, §5) are being reframed by the V1-1
contract (`V1-1_OWNERS_ANIMALS.md`): workspaces, no global client record,
client-animal links with roles; owner orientations awaiting ratification.
Conventions used below:
@@ -54,7 +61,7 @@ Animals, Identity and (optionally) Organizations.
| Item | Content |
|---|---|
| Entities | `profiles` (= `auth.users.id`), `profile_roles` (additive roles: practitioner, student, professor, owner, admin, moderator, support), `platform_invitations` |
| Entities | `profiles` (= `auth.users.id`), `profile_roles` (enum `platform_role`: owner, admin, moderator, support; BDR-026), `platform_invitations` (not built). Professional statuses (practitioner, student, professor) are outcomes of Professional Verification, cabinet roles live in the cabinet membership: neither is a platform role. |
| Depends on | Supabase Auth (email/password, Google, Apple, OTP/magic link, phone verification) |
| Depended on by | every other domain |
| Server-only | role grants (admin action, never a browser update), phone/email verification state, invitation acceptance |
@@ -109,10 +116,10 @@ Animals, Identity and (optionally) Organizations.
| Item | Content |
|---|---|
| Entities | `species` (list: id, labels), `anatomical_sheets` (identity, creator, visibility, status, provenance `based_on_sheet_id`/`based_on_version_id`, `current_version_id`), `anatomical_sheet_versions` (version number, status draft/published/deprecated, `document_schema_version`, `content_jsonb`, assets, publication metadata), sheet assets in Storage (SVG per view) |
| Canonical document (JSONB) | `schema_version`, `species_id`, `vertebral_config` (ordered regions: code, label FR/EN, count), `views[]` (id, kind main/detail, `parent_view_id`, `opened_by_annotation_id`, `view_box`, `svg_asset_id`), `annotations[]` (stable id, view id, kind point/zone/detail-trigger, category id, names FR/EN, laterality, special, geometry), `categories[]` (id, label, colour), `finding_tree.zones{}` (current `ZoneFindings` shape), `annotation_finding_map[]` (annotation id → finding zone id), `scope_disclaimer`, legacy id map (old `data-anno-id` → new id) kept for migration only |
| Canonical document (JSONB) | `schema_version`, `species_id`, `vertebral_config` (ordered regions: code, label FR/EN, count), `views[]` (id, kind main/detail, `parent_view_id`, `opened_by_annotation_id`, `view_box`, `svg_asset_id`), `annotations[]` (stable id, view id, kind point/zone/detail-trigger, category id, names FR/EN, laterality, special, geometry), `categories[]` (id, label, colour), finding tree by finding zone, `finding_zone_id` inline on each annotation (no separate map, BDR-031), `scope_disclaimer`; legacy id mapping kept in the seed's generated files and the report migration map. Exact shape: `ANATOMICAL_SHEET_MODEL.md` |
| Depends on | Identity (creator), Files (SVG assets), Community (visibility/grants read at use time), Billing (private visibility add-on) |
| Depended on by | Reports (exact version reference), Community, Animals (species list), Imports (none) |
| Server-only | version immutability once published, version numbering, garbage collection preconditions (no report, no fork, no grant, no pending process), SVG sanitization before any other user can read the asset, "can use / can fork" evaluation |
| Server-only | version immutability once published, version numbering, garbage collection preconditions (no report, no fork, no grant, no pending process), SVG reading by the core before any other user can read the asset, "can use / can fork" evaluation |
| Reuse | `parseSvgBones` (importer and renderer), `findings.ts` schema (finding tree), `zoneMatch.ts` (importer only), `regionFromLabel` (importer only), `AnatomyCanvas`, `DetailModal`, `VertebraPicker`, `FindingsTreePicker`, the two equine SVGs and the catalog as seed, the tree-edit behaviour of `pathology-editor.html` and the annotation operations of `SvgEditorRoute` as functional references |
| Notes | Rules 2–8 of the brief (§18) all live here. The current code has no sheet object at all (audit 02 §6): no id, no version, no author, no persisted SVG ↔ catalog link. |
@@ -121,7 +128,7 @@ Animals, Identity and (optionally) Organizations.
| Item | Content |
|---|---|
| Entities | `reports` (report number, animal, practitioner, organization nullable, ownership scope, status draft/completed/archived, report date, `anatomical_sheet_version_id`, `current_document`, revision counter, `completed_at`, `free_edit_until`, soft delete), `report_revisions` (document snapshots with reason), `report_access_grants`, `practitioner_report_counters` (row-locked numbering), report PDF artifacts (Files) |
| Report document (JSONB) | current `Report` v2 shape evolved to v3: observations with zones keyed by `annotationId` + `viewId`, vertebrae with region code, findings with snapshots, free text, severity, comment, conclusion, recommendations, next appointment, identity snapshots (practitioner, animal, client), `localAnnotations[]` (report-only points, see `OPEN_QUESTIONS.md` Q6), locale used for the last PDF |
| Report document (JSONB) | current `Report` v2 shape evolved to v3: observations with zones keyed by `annotationId` + `viewId`, vertebrae with region code, findings with snapshots, free text, severity, comment, conclusion, recommendations, next appointment, identity snapshots (practitioner, animal, client), `localAnnotations[]` (report-only points, see `OPEN_QUESTIONS.md` Q6); the locale stays out of the report (BDR-014), the PDF envelope records it |
| Depends on | Animals (and Clients through them), Identity, Organizations, Anatomical Sheets (exact version), Billing & Entitlements (quota, free edit window), Files (PDF artifacts) |
| Depended on by | Community (shared report revisions), Booking (appointment ↔ report link, optional), Imports, Notifications (secure sending to the owner) |
| Server-only | report numbering, completion (quota check, `free_edit_until`), revision checkpoints, "deleted completed reports still count", shared-practitioner revision acceptance, import quota preflight |
@@ -173,10 +180,10 @@ Animals, Identity and (optionally) Organizations.
| Item | Content |
|---|---|
| Entities | `assets` (bucket, object key, owner scope, resource type/id, mime, size, checksum, sanitization status), buckets `avatars/ logos/ professional-documents/ client-files/ animal-files/ report-files/ anatomical-sheets/ imports/` |
| Entities | `assets` (status, owner, server-built keys, lease; `STORAGE.md`), buckets `avatars` (policies), `logos`, `professional-documents`, `client-files`, `animal-files`, `report-files`, `imports` (closed), `anatomical-sheet-assets` (sheet drawings) |
| Depends on | Identity, and every owning domain for access rules |
| Depended on by | Verification, Clients, Animals, Reports (PDF artifacts), Anatomical Sheets (SVG), Imports, Public Profile (photos, logos) |
| Server-only | object key generation (`<resource>/<resource-id>/<asset-id>/<safe-filename>`), signed URL issuance, SVG sanitization and quarantine, `storage.objects` RLS |
| Server-only | object key generation from uuids, quarantine and decoding in the Rust worker's sandboxed child, `storage.objects` RLS through `assets`; owner-only files read under RLS with no signed URL (BDR-048) |
| Reuse | `sanitizeSvg` (10 lines in `SvgEditorRoute` and duplicated in `pathology-editor.html`) as the *client-side* pre-check only; the server sanitizer is new. |
## 13. Billing & Entitlements
@@ -235,8 +242,8 @@ Animals, Identity and (optionally) Organizations.
| Item | Content |
|---|---|
| Entities | `student_professor_links`, `student_access_periods`, student-owned educational reports |
| Depends on | Identity (student/professor roles), Reports, Billing (student entitlement), Anatomical Sheets |
| Notes | Must not be built in the MVP, but `profile_roles` and `entitlement_grants` are shaped so it fits later without migration pain. |
| Depends on | Identity and Professional Verification (student/professor statuses, not platform roles: BDR-026), Reports, Billing (student entitlement), Anatomical Sheets |
| Notes | Must not be built in the MVP, but verification statuses and `entitlement_grants` are shaped so it fits later without migration pain. No plan step owns education yet. |
## 19. Reuse matrix (current code → domain)
@@ -2,6 +2,14 @@
Status: Step 0 deliverable, 2026-10-08. Proposal only; the repository is not
transformed by this document.
Snapshot notice (2026-10-25, P0): this text describes the app of 2026-10-08
and its planned target. Since then: auth and the `/app` shell exist (Step 7,
`IDENTITY.md`), the worker is the Rust `crates/worker` (not a Node `apps/worker`),
Edge Functions are retired (D-R9), the packages `domain`, `anatomy`, `pdf` and
pdf-lib were replaced by `crates/core` and deleted (R4.8, R5.7), the legacy
editors and `public/species` were deleted at Step 5, no TanStack Query
(BDR-041), the public site framework is Astro (D-R8). `CLAUDE.md` (folder map,
architecture) is the current description.
## 1. Starting point
+90 -37
View File
@@ -12,6 +12,39 @@ Reference product/architecture: `faunosteo-business-architecture.md`
does today; the architecture document is the source of truth for what it
must become. Where the two disagree, `OPEN_QUESTIONS.md` records it.
## 0. Where the plan stands (2026-10-25)
Done on `develop`: Steps 0 to 8 (Step 4 in three parts 4, 4b, 4c) and the Rust
migration R0 to R5 (`RUST_ARCHITECTURE_REVIEW.md`, `RUST.md`): every domain
rule, the SVG reader, the PDF reader and writer, the curation pipeline and the
files worker are Rust (`crates/`). Merging into `develop` authorises nothing in
production; release 0.2.0 (Steps 3 to 6) is still waiting (TODO RR-9).
The product roadmap validated by the owner on 2026-10-25 regroups the
remaining steps toward a first usable version: a signed-in practitioner keeps
clients, animals and bilans in the cloud, with history and PDF, on phone and
computer. Inventory: `.claude/audits/2026-10-25-functional-inventory.md`.
| Order | Content | Plan steps |
|---|---|---|
| P0 | Documents realigned on the code, decisions recorded (`OPEN_QUESTIONS.md` statuses) | none |
| V1-1 | Clients and animals of a practitioner's workspace, with the permission frame of future cabinets (`V1-1_OWNERS_ANIMALS.md`) | 12 reduced, frame of 10 |
| V1-2 | Anatomical sheets loaded from Supabase under control (no publication of the equine draft without the owner) | 13 reduced |
| V1-3 | Bilans persisted, linked to an animal, history | 14 (+ 11 skeleton if a quota applies) |
| V1-4 | Stored PDF artifacts and authorised sharing | 15 reduced, sharing part of 12 |
| V1-5 | Cross-cutting mobile and accessibility validation | design README, `TEST_STRATEGY.md` |
| Next | Verification 9, cabinets 10, entitlements 11, then 16 to 27 | per step |
Accessibility and security apply at every step, not only at V1-5. The release
readiness track (TODO RR-1 to RR-10) stays separate: no V1 step authorises a
release or a public exposure, and passing development tests is not a
production authorisation. The step texts below keep their numbering; each V1
item reuses the step it reduces. For a done step, the block is the original
specification: its "as built" note, the code and `CLAUDE.md` are
authoritative where they differ (the TypeScript packages `domain`, `anatomy`
and `pdf` named in Steps 4 to 6 were replaced by `crates/core` and deleted at
R4.8 and R5.7).
## 1. How to read the plan
- Steps follow the real dependency order, not the commercial sprint order of
@@ -32,12 +65,14 @@ must become. Where the two disagree, `OPEN_QUESTIONS.md` records it.
## 2. Guiding principles for every step
1. `pnpm typecheck && pnpm test:run && pnpm lint` green before any commit; for
DB steps also `supabase db reset && supabase test db` (architecture §36).
DB steps also `pnpm db:reset && pnpm db:test` (the CLI runs only through
`scripts/supabase.sh`); after a Rust change `pnpm rust:check`; before a
merge `pnpm check:all`.
2. A step that adds a table adds its RLS policies, indexes, pgTAP tests and
regenerated types in the same branch.
3. The UI is never the security boundary; every rule listed in
`BACKEND_ARCHITECTURE.md` §10 is implemented in PostgreSQL or a server
function.
`BACKEND_ARCHITECTURE.md` §10 is implemented in PostgreSQL or in a Rust
server process (`crates/worker` or a Rust HTTP service, D-R9).
4. No deletion of user data. Soft delete, revisions, archive.
5. Legacy modules are deleted at the step named in
`REPOSITORY_MIGRATION_MAP.md`, in the same branch that makes them dead.
@@ -200,7 +235,8 @@ Risks: snapshot size growth with future sheets (mitigate: snapshot subset = only
Milestone A (after Step 6): release 0.2.0 "canonical sheet + PDF v3", still a
local tool. Everything above has no backend and can ship to faunosteo.com
as-is.
as-is. Status 2026-10-25: `release/0.2.0` cut on 2026-10-11, not finished; its
fate (ship, supersede, rebase) is TODO RR-9.
```text
Step 7
@@ -220,7 +256,7 @@ Step 7 implementation note (2026-10-11): shipped as `docs/development/IDENTITY.m
Deviations: no TanStack Query (a zustand store covers the profile read/update of this
step; the query layer comes with the first list screens); `platform_invitations` and the
MFA helper not written (no admin screen to protect yet, gap documented in IDENTITY.md §4);
professional fields added to `profiles` as declared free text (verification = Step 11);
professional fields added to `profiles` as declared free text (verification = Step 9);
Google/Apple wired in config.toml behind env ids, buttons behind `APP_AUTH_PROVIDERS`.
```text
@@ -244,7 +280,8 @@ Step 8 as built (2026-10-13, `STEP8_FILES_ANALYSIS.md` D1–D9 + Rust R1,
family); there is no `issue_signed_url` RPC (the Storage API signs after the
SELECT policy; the owner-only avatar is downloaded under RLS, no signed URL);
the SVG sanitiser and the user SVG upload path move to Step 13 with their
producer (the allowlist sanitiser already exists in `packages/pdf`); the
producer (the allowlist sanitiser then lived in `packages/pdf`; since R3 it
is the Rust core's one SVG reader, `anatomy::svg::read_svg`); the
avatar pointer is derived from the single clean `assets` row (no
`profiles.avatar_asset_id`); the sheet bucket keeps its name
`anatomical-sheet-assets`.
@@ -288,7 +325,7 @@ Changes expected:
Tests: pgTAP matrix: free user, verified free user, invited grant with expiry, admin role; expired grant yields nothing.
Manual validation: grant an invited entitlement to a user via admin RPC and watch capabilities change.
Definition of Done: no is_paid boolean anywhere; every later feature reads capabilities.
Risks: capability list drift (keep it as one SQL enum + one TS const checked by a test).
Risks: capability list drift (keep it as one SQL enum + one Rust const in the core, exported to TypeScript through ts-rs, checked by a test).
```
```text
@@ -305,20 +342,37 @@ Definition of Done: architecture Sprint 3; rule 1 (animal ≠ sheet) visible in
Risks: the global-client design (C4) if confirmed as plain shared rows; GDPR consent texts not final (version column from day one).
```
Step 12 note (2026-10-25): roadmap item V1-1 proposes a reduced Step 12 under
the owner's orientation C4 (records attached to a workspace, one personal
workspace per practitioner, cabinets later, no global client record shared
between practitioners), without consents, grants, sharing, files or candidate
matching: `V1-1_OWNERS_ANIMALS.md`. The text above stands until the owner
ratifies the contract's orientations (§9.1) and answers its sub-choices
(§9.2).
```text
Step 13 (∥ Steps 9–12)
Name: Anatomical sheets in the database and official equine seed
Objective: Sheet and version tables with immutability, SVG assets in Storage, seed of the official equine sheet v1, SheetProvider over Supabase, read-only sheet library in the app.
Objective: Sheet and version tables with immutability, SVG assets in Storage, seed of the official equine sheet as a draft, SheetProvider over Supabase, read-only sheet library in the app.
Dependencies: Step 3, Step 4, Step 8
Changes expected:
- supabase: anatomical_sheets, anatomical_sheet_versions (content_jsonb + schema CHECK), immutability trigger on published rows, version numbering RPC, deprecate RPC, GC function with the four preconditions (no report, no fork, no grant, no pending process) returning candidates only (deletion job at Step 18), helpers can_use_sheet/can_fork_sheet (creator-only for now), seed script uploading the two SVG assets and inserting v1 published.
- supabase: anatomical_sheets, anatomical_sheet_versions (content_jsonb + schema CHECK), immutability trigger on published rows, version numbering RPC, deprecate RPC, GC function with the four preconditions (no report, no fork, no grant, no pending process) returning candidates only (deletion job at Step 18), helpers can_use_sheet/can_fork_sheet (creator-only for now), operator upload of the drawings (`pnpm assets:upload`) and the generated draft seed. Publication of the official equine sheet is an explicit act of a platform admin after the business review of REVIEW-REPORT.md (BDR-034, BDR-037); no step publishes it automatically.
- packages/supabase: typed accessors; apps/app: SheetProvider.supabase replaces the bundled seed in production builds (bundled kept for tests), /app/anatomy read-only list and preview.
Tests: pgTAP: UPDATE on published content raises; v2 numbering; GC preconditions each individually; non-creator cannot read a private sheet; integration: seed is idempotent and byte-faithful (checksums).
Manual validation: open /app/anatomy, see "Faunosteo / Cheval / officielle v1", preview both views, click zones (no report yet).
Definition of Done: rules 4–7 enforced in SQL; public/species/* no longer fetched by apps/app (nginx /species/ rule removed); SvgEditorRoute loads assets through signed URLs.
Risks: seed drift vs the committed document.json (CI compares); storage policy for public sheets to be widened at Step 18 only.
Manual validation: open /app/anatomy, see "Faunosteo / Cheval / officielle" with its draft or published status, preview both views, click zones (no report yet).
Definition of Done: rules 4–7 enforced in SQL; the app loads the sheet document and its drawings from Supabase, every drawing through the core's SVG reader; the bundled sheet stays for tests and the local tool.
Risks: seed drift vs the generated folders (`pnpm import:equine --check` and the curation tests compare; no CI runs, BDR-047); storage policy for public sheets to be widened at Step 18 only.
```
Step 13 status (2026-10-25): the tables, immutability triggers, RPCs, the
`anatomical-sheet-assets` bucket and the generated equine DRAFT seed exist
since Steps 4, 4b and 4c (migrations `20261008110000`, `20261009100000`,
`20261010100000`); `public/species/` and the SVG editor were deleted at
Step 5. Remaining: the provider over Supabase, the library screen, the GC
candidates. Roadmap item V1-2 reduces the step to a controlled loading of the
sheets; whether a signed-in practitioner may load the unpublished draft is an
owner decision taken at V1-2.
```text
Step 14
Name: Cloud reports
@@ -339,12 +393,12 @@ Name: PDF artifacts and cloud import
Objective: Store generated PDFs as report artifacts; import PDFs into the account through a server-validated path; render historical reports even if the sheet is gone.
Dependencies: Step 6, Step 14. Gate: confirmation before touching import/attachment code again.
Changes expected:
- supabase: report_pdf_artifacts (asset, locale, revision no, sha256), RPC import_report(attachment json, target animal) doing: version check, Zod validation server-side (plpgsql cannot run Zod → validate in an Edge Function or accept the attachment into a staging row and validate in the app with a server re-check of the invariants that matter: sheet version exists or snapshot-only version created, quota, ownership), snapshot-only version creation (read-only, status deprecated, flagged snapshot_only) when the referenced version no longer exists.
- supabase: report_pdf_artifacts (asset, locale, revision no, sha256), RPC import_report(attachment json, target animal) doing: version check, server-side validation of the archive (plpgsql cannot run the core's readers → run the Rust core's archive reader in a Rust service, D-R9, or accept the attachment into a staging row, read it with the core in the browser and re-check on the server the invariants that matter: sheet version exists or snapshot-only version created, quota, ownership), snapshot-only version creation (read-only, status deprecated, flagged snapshot_only) when the referenced version no longer exists. Opening import to external users stays gated by PDF_IMPORT_HARDENING.md §5 (BDR-040).
- apps/app: download/open artifact list on a report; import flow from the dashboard with quota preflight message and pricing redirect.
Tests: pgTAP: import beyond quota denied before any insert; snapshot-only version is never selectable for new reports; integration: export → delete sheet version (as admin) → import → PDF re-renders.
Manual validation: export, import into a second account (denied: wrong animal/owner), import into own account, check artifact list.
Definition of Done: rule 8 (historical restorable) demonstrated by test; PDF v2 import decision (Q1) applied.
Risks: Zod validation location (server vs client) must be decided per Q2; duplicate imports (idempotency by report id + sha256).
Risks: validation location (Rust service vs browser core with server re-check) decided at the step; duplicate imports (idempotency by report id + sha256).
```
```text
@@ -367,15 +421,15 @@ with the practitioner client. Steps 17–18 can start before B.
```text
Step 17 (∥ Steps 14–16)
Name: Anatomical sheet editor (merge of SVG editor and findings editor)
Objective: One structured editor on the canonical document: views, points/zones, categories, laterality, vertebral config, detail view creation, finding tree, annotation ↔ zone mapping, draft/publish/deprecate; personal sheets and official sheet maintenance; old tools deleted.
Dependencies: Step 13 (tables), Step 5 (document), decisions Q4/Q5/C8
Objective: One structured editor on the canonical document: views, points/zones, categories, laterality, vertebral config, detail view creation, finding tree, annotation ↔ zone mapping, draft/publish/deprecate; personal sheets and official sheet maintenance.
Dependencies: Step 13 (tables), Step 5 (document). Q4, Q5 and C8 are settled (OPEN_QUESTIONS statuses).
Changes expected:
- apps/app: /app/anatomy (library: official, own), /app/anatomy/new, /app/anatomy/:sheetId/editor with SheetEditorStore (document + selection + mode + undo), canvas tools (select/point/polygon, drag, vertex edit), properties panel, categories panel, views panel (create detail view from zone: bbox + margin → view_box, child view), vertebral config panel, findings panel (tree edit from pathology-editor behaviour + validation), mapping panel (annotation → finding zone, suggestions from zoneMatch allowed here as a helper), publish flow (new immutable version), deprecate.
- Deleted in the same branch: SvgEditorRoute.tsx, svg-editor.css, svg_editor.* keys, EditorsRoute, public/pathology-editor.html, public/species/equine/pathologies.json, scripts/scaffold-species.mjs.
- supabase: draft uniqueness (one draft per sheet), publish RPC validating the document (mapping targets exist, no dangling views) and uploading assets, personal-sheet creation RPC.
- apps/app: /app/anatomy (library: official, own), /app/anatomy/new, /app/anatomy/:sheetId/editor with SheetEditorStore (document + selection + mode + undo), canvas tools (select/point/polygon, drag, vertex edit), properties panel, categories panel, views panel (create detail view from zone: bbox + margin → view_box, child view), vertebral config panel, findings panel (tree edit + validation by the core), mapping panel (annotation → finding zone), publish flow (new immutable version), deprecate. Document rules, validation and drawing go through `crates/core` (BDR-043).
- The legacy tools (SvgEditorRoute, EditorsRoute, public/pathology-editor.html, public/species, scripts/scaffold-species.mjs) were already deleted at Step 5 (BDR-038); until this step, sheet content changes only through `curation/changes.json` and the Rust pipeline, reviewed, tested and versioned, and no graphic editor changes or publishes it (owner confirmed 2026-10-25). Annotating a bilan never changes the anatomical reference.
- supabase: draft uniqueness (one draft per sheet, exists since Step 4), publish RPC validating the document (mapping targets exist, no dangling views) and uploading assets, personal-sheet creation RPC.
Tests: one test per legacy operation (audit 03 §2, 05 §3.5) on the new model; detail-view geometry; publish creates v+1 and v1 reports still render (regression from Step 15 fixtures); pgTAP for draft uniqueness and publish validation.
Manual validation: fork-free scenario: create a personal sheet from scratch for a second species (dog, 3 points, 1 spine zone, 1 detail), publish, create a report on it, PDF; then edit the official sheet as admin, publish v2, open an old report (still v1).
Definition of Done: architecture Sprint 6 (except "promote manual point", added once Q6 is answered); REPOSITORY_MIGRATION_MAP REPLACE items for the editors closed.
Definition of Done: architecture Sprint 6 (except "promote manual point", added once Q6 is answered); every legacy editor operation of audit 03 §2 and 05 §3.5 covered on the new model.
Risks: largest UI step; split into sub-branches (canvas tools / panels / publish) each merged green behind a "beta" flag; feature parity gaps with the vanilla tool found late (mitigate with the reference tests first).
```
@@ -396,16 +450,15 @@ Risks: discovery performance (indexes §32); GC race with an in-flight report cr
```text
Step 19
Name: Notifications foundation and worker
Objective: Email provider abstraction, PostgreSQL job queue, apps/worker, transactional templates FR/EN, secure links.
Objective: Email provider abstraction, PostgreSQL job queue, notification jobs in the Rust worker, transactional templates FR/EN, secure links.
Dependencies: Step 7, Step 12 (document delivery to clients), decision Q7 (provider)
Changes expected:
- apps/worker: Node service, service-role client, job loop on private.jobs (SKIP LOCKED), EmailProvider interface + one implementation, retry/backoff, no clinical data in logs.
- supabase: private.jobs, email delivery log, secure_links (token hash, purpose, expiry).
- packages/i18n split (dictionaries without React) for templates.
- Docker: worker service in compose.
Tests: unit: queue semantics, template rendering; integration: enqueue → worker sends to Inbucket; secure link single-use and expiry.
- crates/worker (Rust, exists since Step 8 / R1 with the avatar job family and its compose service): a notification job family on the PostgreSQL queue (SKIP LOCKED or the lease-token pattern of BDR-048), EmailProvider trait + one implementation, retry/backoff, no clinical data in logs; least privilege per process (D-R9).
- supabase: job table, email delivery log, secure_links (token hash, purpose, expiry).
- Template dictionaries readable by the worker (FR/EN), kept in step with the app dictionaries.
Tests: unit: queue semantics, template rendering; integration: enqueue → worker sends to Mailpit; secure link single-use and expiry.
Manual validation: trigger "send report to owner" and receive the secure link locally.
Definition of Done: first job that is not SQL runs in the worker; architecture §22.3–22.4.
Definition of Done: notification jobs run in the worker; architecture §22.3–22.4 with D-R9 applied.
Risks: provider deliverability (SPF/DKIM at DNS); worker single instance (acceptable at launch).
```
@@ -417,7 +470,7 @@ Dependencies: Step 12, Step 19, Step 11 (booking.manage)
Changes expected:
- supabase: service_types, locations, availability_rules, availability_exceptions, appointments, intake_forms/questions/answers, RPCs request_booking (row lock on practitioner-day, one pending per client), confirm/reject/cancel/reschedule, expiry function (48h / 24h if <72h / 1h if <25h) run by pg_cron, availability RPC (server-side evaluation; travel buffers as fixed minutes until Step 21).
- apps/app: /app/calendar (week view), services/locations settings, manual appointment, intake form builder (default templates per species).
Tests: pgTAP: double request on the same slot (one wins), second pending request by the same client denied, expiry rules at each boundary, status transitions; unit: expiry rule mirror in TS; integration: full booking lifecycle.
Tests: pgTAP: double request on the same slot (one wins), second pending request by the same client denied, expiry rules at each boundary, status transitions; unit: expiry rule mirror in the Rust core (BDR-043); integration: full booking lifecycle.
Manual validation: book as a client via a test page (public UI comes at Step 22), confirm as practitioner, reminder enqueued (Step 19).
Definition of Done: architecture Sprint 8; principle 13 (race-safe) tested.
Risks: timezone handling (store timestamptz, practitioner tz on profile); calendar UI effort (consider a maintained library, declared at the step).
@@ -430,8 +483,8 @@ Objective: RoutingProvider abstraction with cache, travel before/after, return-t
Dependencies: Step 20, Step 19 (worker, alerts)
Changes expected:
- supabase: travel_profiles, travel_pricing_rules, route_cache, external_calendar_connections (encrypted credentials, server only), external_calendar_events, availability RPC extended with travel.
- apps/worker: routing provider adapter (one provider chosen after evaluation; interface first), calendar sync jobs, conflict detection.
- Edge Function or worker endpoint for Google OAuth callback.
- crates/worker: routing provider adapter (one provider chosen after evaluation; interface first), calendar sync jobs, conflict detection.
- Google OAuth callback served by a Rust HTTP service behind the reverse proxy (same image, `serve` subcommand, its own secrets; D-R9). Edge Functions are not used.
Tests: unit: engine with a mocked provider (previous location → travel → appointment → travel → next); pgTAP: external events block slots, titles never exposed; integration: ICS feed import.
Manual validation: two appointments 30 km apart; the availability RPC refuses the gap; connect a Google test calendar and see the block.
Definition of Done: architecture Sprint 9; no provider name in business logic.
@@ -442,7 +495,7 @@ Risks: provider cost/quota; refresh token storage (pgsodium or app-level encrypt
Step 22
Name: Public web and booking widget
Objective: apps/public-web with landing, practitioner public profile, search, SEO; booking widget (iframe + token).
Dependencies: Step 7, Step 9, Step 20, decision Q8 (framework)
Dependencies: Step 7, Step 9, Step 20. Framework: Astro (D-R8, validated with BDR-045; re-checked at the step's brainstorm per the global rule)
Changes expected:
- supabase: public_practitioner_profiles, public views/RPCs (approved columns only), booking_widget_tokens, public booking RPCs rate-limited.
- apps/public-web: SSR pages /, /osteopathe/<slug>, /osteopathes-animaliers/<region|city|species>, sitemap, metadata; booking UI used both on the profile and inside the widget iframe (postMessage height/theme).
@@ -450,7 +503,7 @@ Changes expected:
Tests: pgTAP: anon sees only published profiles and approved columns, never clients/animals/reports; e2e: book from the public page; widget on a static test site.
Manual validation: publish a profile, open it logged out, book; embed the widget script in a local HTML page; revoke the token.
Definition of Done: architecture Sprint 10; SEO checks (/seo, /web-validate) pass on the public pages.
Risks: SEO data leak via views (allow-list columns, tested); framework choice (Q8).
Risks: SEO data leak via views (allow-list columns, tested).
```
```text
@@ -460,7 +513,7 @@ Objective: Stripe customers/subscriptions for individual monthly/yearly, entitle
Dependencies: Step 11, Step 10, Step 7 (verified email + phone for referral), Step 19 (emails)
Changes expected:
- supabase: subscriptions filled by webhook, subscription_seats, referrals, webhook idempotency table, invoice links; get_effective_entitlements covers active subscriptions and referral months.
- Edge Function stripe-webhook (signature check, idempotent); checkout session creation RPC/Edge.
- Stripe webhook endpoint in a Rust HTTP service behind the reverse proxy (signature check, idempotent, its own secret; D-R9); checkout session creation by the same service.
- apps/app: /app/billing (plan, invoices, cancel at period end), pricing page redirect from quota blocks, referral code and status.
Tests: pgTAP: entitlement with active/cancelled/past-due subscription; referral cap 5/year; reward only after referred becomes paying; unit: webhook handler idempotency; integration with Stripe test clocks.
Manual validation: subscribe in test mode, see capability change, cancel, hit period end with a test clock.
@@ -475,7 +528,7 @@ Objective: Staging model, adapters (generic CSV/XLSX/JSON/ZIP, Faunosteo PDF v2/
Dependencies: Step 15 (PDF import), Step 12, Step 11, Step 19 (long imports in worker)
Changes expected:
- supabase: import_jobs, import_files, import_raw_records, import_mappings, import_errors, import_unmapped_data; commit RPC in one transaction; quota preflight.
- apps/worker: ImportAdapter interface (detect/inspect/map/validate/transform/commit), generic adapters; vendor adapters behind feature flags until samples are obtained.
- crates/worker: ImportAdapter trait (detect/inspect/map/validate/transform/commit), generic adapters; vendor adapters behind feature flags until samples are obtained.
- apps/app: /app/settings/import wizard (upload → preview → duplicates → confirm), "Données importées" panel on client/animal.
Tests: adapters on fixture files; pgTAP: commit is atomic (20 reports on a free account roll back entirely); duplicates never auto-merged; traceability of every transformed field.
Manual validation: import a CSV with a duplicate client; confirm the review; check unmapped data is visible.
@@ -503,7 +556,7 @@ Name: Data lifecycle: export, deletion, archive
Objective: Account data export, deletion workflow with hot retention, archive package to S3-compatible storage, sheet-version GC in production mode, restoration from archive.
Dependencies: Step 19 (worker), Step 23 (subscription states), Step 15 (artifacts)
Changes expected:
- apps/worker: export job (JSON + files manifest + checksums), archive job (lifecycle rules, no Object Lock), restore job; supabase: account_lifecycle states (active, restricted, archived, deleted), minimal archive pointer.
- crates/worker: export job (JSON + files manifest + checksums), archive job (lifecycle rules, no Object Lock), restore job; supabase: account_lifecycle states (active, restricted, archived, deleted), minimal archive pointer.
- apps/app: data export request, account deletion request.
Tests: unit: manifest/checksum; integration: export → delete → restore on staging; GC and archive never delete a version referenced by an archived report before its legal retention.
Manual validation: run the full cycle on a test account with artifacts.
@@ -659,7 +712,7 @@ only on explicit human signal.
| PDF: attachment format change, import of user data, browser-only rasteriser | CRITICAL | Steps 6, 15 | v3 format documented, v2 adapter, confirmation gate, Rasterizer interface |
| RLS mistakes | CRITICAL | every DB step | helper + pgTAP per table, full matrix at Step 27, no `USING (true)` for authenticated on core tables |
| Multi-tenant leakage via organization context | CRITICAL | Steps 10, 14 | context passed explicitly to services; org-scoped tests |
| Storage: direct uploads bypass metadata; signed URL leakage | IMPORTANT | Step 8 | insert policy requires assets row; short-lived signed URLs |
| Storage: direct uploads bypass metadata; signed URL leakage | IMPORTANT | Step 8 | insert policy requires assets row; owner-only files downloaded under RLS with no signed URL (BDR-048); short-lived signed URLs only for shared kinds |
| Offline conflicts overwriting server data | IMPORTANT | Step 16 | stale base rejection, conflict revisions, user choice |
| Agenda race conditions and expiry errors | IMPORTANT | Step 20 | row locks, single SQL expiry function, boundary tests |
| Route/travel provider lock-in or cost | IMPORTANT | Step 21 | `RoutingProvider` interface, cache, provider chosen after evaluation |
@@ -670,7 +723,7 @@ only on explicit human signal.
| Phone/email providers undecided | IMPORTANT | Steps 7, 19 | interfaces first; email-only verification until Q7 |
| Vocabulary collision (Observation) in new UI strings | LOW | all UI steps | fixed in C7 |
| Workspace move regressions | LOW | Step 2 | manual script + CI |
| Public site framework choice | LOW | Step 22 | Q8, isolated app |
| Public site framework choice | LOW | Step 22 | Astro (D-R8), isolated app |
## 9. Deliverable checklist per step (applies to every step)
+6
View File
@@ -3,6 +3,12 @@
Status: Step 0 deliverable, 2026-10-08. Describes *how* the existing code
evolves without a big-bang rewrite. The step-by-step schedule is in
`IMPLEMENTATION_PLAN.md`; this document explains the mechanics behind it.
Snapshot notice (2026-10-25, P0): the migrations described here for the sheet,
the report, the PDF and the editors were carried out at Steps 4 to 6 and by
the Rust phases R2 to R5, with different final shapes (inline
`finding_zone_id`, stable slug ids, PDF envelope v1, Rust core in place of the
TypeScript packages, legacy editors deleted at Step 5). Current sources:
`ANATOMICAL_SHEET_MODEL.md`, `docs/PDF-FORMAT.md`, `RUST.md`.
## 1. Principles
+60
View File
@@ -6,6 +6,66 @@ ambiguities or technically risky points found when confronting
questions for the developer that change architecture or development order.
Items that are merely interesting are left out.
## Status (revised 2026-10-25, P0)
The analysis below is the 2026-10-08 text, kept as written; this table says
what has been settled since and by which record (BDR = `.claude/memory/decisions.md`,
D-R = `RUST_ARCHITECTURE_REVIEW.md` Annex A). Paths it cites under
`public/species/` and `public/pathology-editor.html` no longer exist (deleted at
Step 5).
| Item | Status | Settled by / where it stands |
|---|---|---|
| C1 vertebral formula | settled | ordered `vertebral_config.regions`, free codes (BDR-031) |
| C2 report-only points | open | `localAnnotations` reserved empty in Report v3 (BDR-038); promotion semantics undecided (Q6a); defining it later is a report version bump |
| C3 worker on day one | settled | Rust worker built at Step 8 / R1 (BDR-044, BDR-048) |
| C4 global client record | owner orientation, awaiting ratification | records belong to a workspace (one personal workspace per practitioner in V1-1, cabinets later); no global directory shared between practitioners (owner, 2026-10-25); contract `V1-1_OWNERS_ANIMALS.md` §3, D2 |
| C5 animal update rights | owner orientation, awaiting ratification | writes reserved to workspace members with a write right, in V1-1 the practitioner in their personal workspace; no retroactive silent change of a finished bilan (owner, 2026-10-25); V1-1 contract §5.1, §5.3 |
| C6 unverified accounts | owner orientation, awaiting ratification | email confirmation ≠ professional verification; private use for confirmed-email accounts, verification (Step 9) required for public features presenting a verified professional; statuses are not platform roles (BDR-026) (owner, 2026-10-25); V1-1 contract §5.2. Replaces the 2026-10-08 assumption below (no clients or reports before verification) once ratified |
| C7 « Observation » vocabulary | settled | finding category kind `observation` renamed `consultation_reason` (BDR-033 point 5); *Observation* stays the report block |
| C8 drafts per sheet | settled | one draft per sheet, partial unique index (BDR-032) |
| C9 detail view asset | settled | nullable `svg_asset_id`, crop by `view_box`; the equine head is a crop of one cleaned drawing (BDR-031, BDR-036, BDR-037) |
| C10 Edge Functions on a small VPS | Edge part settled, hosting open | Edge Functions retired, Rust services instead (D-R9, BDR-045); VPS sizing and hosting = Q2 |
| C11 restore after the free window | open | Step 11 / 14 with the quota decision |
| C12 SVG sanitisation vs direct upload | settled (mechanism) | quarantine key, status column, closed policies, sandboxed Rust decoder (BDR-048, `STORAGE.md`); user SVG upload arrives with Step 13 through the core's SVG reader |
| C13 CLAUDE.md rules broken | settled | references registry replaces "≥ 1 source" (BDR-036); contracts are Rust (R2) |
| C14 locale of stored PDFs | open | artifact column at Step 15; the archive envelope already records the locale (`PDF-FORMAT.md`) |
| Q1 v2 PDFs in use | partly settled | v2 import is production code (BDR-038, BDR-039); whether real v2 files exist is unanswered |
| Q2 hosting | open | blocks any production backend (TODO RR-5); BDR-049 fixes only the DEV / STAGING / PROD split |
| Q3 non-mammal layouts | settled | free region codes (BDR-031) |
| Q4 external use of the pathology editor | moot | the tool was deleted at Step 5 (BDR-038); content changes go through `curation/changes.json` until the Step 17 editor (owner confirmed 2026-10-25) |
| Q5 one or two equine assets | settled | one cleaned drawing, head as crop (BDR-036, BDR-037) |
| Q6 manual points, shared client records | open (a); (b) reframed by C4 | (a) as C2; (b) no shared record if C4 is confirmed, so the edit-rights question moves inside a data space (V1-1 contract §5) |
| Q7 phone and email providers | open | Step 7 shipped email only; needed before production SMTP and phone verification |
| Q8 public site framework | settled | Astro (D-R8, validated with BDR-045), Rust exception recorded |
| Q9 catalog anomalies | settled, against the 2026-10-08 recommendation | no medical correction at import, anomalies reported, degraded slugs normalised (BDR-034); later corrections through curation changes (BDR-036, BDR-037) |
### Conflicts raised by P0 and their resolution (2026-10-25)
1. Step 17 keeps the plan's merged-editor scope, but the legacy editors were
deleted at Step 5 (BDR-038): until Step 17, no screen edits sheet content.
Resolved (owner, 2026-10-25): no graphic editor that changes or publishes
anatomical content until Step 17; reference changes go through the curation
sources and the Rust pipeline, reviewed, tested and versioned. Annotating a
bilan is distinct from changing the anatomical reference and never touches
`curation/changes.json`.
2. Publication of the official equine sheet: the plan's Step 13 used to expect
"v1 published"; BDR-034 and BDR-037 keep it a draft until a platform admin
publishes after business review. Confirmed (owner, 2026-10-25): the equine
sheet stays a draft until business validation, and nothing publishes it
automatically. Still open for V1-2: who triggers the review, and whether
V1-2 may serve the unpublished draft to signed-in practitioners.
3. Recorded decision BDR-041 calls professional verification "Step 11"; the
plan numbers it Step 9. Resolved: the plan's numbering is kept and the
correction is the new entry BDR-072 (the registry is append-only, BDR-041
is not edited).
4. README, DEPLOY and CHANGELOG mixed the live 0.1.0 (local tool, no backend)
with the unreleased `develop` (Supabase, worker, Rust core). Resolved in P0:
README separates the public 0.1.0, `develop`, DEV-only features and planned
work; CHANGELOG keeps every unreleased change under `Unreleased`; DEPLOY
marks its historical, unverified and unsafe parts, and the CSP example as
not production-ready. The fixes themselves stay with TODO RR-5.
## A. Contradictions, ambiguities, risky decisions
### C1. Vertebral formula shape (architecture §7.2 vs §23.2)
+3 -3
View File
@@ -84,7 +84,7 @@ Known trade-off: a stamped PDF saved before this change (object streams)
hides its `/Keywords`, so a stripped attachment on such a file reads as
`no_attachment` instead of `attachment_stripped`.
## 5. Prerequisites before external users (Step 7+ sync, Step 14 worker)
## 5. Prerequisites before external users (Step 7+ sync; cloud import at Step 15, through the Rust worker or a Rust service)
- Option A merged and the CLI on the scanner; no `PDFDocument.load` on any
untrusted input in the browser.
@@ -108,7 +108,7 @@ hides its `/Keywords`, so a stripped attachment on such a file reads as
`endstream` search over candidates sorted by data offset and bounded to
the cap, and no JSON parse for a candidate not opening on `{` or nesting
brackets deeper than 64 levels (linear byte pre-scan, strings skipped).
- Option C or a server-side import (Step 14) with a hard memory and time
- Option C or a server-side import (Step 15) with a hard memory and time
budget per file, for any path that still parses PDF objects.
- Dependency decision on pdf-lib (unmaintained since 2021): closed at R4.8
(2026-10-19): pdf-lib left the repository with the TypeScript engine; the
@@ -155,7 +155,7 @@ only; a refused import leaves the tab's texts in place: app suites
| 12 | Report collection caps on read (observations, zones, findings per observation) | §5 item "collection caps" | before public exposure | out of R4 (plan A11); today bounded by `MAX_JSON_VALUES` (400,000 values, 10 × the CAP envelope of 500 observations: a report of about 5,000 observations at the CAP density at most) and by the export's caps (500 × 8 views, closed kind); a dense hostile report slows the editor but cannot exhaust it |
| 13 | `<use>` nesting and reference budget on the PDF path | §5 "remaining low findings" | fixed with proof | every SVG the export composes went through the core's one reader (R3: cycles refused, expansion > 50,000 elements refused, prescan caps); `ExportInput` runs `read_svg` per asset (R4.4); cargo `svg_sanitiser`, `pdf_layout` |
| 14 | PNG logo decoder envelope (4096² cap, four logos) | §5 "remaining low findings" | fixed with proof | the application exports the bundled logos only (`src/assets/brand`, never the archive's branding: `export_from_envelope` is cargo-only); the gate refuses above 8192 px a side, 4096² pixels or 16 MiB of raw scanlines before any allocation (`PNG_MAX_*`, cargo `pdf_png` 108 cases + budget cases); the session frees the planes at `add_raster` |
| 15 | Option C or a server-side import for any path that still parses PDF objects | §5 item 4 | before public exposure | no such path exists today; applies to Step 14 if a server-side reader is introduced |
| 15 | Option C or a server-side import for any path that still parses PDF objects | §5 item 4 | before public exposure | no such path exists today; applies to Step 15 if a server-side reader is introduced |
| 16 | pdf-lib (unmaintained since 2021) | §5 item 5 | fixed with proof | left the repository at R4.8; `r4.census` |
| 17 | Stamped PDFs saved with object streams (before Step 6) read a stripped attachment as `no_attachment` | §4 trade-off | accepted temporarily | pre-Step-6 files only, same outcome as a foreign PDF, no data at stake; documented in PDF-FORMAT |
| 18 | Imports offered to external users | §5 gate | before public exposure | the gate stays closed: the import is a local-tool feature; opening it needs items 3, 9 and 12 closed and a fresh audit of the worker path |
@@ -1,6 +1,11 @@
# Repository migration map
Status: Step 0 deliverable, 2026-10-08. Branch `develop` at `2ae1e48`.
Snapshot notice (2026-10-25, P0): every REMOVE / REPLACE verdict below has been
executed except `practitionerCache.ts` (still used by the local tool); the file
paths, counts and the `anatomical-sheets` bucket name are those of 2026-10-08
(the bucket is `anatomical-sheet-assets`). Kept as the record of the starting
point; `CLAUDE.md` holds the current map.
Sources: `faunosteo-business-architecture.md` (target), `docs/faunosteo-audit/`
(current behaviour, audited at `83e40af`), direct reading of `src/`, `public/`,
`docker/`, `tests/`, `scripts/`.
+9
View File
@@ -3,6 +3,15 @@
Status: Step 0 deliverable, 2026-10-08. Current state: 32 files under
`tests/unit/`, 180 `it(` cases, vitest 3 + happy-dom, no browser, no e2e
(audit 13). All green per TODO as of 2026-07-12; not re-run in Step 0.
Revised 2026-10-25 (P0): counts on `develop` (2026-10-25 inventory): vitest
app 446, core-wasm 60, supabase 40; cargo core 383, worker 33 native + 16
Docker sandbox; 11 pgTAP files under the flat `supabase/tests/`. The locations
`apps/app/tests/components`, `apps/app/tests/integration`, `apps/app/e2e`,
`supabase/tests/{db,rls}` and `supabase/seed/test/` in §1 and §3 are planned,
not created; the real-stack e2e lives in `packages/supabase/tests/e2e`. No
real-browser suite exists yet (TODO RR-8; V1-1 contract §8.4 proposes the
first one). No CI has ever run (BDR-047): "CI" in the tables means the
prepared workflow.
## 1. Layers