Files
faunosteo/docs/development/V1-2-6_OWNER_TRIAL.md
T

25 KiB
Raw Blame History

V1-2.6 : essai par le propriétaire de l'éditeur de fiche

Ce guide permet de tester l'éditeur de brouillon (niveau 1) dans votre navigateur, avant la validation fonctionnelle, sur une pile Supabase jetable. Rien ne touche DEV : les conteneurs supabase_*_faunosteo ne sont ni lus ni arrêtés, la base de l'essai est faunosteo_dbsandbox_* et disparaît avec down.

Toutes les commandes se lancent depuis /home/bchanot/Documents/faunosteo-v1-2 (la racine du worktree durable), une commande pnpm db:sandbox à la fois. Première commande :

cd /home/bchanot/Documents/faunosteo-v1-2

Prérequis : Docker, pnpm install fait, une application d'authentification TOTP (téléphone ou gestionnaire de mots de passe) pour l'étape 3, et un écran d'au moins 1 024 px de large (en dessous l'éditeur est en lecture seule).

Pile d'essai dédiée (pnpm db:trial). Une pile persistante, séparée de la sandbox et de DEV, est préparée (scripts et contrôles, docs/development/SUPABASE.md §5.2). Elle n'est pas encore créée : sa création attend l'accord du propriétaire. Ce guide décrit l'essai sur la sandbox (pnpm db:sandbox trial), qui reste disponible. Sur la pile dédiée, le compte praticien d'essai reçoit le rôle technique admin, puis l'habilitation sheet_editor (refusée tant que admin manque) : ce n'est pas le profil d'un praticien de production.

1. Démarrer la pile jetable

pnpm db:sandbox up fresh

Attendu : une dizaine de secondes, puis == sandbox up (fresh): ….

2. Créer votre compte et ses droits

pnpm db:sandbox trial-account vous@example.com

Un mot de passe est demandé deux fois, sans écho (12 caractères au moins). Il n'est ni affiché ni enregistré. Attendu : == account created and confirmed: vous@example.com. Le compte est déjà confirmé : aucun e-mail à lire.

pnpm db:sandbox trial-grant vous@example.com sheet_editor
pnpm db:sandbox trial-grant vous@example.com sheet_publisher

Attendu : == sheet_editor granted to vous@example.com, puis la même ligne pour sheet_publisher. Le droit sheet_editor donne aussi le rôle d'administrateur (requis par l'éditeur). Relancer une commande est sans effet. Un e-mail inconnu s'arrête sur no rows returned for \gset. Les droits possibles : catalog_reader, sheet_editor, sheet_reviewer, sheet_publisher.

3. Lancer l'application d'essai

Dans un terminal que vous laissez ouvert :

pnpm db:sandbox trial

Attendu : == trial: http://192.168.1.100:5193, puis les lignes de Vite. L'adresse d'essai est celle de cette machine sur le réseau local, déduite comme pour DEV (FAUNOSTEO_DEV_HOST). Si la ligne affiche une autre adresse (par exemple celle d'un pont Docker), arrêtez avec Ctrl+C et relancez avec FAUNOSTEO_TRIAL_HOST=192.168.1.100 pnpm db:sandbox trial. Pour un essai limité à cette machine :

FAUNOSTEO_TRIAL_HOST=127.0.0.1 pnpm db:sandbox trial

Seules sont acceptées l'adresse de bouclage ou une adresse privée (10/8, 172.16/12, 192.168/16) portée par une interface de cette machine ; 0.0.0.0, un nom et une adresse publique sont refusés avec un message.

Un seul port est ouvert au réseau local : 5193, sur cette adresse uniquement (pas sur 0.0.0.0). Vite relaie /auth/v1, /rest/v1 et /storage/v1 vers une passerelle de l'essai publiée sur 127.0.0.1:57801 ; tous les services de la pile jetable restent sur 127.0.0.1. Le serveur d'essai refuse toute requête HTTP dont l'en-tête Host n'est pas l'adresse d'essai, y compris une autre adresse IP ou localhost (réponse 403), et la route /__open-in-editor de Vite est fermée (404 avec l'adresse d'essai). Il ferme toute connexion websocket (pas de rechargement automatique : après une modification du code, rechargez la page à la main). Vite n'ajoute aucun en-tête CORS ; les routes Supabase relayées gardent ceux de la pile jetable, sans effet sur la session, qui reste dans le navigateur de l'essai et n'est jamais un cookie. La commande refuse de démarrer si la passerelle de l'essai existe déjà ou si l'un des ports est pris.

Ouvrez http://192.168.1.100:5193/login, depuis cette machine ou depuis un appareil du réseau local (téléphone compris), et connectez-vous avec le compte de l'étape 2. Si 192.168.1.100:5193 ne répond pas depuis un autre appareil, un pare-feu de la machine peut demander une règle pour ce port depuis le réseau local ; la commande est la vôtre, elle n'est jamais lancée par les outils :

sudo ufw allow from 192.168.1.0/24 to any port 5193 proto tcp

Protections : réseau local de confiance uniquement (jamais d'exposition publique), compte à mot de passe et double authentification pour l'administration, RLS sur toutes les tables, pile jetable. DEV (supabase_*_faunosteo) n'est ni lu ni arrêté. Le site est servi en HTTP simple : sur le réseau, le mot de passe, la clé d'enrôlement TOTP (le QR code), les codes TOTP et la session de l'essai circulent en clair. Quelqu'un qui écoute le réseau pourrait donc copier le facteur : la double authentification ne protège pas contre lui. Supprimez de votre application d'authentification l'entrée créée pour l'essai, une fois celui-ci terminé. N'utilisez donc qu'un réseau de confiance (pas un Wi-Fi public ou partagé), et jamais un mot de passe qui compte. Seuls les fichiers de l'application sont servis (pas les notes du dépôt, ni le seed, ni les secrets de la pile). Sur un réseau douteux, préférez FAUNOSTEO_TRIAL_HOST=127.0.0.1 et le tunnel SSH.

Double authentification (TOTP)

L'administration exige une session renforcée (aal2).

  1. Menu « Mon compte », section « Sécurité », bouton « Ajouter un facteur ».
  2. Nom du facteur (par exemple « Essai »), « Continuer ».
  3. Scannez le QR code avec l'application d'authentification (sinon recopiez la « Clé de configuration manuelle », affichée une seule fois), saisissez le code à 6 chiffres, « Vérifier ». Attendu : « Facteur ajouté et vérifié. »
  4. Menu « Administration » : la page « Double authentification requise » demande un code. Saisissez le code courant (attendez le suivant si le vôtre est sur le point d'expirer), « Vérifier ». Attendu : la liste des fiches officielles.

4. Parcours à dérouler

Chaque étape donne l'action et le résultat attendu. Notez tout écart avec la date et l'étape.

4.1 Créer une fiche non équine

  1. Administration, « Nouvelle fiche ». Choisissez une espèce autre que le cheval (une espèce inactive est acceptée), renseignez « Nom (français) », « Nom (anglais) » et l'identifiant (slug, par exemple essai-chien), « Créer la fiche ».
  2. Attendu : la création ouvre directement le brouillon vide dans l'éditeur, sans page intermédiaire, avec quatre onglets (Général, Annotations, Constats, Vérification). Une fiche neuve et vide s'ouvre sur l'onglet « Général ».
  3. Dans « Général », tapez des espaces autour d'un nom (par exemple Essai ) et validez. Attendu : les espaces du début et de la fin sont retirés des noms et des libellés courts de l'éditeur ; les descriptions, notes, citations et adresses ne sont jamais modifiées.

4.2 Importer une illustration SVG

Préparez trois fichiers dans un dossier hors du dépôt :

mkdir -p ~/essai-svg
cat > ~/essai-svg/valide.svg <<'SVG'
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 300"><rect x="20" y="20" width="360" height="260" fill="#eee" stroke="#333"/><circle cx="200" cy="150" r="60" fill="#c96"/></svg>
SVG
cat > ~/essai-svg/nettoyable.svg <<'SVG'
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 300"><style>.a{fill:#c96}</style><rect class="a" x="20" y="20" width="360" height="260"/></svg>
SVG
cat > ~/essai-svg/hostile.svg <<'SVG'
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 300"><script>alert(1)</script><rect x="20" y="20" width="360" height="260"/></svg>
SVG
  1. Onglet « Annotations », carte « Vues », « Gérer les vues » (section « Vues », avec « Retour au dessin » en tête), vue principale, « Choisir une illustration », fichier valide.svg. Attendu : « L'illustration est ajoutée à la vue. » et le dessin s'affiche (visible après « Retour au dessin »).
  2. Même geste avec nettoyable.svg. Attendu : la boîte « Nettoyer cette illustration ? » avec l'aperçu du dessin nettoyé et la mention que l'élément <style> est retiré. « Nettoyer et utiliser cette version » applique, « Annuler » n'ajoute rien.
  3. Même geste avec hostile.svg. Attendu : refus avec « Ce fichier contient du contenu actif ou externe… » ; aucune boîte de nettoyage, aucune illustration ajoutée.

4.3 Créer des annotations

  1. Onglet « Annotations », carte « Catégories », « Modifier les catégories » (section « Catégories »), bloc « Nouvelle catégorie » : renseignez les noms, puis « Ajouter la catégorie », puis « Retour au dessin ». Sans catégorie, la création d'une annotation le signale : « Créez d'abord une catégorie d'annotation (Annotations, section Catégories). »
  2. Onglet « Annotations », outil « Point » : cliquez dans le dessin, renseignez les noms FR et EN, la catégorie, la latéralité, « Créer ». Attendu : le point apparaît dans la liste et sur le dessin.
  3. Outil « Zone » : posez au moins trois sommets, Entrée ou « Fermer le tracé ». Attendu : la zone est créée.
  4. Ajoutez une vue de détail (onglet « Annotations », « Gérer les vues », formulaire « Nouvelle vue de détail », bouton « Ajouter la vue » ; le recadrage est facultatif ; puis « Retour au dessin »), puis l'outil « Accès à une vue détaillée » : tracez un contour et choisissez la « Vue ouverte ». Attendu : l'accès est créé.
  5. « Annuler » et « Rétablir » (à droite de la rangée d'onglets, sur chaque onglet ; nom accessible « Annuler la dernière modification ») défont et refont chaque création. Ne les confondez pas avec « Abandonner les modifications » (en-tête), qui abandonne tout ce qui n'est pas enregistré et reprend la dernière révision du serveur, après confirmation.

4.3 bis Utiliser l'illustration de la vue parente

Cette étape suppose une vue de détail qui a un recadrage (quatre valeurs) et sa propre illustration : ajoutez-la dans « Gérer les vues » (onglet Annotations) avec un recadrage, puis « Choisir une illustration » avec valide.svg. Placez une annotation sur cette vue (« Retour au dessin »).

  1. Retour dans « Gérer les vues », sur cette vue : « Utiliser l'illustration de la vue parente ». Attendu : la boîte « Utiliser l'illustration de la vue parente ? » qui précise que la vue affichera l'illustration de la vue parente à travers son recadrage, que son propre fichier reste enregistré, que le changement s'annule, et que ses annotations repassent « à confirmer ». Boutons « Annuler » et « Utiliser l'illustration parente ».
  2. « Annuler » ne change rien. Recommencez et confirmez. Attendu : « Utilise l'illustration de la vue parente. » et l'annotation de la vue marquée « À confirmer ».
  3. « Annuler » (à droite de la rangée d'onglets), depuis n'importe quel onglet, restaure l'illustration propre de la vue.

4.3 ter Catégories de constats

  1. Onglet « Constats » : « Ajouter une zone », renseignez les noms, « Créer ».
  2. « Ajouter une catégorie », quel que soit l'élément sélectionné (même aucun). Le formulaire demande la « Zone » ; elle n'est présélectionnée que s'il n'existe qu'une zone. Attendu : le titre devient « Nouvelle catégorie dans la zone « … » » avec la zone choisie, et la catégorie est créée directement sous cette zone. Tant qu'aucune zone n'existe, le bouton est grisé avec « Créez d'abord une zone pour ajouter une catégorie. »
  3. Sélectionnez la catégorie puis « Ajouter un constat » : le constat s'insère sous l'élément sélectionné.

4.4 Correction de géométrie

  1. Avec l'outil « Point », cliquez très près d'un bord du dessin. Attendu : « Le point ne tient pas à l'endroit choisi. Position corrigée proposée : x = …, y = … » avec « Utiliser cette position » et « Annuler ». Le brouillon ne change qu'après « Utiliser cette position ». Sur un petit dessin (quelques centaines d'unités, comme l'export Inkscape de 200 × 150), le cœur accepte souvent un point réduit tout près du bord et la correction n'apparaît pas : faites cet essai sur un dessin d'au moins 1 000 unités de large.
  2. Sélectionnez un point, ouvrez ses propriétés (« Position et rayon ») et saisissez dans « Centre x » une valeur hors du dessin (par exemple 9999). Attendu : « Valeurs non appliquées : le brouillon est inchangé. » ; « Revenir aux valeurs enregistrées » rétablit le champ. Une valeur valide s'applique.

4.5 Enregistrer et restaurer

  1. Faites une modification, puis « Enregistrer ». Attendu : « Révision N » avance, plus de mention de modifications non enregistrées.
  2. Faites une autre modification sans enregistrer et rechargez la page (F5). Attendu : le navigateur demande de confirmer le départ (beforeunload). Confirmez le rechargement.
  3. Attendu au retour, sur l'onglet « Annotations » (une fiche qui a une vue mesurable s'ouvre sur cet onglet, après rechargement aussi ; une fiche sans vue mesurable s'ouvre sur « Général ») : une offre de copie locale (« Une copie locale temporaire de ce brouillon existe dans cet onglet… ») avec « Restaurer la copie » et « Ignorer la copie ». Restaurez : la modification revient, toujours non enregistrée.
  4. Limites sur mobile : beforeunload est peu fiable sur Safari iOS et sur un onglet tué en arrière-plan ; la copie locale appartient à l'onglet et disparaît avec lui. Seul « Enregistrer » met le travail sur le serveur. Au toucher, tant qu'une annotation déplaçable est sélectionnée, le dessin ne défile plus sous le doigt.

4.6 Concurrence entre deux onglets

  1. Ouvrez le même brouillon dans deux onglets (A et B). Dans A, modifiez et enregistrez.
  2. Dans B, modifiez autre chose et enregistrez. Attendu : une boîte intitulée « Une autre session a enregistré la révision N » (« Conflit d'enregistrement » n'apparaît que le temps de la lecture du brouillon du serveur) et indiquant qu'elle vient d'une autre session de votre compte.
  3. « Recharger » (après confirmation) abandonne la modification de B et reprend la révision du serveur. Recommencez le conflit puis « Garder ma version » (après confirmation) : la version de B remplace la révision du serveur et la révision avance.

4.7 Vérification et soumission

  1. Onglet « Vérification » : les erreurs bloquantes sont listées, avec leur nombre accordé (« 0 erreur bloquante », « 1 erreur bloquante », « 2 erreurs bloquantes ») ; « Aller à » ouvre l'onglet concerné.
  2. Corrigez-les, enregistrez, saisissez la « Note de soumission (obligatoire) », « Soumettre à la revue ». Attendu : le brouillon passe en lecture seule, avec la mention de la revue et de la vérification en cours.
  3. Gel : aucun worker de vérification ne tourne dans cet essai et le retrait d'une soumission n'existe pas. Le brouillon reste donc gelé jusqu'à down. C'est attendu, pas un défaut. Refaites un essai avec une nouvelle fiche (4.1) si vous voulez continuer à modifier.

4.8 Déconnexion avec du travail non enregistré

  1. Faites une modification sans l'enregistrer, puis « Se déconnecter ». Attendu : la boîte « Se déconnecter et perdre le travail local ? » : des modifications non enregistrées ou des copies locales de cet onglet seraient perdues, les enregistrer avant les conserve.
  2. « Annuler » : vous restez connecté, rien n'est perdu.
  3. Recommencez et choisissez « Se déconnecter quand même ». Attendu : déconnexion, et les copies locales de ce compte dans cet onglet sont supprimées. Reconnectez-vous (TOTP compris) et rouvrez le brouillon : aucune offre de copie locale, la dernière révision enregistrée.
  4. Fin de session involontaire (expiration) : la copie locale est conservée et n'est proposée qu'au même compte ; si un autre compte se connecte dans l'onglet, les copies des autres comptes sont supprimées sans lui être montrées.

4.9 Démonstration U1 : la nouvelle coque de l'éditeur

À dérouler sur la fiche non équine de 4.1, après les étapes 4.2 et 4.3 (il faut au moins une annotation et un constat avec une référence). La fiche de démonstration n'est pas créée par la commande d'essai : c'est celle que vous avez créée dans l'interface.

  1. Les quatre onglets : « Général », « Annotations », « Constats », « Vérification ». Passez de l'un à l'autre à la souris, puis au clavier (flèches gauche et droite dans la rangée d'onglets). Revenez sur un onglet : ce que vous y aviez saisi et sélectionné est resté.
  2. Dans « Général », modifiez un nom sans enregistrer. Passez sur « Annotations » et cliquez « Annuler » à droite de la rangée d'onglets. Attendu : le nom d'origine revient dans « Général » ; « Rétablir » le remet. Un champ en cours de saisie est validé avant l'annulation, donc sa saisie est la dernière modification annulée.
  3. Références : le bouton « Références » de l'en-tête ouvre un panneau latéral (non modal) avec une recherche sur la citation, le DOI et l'URL (« Rechercher une référence »). Dans « Constats », sélectionnez un constat qui cite une référence : le bouton « n référence(s) » ouvre le même panneau limité à « Citées par « … » (n) », avec « Tout afficher (n) » pour revenir à la liste entière. « Fermer les références » ou Échap ferme le panneau et rend le focus au bouton qui l'a ouvert.
  4. Dans « Annotations », la carte « Vues » propose « Gérer les vues », la carte « Catégories » « Modifier les catégories », et une entrée « Régions vertébrales (n régions) » est toujours là. Chacun ouvre sa section pleine largeur avec « Retour au dessin » en tête. Une saisie commencée dans une section reste là quand vous revenez au dessin puis rouvrez la section.
  5. Redimensionnez la fenêtre à 1 180 px de large. Attendu : le menu latéral de l'application disparaît dans l'éditeur (il revient dès 1 280 px) et s'ouvre en un geste par « Ouvrir le menu » ; le dessin gagne la place libérée. Sous 1 024 px l'éditeur passe en lecture seule (voir les limites) ; en dessous de 640 px, deux onglets restent visibles et « Plus » ouvre les deux autres.

5. Limites à connaître

  • Risque résiduel RR-12 : les opérations du catalogue lisent la mention aal2 du jeton, pas la session vivante. Un jeton émis à aal2 reste accepté après la suppression du facteur, jusqu'à son expiration (une heure).
  • Les e-mails ne partent nulle part (l'interface de courrier de la pile jetable est sur 127.0.0.1:57025).
  • Un appareil du réseau local ne reçoit pas de contexte sécurisé (HTTP) : l'essai n'en a pas besoin.
  • Les mots de passe créés ici n'ont de valeur que pour cette pile.
  • La pile est jetable : tout ce que vous créez (comptes, fiches, brouillons) est perdu à down.
  • Juste après un down, up fresh peut échouer sur address already in use (un port pas encore libéré par Docker). Attendez quelques secondes, lancez pnpm db:sandbox down puis pnpm db:sandbox up fresh.
  • Safari iOS : beforeunload n'y est pas fiable (voir 4.5) ; seul « Enregistrer » protège le travail.
  • Réparation à l'attache : si une vue sans illustration porte déjà des annotations (anciennes sauvegardes), attacher une illustration dont le cadre en laisse certaines dehors ouvre la boîte « Réparer les annotations hors du nouveau cadre » (boutons « Attacher et appliquer » et « Annuler »). Les valeurs proposées sont modifiables et un seul « Annuler » restaure tout. Un tracé libre n'est jamais modifié : s'il sort du nouveau cadre, la boîte l'indique (« Ce tracé libre est conservé tel quel. … ») et « Attacher et appliquer » reste désactivé ; « Annuler » laisse le document intact. Corriger ses points demandera une évolution du cœur (proposée, pas développée). Ce cas ne s'obtient pas depuis une fiche construite avec ce guide : il n'a pas d'étape et n'est couvert que par les tests automatiques.

Limites connues de U1

  • Une décision en attente sur une vue (nettoyage de l'illustration, réparation des annotations, retour à l'illustration parente) n'est pas perdue par un simple changement d'onglet, de section ou l'ouverture du panneau des références : elle est retenue, signalée par une ligne « … attend votre décision » avec « Reprendre », et ne se rouvre que par ce bouton. Elle est perdue quand sa vue disparaît (annulation, abandon des modifications, rechargement, suppression de la vue), et « Rétablir » ne la ramène pas.
  • Une décision en attente au moment d'une soumission reste affichée comme ligne en attente, sans bouton d'action, tant que le brouillon est gelé.
  • Une offre de copie locale peut devenir en attente en cours de session (après une soumission suivie d'une relecture, ou un changement de droits puis d'édition). Les parties d'édition déjà ouvertes restent montées et masquées : rien n'est perdu, vous choisissez « Restaurer la copie » ou « Ignorer la copie », et les brouillons conservés restent après l'un ou l'autre.
  • Sous 1 024 px de large, l'éditeur est en lecture seule : les valeurs saisies sont conservées et l'édition revient quand la fenêtre s'élargit de nouveau.
  • Exception à la règle précédente : un champ qui passe sur place à sa valeur en lecture seule (hors des parties d'édition conservées) perd une saisie que l'enregistrement de la modification a refusée ; le message d'erreur disparaît avec le champ en lecture seule et revient si la fenêtre s'élargit de nouveau. Un champ placé dans une partie conservée garde sa saisie.
  • Une illustration en cours d'envoi quand la fenêtre passe sous 1 024 px est quand même rattachée à sa vue : c'est une modification non enregistrée, comme au niveau 1.
  • La fenêtre de réparation des annotations garde les géométries saisies au passage sous 1 024 px, mais pas le message de refus d'une application ni une saisie illisible encore en cours dans un groupe de géométrie.
  • Tant que le panneau des références est ouvert, le contenu des onglets n'est pas atteignable au clavier (il est inerte sous le voile) : on parcourt d'abord le panneau, le contenu après sa fermeture.
  • « Gérer les vues », « Modifier les catégories » et « Régions vertébrales » ouvrent les éditeurs existants en section pleine largeur ; U3, U4 et U6 les remplacent.
  • Largeur du dessin (choix 2.6) : 538 px à 1 024 px et à 1 280 px (la barre latérale revient à 1 280 px), 694 px à 1 180 px, 793 px à 1 279 px ; le panneau des références ouvert ne la change pas.
  • Le parcours automatique sur un second appareil du réseau local (e2e/lan/trial-lan.spec.ts) n'a pas été exécuté : il demande cette pile d'essai. Votre essai depuis un autre appareil (section 3) en est la première vérification.
  • Suite de navigateur au dernier commit de U1 (da95b84) : 188 réussis, 90 ignorés, 4 échecs, tous dans le test d'accessibilité des écrans d'administration (admin.spec.ts:717, fr et en, bureau et 375 px). Cause probable : l'état de la pile jetable (la copie de travail unique de la fiche historique existait déjà après un passage précédent), à confirmer par une reproduction non destructive ou un test isolé. Les 192 réussites sans échec datent du commit 81fba46 sur une pile neuve, pas du dernier commit.

Repli facultatif : tunnel SSH

Le réseau local suffit normalement. Hors de ce réseau, ou si l'essai tourne en FAUNOSTEO_TRIAL_HOST=127.0.0.1, ouvrez un tunnel depuis l'autre ordinateur :

ssh -N -L 5193:127.0.0.1:5193 <utilisateur>@<machine>

Puis ouvrez http://127.0.0.1:5193 sur cet ordinateur. Laissez ce terminal ouvert ; Ctrl+C ferme le tunnel. Ce repli ne marche que si l'essai écoute sur 127.0.0.1.

6. Arrêt et nettoyage

  1. Dans le terminal de trial : Ctrl+C. Vite et la passerelle de l'essai s'arrêtent ensemble.
  2. Puis :
pnpm db:sandbox down

Attendu : == sandbox removed. Vérification :

docker ps -a --format '{{.Names}}' | grep dbsandbox

Attendu : aucune ligne. Les secrets de la pile jetable sont supprimés avec elle. Rien n'a été écrit dans DEV. Si le terminal de trial a été fermé sans Ctrl+C, pnpm db:sandbox down retire aussi la passerelle de l'essai ; vérifiez ensuite que rien n'écoute plus sur le port 5193 (ss -ltn | grep 5193).