Modèle de document de design¶

Status: GOVERNANCE / TEMPLATE

Ce document est un modèle de rédaction pour les pages du dossier design/.

Il ne décrit aucun composant réel et ne constitue ni un état CURRENT, ni une cible d'implémentation à lui seul.

Règle d'utilisation¶

Lorsqu'un nouveau document de design est nécessaire, copier uniquement les sections pertinentes ci-dessous et les remplir avec des faits, contrats ou choix explicitement vérifiés.

Ne pas conserver une rubrique vide juste pour respecter le modèle.

Statut¶

Indiquer explicitement l'un des statuts utiles :

CURRENT : comportement observé et vérifié ;
TARGET : architecture souhaitée ;
CONTRACT : règle stable à respecter ;
HISTORICAL : ancien état ou ancienne décision conservée pour contexte.

Un document peut combiner plusieurs statuts si chaque partie est clairement identifiée.

Mission¶

Expliquer en quelques phrases pourquoi le composant existe et quelle responsabilité il porte.

Pourquoi ce composant existe¶

Décrire le problème qu'il résout et ce qui se passerait si cette responsabilité était placée dans une mauvaise couche.

Responsabilités¶

Lister uniquement les responsabilités qui appartiennent réellement au composant.

Ce qui lui appartient¶

Préciser les règles, décisions, données ou opérations qu'il peut posséder.

Ce qui lui est interdit¶

Documenter les frontières importantes :

aucune décision métier dans le Runtime ;
aucune mutation persistante dans un Read Service ;
aucune vérité métier reconstruite dans le Frontend ;
aucune règle de verticale dans le Domain Core ;
aucune dépendance d'infrastructure cachée dans le domaine.

Adapter cette liste au composant concerné.

Dépendances autorisées¶

Nommer les couches, Contracts ou services que le composant peut utiliser.

Dépendances interdites¶

Nommer les dépendances qui créeraient un couplage inverse ou une violation de frontière.

Entrées¶

Décrire les données ou contrats reçus, leur provenance et les préconditions importantes.

Sorties¶

Décrire les résultats produits, les statuts possibles et les informations nécessaires à l'audit.

Lorsque pertinent, conserver explicitement les états resolved, unknown, ambiguous et conflict.

Contracts utilisés¶

Référencer les Contracts réellement applicables. Ne pas inventer une interface future juste pour compléter le document.

Composants internes¶

Lister uniquement les sous-composants stables ou prévus par le design cible.

Compatibilités et historique¶

Si un wrapper, shim ou composant legacy intervient encore, documenter :

pourquoi il existe ;
qui le consomme ;
s'il est CURRENT, HISTORICAL ou DEPRECATED ;
les preuves nécessaires avant son retrait.

La présence d'un composant historique ne signifie pas qu'il doit forcément « migrer ici ».

Observation et diagnostic¶

Indiquer comment vérifier le comportement sans mutation :

Read Service ;
audit ;
commande CLI ;
métrique ;
log ;
test ou fixture.

Intervention sûre¶

Décrire, si une mutation est possible, la séquence recommandée :

Observation
→ Audit
→ Simulation
→ Validation
→ Write Service explicite
→ Vérification

Critères de qualité¶

Documenter les critères applicables : déterminisme, testabilité, observabilité, performance, idempotence, rollback, absence d'écriture implicite, etc.

Vérification¶

Donner les tests, commandes ou contrôles permettant de prouver qu'une évolution respecte le design.

Évolution future¶

Réserver cette section aux choix TARGET réellement identifiés. Les idées exploratoires doivent être distinguées d'une décision approuvée.