UI des Paramètres
Cette page documente l'architecture de l'interface Paramètres elle-même — le motif de constructeur piloté par schéma, le contrat de validation, l'éditeur Monaco brut comme issue de secours, le tableau de bord technique. Pour des parcours orientés tâche sur chaque constructeur, voir la section Construire une application.
La page Paramètres (icône engrenage dans l'en-tête, visible des utilisateurs disposant de la permission settings:read) est l'éditeur in-app pour chaque fichier TOML par section. Chaque type de configuration dispose d'un éditeur dédié — un formulaire piloté par schéma généré à partir des modèles Pydantic que le backend utilise pour charger le fichier. Un éditeur Monaco brut figure sur chaque onglet comme échappatoire quand le formulaire d'un éditeur ne présente pas le champ qui manque.
Chaque enregistrement écrit le TOML sur disque, puis déclenche un rechargement côté serveur — le changement est actif dans le même onglet du navigateur sans redémarrage.
Vue d'ensemble
La colonne des éditeurs à gauche est affichée repliée ; chaque entrée ouvre un panneau de détail à droite (la capture montre l'éditeur Pools).
Les éditeurs
La page Paramètres présente neuf éditeurs plus le tableau de bord technique et l'échappatoire TOML brute :
| Onglet | Édite | Permission |
|---|---|---|
| Pools | connectors.toml → blocs [pools.*] — URLs JDBC, dialectes, tailles de pool, identifiants. | settings:pools |
| Connecteurs | connectors.toml → blocs [connectors.*] — requêtes SQL, endpoints HTTP, auth API. | settings:connectors |
| Dictionnaire | dictionary.toml — métadonnées de colonne : libellés, formats, énumérations, recherches, validation. | settings:dictionary |
| Menus | menus.toml — arborescences du menu latéral par application, dossiers, feuilles et gardes de permission. | settings:menus |
| Écrans | screens.toml — grilles, dialogues, onglets, conditions par champ, colonnes d'audit. | settings:screens |
| Tableaux de bord | dashboards.toml — mises en page stat / bar / line / pie / grid. | settings:dashboards |
| Graphiques | charts.toml — config wrapper Recharts référencée par les tableaux de bord. | settings:charts |
| Jobs | plugins/*/jobs.toml — catalogue de jobs Nomaflow par application. | settings:jobs |
| Technique | Lecture seule — stats de pool en direct, verrous d'enregistrement, exécutions de jobs en cours, événements socket récents. | settings:technical |
| TOML brut | Un éditeur Monaco par fichier. Charge le fichier tel quel, l'enregistre tel quel. Chemin de dernier recours quand un éditeur manque d'un champ. | settings:raw |
Les codes de permission sont les chaînes utilisées par le moteur de rôles — voir Authentification → Rôles et permissions pour la procédure d'attribution.
Comment fonctionne un éditeur
Chaque éditeur suit la même forme :
- Vue liste — chaque entrée de la section TOML sous-jacente en tant que ligne.
- Panneau de détail — l'entrée sous forme de formulaire piloté par schéma (un champ par attribut Pydantic) plus des onglets secondaires quand le modèle contient des objets imbriqués.
- Validation — chaque entrée est contrôlée par rapport au modèle Pydantic ; une valeur invalide met le champ en rouge et désactive le bouton Enregistrer.
- Tester (SQL / HTTP / API uniquement) — exécute la requête ou l'endpoint sur le pool actif et affiche les 50 premières lignes.
- Enregistrer et recharger — écrit le TOML sur disque et déclenche un rechargement côté serveur. Le toast de succès porte le chemin du fichier affecté.
Aperçu en direct des champs imbriqués
Pour les configurations à lignes imbriquées (les colonnes d'un écran, les feuilles d'un menu, les étapes d'un job), le panneau de détail utilise une liste glisser-déposer avec des éditeurs en ligne. L'ordre du TOML est préservé exactement tel que l'opérateur l'arrange — le framework ne re-trie pas les entrées à l'enregistrement.
Références inline
Le champ Pool d'un connecteur est une liste déroulante des pools actuellement définis. Le champ Connecteur d'un écran liste chaque connecteur. Le champ Écran d'une feuille de menu liste chaque écran de l'application sélectionnée. La suppression d'une entrée référencée est refusée — l'éditeur indique quelles configurations pointent toujours dessus, avec un lien vers chacune.
Éditeur TOML brut
L'onglet TOML brut ouvre un éditeur Monaco sur le fichier sous-jacent. Les erreurs de syntaxe sont surlignées à la volée ; le bouton Enregistrer reste désactivé tant que le fichier ne parse pas. L'éditeur est volontairement minimal — pas d'aide au renommage, pas de validation par rapport aux modèles Pydantic — car son rôle est de débloquer un opérateur quand un éditeur manque d'un champ précis.
Une boîte de dialogue de confirmation apparaît à l'enregistrement de TOML brut si une édition via éditeur a été faite dans la même session : l'enregistrement brut écraserait le diff de l'éditeur. Choisir Garder les modifications de l'éditeur pour annuler l'enregistrement brut, ou Utiliser le contenu brut pour rejeter les éditions de l'éditeur et enregistrer le texte brut.
Sémantique d'enregistrement
| Étape | Effet |
|---|---|
| Cliquer sur Enregistrer et recharger dans un éditeur | Le modèle Pydantic est re-validé. En cas de succès, le TOML est ré-écrit sur disque via tomlkit (les commentaires sont préservés sur les entrées qui en avaient déjà). |
| Rechargement côté serveur | POST /admin/reload est invoqué avec la portée du fichier — seul le registre affecté est reconstruit. Les requêtes HTTP en cours conservent leur état courant ; les nouvelles requêtes utilisent la configuration rechargée. |
| Rafraîchissement de l'UI | La page Paramètres re-récupère la configuration parsée ; tout autre onglet ouvert sur le même modèle (par exemple la page catalogue des Connecteurs) se rafraîchit via une diffusion Socket.IO. |
Pour le contrat de rechargement exact — ce qui recharge, ce qui reste en cours, ce qui retombe sur un redémarrage — voir Rechargement à chaud.
Tableau de bord technique
L'onglet Technique est en lecture seule et fait remonter ce que fait le framework en ce moment :
| Panneau | Contenu |
|---|---|
| Stats de pool | Par pool : connexions ouvertes, inactives, en cours d'utilisation, max, temps de checkout moyen. Se rafraîchit toutes les 2 s via Socket.IO. |
| Verrous d'enregistrement | Verrous actifs pris par le moteur d'écran (une ligne par paire (connector, key) verrouillée). |
| Exécutions de jobs | Les 50 dernières exécutions Nomaflow avec leur état et leur durée écoulée. |
| Événements socket | Fin de file des événements récents poussés par le serveur (verrou acquis/libéré, configuration rechargée, étape de job transitionnée). |
La page est restreinte aux utilisateurs portant settings:technical et est destinée au diagnostic — aucune action n'est proposée.
Adossé à une surface REST
Chaque éditeur dialogue avec un petit ensemble d'endpoints /admin/config/*. Ils sont documentés dans Référence API REST → Admin config et sont utilisables depuis curl pour le scripting :
| Endpoint | Objectif |
|---|---|
GET /admin/config/<section>/parsed | Retourne le TOML parsé en JSON. |
PUT /admin/config/<section>/parsed | Remplace le TOML parsé — le serveur re-sérialise en préservant les commentaires. |
POST /admin/config/<section>/raw | Remplace le texte TOML brut. |
POST /admin/config/connectors/{name}/test-sql | Exécute une requête SQL unique et retourne ses premières lignes. |
POST /admin/config/api/test | Exécute un endpoint HTTP et retourne la réponse. |
POST /admin/config/rename | Renomme une entité à travers chaque fichier TOML qui la référence. |
POST /admin/reload | Force un rechargement global (sans changement de fichier). |
Conseils et bonnes pratiques
- Éditer une section à la fois. Un Enregistrer et recharger ne remplace que le registre affecté — un changement multi-sections peut laisser le système dans un état transitoire où une configuration est à jour et une autre non.
- Utiliser l'échappatoire TOML brut avec parcimonie. En cas de recours fréquent, ouvrir un ticket — un manque dans un éditeur mérite d'être corrigé côté framework.
- Lancer Tester avant Enregistrer sur un connecteur SQL ou HTTP. Le framework rejette l'Enregistrer si le analyseur de chaîne de connexion échoue, mais il laisse passer une requête que la base refuse à l'exécution. Le bouton Tester détecte cela plus tôt.
- Restreindre étroitement la permission TOML brut. Les opérateurs qui n'ont besoin que de modifier un connecteur n'ont pas besoin de pouvoir écraser tout le fichier.
- Garder
git statuspropre. Chaque enregistrement dans Paramètres atterrit comme un diff dansliberty-apps; committer avec un message clair pour que le chemin de retour arrière reste évident.