docs(docs): R0 owner decisions, A1-A15 table, R3 SQL checkpoint proposal
This commit is contained in:
1 parent
95009069ca
commit
84aba41b7d
5 files changed
+196
-32
No files matched your search
@@ -1,6 +1,9 @@
|
||||
# Dedicated manual trial stack: technical plan
|
||||
|
||||
Status: PROPOSAL, 2026-11-09 (owner brief « V1-2.6 UX — Arbitrages du premier essai propriétaire », §5). Plan
|
||||
Status: PROPOSAL, 2026-11-09 (owner brief « V1-2.6 UX — Arbitrages du premier essai propriétaire », §5), with the
|
||||
decisions of the brief « R0 — Décisions propriétaire et dernière validation graphique » (2026-11-09, BDR-108): name
|
||||
`pnpm db:trial`, two trial accounts, `db:sandbox trial*` kept for now, isolation from the suites, volumes preserved,
|
||||
resources capped, secrets renewable. Plan
|
||||
only: no stack is created, started, reset or removed, no script changes, existing data untouched. Implementation
|
||||
needs its own owner authorisation. Companion of `V1-2-6_U1_CORRECTIONS.md`.
|
||||
|
||||
@@ -61,7 +64,10 @@ gateway does (:422-423).
|
||||
never argv. Generated once at creation; `start` never regenerates them (the database keeps the role passwords set at
|
||||
its first initialisation). Keys valid one year instead of 30 days, with a `rotate-keys` command that re-signs both
|
||||
keys with the same secret and restarts the services: a persistent stack with the sandbox's 30-day keys would lock
|
||||
itself out after a month. Since every secret differs from the sandbox's, a suite that reached a trial port by mistake
|
||||
itself out after a month. Full renewal (owner 2026-11-09) is `rotate-secrets`: a new JWT secret and new keys, new role
|
||||
passwords set in the database (`alter role … password`, values through psql variables, never argv), env files
|
||||
rewritten (600), services restarted in order, the previous secrets file kept as `secrets.prev.sh` (600) until the
|
||||
stack answers; account passwords are untouched. Both commands print no secret. Since every secret differs from the sandbox's, a suite that reached a trial port by mistake
|
||||
would be refused by GoTrue, PostgREST and Postgres instead of writing.
|
||||
|
||||
### 3.4 Persistence and lifecycle
|
||||
@@ -83,10 +89,16 @@ would be refused by GoTrue, PostgREST and Postgres instead of writing.
|
||||
|
||||
- Migrations of the branch, then `equine_draft.sql` only. Not `seed.sql`: its three accounts carry the public DEV
|
||||
password (`seed.sql:5`).
|
||||
- Trial accounts: `account <email>` creates a confirmed account through GoTrue's admin API, password at a hidden
|
||||
prompt (12 characters minimum), as `cmd_trial_account` does (`db-sandbox.sh:457-472`); `grant <email> <right>` as
|
||||
`cmd_trial_grant` (:476-496), plus the platform role `owner` if the owner wants the rights screen (arbitration A13).
|
||||
Administration then asks for a TOTP factor, enrolled in Mon compte.
|
||||
- Trial accounts (owner 2026-11-09: two distinct accounts): `account <email>` creates a confirmed account through
|
||||
GoTrue's admin API, password at a hidden prompt (12 characters minimum), as `cmd_trial_account` does
|
||||
(`db-sandbox.sh:457-472`); `grant <email> <right>` as `cmd_trial_grant` (:476-496).
|
||||
1. Owner/admin account, for the administration trials: platform roles `owner` and `admin`, catalogue rights
|
||||
`sheet_editor`, `sheet_reviewer`, `sheet_publisher`.
|
||||
2. Practitioner account, for the normal journey: `sheet_editor` only, no `owner`, no reviewer or publisher right.
|
||||
Fact to weigh: today a `sheet_editor` right is active only for a platform admin (rule O1,
|
||||
`supabase/migrations/20261028100000_sheet_access_hardening.sql:199`), so this account also needs the `admin`
|
||||
role; without it, it can read the catalogue (`catalog_reader`) but not edit. Changing O1 is out of scope.
|
||||
Editing and Administration require a TOTP factor (aal2, same file :321-341), enrolled in Mon compte by each account.
|
||||
- The equine sheet: the seed gives the historical sheet its fixed id and `private.historical_sheet_id()` flags it
|
||||
(`20261102100000_sheet_admin_reads.sql:56`); it is the only official sheet at creation.
|
||||
- Its drawings: the existing tool `pnpm assets:upload supabase/seed/anatomical-sheets/equine/draft` (R5.5), through
|
||||
@@ -113,7 +125,7 @@ sandbox up, about 2 GiB of 14.7 GiB. DEV shares no name, port, network, volume o
|
||||
|
||||
## 4. Commands (proposal, arbitration A11)
|
||||
|
||||
`pnpm db:trial create | start | stop | status | migrate | backup | rotate-keys | app | account <email> |
|
||||
`pnpm db:trial create | start | stop | status | migrate | backup | rotate-keys | rotate-secrets | app | account <email> |
|
||||
grant <email> <right> | assets | destroy`, in a new `scripts/db-trial.sh` built on the sandbox script's functions
|
||||
(shared helpers extracted to one sourced file rather than copied).
|
||||
|
||||
@@ -131,8 +143,8 @@ they created; `shellcheck` on both scripts.
|
||||
|
||||
| # | Question | Recommendation |
|
||||
|---|---|---|
|
||||
| A11 | Command name, prefix, ports | `pnpm db:trial`, `faunosteo_trial_`, 58xxx and 5194 as in 3.2. |
|
||||
| A12 | Fate of `pnpm db:sandbox trial`, `trial-account`, `trial-grant` | Removed once the trial stack is validated: one trial path. |
|
||||
| A13 | Platform roles of the owner's trial account | `admin` with the catalogue rights, plus `owner` only if the rights screen is part of the trial. |
|
||||
| A14 | Key lifetime | One year, with `rotate-keys`. |
|
||||
| A11 | Command name, prefix, ports | `pnpm db:trial` (RATIFIED), `faunosteo_trial_`, 58xxx and 5194 as in 3.2 (open). |
|
||||
| A12 | Fate of `pnpm db:sandbox trial`, `trial-account`, `trial-grant` | DECIDED: kept for now, neither removed nor silently redirected. |
|
||||
| A13 | Trial accounts | DECIDED: two accounts (3.5). Open: confirm the practitioner account takes `admin` because of O1. |
|
||||
| A14 | Key lifetime and renewal | Renewal DECIDED (`rotate-keys`, `rotate-secrets`); one-year lifetime open. |
|
||||
| A15 | Backup before every `migrate` | Automatic, kept in the state folder, never pruned without the owner. |
|
||||
@@ -0,0 +1,67 @@
|
||||
# R3 SQL checkpoint: a true last-modification date for the sheet list
|
||||
|
||||
Status: PROPOSAL for the owner's dedicated SQL checkpoint, 2026-11-09 (brief « R0 — Décisions propriétaire et
|
||||
dernière validation graphique », A7). Nothing here is written as a migration; no SQL, application, script or sandbox
|
||||
change before the owner authorises this checkpoint. Companion of `V1-2-6_U1_CORRECTIONS.md` (lot R3).
|
||||
|
||||
## 1. The problem
|
||||
|
||||
The admin list and the sheet page read `private.official_sheet_admin_summary` (`supabase/migrations/
|
||||
20261102100000_sheet_admin_reads.sql:40-92`), which returns `anatomical_sheets.updated_at` (:54). A draft save writes
|
||||
`anatomical_sheet_versions` only (`public.save_sheet_draft`, `20261028110000_sheet_review_workflow.sql:569-630`), so
|
||||
the sheet row's date does not move when a draft is edited. Read on the sandbox (2026-11-09, select only): 28 of 219
|
||||
official sheets have a version newer than the sheet row, up to 15 s apart; the fixed historical draft and the owner's
|
||||
`cheval11` happen to agree. The owner's rule until this lands: no creation date shown as a modification date, no
|
||||
misleading sort.
|
||||
|
||||
## 2. Proposed change (one read change, no table, policy or privilege change)
|
||||
|
||||
A new migration replaces `private.official_sheet_admin_summary` with the same body plus one key:
|
||||
|
||||
```sql
|
||||
'last_modified_at', greatest(s.updated_at, (
|
||||
select max(v.updated_at) from public.anatomical_sheet_versions v where v.sheet_id = s.id))
|
||||
```
|
||||
|
||||
- `greatest` ignores a null, so a sheet without a version keeps its own date.
|
||||
- Both columns are kept by the existing `set_updated_at` triggers (`20261008110000_anatomical_sheets.sql:90-92`,
|
||||
:143-145): a draft save, a status change, a publication, an archive, a metadata edit and the working copy's own
|
||||
writes all move one of them. Review rounds and audit rows are not modifications of the sheet and do not count.
|
||||
- The per-sheet `max` uses the existing unique index on `(sheet_id, version_number)` (:118) for the lookup by
|
||||
`sheet_id`; the list is already one summary call per sheet, so the cost is one more indexed aggregate per row. RR-13
|
||||
(server paging) will sort on the same expression.
|
||||
- `get_official_sheet_admin` and `list_official_sheets_admin` both call the summary and return the key unchanged;
|
||||
their signatures, `security definer`, `search_path` and grants are untouched (the revokes at
|
||||
`20261102100000_sheet_admin_reads.sql:244` stay in force).
|
||||
- `updated_at` stays in the payload with its current meaning; nothing that reads it changes.
|
||||
|
||||
## 3. Verification the checkpoint asks for
|
||||
|
||||
- pgTAP in `supabase/tests/022_sheet_admin_reads.sql`: a draft save moves `last_modified_at` and not `updated_at`; a
|
||||
sheet metadata change moves both; a sheet without a version answers its own date; the key is present for every
|
||||
listed sheet; the call rights unchanged (existing tests :186-190 re-run).
|
||||
- `pnpm --filter @faunosteo/supabase test:run` (PGlite) and `pnpm db:test` on a real stack.
|
||||
- `pnpm db:types`: the functions return `jsonb`, so the generated types do not change; the hand-written summary type
|
||||
in `packages/supabase/src/sheets.ts` gains `last_modified_at`.
|
||||
|
||||
## 4. Applying it to a stack: an owner decision
|
||||
|
||||
`scripts/db-sandbox.sh` has no command that applies a new migration to a running sandbox: `up upgrade` builds a new
|
||||
one, which removes the current sandbox (owner rule: inventory, then a go for that operation). Three paths, none taken
|
||||
without the owner:
|
||||
|
||||
| Path | Effect |
|
||||
|---|---|
|
||||
| a. Apply to the trial stack once it exists (`pnpm db:trial migrate`, `TRIAL_STACK.md` §3.4) | No sandbox change; the owner sees the date in the trial |
|
||||
| b. A `migrate` command added to `db-sandbox.sh` (forward only, no reset) | A script change, its own go; keeps the sandbox's data |
|
||||
| c. `pnpm db:sandbox up upgrade 2026…` on a new sandbox | Removes the current sandbox: inventory and owner go first |
|
||||
|
||||
Recommendation: a (with b only if the shell suite must see the date before the trial stack exists). PGlite and
|
||||
`pnpm db:test` need no existing stack.
|
||||
|
||||
## 5. What R3 does before and after
|
||||
|
||||
- Before: search and clear, sort by name only, no date on the rows, the Administration card without a date or a
|
||||
« most recent » claim (the first five by name, with « Voir les N fiches »).
|
||||
- After: « Modifiée le … » from `last_modified_at`, « Dernière modification » as the default sort, the card listing the
|
||||
five most recently modified sheets. Boards 28 and 29 draw this final state.
|
||||
@@ -69,7 +69,8 @@ reference of R1 to R4.
|
||||
first (it has no explicit handler today).
|
||||
- Unit tests: deselect leaves the document text and the history length unchanged; undo after a deselect undoes the
|
||||
previous edit; the Escape matrix (dialog, menu, panel, tracing, nothing open) with one consumer each time; focus
|
||||
after « Désélectionner » on the annotation's list row (arbitration A6); accessible names of both history buttons in FR and EN; read-only modes
|
||||
after « Désélectionner »: the annotation's list row if it still exists, else the drawing, with no new selection
|
||||
and a polite announcement (A6 as ratified); accessible names of both history buttons in FR and EN; read-only modes
|
||||
show « Désélectionner » and no « Supprimer ».
|
||||
- E2E: the journeys that name « Annuler » / « Rétablir » rewritten one for one; a new desktop spec for the button and
|
||||
Escape; axe on Annotations with a selection.
|
||||
@@ -98,7 +99,8 @@ reference of R1 to R4.
|
||||
- Unit tests (about 15 files today assert the four-tab structure or the panel): five tabs and the « Plus » tier at
|
||||
500 px; each sort, stable, document untouched (text compared before and after); reorder commands present only in
|
||||
document order without search; clear button; tile disclosure and focus; « Aller à » from Vérification opens the
|
||||
tab, the tile open and focused; « Aller à » from a tile reaches the finding; the panel from a finding: filtered,
|
||||
tab, the tile open and focused; « Aller à » from a tile reaches the finding; the panel from a finding: filtered, « Retirer de ce constat » removes only that citation (the reference
|
||||
stays in the document) and one undo restores it,
|
||||
« Tout afficher » opens the tab with search and sort reset and focus on its heading, close returns focus to the
|
||||
finding's button; unsaved edits in a tile form survive a tab change (kept-mounted places); no edit control in any
|
||||
read-only mode or without the editor right; the reduced-motion class.
|
||||
@@ -120,7 +122,9 @@ reference of R1 to R4.
|
||||
the sandbox, 28 of 219 official sheets have a version newer than the sheet row. A true « dernière modification »
|
||||
needs one read change in SQL (a `last_modified_at` field, greatest of the sheet's and its versions' `updated_at`,
|
||||
in `private.official_sheet_admin_summary`; no table, policy or privilege change), hence an SQL checkpoint, pgTAP,
|
||||
regenerated types, and its application to the sandbox, which needs the owner's go for that operation.
|
||||
regenerated types, and its application to a stack, which needs the owner's go for that operation. Ratified (A7):
|
||||
the dedicated checkpoint is `V1-2-6_R3_SQL_CHECKPOINT.md`; R3 ships in two steps, search and name sort with no date
|
||||
first, the date, the date sort and the « most recent » card only once the SQL change is authorised and applied.
|
||||
- Search and sort run in the browser on the full list: `shortcut:` until RR-13 pages the list on the server, where
|
||||
search and sort move with it.
|
||||
- Tests: unit for search (accents, both languages, empty, clear), sort (date ties by name, collation), date format
|
||||
@@ -141,7 +145,7 @@ reference of R1 to R4.
|
||||
## 4. Order and dependencies
|
||||
|
||||
R0 first (validation). R1 is independent of R2 and can ship first. R2 depends on the validated boards 23 to 27. R3
|
||||
depends on arbitration A7; with the SQL option, its migration goes through its own checkpoint before the UI part.
|
||||
ships search and name sort first; its date part waits for the SQL checkpoint (A7 ratified).
|
||||
R4 is independent and may run any time after its board (30) is validated. Anomaly B (section 5) should land before
|
||||
the gates of R2 and R3 are read, since its taken slot fails four admin specs on every run.
|
||||
|
||||
@@ -153,19 +157,26 @@ the gates of R2 and R3 are read, since its taken slot fails four admin specs on
|
||||
| B. Working copy never archived | `packages/supabase/tests/sandbox/sheets-admin.sandbox.ts:181-195` creates the historical sheet's working copy (`8c315a12-…`, 2026-11-08 21:00:30) and never archives it; the single slot then disables « Créer une copie de travail » (`WorkingCopyAction.tsx:88`) and fails `admin.spec.ts:717` four times. | Make the suite independent (its own cleanup, or a precondition it creates and removes); the existing copy is not touched before the owner authorises it. |
|
||||
| C. Silent card failure | Section 3, R4. | Show the failure, never hide or route around it. |
|
||||
|
||||
## 6. Arbitrations for the owner
|
||||
## 6. Arbitrations
|
||||
|
||||
| # | Question | Recommendation |
|
||||
|---|---|---|
|
||||
| A1 | Reorder commands with a search active in document order | Hidden, as checkpoint choice 10 already rules (moving among a hidden subset is ambiguous); one hint line. |
|
||||
| A2 | Tiles open at once; how long open state, search and sort last | Several open at once; kept while the editor stays open (kept-mounted tab), reset when it reopens. |
|
||||
| A3 | Actions in the contextual panel | Modifier, « Aller à »; no add, no reorder. Every reference in the panel is cited by the finding, so « Supprimer » would always be refused by the core (no dangling reference): offer « Retirer de ce constat » (removes the id from the finding's citations, an ordinary undoable edit) instead, or nothing. « Tout afficher » opens the tab with search and sort reset, focus on its heading. |
|
||||
| A4 | Closed tile content | Citation on two lines at most, type, « Citée par N constats » or « Non citée ». |
|
||||
| A5 | Escape priority | Dialog, then open menu, then contextual panel, then tracing in progress, then selection. |
|
||||
| A5b | « Toutes les annotations » (top of the properties panel) already clears the selection | Keep both: « Désélectionner » sits where the eye is after acting on an annotation, as decided (D6); the top entry keeps its role of returning to the list. Alternative: rename the top entry. |
|
||||
| A6 | Focus after « Désélectionner » (the button leaves with the selection) | The annotation's row in the list, as « Toutes les annotations » already does (`PropertiesPanel.tsx:92-102`, `focusRow`). |
|
||||
| A7 | Source of the last-modification date | SQL read change `last_modified_at` with its own checkpoint (recommended). Without it, label the row « Fiche modifiée le » and accept that draft saves do not move it. |
|
||||
| A8 | Date format | Absolute, « 9 nov. 2026, 12:06 » (EN « 9 Nov 2026, 12:06 »). |
|
||||
| A9 | Administration home card | The five most recently modified sheets with species, status and date, then « Voir les N fiches ». |
|
||||
| A10 | Catalogue warning wording | FR « Contrôle d'intégrité échoué : cette version ne peut pas être affichée. », a distinct line for a load that failed for another reason. |
|
||||
| A11 to A15 | Trial stack: names, ports, old trial commands, account roles, key lifetime, backups | `TRIAL_STACK.md` section 6. |
|
||||
Status as of the brief « R0 — Décisions propriétaire et dernière validation graphique » (2026-11-09, BDR-108).
|
||||
The owner-facing table with consequences, in French: `docs/design/v1-2-6-r0/ARBITRAGES.md`.
|
||||
|
||||
| # | Question | Recommendation | Status |
|
||||
|---|---|---|---|
|
||||
| A1 | Reorder commands with a search active in document order | Hidden, as checkpoint choice 10 already rules (moving among a hidden subset is ambiguous); one hint line. | open |
|
||||
| A2 | Tiles open at once; how long open state, search and sort last | Several open at once; kept while the editor stays open (kept-mounted tab), reset when it reopens. | open |
|
||||
| A3 | Actions in the contextual panel | « Modifier », « Retirer de ce constat », « Aller à »; no add, no reorder, no « Supprimer » (always refused by the core there). « Tout afficher » opens the tab with search and sort reset, focus on its heading. | RATIFIED: « Retirer de ce constat » removes only the finding's citation of the reference, never the reference; undoable through the editor history |
|
||||
| A4 | Closed tile content | Citation on two lines at most, type, « Citée N fois » or « Non citée » (the count includes families). | open |
|
||||
| A5 | Escape priority | Dialog, then open menu, then contextual panel, then tracing in progress, then selection. | open |
|
||||
| A5b | « Toutes les annotations » already clears the selection | Keep both (D6). | open |
|
||||
| A6 | Focus after « Désélectionner » | The annotation's row in the list. | RATIFIED with precision: the row if it still exists, else the drawing; focus never selects again; an accessible announcement |
|
||||
| A7 | Source of the last-modification date | SQL read change `last_modified_at`, own checkpoint. | RATIFIED: dedicated SQL checkpoint `V1-2-6_R3_SQL_CHECKPOINT.md`; until then no creation date shown as a modification date and no misleading sort |
|
||||
| A8 | Date format | Absolute, « 9 nov. 2026, 12:06 » (EN « 9 Nov 2026, 12:06 »). | open |
|
||||
| A9 | Administration home card | The five most recently modified sheets with species, status and date, then « Voir les N fiches ». | open (needs A7 first) |
|
||||
| A10 | Catalogue warning wording | FR « Contrôle d'intégrité échoué : cette version ne peut pas être affichée. », a distinct line with « Réessayer » for a load that failed for another reason. | R4 ACCEPTED as an independent display fix, the fingerprint check unchanged; wording open |
|
||||
| A11 | Trial stack command | `pnpm db:trial`, prefix `faunosteo_trial_`, ports 58xxx and 5194. | RATIFIED: `pnpm db:trial`; prefix and ports open |
|
||||
| A12 | Old `db:sandbox trial*` commands | Remove once the trial stack is validated. | DECIDED otherwise: kept for now, neither removed nor silently redirected |
|
||||
| A13 | Trial accounts | `admin` with catalogue rights, `owner` if needed. | DECIDED: two accounts, an owner/admin account and a practitioner account with the editing rights (see `TRIAL_STACK.md` §3.5 on rule O1) |
|
||||
| A14 | Key lifetime and secret renewal | One year, `rotate-keys`. | Renewal RATIFIED (`TRIAL_STACK.md` §3.3); lifetime open |
|
||||
| A15 | Backup before every `migrate` | Automatic, kept, never pruned without the owner. | open (volumes preserved: ratified) |
|
||||
Reference in new issue
Block a user