Tableaux de bord

Un tableau de bord est un agencement de graphiques et de cartes d'indicateurs au-dessus des mêmes requêtes nommées que celles utilisées par les Écrans. Un seul fichier (config/dashboards.toml) déclare tous les tableaux livrés par l'application. Le DashboardView React lit la mise en page, lance une requête par panneau puis rend la grille.

Les tableaux de bord sont rechargeables à chaud avec le reste de la configuration.

---

Vue d'ensemble

---

Déclarer un tableau de bord

[dashboards.myapp.overview]
label       = "Vue d'ensemble utilisateurs"
description = "Instantané des comptes, des statuts et de la croissance récente."
auto_load   = true

# Un panneau par indicateur ou graphique
[[dashboards.myapp.overview.panels]]
id          = "users_total"
type        = "stat"
label       = "Utilisateurs · total"
query       = "users_count"          # toute requête SELECT — la première colonne de la première ligne est lue
columns     = 3                       # largeur dans la grille du tableau (sur 12)
delta_field = "delta_month"           # nombre secondaire optionnel

[[dashboards.myapp.overview.panels]]
id      = "users_per_status"
type    = "bar"
label   = "Utilisateurs par statut"
query   = "users_by_status"           # SELECT status, count(*) FROM users GROUP BY status
columns = 6
x       = "status"
y       = "count"

[[dashboards.myapp.overview.panels]]
id      = "created_per_month"
type    = "line"
label   = "Créations par mois"
query   = "users_created_per_month"
columns = 6
x       = "month"
y       = "count"

[[dashboards.myapp.overview.panels]]
id      = "users_by_role"
type    = "pie"
label   = "Utilisateurs par rôle"
query   = "users_by_role"
columns = 4
slice   = "role"
value   = "count"

La grille du tableau de bord est divisée en 12 colonnes. Un panneau avec columns = 6 occupe une demi-ligne ; deux panneaux columns = 3 plus un panneau columns = 6 partagent une ligne.

---

Types de panneau

type	Ce qui est rendu	Champs requis
stat	Un grand nombre, accompagné d'un delta optionnel.	query (lit la première colonne de la première ligne). delta_field optionnel.
bar	Des barres verticales, une par catégorie.	x (catégorie), y (valeur numérique).
line	Une courbe sur un axe temporel ou ordonné.	x, y. Les points sont rendus dans l'ordre renvoyé par la requête.
pie	Un camembert, une part par tranche.	slice (catégorie), value (valeur numérique).
grid (prévu)	Une mini-table directement dans le tableau de bord.	query, options columns optionnelles.

Chaque panneau s'appuie sur une requête nommée du connecteur du tableau — ou d'un autre connecteur si le panneau précise connector = "autre". La permission requise est sql:<connecteur>:<requête> ; un panneau auquel l'utilisateur n'a pas accès disparaît, et la mise en page se réajuste automatiquement.

---

Mise en page

Les panneaux sont rendus dans l'ordre de déclaration, de gauche à droite, dans une grille de 12 colonnes. Un panneau qui n'indique pas columns prend la valeur 4 par défaut (trois panneaux côte à côte).

Options de mise en page :

Champ	Effet
columns	Largeur du panneau (entre 1 et 12). Le panneau passe à la ligne suivante en cas de débordement.
rows	Hauteur optionnelle en nombre de lignes. Valeur par défaut : 1.
group	Étiquette de groupe ; l'interface affiche un en-tête de section au-dessus du premier panneau de chaque groupe.
auto_load	Exécute la requête du panneau à l'ouverture du tableau. Hérite par défaut du auto_load du tableau de bord.

---

Endpoints REST

Méthode	Chemin	Rôle
GET	/api/dashboards	Tous les tableaux de bord accessibles, regroupés par app.
GET	/api/dashboards/{app}	Les tableaux de bord d'une app.
GET	/api/dashboards/{app}/{id}	La mise en page complète du tableau.
POST	/api/dashboards/{app}/{id}/refresh	Relance chaque panneau côté serveur (passe par les routes /api/query/… sous-jacentes).

Le DashboardView appelle directement /api/query/{connecteur}/{nom} pour chaque panneau — mêmes contrôles que pour une grille de table. Un panneau dont la requête n'est pas autorisée est masqué silencieusement.

---

Conseils & bonnes pratiques

• Réutiliser les requêtes de l'écran. Un tableau de bord a rarement besoin de SQL nouveau : un users_by_status avec GROUP BY se déclare à côté de users_get, dans le même connecteur. Le dictionnaire reste unique.
• Les panneaux numériques sont peu coûteux ; les camemberts moins. Un camembert sur des milliers de tranches devient illisible. Au-delà de huit tranches, basculer sur un panneau barre avec un LIMIT N et un agrégat Autres.
• Choisir une largeur cohérente par type. Les indicateurs numériques rendent bien à columns = 3 (quatre côte à côte) ; les graphiques barre et ligne à columns = 6 (deux côte à côte) ; les camemberts à columns = 4. La grille s'ajuste alors naturellement.
• Un tableau de bord est filtré par les permissions. Les panneaux que l'utilisateur ne peut pas exécuter disparaissent. La mise en page s'adapte d'elle-même — il faut éviter de concevoir des panneaux qui dépendent les uns des autres.