260 lines
19 KiB
Markdown
260 lines
19 KiB
Markdown
# Open questions, contradictions and flagged decisions
|
|
|
|
Status: Step 0 deliverable, 2026-10-08. Two lists: (A) contradictions,
|
|
ambiguities or technically risky points found when confronting
|
|
`faunosteo-business-architecture.md` with the code and the audit, and (B)
|
|
questions for the developer that change architecture or development order.
|
|
Items that are merely interesting are left out.
|
|
|
|
## Status (revised 2026-10-25, P0 and V1-1 ratification)
|
|
|
|
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 | settled (owner ratification 2026-10-25, BDR-073) | records belong to a workspace (`workspaces`, `workspace_members`; one personal workspace per practitioner in V1-1, cabinet workspaces later without destructive transfer); no global directory shared between practitioners, no data visible between them; contract `V1-1_OWNERS_ANIMALS.md` §4, D2 |
|
|
| C5 animal update rights | settled (owner ratification 2026-10-25, BDR-073) | 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; V1-1 contract §6.1, §6.4 |
|
|
| C6 unverified accounts | settled (owner ratification 2026-10-25, BDR-073) | email confirmed, professional status verified and platform role are three distinct notions; a confirmed email gives private use of the workspace; verification (Step 9) required later for public features presenting a verified professional; no verified status by default; statuses are not platform roles (BDR-026); V1-1 contract §6.2. Replaces the 2026-10-08 assumption below (no clients or reports before verification) |
|
|
| 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) settled by C4 | (a) as C2; (b) no shared record (C4 ratified), so edit rights live inside a workspace (V1-1 contract §6) |
|
|
| 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`.
|
|
Superseded for official sheets (owner, 2026-10-27, D9, BDR-081; decisions
|
|
ratified 2026-10-28, BDR-082): V1-2 brings the editor of official sheets,
|
|
with server-verified review and publication (`V1-2_ANATOMICAL_SHEETS.md`).
|
|
The curation pipeline stays the authority of the historical equine sheet
|
|
only; equine work moves to an application working copy (O17).
|
|
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.
|
|
Resolved (owner, 2026-10-27 and 2026-10-28; BDR-081, BDR-082): drafts are
|
|
never served to readers (D3); an editor submits, a reviewer outside the
|
|
author set approves, a publisher publishes (O1, O2); the historical equine
|
|
sheet is never published and its review is prepared on a working copy,
|
|
whose publication stays an owner act after the business review, outside
|
|
V1-2 (O17, O18).
|
|
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)
|
|
|
|
§7.2 shows `"vertebral_formula": { "C": 7, "T": 13, "L": 7, "S": 3, "Cd": 20 }`,
|
|
the same fixed five-key object as today's `VertebralFormula`. §23.2 asks to
|
|
"remove hard-coded five-region assumptions from generic domain code". The
|
|
canonical document must use an ordered list of regions `{ code, label_fr,
|
|
label_en, count }` and the report must store the region code, otherwise the
|
|
report schema keeps the `z.enum(['C','T','L','S','Cd'])` of
|
|
`observation.ts:7`. This plan assumes the ordered list. See also Q3.
|
|
|
|
### C2. Report-only manual points vs "report references an immutable sheet version" (§3.2 step 7, rule 3)
|
|
|
|
"A manually created point exists only in this report until promoted to a
|
|
personal sheet." Such a point is not in any sheet version, so the report
|
|
document must carry `localAnnotations[]` (geometry, view id, names, optional
|
|
finding free text) and the PDF must render them. The architecture does not
|
|
say where they live or how promotion rewrites the report (does the report
|
|
then reference a *new* version of the personal sheet?). Decision needed
|
|
before the report document v3 is frozen. See Q6.
|
|
|
|
### C3. Worker on day one (§21.1) vs PostgreSQL-backed jobs first (§22.3)
|
|
|
|
Not a contradiction in substance, but the monorepo tree lists `apps/worker`
|
|
as if it existed from the start. The plan creates it at the first job that
|
|
cannot be a SQL function (reminders / calendar sync).
|
|
|
|
### C4. Global client record shared across practitioners (§2.3, §6)
|
|
|
|
`clients` is "a global Faunosteo person record, not a copy per practitioner".
|
|
Two practitioners with a care relationship to the same person then edit the
|
|
same `first_name`/`last_name`/`notes_general`. Risks: one practitioner's edit
|
|
silently changes another's records; `notes_general` is clinical-adjacent and
|
|
must not be shared by default. The architecture also requires that identity
|
|
matching never reveals another relationship. The plan assumes: core identity
|
|
fields editable only by the creating practitioner or the claimed client
|
|
account, per-relationship notes in a separate table, and a verification flow
|
|
for linking. Q6 asks for confirmation. **Technically dangerous if left as a
|
|
plain shared row.**
|
|
|
|
### C5. Animal update rights "owner-controlled" (§17.3) with no client accounts in MVP (§20)
|
|
|
|
In the MVP the owner has no login. The rule "update is owner-controlled, with
|
|
practitioner update permitted only after a consultation context or explicit
|
|
owner permission" is unenforceable as written. Plan assumption: the
|
|
practitioner who created the animal (or an org member with the relationship)
|
|
can update it; owner control starts with the client portal (post-MVP).
|
|
|
|
### C6. What an unverified account may do (§3.1, §5)
|
|
|
|
"A non-verified account must not access full professional functionality."
|
|
Ambiguous: may it create clients/animals and drafts? May it complete a report?
|
|
Plan assumption: unverified = can set up profile, cabinet invitation
|
|
acceptance, browse public sheets; cannot create clients/animals/reports.
|
|
Affects the entitlement capability list. Confirm.
|
|
|
|
### C7. Vocabulary collision on "Observation" (audit 05 §1)
|
|
|
|
In the code an `Observation` is a group of zones + findings + severity +
|
|
comment; in the catalog "Observations / motifs de consultation" is a finding
|
|
category; the architecture lists "finding/observation/anamnesis tree". The
|
|
product vocabulary must fix one word for each before UI strings and schema
|
|
names are created in the SaaS. Plan uses: *Observation* = the report block
|
|
(unchanged), *Finding* = a leaf, *Finding category* = a tree root.
|
|
|
|
### C8. Multiple drafts per sheet (§7.1)
|
|
|
|
`anatomical_sheet_versions.status ∈ {draft, published, deprecated}` and
|
|
`current_version_id` on the sheet. Nothing says whether a sheet may hold more
|
|
than one draft at a time or who may edit a draft (creator only? org
|
|
members?). Plan assumption: at most one draft per sheet, editable by the
|
|
creator; a unique partial index enforces it.
|
|
|
|
### C9. Detail view storage: separate SVG asset vs viewBox on the parent asset (§7.3 vs audit 04)
|
|
|
|
`Horse_head.svg` is a full copy of `Horse.svg` with a different `viewBox` and
|
|
its own overlays (audit 04 §2). §7.2 gives every view its own
|
|
`svg_asset_id`. The future editor's "create detail from a zone" naturally
|
|
produces a `view_box` on the *same* asset. Plan assumption: `svg_asset_id`
|
|
nullable on detail views; null means "render the parent asset with this
|
|
`view_box`". The equine seed may keep two assets to stay byte-faithful to the
|
|
source files. Q5 asks which.
|
|
|
|
### C10. Edge Functions on self-hosted Supabase (§22.2, §31) on a 1 vCPU / 1 GB VPS (DEPLOY.md)
|
|
|
|
The current runbook provisions 1 vCPU / 1 GB. A self-hosted Supabase stack
|
|
(Postgres, GoTrue, PostgREST, Storage, Kong, Studio, edge-runtime, Realtime,
|
|
imgproxy) needs several GB of RAM and is operationally heavy for one person.
|
|
Either the VPS is upgraded, or the launch uses managed Supabase from day one
|
|
(the architecture's "stage 2" contract is the same schema anyway). This
|
|
changes Step 3 and the deploy runbook. Q2.
|
|
|
|
### C11. Free-plan quota counted on "completed" reports but editing a completed report is allowed 5 days (§1.2)
|
|
|
|
Consistent, but note the interaction with revisions: a restore of an old
|
|
revision after the 5-day window is an edit and must be denied for free
|
|
accounts. The plan treats *any* write to a completed report as
|
|
`reports.edit_after_free_window` after `free_edit_until`.
|
|
|
|
### C12. SVG sanitization "server-side before becoming available to others" (§15.3) vs direct-to-Storage uploads
|
|
|
|
Supabase Storage uploads go straight from the browser to the bucket. The
|
|
sanitizer must therefore run between upload and publication (quarantine
|
|
prefix + status column + policy), not "on upload". Designed in
|
|
`BACKEND_ARCHITECTURE.md` §5; flagged because a naive implementation would
|
|
ship the client sanitizer as the boundary, which the audit already marks
|
|
insufficient (F1).
|
|
|
|
### C13. CLAUDE.md rules that the migration necessarily breaks
|
|
|
|
- "domain/schema/*.ts are the data contracts, never change without bumping version": honoured (v3).
|
|
- "Ask before any change to importReportFromPdf or extractReportJson": honoured as a confirmation gate in the PDF step.
|
|
- "Never modify anatomy SVGs in public/species/": honoured; the importer reads, never writes them.
|
|
- "Each entry needs ≥1 source with citation": violated today by all 792 nodes (audit 05 §2.4). Either the rule is relaxed for the official seed or sources are authored before publication. Plan assumption: relaxed, `sources` optional, a warning in the editor.
|
|
- "React SPA exception" (BDR-001): still valid for `apps/app`; the public site is the SSR part.
|
|
|
|
### C14. Report locale not persisted (BDR-014) vs stored PDF artifacts
|
|
|
|
Server-stored PDFs must record the locale they were rendered in (artifact
|
|
metadata), otherwise re-rendering from the snapshot cannot reproduce the
|
|
document. Not a schema change on the report document; an artifact column.
|
|
|
|
## B. QUESTIONS POUR LE DEVELOPPEUR
|
|
|
|
Only questions whose answer changes the architecture or the order of work.
|
|
|
|
### Q1. Are there Faunosteo PDFs (report v2) in real use that must import into the SaaS?
|
|
|
|
- What: whether practitioners (or the client osteopath) hold exported PDFs today.
|
|
- Why: decides if the `v2ToV3` + legacy-id reconciliation path is production code with its own UI (quota, mapping review) or a dev-only adapter kept for regression tests (architecture §23.4 assumes no install base; CHANGELOG 0.1.0 says the same, but faunosteo.com is live per TODO Phase C).
|
|
- How to answer: ask the client; check the live site usage if any analytics exist (none in the repo).
|
|
|
|
### Q2. Hosting target for the first steps: self-hosted Supabase on an upgraded VPS, or managed Supabase?
|
|
|
|
- What: RAM/CPU available on the Scaleway VPS, and whether running the full Supabase Docker stack (plus Edge Functions) is acceptable operationally.
|
|
- Why: changes Step 3 (local dev is identical, but the deploy runbook, backups, Edge Function deployment and cost differ), and whether Edge Functions are used at all before the agenda/widget steps.
|
|
- How to answer: `DEPLOY.md` says 1 vCPU / 1 GB; confirm the plan for the box (`free -m`, `nproc` on the VPS) and the budget.
|
|
|
|
### Q3. Must the vertebral model support non-mammalian layouts (birds) in the MVP data model?
|
|
|
|
- What: the species list. README cites dog, cat, goat, cow, pig, rabbit, donkey, sheep; TODO Phase D cites "chicken". Birds have fused regions (notarium, synsacrum, pygostyle).
|
|
- Why: with an ordered region list (C1) any mammal fits; birds need fused/variable regions and change the picker. Deciding now avoids a document schema v2 right after launch.
|
|
- How to answer: product decision; the model in this plan (ordered region list with free codes) covers birds if region labels are free, so the answer only affects the picker UI.
|
|
|
|
### Q4. Is `public/pathology-editor.html` used today by an external domain expert?
|
|
|
|
- What: BDR-022 mentions a "domain expert" authoring the catalog; audit 11 could not tell whether the static tool is their workflow.
|
|
- Why: if yes, it must keep working against a JSON export of the official sheet during the editor-merge step and gets a documented export/import bridge; if no, it is deleted with the SVG editor.
|
|
- How to answer: ask the expert; check whether any `pathologies-equine-<timestamp>.json` exports exist outside the repo.
|
|
|
|
### Q5. Equine seed: two SVG assets (byte-faithful to `Horse.svg` and `Horse_head.svg`) or one asset + `view_box` for the head?
|
|
|
|
- What: storage shape of the official sheet v1.
|
|
- Why: affects the sheet document schema (`svg_asset_id` nullable), the renderer, the PDF detail view, and the "create detail view" editor feature. Two assets keep the files untouched; one asset halves storage and matches the future editor.
|
|
- How to answer: product/technical choice; recommendation is nullable `svg_asset_id` and two assets for v1 only.
|
|
|
|
### Q6. Report-only manual points and shared client records: where do they live?
|
|
|
|
- What: (a) schema and rendering of points created inside a report and not in any sheet (C2); (b) edit rights on global client core fields and whether `notes_general` is shared (C4).
|
|
- Why: both freeze the report document v3 and the client RLS, which are the two hardest migrations.
|
|
- How to answer: product decision. Recommendation: (a) `localAnnotations[]` in the report document, rendered in the PDF, promotion creates a new personal-sheet version and rewrites the report to reference it; (b) core identity editable by creator or claimed client only, notes per relationship.
|
|
|
|
### Q7. Phone verification and transactional email providers
|
|
|
|
- What: which SMS provider and which email provider (EU processing).
|
|
- Why: phone verification is a sign-up gate (§3.1) and a referral prerequisite; without a provider decision Step 7 ships email-only verification and the referral rules cannot be tested end-to-end.
|
|
- How to answer: business decision; GoTrue supports Twilio, MessageBird, Vonage, Textlocal.
|
|
|
|
### Q8. Public site framework: Next.js (architecture §21.2) or Astro SSR (global rule "Astro by default")?
|
|
|
|
- What: the framework of `apps/public-web`.
|
|
- Why: toolchain, Docker image, SEO tooling for the public-profile step. Does not affect the private app.
|
|
- How to answer: decide at that step; default to Next.js as approved unless the global rule is meant to override.
|
|
|
|
### Q9. Catalog anomalies to normalise or preserve in the official seed
|
|
|
|
- What: `sphenoid.categories[0].id === 'ssb-dysfunctions'` (same id as under `ssb`), degraded category slugs (`charni-res-vert-brales`, `cadrans-du-cr-ne`), zero `sources`, zero `description_en`.
|
|
- Why: the importer is deterministic and the seed v1 is immutable once published; renaming later means v2 of the official sheet. Finding paths in future reports anchor on these ids.
|
|
- How to answer: domain expert review of `docs/faunosteo-audit/05-findings-editor.md` §2.4; recommendation: fix the `ssb-dysfunctions` id to `sphenoid-dysfunctions` before v1 (no report references it yet), keep slugs verbatim with human labels.
|