Files
faunosteo/docs/development/V1-2-6_R3_SQL_CHECKPOINT.md
T
bchanot a86020d6e3 docs(app): R3 sheet list documents as built, M9 applied
V1-2-6_U1_CORRECTIONS §R3 as built (A7 split superseded by D2, exact
results, deviations), the SQL checkpoint applied with corrections F2 to
F4, the owner's answers and the date limits F7, M9 in §12.3, db:sandbox
migrate, the sheet list spec and its named failures, class C rows, the
design deviations, CLAUDE.md and CHANGELOG. Gates pending.
2026-11-16 17:47:49 +01:00

148 lines
11 KiB
Markdown

# R3 SQL checkpoint: a true last-modification date for the sheet list
Status: APPLIED 2026-11-16 as M9 `supabase/migrations/20261116100000_sheet_admin_last_modified.sql`, on the
sandbox and on the trial stack (`pnpm db:trial`); DEV unchanged. History: design accepted by the owner, 2026-11-09
(verdict « R0 — Verdict de revue graphique propriétaire », BDR-109), after the brief « R0 — Décisions propriétaire et
dernière validation graphique » (A7); writing and applying it authorised by the owner on 2026-11-16 (section 6). The
split before and after this checkpoint (section 5) is superseded by the owner's decision D2: R3 shipped in one lot.
Sections 1 to 5 are the checkpoint as accepted on 2026-11-09, with the corrections of 2026-11-16 marked in place.
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.
Correction 2026-11-16 (F3): `pnpm db:test` runs `supabase test db` on the DEV stack, and V1-2 is sandbox only. The
real-PostgreSQL run is `pnpm db:sandbox test-db`, after the sandbox is migrated; DEV stays untouched.
- Correction 2026-11-16 (F4): a pgTAP file runs in one transaction, where `now()` is frozen and `set_updated_at`
stamps `now()`. « A draft save moves `last_modified_at` and not `updated_at` » cannot be seen on rows dated
`now()`, so the new fixture rows are dated in the past at insert (the trigger stamps updates only).
- `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.
Correction 2026-11-16 (F2, F3): path a alone was not enough. The shell suite runs on the sandbox, and once the
client requires the key every admin and editor spec fails at load on a stack without M9, and nothing would prove the
date on a real PostgreSQL. Both paths were taken: b first (`pnpm db:sandbox migrate`, forward only, additions
only to the script), then a, then the application code (owner decision D3). The last sentence above is
wrong for `pnpm db:test`, which runs on DEV (section 3).
## 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.
Superseded 2026-11-16 (owner decision D2): the « before » state was never built. R3 shipped once, in the « after »
state.
## 6. Owner's answers and application (2026-11-16)
Owner messages of 2026-11-16, verbatim in `.claude/tasks/contracts/2026-11-16-r3-sheet-list-1720.md`:
- Plan validation (rev 2): D1 yes (write M9 and its pgTAP), D2 yes (one delivery in the final state), D3 yes (the
sandbox through the new `pnpm db:sandbox migrate` without a reset, then `db:trial` after an operational checkpoint,
then the application), D4 yes (RR-13 widened to the paging of the admin lists, rights and official sheets, not
implemented in R3), D5 no (the list state kept on return stays out of R3, tracked as a later navigation
improvement), D6 yes, D7 yes. Precisions: (P1) the tests cover the real computation on PostgreSQL, drafts and
working copies included; (P2) the migration reviewed and frozen before its first application; (P3) the application
never shows an old or wrong date as a reliable last modification; (P4) exact test results kept, the known BLK-015
failures included.
- Go for the trial stack: the controller runs the operations (state check, the app on port 5194 identified then
stopped, cold backup, `pnpm db:trial migrate`, the six containers checked, integrity checks, the app restarted); on
a backup or migration failure, stop and report, no destructive restore without a new go; the pgTAP failures of 014
and 021 kept in the tracking, the suite never presented as green.
As applied:
- M9 is the M7 summary body plus the key of section 2, the revoke restated; no table, policy, index or privilege
change. Task review and security review before the first application (security PASS, one LOW finding that
predates M9: file 022 checks the helper's revoke for `authenticated` only, not for `service_role`). Frozen since:
blob `a33b1770`.
- pgTAP `022_sheet_admin_reads.sql`, plan 74 (60 before): a draft newer than its sheet row, a sheet without a version,
a draft save that moves `last_modified_at` and leaves the sheet row's `updated_at`, a sheet change that moves
both, a dated working copy and its draft save, a sheet row newer than its versions, the key on every listed sheet.
- Sandbox (`pnpm db:sandbox migrate`): `20261103100000` → `20261116100000`, a second run applies nothing. Data guard
before and after (6 981 sheets, 7 130 versions, full rows per id): identical. Function digest
`3a61a802…` → `1a4a1157…`. `pnpm db:sandbox types --check`: no drift. Recomputation of every official sheet not
deleted against `greatest(s.updated_at, max(v.updated_at))`: 6 981 checked, 0 mismatch, 0 null, 11 working copies
(0 mismatch), 1 historical sheet; 6 579 sheets whose date now differs from `updated_at`, 0 older than it. pgTAP on
the real image: Files=21, Tests=1958, Result FAIL, with `022` and `023` ok, `014_animals_relations` 2 of 258 failed,
`021_sheet_verification_jobs` 23 failed with « Bad plan. You planned 90 tests but ran 42 ». Read as dependent on the
accumulated sandbox state, M9 touching neither file's functions; NOT proven by a run without M9 or on a fresh
stack.
- Trial stack (`pnpm db:trial migrate`, 21 s, 14:41:52Z to 14:42:13Z): backup `20261116T144154Z-pre-migrate` (63M),
checked by the script before the migration, then by hand (`SHA256SUMS` 5 entries all match, `db.tar` 1 371 entries,
`storage.tar` 6 entries); 18 migrations applied, six containers running. Digest of 58 tables, 155 functions
(definition and privileges), 23 policies and 20 table grants before and after: exactly 3 lines differ (the
migration registry 17 → 18 rows and its new row, the summary function's definition = the sandbox's digest
`1a4a1157…`, its privileges unchanged). Accounts, roles, TOTP factors, the 2 sheets, 2 versions and 2 drawing rows
identical. Recomputation: 2 checked, 0 mismatch, 0 null, 1 working copy, 1 historical. Reads as the trial's
practitioner account (admin and `sheet_editor`, its own `aal2` session, read-only transaction rolled back): the
admin list 2 rows, each with `last_modified_at`; one sheet's overview; each version with its document and
drawings. The app restarted, its pages and the auth health check answering 200 through its proxy. NOT checked: a
browser sign-in with TOTP and the admin and editor screens in a browser (the owner's accounts, the owner's
trial); the restore of the backup was not exercised (destructive).
## 7. Known limits of the date (F7)
`last_modified_at` moves, or fails to move, in these cases the checkpoint did not list. Only (iii) is reachable from
the application today.
| # | Case | Effect |
|---|---|---|
| i | `delete_sheet_version` removes a draft row (`20261028110000_sheet_review_workflow.sql:1304-1332`) | the date can go back to an older one. No screen calls it today; fixed in that write the day a « supprimer le brouillon » screen exists |
| ii | deleting an account that created a draft sets the version's `created_by` to null (`20261008110000_anatomical_sheets.sql:111`) | that update stamps the version: the sheet reads as modified at the account's deletion |
| iii | review rounds and audit rows | never move the date, by design (section 2) |
| iv | a future data migration that rewrites drafts | re-dates every such sheet to the deploy time |
| v | the autumn clock change in Paris | two saves an hour apart can read the same « 02:30 » and still sort in their true order, which looks inconsistent |