Ferme/docs/superpowers/specs/2026-05-21-pont-bascule-healthcheck-design.md

Health-check pont-bascule branché sur l'écran de pesée

Date: 2026-05-21 Ticket: FER-19 Statut: Spec validée

Contexte

Aujourd'hui, à l'arrivée sur l'écran de pesée (réception ou expédition), l'UI affiche un texte hardcodé « Pont-bascule connecté » et un loader. C'est du faux : l'état réel du pont-bascule n'est jamais vérifié.

Le pont-bascule (Raspberry sur le réseau, ex. http://100.122.43.54:8000) expose deux routes :

• POST /send/dsd — déclenche une pesée et renvoie le poids + le DSD. Déjà utilisée via GET /receptions/weigh et GET /shipments/weigh (state providers → PontBasculeService::fetch()).
• GET /health — health-check, non branchée aujourd'hui.

Réponse type de /health :

{
  "ok": true,
  "mode": "serial",
  "busy": false,
  "hostname": "liot-rasp-ferme-01",
  "timestamp": 1779357080.6277,
  "port": "/dev/ttyUSB0",
  "baudrate": 9600,
  "port_connected": true,
  "port_error": null
}

Un bypass existe déjà côté backend (PONT_BASCULE_BYPASS=true) : il court-circuite l'appel HTTP et renvoie un payload de test. Il est actif partout aujourd'hui (.env.local, .env.prod).

Objectif

1. Brancher le vrai health-check du pont-bascule à l'arrivée sur l'écran de pesée.
2. Afficher le véritable état (connecté / non connecté) à la place du texte hardcodé.
3. Désactiver le bouton « peser » tant que le pont n'est pas valide.
4. Conserver le bypass : en bypass, l'état est « sain » pour ne pas casser le dev.
5. Ne pas dupliquer la configuration d'URL (une seule variable d'env de base).

Décisions de design

• Endpoint générique GET /pont_bascule/health (ressource API Platform autonome). Le health-check est agnostique de l'entité pesée — un seul endpoint partagé, pas un par entité.
• Check unique au montage de l'écran de pesée (pas de polling). Si le pont est down à l'arrivée, le bouton reste désactivé jusqu'au rechargement de la page. Conforme à la demande.
• Critère de validité : healthy = ok === true && port_connected === true && port_error === null && busy === false. (busy bloquant car une pesée déjà en cours met busy à true.)
• Bypass : PONT_BASCULE_BYPASS=true → health renvoie healthy: true sans appel réseau.
• Pont injoignable = état normal : le backend renvoie 200 { healthy: false } (jamais 500), pour ne pas déclencher de toast d'erreur côté useApi. /weigh garde son comportement 500 actuel.

Configuration env (suppression de la duplication)

• Remplacer PONT_BASCULE_URL (URL complète .../send/dsd) par PONT_BASCULE_BASE_URL (URL de base sans chemin, ex. http://100.122.43.54:8000).
• Le service construit lui-même {base}/send/dsd et {base}/health.
• Fichiers à mettre à jour : .env (valeur vide), .env.local, .env.prod, et config/services.yaml (argument $baseUrl au lieu de $endpoint).
• PONT_BASCULE_BYPASS inchangé.

Backend

PontBasculeService (src/Service/PontBasculeService.php)

• Renommer la dépendance $endpoint → $baseUrl.
• fetch() : POST sur {baseUrl}/send/dsd (comportement inchangé sinon).
• Nouvelle méthode checkHealth(): PontBasculeHealth :
  • si $bypass → renvoie un PontBasculeHealth sain (healthy = true) sans appel réseau ;
  • sinon → GET {baseUrl}/health, parse le JSON, calcule healthy = ok === true && port_connected === true && port_error === null && busy === false ;
  • si l'appel transport échoue ou le JSON est invalide / incomplet → renvoie PontBasculeHealth avec healthy = false (aucune exception levée).

DTO PontBasculeHealth (src/Dto/PontBasculeHealth.php)

Groupe de sérialisation pont_bascule:health:read. Champs :

• healthy: bool — le seul champ consommé par le front.
• Champs informatifs (debug / affichage futur) : ok: bool, busy: bool, portConnected: bool, portError: ?string, hostname: ?string.

Ressource API PontBasculeHealthCheck (src/ApiResource/PontBasculeHealthCheck.php)

• Classe carrier fine (vide) hébergeant l'opération GET /pont_bascule/health, sans état persistant, output = PontBasculeHealth::class (le DTO), provider = PontBasculeHealthProvider. Même montage que /receptions/weigh (host déclare l'opération, output = DTO, provider renvoie le DTO).
• Nommée PontBasculeHealthCheck pour éviter la collision de nom court avec le DTO Dto\PontBasculeHealth.
• Route conservée /pont_bascule/health (pont_bascule invariable).

PontBasculeHealthProvider (src/State/PontBasculeHealthProvider.php)

• Appelle PontBasculeService::checkHealth() et renvoie le DTO PontBasculeHealth.
• Toujours 200, même pont down (pas de HttpException).

Frontend

Couche service

• Nouveau composable usePontBascule (composables/usePontBascule.ts) exposant checkHealth() → api.get('pont_bascule/health'), renvoie { healthy: boolean, ... }. Le health-check étant agnostique de l'entité, il vit dans son propre composable (et non dans workflow-service.ts qui est un factory par entité) — une seule implémentation, pas de duplication réception/expédition.

useWeighingStep.ts (composables/steps/)

• Ajout d'un état réactif pontBasculeStatus: 'checking' | 'connected' | 'disconnected' (initialisé à 'checking').
• Au onMounted : appel du health-check → connected si healthy === true, sinon disconnected.
• Exposer pontBasculeStatus au composant.

workflow-weight.vue (components/workflow/)

• Le texte hardcodé ligne 5 (Pont-bascule connecté) devient dynamique selon pontBasculeStatus :
  • checking → « Vérification du pont-bascule… »
  • connected → « Pont-bascule connecté » (vert, style actuel)
  • disconnected → « Pont-bascule non connecté » (rouge)
• Le bouton « peser » reçoit disabled tant que pontBasculeStatus !== 'connected' (état grisé). Les boutons « Valider la pesée » et « Générer le bon » restent inchangés.

Textes d'état (codés en dur)

Convention du projet : les textes d'UI dans les composants/pages sont codés en dur en français (le « Pont-bascule connecté » actuel l'est déjà). fr.json n'est consommé que par useApi pour les toasts. On reste cohérent : les trois libellés sont écrits directement dans workflow-weight.vue, pas dans fr.json.

• checking → « Vérification du pont-bascule… » (couleur primary)
• connected → « Pont-bascule connecté » (vert)
• disconnected → « Pont-bascule non connecté » (rouge)

Error handling

• /weigh : comportement inchangé (500 + PontBasculeException).
• /pont_bascule/health : ne lève jamais d'erreur réseau vers le front. Pont injoignable ou payload invalide = 200 { healthy: false } → pas de toast d'erreur useApi.

Tests

Backend (PHPUnit, MockHttpClient)

Couvrir PontBasculeService::checkHealth() :

• bypass actif → healthy = true, aucun appel réseau ;
• payload sain (ok, port_connected, port_error: null, busy: false) → healthy = true ;
• port_error non null → healthy = false ;
• port_connected: false → healthy = false ;
• busy: true → healthy = false ;
• transport KO / JSON invalide → healthy = false (pas d'exception).

Frontend

Pas de test auto existant pour ce flux. Validation manuelle :

• bypass on → bouton « peser » actif, texte « connecté » ;
• simuler un fail (healthy: false) → bouton grisé, texte « non connecté ».

Hors périmètre

• Polling / rafraîchissement automatique de l'état (check unique au montage retenu).
• Bouton « réessayer » manuel.
• Traductions autres que fr.