Exploitation et contribution¶

Validation avant livraison¶

Toute modification doit mettre à jour la documentation fonctionnelle, la documentation technique et le scénario correspondant sous docs/testing/. La recette utilise des identifiants stables afin de consigner le résultat, la version testée et les preuves dans un rapport d'exécution.

Toute évolution commence également par un plan versionné et humainement validé selon le workflow de développement assisté par IA. Les diagnostics en lecture seule restent possibles sans plan ; la première modification déclenche obligatoirement ce cycle.

Santé et journaux¶

/health vérifie le processus API ; /ready vérifie ses dépendances et le schéma. Les services Compose possèdent leurs healthchecks. logs-init termine normalement avec le statut exited (0).

docker compose ps
docker compose logs -f api
docker compose logs -f fivem
docker compose logs -f bot
docker compose logs -f docs

Les fichiers de plus de 10 Mio sont archivés toutes les cinq minutes et cinq rotations sont conservées.

Validation¶

docker compose exec api pytest
docker compose exec api ruff check .
node --check admin/public/app.js
docker compose build docs

Le dernier contrôle exécute mkdocs build --strict dans l'image et échoue sur les avertissements.

Règle de contribution documentaire¶

Chaque modification de code, configuration, infrastructure ou comportement doit :

mettre à jour la documentation fonctionnelle concernée ;
mettre à jour la documentation technique concernée ;
synchroniser mkdocs.yml si une page change ;
valider le build strict avant le commit.

Cette règle figure aussi dans .agents/AGENTS.md afin qu'elle fasse partie du workflow de toutes les futures interventions.

Sauvegardes¶

Sauvegarder régulièrement PostgreSQL et les volumes fivem_txdata et fivem_resources. Redis n'est pas la source de vérité, mais son volume peut être conservé pour préserver les états temporaires lors d'une restauration complète.

Diagnostic des synchronisations API¶

Chaque requête FiveM transmet un X-Correlation-ID, également renvoyé par l'API. Les erreurs des ressources indiquent méthode, route, code, statut éventuel et corrélation, jamais la clé interne ni le payload. Les synchronisations périodiques bruyantes journalisent une transition degraded, puis une transition recovered, au lieu de répéter la même erreur à chaque poll.

Diagnostic du module véhicule étendu¶

Au démarrage, contrôler dans cet ordre : head Alembic 0033, état des trois flags, synchronisation du catalogue ORIGINAL, nombre de sources valides/ambiguës, profils non affectés, puis synchronisation des capacités. Une source absente ou ambiguë doit laisser le véhicule intact ; elle ne justifie pas une valeur de remplacement Internet.

Les refus API/FiveM doivent afficher un message français et un code/correlation ID dans F10 ou la NUI concernée. Les logs ne contiennent ni clé interne, boot_token, contenu d'inventaire, token de siège ni paramètres complets d'un payload. Les lectures détaillées et mutations administratives créent un audit minimal ; les résumés restent non sensibles.

En panne API, DB ou Redis, refuser ouverture, mutation, preview et purge sans faux succès. Une explosion non commitée conserve les objets et ne crée aucune reprise différée. Après retour du service, le polling borné recharge flags/handling et les joueurs rouvrent une nouvelle session ; une ancienne mutation n'est jamais rejouée sans son request_id idempotent.

Exploitation énergie¶

Surveiller head 0040, sessions actives/recovery, volumes par produit/propulsion, recettes, refus, règlements/restitutions, stations actives/archivées, anomalies, états available|recent_zero|stale|never et nombre de pompes ou points physiques. Un zéro récent signale une zone sans installation détectable ; never/stale signale surtout un manque d'observation et ne doit pas être maquillé par une interaction invisible.

En incident énergie, couper la famille de stations concernée ou le système, laisser le recovery régulariser et rechercher une ressource fuel concurrente. La migration 0040 ne se downgrade pas ; appliquer un correctif en avant ou restaurer une sauvegarde coordonnée. Le runbook complet est dans Énergie des véhicules.