Guides pratiques › Construire des applications de données

Guides pratiques

Applications de données

Une application de données est un écran de chiffres : des indicateurs, des graphiques, des filtres et des tableaux sur les données qu’arche-lang écrit déjà. Ce sont les exécutions de tests et leurs preuves, les traces de simulation, les essais, l’analyse temporelle, la télémétrie en direct et vos propres fichiers. Les données sont déclarées dans le modèle, sous forme de dataset et de metric. Un ui les affiche, et archec vérifie chaque nom, chaque unité et chaque cible. Chaque chiffre garde sa provenance : la métrique, le jeu de données, le fichier d’où il vient, la ligne du modèle et l’exigence à laquelle il est tenu.

Les modèles lancent une application de données sur des lignes d’exemple : archec new my-app --kind data-app --template product-overview, et archec new --kind data-app --list les liste. Cette page est un premier guide. Chaque mot se trouve dans la référence du langage et dans la spécification. archec explain data liste les vérifications. L’exemple est examples/bench-console.

Une première application de données#

requirement REQ-PASS "Release pass rate" {
  text "A release candidate shall pass at least 95 % of its bench runs."
  limit 95
}

dataset Runs "Test runs" {
  from json "data/runs.jsonl"
  dimension case, board, firmware, status
  measure duration unit ms
  time at
}

metric runs "Runs" = count() in Runs
metric pass_rate "Pass rate" = count(status == pass) / count() unit % in Runs { target REQ-PASS }

component Console "Bench console" {
  ui {
    display web
    screen Overview "Overview" {
      filters { date last 30d; select board; search case }
      row {
        kpi pass "Pass rate" { value pass_rate; compare previous period; sparkline by at week }
        kpi count "Runs" { value runs; compare previous period }
      }
      chart trend "Pass rate by week" { line pass_rate by at week; split board; on select filter }
      chart fails "Fails" { heatmap count(status == fail) by case, firmware; on select drill Case(case) }
      table recent "Recent runs" { rows Runs; columns at, case, board, status; sort at desc; page 20; export csv }
    }
    screen Case "Case" {
      table boards "By board" { columns board, pass_rate; group board; pivot firmware }
      button back "Back" { on press back }
    }
  }
}
Diagramme : Bench console
Ce qu’archec dessine depuis ce code : Bench console

archec ui main.arche liste chaque élément avec ce qu’il demande : ses métriques, son jeu de données, ses dimensions et sa granularité, sa comparaison, sa cible. archec ui main.arche --json donne le modèle qu’une page dessine.

Jeux de données#

Un jeu de données dit d’où viennent ses lignes, et quels sont ses champs.

from Lignes
evidence test .arche/evidence/test.jsonl : une par enregistrement (subject, plan, case, verdict, place, at, requirements)
sim "run.json" archec sim --json : une par événement (t, at, kind, part, msg, state, les champs de la charge utile)
tries, tries verdicts .arche/tries/ : une par essai (ses valeurs en params.NAME), ou une par verdict
analyze threads "timing.json" archec analyze --json : une par thread, avec sa load (son temps sur sa période) ; ou cores, buses, memory, chains
csv "file.csv", json "file.json" un fichier à vous : une ligne, ou un objet (JSON Lines aussi) ; archec status --json en donne une par exigence
live archec live : une par exigence, chaîne, thread et conteneur à chaque mise à jour
observe "spans.json" traces OTLP en JSON : une par span
budgets le modèle lui-même : une par part qu’additionne un budget (budget, on, part, top, name, value, unit, allowance, mode, copies), avec les mots de la part (prop maturity = "quote")

dimension nomme ce par quoi un graphique regroupe et filtre. measure nomme les nombres qu’une métrique additionne, chacun avec son unité. time nomme le moment d’une ligne : des ms depuis 1970, ou une date ISO 8601. Une métrique ne lit que ces champs.

Métriques#

Une métrique est une expression d’agrégations : count(), count(status == fail), sum(x), mean(x), min, max, median, p95(x) (n’importe quel centile) et distinct(x). Elle peut utiliser + - * /, des nombres et d’autres métriques. where garde certaines lignes. Un rapport avec unit % est donné en pourcentage. Une target est un nombre, ou l’exigence dont la limit s’impose à la métrique.

Une cible sait de quel côté d’elle est le bon. target <= 80 est un maximum, target >= 95 un minimum, et un simple target 95 est un minimum. La limite d’une exigence est un maximum quand elle le dit (limit driver_temp <= 80degC) ou quand son texte le dit ("below 80 °C", "at most", "shall not exceed", ou en français "en dessous de", "au plus", "ne doit pas dépasser"). C’est un minimum pour "at least" ou "above" ("au moins", "au-dessus"). Ainsi une température maximale de 79,3 °C tient "below 80 °C", et son kpi dit Cible ≤ 80 °C atteinte.

Une métrique se nomme autrement que les champs de son jeu de données. metric vout = mean(vout) dit deux choses : archec avertit et propose un nom (vout_mean). En attendant, un graphique, un kpi et une table de métriques lisent la métrique, tandis qu’une table de rows, un histogramme et un where lisent le champ.

La dernière ligne d’un tableau additionne ce qui s’additionne : un comptage et une somme. Une colonne max y montre la plus grande valeur, une colonne min la plus petite. Une moyenne, un centile, un taux ou la valeur propre d’une ligne n’y montre rien, car leur somme ne veut rien dire.

Les éléments#

  • kpi : le nombre d’une métrique, avec compare previous period (ou compare baseline firmware == "1.3.0"), sa target et une sparkline. Une référence est nommée sur la page : "Comparer à la référence firmware == "1.3.0"".
  • chart : une ligne dit son type et ce qu’il montre : line, area, bar, stacked-bar, pie, donut, scatter, heatmap, funnel, xmr, histogram, map, floorplan, sparkline. Puis les métriques, by les dimensions (un temps avec sa granularité : by at week), split en séries. Un funnel sans by prend ses étapes dans ses métriques, dans l’ordre écrit : funnel written, tested, proved.
  • table : les rows d’un jeu de données, ou des métriques regroupées (group) par dimensions et croisées en colonnes (pivot) ; sort, page, export csv. Une table regroupée par plusieurs champs montre chacun d’eux, puis les métriques.
  • filters : une plage de dates date, un choix select parmi les valeurs d’une dimension, une recherche search. Chacun filtre chaque élément de l’écran dont le jeu de données a ce champ.

Un bar ou un stacked-bar sur un temps l’écrit à sa granularité (Nov 3, W45), comme le fait une ligne. Avec compare previous period, chaque barre a la période d’avant à côté d’elle, plus claire ; une barre empilée a un trait en pointillés au total d’avant. La légende le nomme. Un floorplan est coloré par une métrique (une rampe) ou par une dimension : floorplan state by bench, x, y, w, h. Chaque mot a alors une couleur et la légende les liste. Un mot d’état (ok, pass, running ; warning, busy ; fail, error, down) prend sa couleur d’état. Un filtre date last 60d propose d’abord « 60 derniers jours » ; w compte des semaines, mo des mois, y des années.

on select filter filtre les autres éléments de l’écran selon ce que le lecteur a cliqué. on select drill Case(case) ouvre l’écran Case filtré sur cette valeur.

La voir tourner#

archec ui preview main.arche écrit une seule page, screens.html, qui fait tourner l’application de données sur ses lignes. La page porte les lignes et le code des graphiques : elle s’ouvre depuis un fichier et ne charge rien du réseau. Chaque écran de données a sa barre de filtres, ses filtres croisés, ses zooms, View rows, Export CSV et Inspect. Un zoom va à l’écran qu’il nomme, et le bouton back de cet écran revient. Les autres éléments de l’écran, comme un bouton qui mène à un autre écran, sont dessinés en dessous.

  • --theme light ou --theme dark choisit les couleurs. Sans lui, une application de données prend le theme qu’écrit son ui, sinon celui de la page (celui du système, ou de VS Code).
  • --png shots.png prend une image des écrans avec Chrome sans interface, une fois les graphiques dessinés. --screen Overview garde un seul écran.
  • --serve sert la page sur http://localhost:8040/ (--port pour en changer). Les lignes sont renvoyées chaque fois que l’un de leurs fichiers change. Un jeu de données from live lit .arche/live.json, que archec live réécrit : ses graphiques suivent le système en marche.

L’UI Preview de VS Code montre la même page à côté de l’éditeur. Le main.arche:37 d’Inspect ouvre le modèle à cette ligne. Export CSV demande où enregistrer le fichier. Les couleurs suivent le thème de l’éditeur, et les graphiques sont redessinés quand un fichier de données change. La page du simulateur (archec sim --html) et archec gen --target ui-web font aussi tourner l’application de données. archec doc --html dessine chaque écran de données en figure, avec ses filtres tels qu’ils démarrent.

Ce que devient un clic est l’entrée du moteur : la valeur d’une barre de filtres, les dimensions d’une marque choisie (un temps est l’intervalle de sa granularité, une classe son intervalle), les arguments d’un zoom. Un drill sans écran (on select drill) montre le même graphique une granularité plus fine, sur la période choisie.

Interroger les données#

archec mcp donne à un agent d’IA trois outils sur les mêmes données. dataset_list dit d’où viennent les lignes de chaque jeu de données, ses champs et combien de lignes il a maintenant. metric_query demande une métrique par dimensions, granularité, filtres et comparaison. Il répond le résultat qu’un graphique dessine, avec la provenance de chaque colonne. data_app_check lance les seules vérifications des données. La compétence build-data-app du plugin Claude Code s’en sert.

Ce que le lecteur fait bouger#

Certains écrans s’utilisent, ils ne se lisent pas seulement. Ces pièces se placent dans la grille de l’écran comme un graphique, et la page les dessine :

Pièce Ce que fait le lecteur
slider s "Setpoint" { param SETPOINT } bouge un parameter que nomme une métrique ; input le fait taper, stepper le fait avancer pas à pas
scenarios plan "…" { columns energy, cost } voit les métriques aux valeurs écrites des paramètres et à leurs valeurs actuelles ; nomme et enregistre un scénario
review approve, reject by chain sur une table de lignes choisit une décision pour chaque ligne ; Sign off les enregistre dans un fichier une fois que toutes en ont une
replay week "…" { date last 7d } rejoue l’écran sur les sept derniers jours, ou pas à pas ; Live montre toutes les lignes
ask q "…" { rows Telemetry; text "max temp by board, weekly" } tape une question en mots, lue dans la page sans IA
canvas c "…" { blocks Telemetry } ajoute, déplace et retire des graphiques ; un clic sur l’un filtre les autres
canvas c "…" { dice Telemetry } tire au sort une métrique, une dimension, un filtre et une granularité, et en garde certains
canvas c "…" { links part, requirement in Trace; split status } voit un lien par ligne, éclairé par son état
canvas c "…" { walk part in Parts; columns max(temp) } se déplace avec les flèches vers un lieu par valeur, qui montre ses nombres

Une métrique peut nommer un paramètre du projet comme un nombre : metric energy = LOSS * (SETPOINT - mean(outside)) * count() unit kWh in Climate. Son unité est celle écrite. Une étape d’histoire montre un écran de données avec screen Overview, et archec story export le dessine avec ses nombres. Ce que garde un lecteur (décisions, scénarios, blocs) reste dans le navigateur. Les vérifications sont data-param, data-review et data-story. Les modèles utilisent chaque pièce.

Sur un appareil#

archec gen --target ui-lvgl et --target ui-slint dessinent une application de données sur l’écran d’un appareil :

Élément Sur l’appareil
kpi son nombre et son unité, son écart avec la comparaison, sa cible
line un point à chaque mise à jour, une série par métrique, la cible en ligne plate
xmr les valeurs, leur moyenne et les limites naturelles du procédé (moyenne ± 2,66 × l’étendue mobile moyenne)
bar les barres que donne l’appareil, 12 au plus
table les lignes que donne l’appareil, en textes, au plus sa page (10 sans elle)

Un appareil n’a pas de fichiers : les preuves, le CSV ou la trace qu’un jeu de données lit sur un PC n’y sont pas. Le code généré a donc une structure de données avec une case par élément, et une fonction à vous la remplit à chaque mise à jour. En C, c’est ui_<id>_data_fill dans ui_<id>_data.c, écrit une seule fois. Dans la glue Slint, c’est la structure <Id>Data (ui.borrow_mut().data.<element> = …).

Un jeu de données from live est celui de l’appareil lui-même. Ses lignes y sont les variables de la part, une ligne à chaque mise à jour. Un champ qui porte le nom d’une variable de la part (temp, motor.rpm) est cette variable. Ainsi metric peak "Peak" = max(temp) in Telemetry, sur une part qui a var temp: float32, est calculée par le code généré au fil des mises à jour : count, sum, mean, min et max d’une variable. En C, il ne reste rien à remplir. En Slint, live(temp, motor_rpm) prend une ligne.

dataset Telemetry "Telemetry" {
  from live
  measure temp unit degC
  time at
}
metric peak "Peak temperature" = max(temp) unit degC in Telemetry

component Panel {
  var temp: float32 = 20
  ui {
    display 480x320
    screen Main "Main" {
      kpi hot "Peak temperature" { value peak }
      chart temps "Temperature" { line peak by at minute }
    }
  }
}
Diagramme : Panel
Ce qu’archec dessine depuis ce code : Panel

Tout autre élément de données (une aire, un camembert, une carte de chaleur, un tableau croisé, la barre de filtres) est une étiquette à sa place. Le générateur le dit dans une note pour chacun, comme il le fait pour un split, une sparkline ou un export qu’un appareil laisse de côté. --target ui-qml ne dessine encore aucun élément de données ; il le dit pour chacun.

Limites#

  • Le moteur de requêtes est en TypeScript, le même dans node et dans la page. Il convient aux exécutions et aux traces, des milliers de lignes, pas des millions.
  • Une pièce n’est dessinée que par la page : sur un appareil, c’est une étiquette à sa place. Un paramètre bougé dans la page n’est pas réécrit dans le modèle.
  • Une page servie renvoie toutes les lignes quand un fichier change, pas seulement les nouvelles.
  • Une map et un floorplan prennent leurs positions d’une dimension ; le dessin sur lequel ils sont posés n’est pas encore dans le modèle.
  • from budgets lit les budgets qu’additionne la vérification, part par part. Le budget d’un mode (operating-mode … { budget power 60W }) n’est pas dans ses lignes.
  • Une barre sur un temps se compare à la période d’avant par sa place : la première barre avec la première barre de la période d’avant. Un jour manquant décale les paires qui suivent.
  • Sur un appareil, une métrique d’un jeu de données from live n’est calculée que si elle est une seule agrégation d’une seule variable ; la fonction de l’appareil remplit les autres. Un appareil ne garde pas de période antérieure : la fonction donne la valeur qu’une compare affiche.