Files
faunosteo/docs/design/v1-2-6/ETUDE-TECHNIQUE.md
T

12 KiB

V1-2.6 · Étude technique de la nouvelle UX (sans implémentation)

Synthèse des impacts des seize maquettes sur le cœur Rust, le schéma du document, les PDF, le worker, SQL et les fiches existantes. Rien n'a été modifié : ni code, ni schéma SQL, ni worker, ni Supabase DEV. Les recommandations de ce document ne valent pas autorisation d'implémenter : la voie A du §3 comme les opérations du §2 restent des propositions, à décider après l'approbation visuelle finale, dans un plan technique séparé. Les références fichier:ligne sont dans .claude/audits/2026-11-05-v1-2-6-ux-feasibility.md, dont ce document reprend les conclusions et ajoute les vérifications faites depuis (SQL, instantané PDF, empreinte, ordre de dessin du calque).

1. Opérations Rust existantes, réutilisables telles quelles

Opération du cœur Sert à
sheet.edit : insert, update, remove, move, set_status, mark_reviewed Chaque geste sur le dessin se ramène à un update de l'annotation au relâchement : point déplacé ou redimensionné, sommet glissé, inséré ou retiré, polygone déplacé ou redessiné. Catégories, vues et régions passent par insert, update, remove
dependents et le refus has_dependents Suppression d'une catégorie, d'une région ou d'une vue encore utilisée (planches 07, 09)
Handle d'aperçu (PreviewSheet) et composition view.canvas Dessin de chaque vue, cadrage d'une vue détaillée par son view_box : le SVG entier est gardé, définitions et transformations comprises, seul le cadre change
Règles de placement : out_of_frame, too_small, interior_too_small Refus d'une forme au relâchement (planches 12 B, 16 D), moins de 61 ms par validation sur l'équin
Règles des régions : region.code.duplicate, region.count_range.invalid, grammaire du code, annotation.region.missing Planche 09, sans changement
Nettoyage clean_svg, téléversement, rattachement d'un dessin « Remplacer par un SVG spécifique »
Mesure de taille, verdict, instantané PDF Inchangés par l'UX

Côté page, existent déjà : la pile d'annulation (8 Mio, une entrée par modification acceptée), Ctrl+Z et Ctrl+Maj+Z, le pincement et le défilement au doigt, la copie locale, le dialogue de conflit.

2. Opérations Rust manquantes

Besoin Opération à créer (esquisse) Poids
Nom proposé pour une vue détaillée sheet.annotations_in_rect {document, view_id, rect} → [{id, name, category_id, inside | partial}] Faible : les briques geometry_bounds et placement existent dans le cœur
Éditer une courbe sans la simplifier sheet.path_points {d, frame} → [{index, anchor | control, x, y, outside}] et sheet.path_move_points {d, moves} → {d}. Proposition écrite, non construite (.claude/tasks/plans/2026-11-04-v1-2-6-path-repair-core-proposal.md) Élevé : chemins relatifs (déplacer un point décale les suivants), commandes H et V, contrôles implicites S et T, arcs
Déplacer une zone courbe entière sheet.path_translate {d, dx, dy} → {d} Moyen, même lecteur de chemin
Remplacer un cadrage par un SVG spécifique sans décaler les annotations sheet.remap_view {document, view_id, from_box, to_box} → document, annotations passées « À confirmer » Moyen
Catégories fixes Règles du cœur : refus de supprimer une catégorie fixe, une seule catégorie par rôle, rôles obligatoires dans une fiche neuve ; sheet.empty crée les trois catégories Moyen, lié au choix de schéma (§3)
Opacité par catégorie Le calque lit l'opacité de la catégorie à la place des constantes (point 0,65 ou 0,5, zone 0,3) ; docs/ANNOTATION-RENDERING.md mis à jour d'abord Moyen ; les références R3 ne se régénèrent pas sans décision
Lier les régions à la catégorie Vertèbres (facultatif) Règle de validation : vertebral_region_code réservé aux annotations de rôle « vertèbres » Faible ; aujourd'hui toute annotation peut porter une région

Aucune n'est nécessaire pour : glisser un sommet, insérer ou retirer un sommet, déplacer ou redessiner un polygone, tracer le rectangle d'une vue détaillée, régler la taille d'un point. Ces gestes ne changent que la page.

Contrainte de taille : il reste environ 17 Ko sur le module WebAssembly (583 126 o sur 600 000 o compressés). Les opérations sur les courbes en prendront une bonne part.

3. Catégories fixes et opacité face au schéma actuel

Aujourd'hui une catégorie porte id, name FR/EN et color (#rrggbb, sans transparence). Aucune notion de catégorie fixe ; une fiche neuve démarre sans catégorie ; l'opacité n'existe que dans des constantes du calque.

Voie Principe Effets
A. Champs optionnels dans le schéma v2 role (bone, joint, vertebra) et fill_opacity en pourcentage entier, absents par défaut et jamais écrits quand ils sont absents Les documents existants se lisent et se réécrivent à l'identique : leur empreinte ne change pas, les contrôles SQL schema_version = 2 non plus. Un entier évite le flottant, qui retirerait Eq au type et compliquerait l'écriture canonique. Mais un lecteur strict antérieur refuse un document qui porte ces champs
B. Schéma v3 Nouvelle version explicite du document Les contrôles SQL acceptent 2 et 3 (migration), le cœur lit les deux, le worker aussi, une convention d'empreinte pour v3. Plus propre sur le papier, beaucoup plus lourd
C. Sans changement de schéma Identifiants réservés (os, articulations, vertebres) et opacité fixe par rôle Pas de champ nouveau, mais l'opacité n'est plus réglable, et la catégorie vertébrale équine (zone-colonne) devrait être remplacée par une nouvelle, les identifiants étant immuables

Recommandation : voie A. Elle garde les identifiants existants : sur la copie de travail équine, il suffit d'ajouter un rôle à os, articulations et zone-colonne. La convention d'empreinte sha256-rfc8785-validated-v1 décrit la lecture stricte du document ; l'élargir à deux clés optionnelles est une décision à prendre avec BDR-068, même si les empreintes existantes ne bougent pas.

4. Lecteur des anciens documents

  • Documents v2 existants : lus par le nouveau cœur sans changement (voie A), car les champs sont optionnels.
  • Anciens PDF (enveloppe v1, Report v2 et v3) : inchangés, leur instantané ne porte aucun champ nouveau.
  • Anciennes versions de l'application lisant un nouveau document : le lecteur N-1 figé et le build 0.2.0 sont stricts et refusent une clé inconnue. Deux cas :
    • dans un PDF, si l'instantané retire role et fill_opacity (le PDF n'en a pas besoin, voir §5), le lecteur N-1 lit les nouveaux PDF comme avant ;
    • sur le serveur, un retour arrière de l'application après l'ajout de ces champs à un brouillon rendrait ce brouillon illisible par l'ancienne version. C'est une limite de retour arrière, du même ordre que RR-2, à inscrire au suivi de mise en production.
  • Règle maintenue : un lecteur d'archives ne perd jamais une version (enveloppe v1, Report v2 et v3, document v2).

5. PDF, worker, SQL et migrations

  • PDF : la surbrillance du PDF est une couleur fixe (#b85a3f à 0,85), pas celle de la catégorie. L'opacité d'une catégorie ne change donc aucun rendu PDF. L'instantané copie aujourd'hui les catégories telles quelles ; le retirer de ces deux champs, comme il retire déjà les références, garde la compatibilité N-1. Un bilan déjà exporté se reproduit à l'identique.
  • Praticien : son canevas utilise la couleur de la catégorie ; il utiliserait aussi son opacité, absente par défaut, donc rendu inchangé pour les fiches existantes.
  • Worker : il embarque le cœur et lit le document strictement pour le verdict. Un worker construit avant le changement refuserait un brouillon portant les nouveaux champs. Ordre de déploiement : image du worker reconstruite et déployée avant l'application, comme pour toute évolution du cœur.
  • SQL : la forme contrôlée côté serveur ne regarde que les tableaux et les identifiants de catégories ; des champs optionnels passent sans migration (voie A). La voie B demande une migration qui élargit anatomical_sheet_versions_schema_known et le contrôle document.schema_version. Les empreintes des groupes de revue incluent les catégories : un brouillon qui gagne un rôle ou une opacité voit le groupe de revue qui contient ses catégories marqué modifié, ce qui est le comportement attendu.
  • Taille : quelques octets par catégorie, sans effet sur le plafond de 2 Mio.

6. Préservation des fiches anatomiques historiques

  • La fiche historique (503dc301-…) reste en lecture seule : aucune étape ne la modifie, la soumet ou la publie, et le pipeline Git n'est pas régénéré (pnpm r5:import-equine --check sans différence). Son document reste v2 sans champ nouveau ; son empreinte et l'alias historique restent valides.
  • Les versions publiées sont figées par le serveur : elles gardent leur document tel quel, sans rôle ni opacité, et s'affichent comme aujourd'hui.
  • La copie de travail équine porte la conversion, par une modification ordinaire de son brouillon, relue en revue :
    • rôles ajoutés à trois catégories existantes ;
    • « Charnières vertébrales » et « Os du crâne » gardées comme catégories de la fiche ;
    • les trois couleurs propres d'annotations traitées selon l'arbitrage 11.
  • L'outil local et les PDF déjà émis ne changent pas.

7. Édition tactile et restrictions de largeur

  • Règle actuelle : l'édition demande une fenêtre d'au moins 1 024 px (MIN_EDIT_WIDTH), sinon mode lecture seule (O14 A ratifiée, contrat §8.4). Les tests de bout en bout sautent exprès 49 cas d'édition sous cette largeur.
  • Tablette en paysage (1 024 px et plus) : déjà autorisée à éditer. Pincer et défiler fonctionnent. Il manque, côté page :
    • des poignées à zone de contact de 44 px (les sommets actuels sont décoratifs) ;
    • un contrôle de pointerId dans le geste de déplacement, sinon un second doigt peut l'alimenter ;
    • la priorité de la poignée la plus proche quand deux se chevauchent.
  • Tablette en portrait (768 à 834 px) : reste en lecture seule tant que le seuil tient.
  • Téléphone : éditer impose de lever O14 A, d'écrire les parcours de bout en bout à 375 px et de tester sur WebKit. La tolérance de tap de Chromium (LRN-108) n'est pas celle de Safari, et les suites ne tournent que sur Chromium jusqu'à V1-5. La précision pose aussi problème : certaines zones équines ne font que quelques pixels sans zoom. Recommandation : arbitrage 9.

8. Préalables avant tout développement

Repris de la revue externe du 2026-11-05 et du dossier. Aucun n'est engagé ; chacun conditionne le plan technique séparé.

  • Modèle des catégories : role et fill_opacity dans le schéma v2 restent une proposition. Avant décision, vérifier :
    • la lecture stricte du lecteur N-1 ;
    • les empreintes RFC 8785 et l'alias historique ;
    • les instantanés PDF ;
    • le worker ;
    • les oracles R3 et R4 ;
    • le scénario de retour arrière.
  • Fiches historiques : ne régénérer ni modifier aucun fichier de la fiche historique ni du pipeline Git. Toute conversion des catégories se fait dans la copie de travail, après décision, et passe en revue.
  • Opérations du cœur (annotations_in_rect, path_points, path_move_points, path_translate, remap_view) : valider leurs signatures, leurs codes de refus fermés, leurs tests et leur part du budget WebAssembly avant d'en écrire une ligne.
  • Polygones : les règles métier sont vérifiées par le cœur à la fin du geste. Un refus ne déforme et ne perd aucun tracé : la forme précédente revient. Il faut aussi :
    • des poignées tactiles de 44 px ;
    • un contrôle de pointerId ;
    • une alternative au clavier pour chaque geste.
  • Vues détaillées : conserver le SVG entier par recadrage vectoriel, sans extraction destructive. Régler explicitement le recouvrement des accès avec les annotations (arbitrage 6).
  • Texte commun : rédaction juridique validée par le propriétaire, jamais présentée comme un avis vétérinaire ou juridique approuvé d'office.
  • Chantiers distincts : le TOTP demandé à la connexion et les illustrations historiques manquantes sur la sandbox restent hors de cette refonte.