Aller au contenu

ADR-0009 — Justification à deux niveaux & naissance de l'Atelier

Statut : accepté (2026-06-14, arbitrages user). Contexte : la justification d'hypothèse (ADR-0008 §workspace) est scopée demande_id. Conséquence : la justif d'un taux d'actualisation — « 4 % = rendement des obligations d'État BEAC sur la duration de l'engagement » — doit être resaisie à chaque dossier. Corvée et source d'incohérence (deux dossiers, deux formulations du même argument). Or un jeu d'hypothèses est une thèse actuarielle ; une thèse se justifie là où elle se construit, pas à chaque application. En parallèle, l'écran Calcul ad-hoc (/dbo, calculateur jetable du Jalon 2) est devenu orphelin : sa fonction a été mangée par le Studio (calcul sur données réelles) et le Labo (exploration de jeux).

Les deux problèmes ont une seule réponse : donner un lieu à la doctrine.

🎯 À retenir

Une hypothèse porte deux justifications : « en soi » (pourquoi 4 % est défendable — doctrine, portée par le jeu, réutilisable) et « d'adéquation » (pourquoi 4 % convient à ce dossier — portée par l'étude). La grille hérite la première et surcharge/complète la seconde, le snapshot fige une copie résolue avec sa provenance. L'écran /dbo orphelin devient l'Atelier d'hypothèses : composer, justifier, éprouver et sauver UN jeu dans la doctrine cabinet — le Labo restant le lieu pour comparer PLUSIEURS jeux.

La distinction fondatrice

Une hypothèse porte deux justifications, pas une déplacée :

  • « En soi » — pourquoi 4 % est défendable. Source, méthode, doctrine. Ne dépend pas du dossier. → appartient au jeu.
  • « D'adéquation » — pourquoi 4 % convient à CE dossier. La duration de l'engagement de cette population colle-t-elle à la maturité de la courbe retenue ? → appartient à l'étude.

Écraser la seconde sous la première transformerait la justification en signature automatique — exactement ce que l'audit fuit. On hérite la première, on surcharge/complète la seconde, on fige une copie résolue.

Décisions

# Décision Arbitrage
D-JUST-1 La justif « en soi » + ses pièces vivent sur le jeu (table JustificationJeu, scopée tenant cabinet), saisies au constructeur de jeu. C'est la doctrine maison, réutilisable d'un dossier à l'autre. user, 2026-06-14
D-JUST-2 À la sélection du jeu dans l'étude, la grille est pré-remplie en hérité (affiché « du jeu », grisé). Éditer crée une justif d'étude propre (override local, badge « spécifique au dossier »). Modifier la doctrine = action explicite « promouvoir au jeu ». user, 2026-06-14
D-JUST-3 Acte d'adéquation signalé non bloquant : si tout est hérité sans confirmation, badge « adéquation non confirmée » visible du reviewer. N'empêche jamais de soumettre (cohérent D-REV-3). user, 2026-06-14
D-JUST-4 À la soumission, le snapshot fige la copie résolue (hérité OU surchargé) + la provenance (« hérité du jeu v_N » / « spécifique »). La doctrine peut évoluer ensuite sans bouger le passé. découle de D-JUST-1..2

Mécanique

  • Héritage à la lecture. etude.py résout le merge jeu → étude champ par champ : pour chaque champ sans justif d'étude propre, la justif de jeu est servie en hérité. Le junior laisse hériter (rien à faire), surcharge (justif propre + badge « spécifique »), ou promeut une justif d'étude vers le jeu (action explicite — sinon la doctrine se pollue d'ad-hoc).
  • Immutabilité sauvée gratuitement. La justif de jeu est mutable (doctrine vivante) ; mais le snapshot à la soumission en fige une copie dans resultat_json — on le fait déjà (ADR-0008 D-REV-5). L'audit d'une demande passée ne bouge jamais, même si une coquille est corrigée demain.
  • Pièces portables. Le PDF BEAC vit au niveau jeu (storage/<tenant>/jeu-<id>/), réutilisable ; les pièces propres au dossier restent sous la demande (ADR-0008).
  • Fenêtre de conception. Le modèle JeuHypotheses porte version mais le versionnement fin (immutabilité, arbre) n'existe pas encore. On pose la couche justification avant l'éditeur de jeux riche, sans rien défaire.

L'Atelier — le lieu de la doctrine (ex-« Calcul ad-hoc »)

L'écran /dbo orphelin devient l'Atelier d'hypothèses (/atelier, label rail « Atelier ») : le lieu où le junior, indépendamment d'un dossier officiel, (1) compose un jeu, (2) le teste contre une population — inline ou un dossier-test, (3) le justifie (D-JUST-1), (4) le sauve dans la doctrine cabinet. Le calcul jetable d'aujourd'hui devient son mode « tester sans sauver » — capacité subsumée, pas perdue.

Frontière nette avec le Labo (sinon recouvrement) :

  • Atelier = composer UN jeu (construction : régler, justifier, tester, sauver) ;
  • Labo = comparer/explorer PLUSIEURS jeux (analyse : A/B, sensibilité, distribution, multi, OHADA).

Construction vs exploration. Le plan de travail de l'étude (/cabinet/etude/[id]) reste le point de convergence : le jeu (sorti de l'Atelier/Labo) y rencontre le dossier (sorti de l'ingestion client).

Le rail raconte le pipeline

DESIGN.md exige déjà « toutes les destinations dans l'ordre du workflow » ; l'implémentation l'avait trahi (liste plate désordonnée, Cabinet en 2ᵉ). On restaure l'intention en groupant par phase — zones stables = mémoire musculaire, et le Cabinet redevient un bloc repérable pour senior/externe (pour qui il est la porte d'entrée, pas la fin de chaîne) :

PRODUCTION   Atelier → Labo → Studio DBO   (le junior fabrique)
CONTRÔLE     Cabinet                        (senior/externe : revue, audit, admin)
RÉFÉRENCE    Référentiel                    (socle normatif transverse)

Rôles figés : Atelier = concevoir & justifier la doctrine ; Labo = éprouver contre un dossier (timelines, multi, sensibilités) ; Studio = formaliser le dossier officiel (+ particules employé/entreprise à venir) ; Cabinet = dialogue senior/externe + workflow ; Référentiel = cross-check des pièces.

Respect de l'identité (DESIGN.md)

L'Atelier est un cousin visuel du plan de travail et du Labo, pas un nouvel idiome : 3 zones (rail · contenu · panneau d'actions), réactivité (la composition recalcule sa DBO de test toute seule — debounce, réponses périmées annulées, jamais de scroll réactif), StatCard pour la DBO de test, titres serif, accents laiton sur la sélection/progression, primary ≤ 10 %, Hicks (une action primaire — « Sauver dans la doctrine » — l'accessoire sous disclosure). DESIGN.md sera mis à jour (rail en sections, fiche Atelier).

Découpage de réalisation

  1. Lot 1 — Rail + coquille Atelier : sections dans NavBar, route /dbo → /atelier (page re-titrée, fonction inchangée), middleware/liens/ proxy suivis, DESIGN.md (rail en sections). Zéro régression.
  2. Lot 2 — Cœur : JustificationJeu + pièces de jeu + provenance/adéquation sur l'étude ; backend (CRUD justif jeu, merge héritage, snapshot résolu) ; l'Atelier devient composeur-justifieur-sauveur ; Etude.tsx hérite/surcharge.
  3. Lot 3 — Finition d'audit : provenance + badge « adéquation non confirmée » dans Revue.tsx, citation dans le PDF livrable, action « promouvoir au jeu ».

§atelier-recentré — l'Atelier autour de la doctrine (2026-06-14)

Le premier Atelier (Lots 1-2) était « un calculateur avec la doctrine en pièce rapportée » : tout s'empilait dans le contenu, la page devenait lourde. Or ADR-0009 dit l'inverse : l'Atelier sert à composer et justifier la doctrine ; le calcul DBO n'est qu'un banc d'essai. On renverse — et on applique enfin le pattern 3 zones que Labo/Studio/Cabinet suivaient déjà (l'Atelier était l'exception).

Principe (formulé par le user) : rien d'imposé — le panneau d'actions porte les verbes, la fenêtre principale ne montre que l'objet invoqué ; pas de surcharge cognitive, mais pas de culte du clic non plus (une vue par défaut sensée, jamais d'écran vide).

# Décision Arbitrage
D-ATEL-1 Panneau = verbes : bibliothèque de doctrine (jeux du cabinet, sélection ◉/○, complétude « n/10 » — contexte obligatoire), « ✦ Composer un jeu », et pour le jeu sélectionné : Forker au Labo → · Archiver. user, 2026-06-14
D-ATEL-2 Contenu = l'objet invoqué, deux modes sur le jeu, jamais les deux à la fois : Justifier (grille de doctrine, défaut au clic) et Éprouver (population jetable + DBO de test). user, 2026-06-14
D-ATEL-3 Vue par défaut = la bibliothèque en vue d'ensemble (jeux + complétude) — jamais d'écran vide ; on plonge dans un jeu au clic. user, 2026-06-14
D-ATEL-4 Composer un jeu = hypothèses + nom, sans population (le banc d'essai vit dans Éprouver) ; population de test jetable (le dossier officiel se traite au Studio). découle

Mécanique : Atelier.tsx (orchestrateur, PageShell + panneau) dispatche le contenu selon (selId, mode) ; ComposerJeu (hypothèses + nom laiton → POST /api/hypotheses), DoctrineJeu (grille pilotée par jeuId, remonte la complétude au parent via onCount), EprouverJeu (détail figé + population jetable + POST /api/dbo). Backend : justif_count ajouté à /api/hypotheses (2 requêtes batchées, pas de N+1). Frontière inchangée : Atelier = composer UN jeu ; Labo = comparer PLUSIEURS jeux.

§lot-3 — Provenance, adéquation, promotion (2026-06-14)

La revue et le PDF doivent rendre visible d'où vient chaque justification, et le junior doit pouvoir remonter un bon choix vers la doctrine.

  • Pièces héritées matérialisées (audit immuable). Arbitrage user : à la soumission, chaque pièce de doctrine héritée (champ non surchargé) est copiée dans la demande (PieceJustificative.source_piece_jeu_id → PieceJeu). Le snapshot ne référence que des pièces de la demande → téléchargement uniforme par la route demande, et la doctrine peut évoluer ensuite sans casser une soumission passée. materialiser_pieces_heritees s'exécute avant le snapshot (idempotent : ré-archive ses copies à chaque re-soumission). Un champ surchargé n'hérite pas (sa pièce propre l'emporte).
  • Provenance affichée. La revue (Revue.tsx) porte une puce hérité du jeu / spécifique au dossier par hypothèse ; le PDF cite doctrine du cabinet / choix propre à ce dossier (information de méthode, pas du jargon interne).
  • Adéquation signalée (D-JUST-3). Si TOUTES les justifications sont héritées sans aucun choix spécifique, la revue affiche « Adéquation au dossier non confirmée » — non bloquant, le reviewer challenge.
  • Promotion au jeu (D-JUST-2). POST /api/demandes/{id}/justifications/ {champ}/promouvoir {jeu_id} copie la justif d'étude (texte + Référentiel + pièces saisies) vers la doctrine du jeu. Action explicite (bouton ⤴ sur un champ surchargé), junior assigné, étude ouverte, jeu du tenant cabinet — la doctrine ne se pollue jamais d'ad-hoc par accident.

Alternatives écartées

  • Migrer toute la justification vers le jeu : ferait disparaître la justification d'adéquation — le lieu même du risque que la revue doit challenger.
  • Retirer l'ad-hoc : perd la capacité « calcul jetable » et rate le candidat naturel pour la doctrine.
  • Fusionner Atelier + Labo : redonne un écran lourd ; on vient justement de séparer la composition (plan de travail) du reste pour cette raison.
  • Override remontant au jeu : une justif bricolée pour un dossier contaminerait tous les dossiers futurs du jeu.
  • Adéquation bloquante : casserait le caractère facultatif des justifs (D-REV-3) et durcirait le workflow sans gain d'audit réel. ```