chore(docs): R3 contract from the owner's three messages

This commit is contained in:
bchanot committed 2026-11-16 17:40:08 +01:00
1 parent 1adb19b479
commit 73ed37546f
1 file changed
+199
@@ -0,0 +1,199 @@
# CONTRACT — r3-sheet-list
- date: 2026-11-16 | flow: subagent-driven-development (plan `.claude/tasks/plans/2026-11-16-r3-sheet-list-0017.md` rev 2b) | branch: feature/v1-2-anatomical-sheets (worktree /home/bchanot/Documents/faunosteo-v1-2)
- status: active
- range under review: `98178de..HEAD` (`98178de` = the commit before the R3 plan)
## REQUEST (verbatim — IMMUTABLE)
### Owner brief 2026-11-16 (R3 start)
Je confirme la clôture de R2. Merci pour le travail réalisé.
Je donne maintenant mon feu vert pour démarrer la préparation de R3 : amélioration de la liste des fiches anatomiques et de l'accueil Administration.
Les maquettes R0 correspondantes, notamment les planches 28 à 30, sont déjà validées et constituent notre référence graphique.
Je souhaite retrouver une liste de fiches claire et facile à utiliser, avec :
- Une recherche efficace.
- Des filtres compréhensibles sur les statuts.
- Un tri par nom.
- Un tri par véritable date de dernière modification.
- Une présentation permettant de distinguer facilement une fiche historique, une fiche publiée, un brouillon et une copie de travail.
- Une navigation simple pour retrouver rapidement la fiche que je souhaite consulter ou modifier.
Pour la date de dernière modification, reprends la conception déjà validée dans V1-2-6_R3_SQL_CHECKPOINT.md.
Présente-moi d'abord le checkpoint SQL et ses conséquences avant toute application de migration.
Je te laisse autonome pour :
- Auditer l'existant.
- Réutiliser les décisions et maquettes déjà validées.
- Préparer le plan technique.
- Organiser les relectures indépendantes.
- Identifier les éventuelles contradictions ou dépendances.
Conserve BLK-015 et RR-13 comme chantiers séparés, sans perdre leur suivi.
Je souhaite pouvoir tester R3 sur db:trial lorsqu'il sera terminé.
Une fois le checkpoint SQL et le plan prêts, présente-moi les décisions nécessitant mon accord avant l'implémentation.
### Owner validation 2026-11-16 (plan rev 2, decisions D1 to D7)
Je valide le plan R3 en révision 2 et les décisions suivantes.
D1 : OUI.
Écriture de la migration SQL et des tests correspondants.
D2 : OUI.
Une seule livraison à l'état final. Il n'est pas nécessaire de construire l'état intermédiaire sans date.
D3 : OUI.
L'ordre retenu est :
- Migration de la sandbox.
- Migration de db:trial.
- Mise à jour de l'application.
Je valide le principe de la nouvelle commande pnpm db:sandbox migrate, sans réinitialisation de la sandbox.
En revanche, présente-moi le checkpoint opérationnel avant d'appliquer la migration à db:trial.
Cette opération nécessite l'arrêt temporaire de mon application d'essai et une sauvegarde. Je donnerai mon accord au moment voulu.
D4 : OUI.
Élargir RR-13 à la pagination des listes d'administration, notamment les droits et les fiches, sans implémenter ce chantier dans R3.
D5 : NON.
Conserver la recherche, le tri et les filtres au retour d'une fiche reste hors R3, conformément aux décisions existantes.
Le besoin reste suivi pour une amélioration ultérieure de la navigation.
D6 : OUI.
Je conserve les libellés recommandés :
- « Toutes les fiches officielles » pour zéro ou une fiche.
- « Voir les {n} fiches » à partir de deux.
D7 : OUI.
Les tests peuvent effectuer une suppression logique des fiches qu'ils ont eux-mêmes créées.
Ils doivent identifier précisément leurs propres données et ne jamais modifier ou supprimer les données préexistantes de la sandbox.
Je valide également les autres choix retenus dans le plan :
- Présentation conforme aux maquettes R0.
- Filtres existants.
- Recherche sans résultat conforme à la planche 28.
- Pas de nouvelle icône de recherche.
- Tri alphabétique selon la langue.
- Dates affichées en heure de Paris.
- Recherche et tri de présentation en TypeScript.
Quelques précisions :
1. Vérifie que les tests couvrent le calcul réel de last_modified_at sur PostgreSQL, notamment les brouillons et les copies de travail.
2. La migration doit être relue et figée avant sa première application.
3. L'application ne doit jamais afficher une date ancienne ou incorrecte comme une date fiable de dernière modification.
4. Conserve les résultats exacts des tests, notamment les échecs connus de BLK-015.
Tu peux maintenant committer le plan et le TODO, puis engager l'implémentation de R3 selon ton processus habituel.
Tu disposes de mon accord pour les développements et les vérifications sur la sandbox dans le périmètre du plan validé.
Avant toute migration de db:trial, présente-moi :
- Les opérations exactes.
- La sauvegarde prévue.
- Le temps d'indisponibilité estimé.
- La procédure de vérification après redémarrage.
Je donnerai alors mon accord pour cette opération.
DEV reste inchangé.
Je te laisse autonome pour les choix techniques et les relectures habituelles.
### Owner go 2026-11-16 (db:trial migration, then the application tasks)
Je valide le checkpoint SQL M9 et j'autorise son application sur db:trial.
Je préfère que tu réalises toi-même les opérations prévues, puisque tu as préparé et audité la procédure.
Mon autorisation couvre :
1. La vérification de l'état initial de db:trial.
2. L'arrêt temporaire de l'application d'essai sur le port 5194.
3. La sauvegarde à froid des volumes et des secrets par la procédure prévue.
4. L'application de la migration M9 avec pnpm db:trial migrate.
5. Le redémarrage et la vérification des six conteneurs.
6. Les contrôles d'intégrité des données et de la nouvelle fonction SQL.
7. Le redémarrage de l'application d'essai.
Avant d'arrêter l'application, vérifie que le processus ciblé correspond bien à l'application Faunosteo sur le port 5194. Ne te fie pas uniquement au PID 1718512, qui peut avoir changé.
La sauvegarde doit être complète, vérifiée et récupérable avant l'application de M9.
Je valide l'interruption temporaire annoncée de db:trial.
En cas d'échec de la sauvegarde ou de la migration, arrête la procédure et présente-moi le diagnostic. N'effectue pas de restauration destructive sans mon accord.
Après migration, vérifie notamment :
- Les 18 migrations appliquées.
- Les comptes, rôles et facteurs TOTP.
- Les fiches, versions et illustrations.
- Le calcul de last_modified_at.
- L'absence de modification inattendue des données.
- Le fonctionnement de l'administration et de l'éditeur.
DEV reste strictement inchangé.
Conserve les échecs pgTAP 014 et 021 dans le suivi, avec leurs résultats exacts. Ne présente pas la suite complète comme verte.
Une fois M9 appliquée et vérifiée sur db:trial, tu peux poursuivre les tâches applicatives de R3 selon le plan validé, avec tes relectures et tests habituels.
À la fin, présente-moi le bilan et la procédure d'essai propriétaire de R3.
## CLARIFICATIONS
- Graphic reference: boards 28 and 29 of `docs/design/v1-2-6-r0/` (R0, validated 2026-11-09). Board 30 belongs to R4.
- Labels: `docs/design/v1-2-6-r0/REVUE.md:82-84`. Date format (A8): « 9 nov. 2026, 12:06 » / « 9 Nov 2026, 12:06 », Paris time.
- Recorded choices the owner validated with the plan: no new badge (published and draft told apart by the detail line), the four existing filters unchanged, the no-result note of board 28 literally, no magnifier in the search field, name sort in the collation of the interface language, search and sort in TypeScript (display only).
- Out of scope, tracked: BLK-015 (rights screen under axe on accumulated grants), RR-13 (server paging of the admin lists, widened per D4, not implemented), D5 (list state kept on return), R4 (board 30).
## ACCEPTANCE CRITERIA
1. SQL: `private.official_sheet_admin_summary(uuid)` returns `last_modified_at` = the newest of the sheet row's `updated_at` and of its versions' `updated_at`; the migration is the M7 function body plus that key and the restated revoke, nothing else; privileges unchanged.
CHECK: cd /home/bchanot/Documents/faunosteo-v1-2 && [ "$(git hash-object supabase/migrations/20261116100000_sheet_admin_last_modified.sql)" = a33b1770ec284bfbb25245fc606c9f952d4651e3 ] && echo M9_FROZEN_OK
EXPECT: M9_FROZEN_OK
2. Precision 1: pgTAP (`supabase/tests/022_sheet_admin_reads.sql`) covers the real computation on PostgreSQL for a saved draft, a saved working copy, a sheet without version and a sheet row newer than its versions; the file passes on PGlite.
CHECK: cd /home/bchanot/Documents/faunosteo-v1-2 && grep -q "select plan(74)" supabase/tests/022_sheet_admin_reads.sql && grep -c "last_modified_at" supabase/tests/022_sheet_admin_reads.sql
EXPECT: a count of at least 8
3. Precision 2: the migration file was reviewed (task review, security review) before its first application and has not changed since (criterion 1's digest; no other file under `supabase/migrations/` changed in the range).
CHECK: cd /home/bchanot/Documents/faunosteo-v1-2 && git diff --name-only $(git rev-parse 2277e41^)..HEAD -- supabase/migrations | tr '\n' ' '
EXPECT: supabase/migrations/20261116100000_sheet_admin_last_modified.sql only
4. Precision 3: the application never shows an old or wrong date as the last modification: the client refuses an answer without `last_modified_at` or with a value that is no timestamp (`unavailable`), the list and the card show `last_modified_at` only (never `updated_at` or `created_at` under « Modifiée le »), the `<time>` carries the same instant.
CHECK: cd /home/bchanot/Documents/faunosteo-v1-2 && grep -q "last_modified_at: z.string().datetime({ offset: true })" packages/supabase/src/sheets.ts && ! grep -rn "ModifiedDate iso={[^}]*\(updated_at\|created_at\)" apps/app/src && echo DATE_SOURCE_OK
EXPECT: DATE_SOURCE_OK
5. List page `/app/admin/sheets`: a search on the sheet name (French or English, accents and case ignored, instant), combined with the four existing status filters; a native « Trier par » with « Dernière modification » (default, newest first) and « Nom » (collation of the interface language); a count line « {n} fiches » / « {n} fiches sur {total} »; each row shows « Modifiée le {date} » in the ratified format, Paris time.
6. The search field: label « Rechercher une fiche par son nom », 100 characters at most, no magnifier; a clear control « Effacer la recherche » only while it holds text; Escape empties a non-empty field and does nothing on an empty one; clearing returns the focus to the field.
7. Empty states as board 28's note: no official sheet at all, nothing under active filters, nothing for a search (« Aucune fiche ne contient « {q} » dans son nom. » with « Effacer la recherche »); the searched text is shown as typed (a `$&` stays `$&`), long text wraps without sideways scroll.
8. The presentation tells a historical sheet, a published sheet, a draft and a working copy apart with the existing badges and the detail line; no new badge, no rule built on a UUID, a name, a slug or a test convention (D7 of the R0 arbitration).
9. Administration home card (board 29 B): sub-heading « Dernières modifications », at most five sheets by last modification, each with its name link, badges, detail line and date; the footer link reads « Voir les {n} fiches » from two sheets and « Toutes les fiches officielles » for zero or one (D6); a failed species read never hides the card; a rights refusal of the sheet list still hides it.
10. Labels in French and English exactly as the ratified list, through the dictionaries with fr / en parity; no raw string in JSX.
CHECK: cd /home/bchanot/Documents/faunosteo-v1-2/apps/app && for k in admin.sheets.search admin.sheets.clear_search admin.sheets.sort_by admin.sheets.sort.modified admin.sheets.sort.name admin.sheets.count_one admin.sheets.count_other admin.sheets.count_of_one admin.sheets.count_of_other admin.sheets.modified admin.sheets.no_result admin.home.latest admin.home.see_all; do grep -q "'$k'" src/i18n/fr.ts && grep -q "'$k'" src/i18n/en.ts || echo "MISSING $k"; done; echo KEYS_CHECKED
EXPECT: KEYS_CHECKED with no MISSING line
11. D3: the sandbox was migrated through `pnpm db:sandbox migrate` without a reset; `scripts/db-sandbox.sh` received additions only.
CHECK: cd /home/bchanot/Documents/faunosteo-v1-2 && git diff $(git rev-parse 2277e41^)..HEAD -- scripts/db-sandbox.sh | grep -c '^-[^-]'
EXPECT: 0
12. D7: the browser spec `apps/app/e2e/shell/admin-sheets-list.spec.ts` deletes (soft deletion) only the sheet ids it created in its own run, captured one by one; no statement of the spec can match a pre-existing sheet row.
13. Browser proof on the sandbox: the spec proves the order by the true date (a draft save moves a sheet first), the name sort, the no-result state, the focus return, axe and no sideways scroll, in French and English at desktop and 375 px.
14. Precision 4 and the go message: exact test results are kept in `.claude/tasks/TODO.md` and the documents, including the `admin.spec.ts` failures of BLK-015 and the pgTAP failures of `014_animals_relations` and `021_sheet_verification_jobs` on the accumulated sandbox; no suite that failed is called green anywhere.
CHECK: cd /home/bchanot/Documents/faunosteo-v1-2 && grep -c "Bad plan. You planned 90 tests but ran 42" .claude/tasks/TODO.md
EXPECT: at least 1
15. BLK-015 and RR-13 stay separate, open tracks with their lines kept; RR-13's text is widened to the admin lists (rights and sheets) per D4; D5 is tracked as a later navigation improvement.
16. Scope: nothing changed under `crates/`, `scripts/db-trial*`, `apps/app/src/components/editor/`, `apps/app/src/components/catalogue/`, `GrantList`; `admin.spec.ts` changed only by the two locator rewrites.
CHECK: cd /home/bchanot/Documents/faunosteo-v1-2 && [ -z "$(git diff --name-only $(git rev-parse 2277e41^)..HEAD -- crates 'scripts/db-trial*' apps/app/src/components/editor apps/app/src/components/catalogue apps/app/src/components/admin/GrantList.tsx)" ] && echo SCOPE_OK
EXPECT: SCOPE_OK
17. Documents as built: the R3 section of `V1-2-6_U1_CORRECTIONS.md`, the SQL checkpoint status, the owner trial procedure in French (`V1-2-6_OWNER_TRIAL.md` §4.15), M9 in `V1-2_ANATOMICAL_SHEETS.md`, `SUPABASE.md`, `BROWSER_TESTS.md`, the Rust exception rows, `docs/design/README.md` (deviations), `CLAUDE.md`, `CHANGELOG.md`.
18. No merge, no deploy, DEV unchanged; the trial stack changed only by the authorised `pnpm db:trial migrate` (backup first).
## FILE SCOPE
supabase/migrations/20261116100000_sheet_admin_last_modified.sql, supabase/tests/022_sheet_admin_reads.sql, scripts/db-sandbox.sh, packages/supabase/{src/sheets.ts,tests/sheets-admin.test.ts}, apps/app/src/{admin/sheetList.ts,admin/labels.ts,catalogue/useCatalogue.ts,components/admin/ModifiedDate.tsx,app/routes/app/admin/{AdminSheetsRoute,AdminHomeRoute}.tsx,i18n/{fr,en}.ts}, apps/app/tests/**, apps/app/e2e/{shell/admin-sheets-list.spec.ts,support/admin.ts} and the three locator call sites, docs/**, CLAUDE.md, CHANGELOG.md, .claude/tasks/**.