panfu/arch-diagram

Que fait arch-diagram ?

Deux méthodes, utilisables séparément ou enchaînées (langage naturel → Mermaid → HTML).

• nl2mmd : langage naturel → dialecte Mermaid
• mmd2html : dialecte Mermaid → HTML interactif (template : dossier de cette compétence assets/template.html)

Convention commune : dialecte Mermaid

Structure (trois niveaux, correspondant au HTML serveur→service→sous-service) :

• subgraph de niveau supérieur = serveur, écrire direction TB à l'intérieur
• subgraph de second niveau = service (créer un sous-graphe uniquement s'il a des sous-services ; les services sans sous-service sont écrits directement comme nœuds)
• nœuds à l'intérieur du sous-graphe de service = sous-services
• Tous les titres avec texte entre guillemets : subgraph X["Titre"], N["Titre"]

Remarque (meta) : séparer le nom de la remarque par | dans le titre ; après génération HTML, la remarque s'affiche en petits caractères clairs à côté du nom (spécifications du serveur, port, charge, paramètres, etc.). Pas de | si pas de remarque :

• subgraph WEB["Web Edge | Biactif · LAN"] → nom du serveur "Web Edge", remarque "Biactif · LAN"
• WEB_GW["API Gateway | QPS 3k"] → nom du service + remarque
• Règle d'analyse : prendre le dernier |, à gauche le nom, à droite la remarque

Le type d'arête est exprimé par le trait, fixe et immuable :

Type	Trait	Sémantique
sync (synchronisation)	==>	Synchronisation / écriture retour
call (appel)	-->	API / RPC / WS
job (tâche planifiée)	-.->	cron / tâche programmée / push
data (lecture)	-.-	Lecture seule / requête base

• Étiquette d'arête : ==>|"type · heure ou fréquence"|, par exemple ==>|"sync · 07:10 4×/jour"| ; -->|call| peut omettre la description
• Les identifiants des nœuds sont en MAJUSCULES_AVEC_TRAIT_D_UNION : <serveur>_<service>_<sous_service>, ex. NAS_SCHED_FLAT
• Les arêtes peuvent être ancrées sur des sous-graphes (niveau service ou serveur), signifiant que l'arête s'applique à ce niveau
• Le diagramme commence par flowchart LR ; les arêtes internes au même hôte s'écrivent normalement (le HTML les dessinera en boucle sortante/entrante à droite)

Méthode 1 : nl2mmd (langage naturel → Mermaid)

1. Extraire les entités : machines/hôtes/environnements → serveurs ; logiciels installés ou exécutés dessus → services ; composants/fonctions/tâches/bibliothèques dans le logiciel → sous-services.
2. Extraire les relations : mapper les verbes aux types — synchronisation/écriture retour/miroir → sync ; appel/requête/envoi-réception → call ; quotidien/planifié/cron/xx:xx/push → job ; lecture/requête/boîte blanche → data. Inscrire l'heure et la fréquence dans les étiquettes d'arêtes.
3. En cas de doute sur le niveau, mettre au niveau service, ne pas inventer de sous-services.
4. Les informations numériques et les spécifications (port, capacité, charge, plage IP, etc.) vont dans les remarques des nœuds : ["Nom | Remarque"] ; l'heure et la fréquence dans les étiquettes d'arêtes. Ne pas perdre d'information.
5. Sortir un bloc flowchart LR complet, sans explication.

Méthode 2 : mmd2html (Mermaid → HTML interactif)

Étapes

1. Lire le contenu complet de assets/template.html (environ 38 Ko, fichier unique autonome, les données par défaut sont le contenu de examples/sample.mmd).
2. Analyser le Mermaid (selon le dialecte ci-dessus), construire une correspondance mermaid id → chemin hiérarchique : le chemin est serveur.service.sous_service séparé par des points (tronqué selon la profondeur d'imbrication). Lorsque l'arête est ancrée sur un sous-graphe, le chemin s'arrête au niveau correspondant.
3. Dans le template, remplacer tout le bloc entre /*==DATA==*/ et /*==DATA-END==*/ par un nouveau bloc de données, sans modifier le reste du code :

/*==DATA==*/
var ARCH_TITLE='Titre du diagramme (barre de titre du terminal et <title> du document) ';
var ARCH_LSKEY='arch-<slug>';   // clé localStorage, unique pour chaque diagramme
var TYPE={sync:{c:'#3ecf8e',dash:'10 4',dur:'1.5s',label:'Synchronisation'},
 call:{c:'#58a6ff',dash:'6 5',dur:'1.1s',label:'Appel'},
 job :{c:'#f0a942',dash:'2 4',dur:'0.85s',label:'Planifié'},
 data:{c:'#b18cff',dash:'14 5',dur:'1.9s',label:'Lecture'}};
var COLS=[['srvA','srvB'],['srvC']];   // disposition par défaut en colonnes : chaque élément du tableau = groupe d'ids de serveurs
var SERVERS=[
 {id:'srvA',short:'A',name:'A · Nom affiché',meta:'Remarque',ac:'#b18cff',svc:[
   {id:'svc1',short:'svc1',name:'Service1',meta:'',subs:[
     {id:'sub1',short:'sub1',name:'SousService1',meta:''}]},
   {id:'svc2',short:'svc2',name:'Service2'}]},
];
var EDGES=[
 {from:'srvA.svc1.sub1',to:'srvC.svc2',type:'sync',sched:'07:10 4×/jour'},
];
/*==DATA-END==*/

Règles des champs :

• id en ASCII (les chemins par points sont construits à partir de ceux-ci) ; name peut être en chinois ; short est le nom court utilisé dans les connexions/journaux
• meta provient de la partie après le dernier | dans le titre du nœud/sous-graphe ; omis si absent
• ac depuis la palette tournante : #b18cff #3ecf8e #39d0c4 #58a6ff #f0a942
• type ∈ sync|call|job|data (correspond au trait Mermaid) ; sched provient de la partie après le type dans l'étiquette d'arête ; écrire Temps réel si absent
• COLS : tri approximatif par flux des arêtes (source à gauche, collecteur à droite) ; le générateur de colonnes à serveur unique centre verticalement automatiquement

4. Écrire le résultat dans le chemin cible (version fragment). Pour une version prête à double-clic, envelopper :

<!doctype html><html lang="fr"><head><meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>{ARCH_TITLE}</title>
<style>html,body{margin:0;padding:0;background:#080b12}#svcarch{min-height:100vh}</style></head><body>
{fragment}</body></html>

QA

1. Obligatoire : extraire <script> et exécuter node --check ; vérifier les données — nombre de serveurs/services/sous-services cohérent avec Mermaid, nombre d'arêtes = nombre d'arêtes Mermaid, nombre de connexions en vue par défaut = nombre de groupes (from,to,type) dédoublonnés.
2. Avec navigateur : démarrer un serveur local avec en-tête charset (python3 -m http.server ne fournit pas charset, les caractères chinois seront mal encodés ; il faut un gestionnaire personnalisé pour ajouter Content-Type: text/html; charset=utf-8 aux .html), ouvrir et vérifier le titre, le comptage, la granularité ▾ servers, le repliement par clic.
3. Modifier uniquement le bloc DATA dans le template ; ne pas réimplémenter le reste du code (glisser-déposer/repliement/persistance).

Exemples

• examples/sample.mmd — exemple complet du dialecte (4 serveurs, 9 arêtes, couvre les 4 types de traits et les arêtes internes au même hôte)
• examples/sample.html — version générée à partir du template (prêt à double-clic)

Capacités de l'HTML généré (ne pas réimplémenter en dehors du template)

Déplacement par glisser (poignée en haut du cadre, maintenir Alt pour tout afficher), ajustement de la largeur par la bordure droite, repliement, trois présélections de granularité (serveurs/services/feuilles), journal des arêtes / inspecteur, mise en page et état de repliement persistés dans localStorage (clé = ARCH_LSKEY). L'interface est en anglais.

• Zoom et déplacement du canevas : Ctrl+molette pour zoomer autour du curseur (0.4–2.5×), maintenir Ctrl pour transformer la souris en main et déplacer le canevas ; cliquer sur l'indicateur de pourcentage en bas à droite pour réinitialiser. Zoom/déplacement persistés via localStorage.
• Édition intégrée : Alt+clic sur n'importe quel en-tête de nœud (les trois niveaux) pour modifier le nom/remarque/couleur du cadre du serveur, ajouter un sous-élément, supprimer (double confirmation, cascade des sous-arbres et arêtes) ; Alt+clic sur une arête pour modifier le type/l'heure ou supprimer l'arête ; lorsque Alt est maintenu, un bouton ⇱ export apparaît en haut à droite, affichant une fenêtre modale avec le Mermaid à jour (surlignage syntaxique + copie), contenant ⟲ relayout et ↺ restaurer les données par défaut. Les modifications sont persistées via localStorage.