Vérification et dépannage

12 min

Vue d'ensemble

Cette page permet de contrôler qu'un projet fraîchement installé fonctionne de bout en bout, puis de diagnostiquer les erreurs les plus fréquemment rencontrées lors des premiers pas.

Elle est organisée par symptôme : à chaque symptôme correspond une cause probable et une correction.

Checklist de vérification

#	Contrôle	Attendu
1	docker compose ps	Les services annexes sont démarrés.
2	npm run migrate:dev	Les migrations en attente sont appliquées sans erreur.
3	npm run start-server:dev	Le serveur Express démarre et journalise sa version.
4	npm run front:dev	Le client Vite est servi sur le port 8000.
5	Décrochage	La première vue s'affiche dans le navigateur.
6	npm run entities:gen	La commande se termine sans erreur et ne produit pas de migration inattendue.
7	npm run views:gen	La commande valide les transitions de chaque vue.
8	npm run lint et npm run test	Aucune erreur.

Erreurs courantes

Installation et initialisation

Symptôme	Cause probable	Correction
npm install échoue sur une erreur d'authentification.	Le registre npm privé @fasstech n'est pas accessible.	Vérifiez l'authentification déclarée dans le fichier .npmrc.
Le clone du modèle de projet échoue.	Absence de droits sur fasst/fasst-oip-starter.	Faites vérifier votre accès au dépôt, et l'existence de la branche v4.
docker compose up -d échoue au téléchargement d'une image.	Absence de droits sur les images fasstech/*.	Authentifiez-vous auprès du registre Docker, puis relancez la commande.
Les commandes distantes d'OIP Tools échouent.	OIP_TOOLS_CLIENT_SECRET absente ou invalide.	Renseignez la variable dans le fichier .env avant de relancer la commande.

Génération de code et migrations

Symptôme	Cause probable	Correction
views:gen s'arrête sur une erreur de transition.	Le fichier de transition d'une vue est absent, mal nommé ou invalide.	Créez transitions/<viewId>.mjs : le nom du fichier doit correspondre exactement au viewId de la vue.
migrate:dev échoue en signalant une migration manquante.	Un fichier de migration déjà exécuté a été supprimé, renommé ou modifié.	Restaurez le fichier depuis l'historique Git. Toute correction passe par une nouvelle migration.
Une entité déclarée dans la configuration n'existe pas en base.	La migration produite par entities:gen n'a pas été appliquée.	Exécutez npm run migrate:dev.
Une modification apportée à un fichier du répertoire entities/ ou views/ a disparu.	Le fichier est généré et a été réécrit.	Modifiez la configuration source, puis régénérez. Voir « Code généré ».

Démarrage du serveur

Symptôme	Cause probable	Correction
Le serveur s'arrête immédiatement au démarrage.	Une variable d'environnement obligatoire est absente ou invalide.	Le journal indique la variable fautive. Comparez .env et .env.dist, puis corrigez.
Le serveur démarre mais aucune donnée n'est persistée.	OIP_API_URL ou OIP_API_KEY incorrecte.	Vérifiez que l'URL pointe bien vers le service OIP Headless démarré localement.
Les erreurs GraphQL retournées au client sont génériques.	NODE_ENV vaut production.	Comportement attendu. En développement, positionnez une autre valeur.

Décrochage et session

Symptôme	Cause probable	Correction
Le décrochage échoue alors qu'aucun jeton n'est fourni.	SECURE_SESSION vaut true.	Fournissez un jeton en paramètre d'URL, ou positionnez SECURE_SESSION=false en développement.
Le jeton est refusé.	Jeton expiré, ou SESSION_SERVICE_URL incorrecte.	Générez un nouveau jeton et vérifiez l'URL du service de sessions.
La session est perdue à chaque requête.	Le cookie de session n'est pas transmis.	SECURE_COOKIE=true impose l'usage d'HTTPS : positionnez la variable à false en développement local.
Le magasin de sessions est inaccessible au démarrage.	La base désignée par SESSION_STORE_URL n'existe pas.	Créez la base de données dédiée aux sessions.
Le parcours redémarre systématiquement sur la première vue.	resolveFirstView ignore le viewId reçu en paramètre.	Retournez le viewId reçu lorsqu'il est non nul, afin de reprendre le parcours où il s'était arrêté.

Client

Symptôme	Cause probable	Correction
Le client n'atteint pas le serveur dans un déploiement multi-origines.	SERVER_URL non définie, ou variable __SERVER_URL__ absente de vite.config.js.	Déclarez la variable d'environnement et son équivalent dans la section define de vite.config.js.
Les appels GraphQL sont rejetés par le navigateur.	Configuration CORS trop restrictive.	Ajustez corsOptions dans la configuration du serveur.
L'authentification client échoue.	CLIENT_ID, CLIENT_SECRET ou API_KEYS incohérents.	API_KEYS doit valoir CLIENT_ID:CLIENT_SECRET.

Tâches asynchrones

Symptôme	Cause probable	Correction
Une tâche est programmée mais jamais exécutée.	Le consommateur AMQP n'est pas enregistré.	Enregistrez un consommateur sur la file <OAV_ID>.events avec handleTask dans server/index.mjs.
Aucune notification n'est reçue côté client.	Connexion RabbitMQ invalide.	Vérifiez RABBIT_MQ_HOST, RABBIT_MQ_USER, RABBIT_MQ_PASSWORD et RABBIT_MQ_VHOST.
La tâche reste dans l'état executing.	Le processus enfant ne se termine pas.	Terminez explicitement le processus par process.exit(0) ou process.exit(1).

Journalisation

Le niveau de journalisation est piloté par la variable LOGGER_LEVEL. L'implémentation fournie par défaut propose quatre niveaux :

Niveau	Usage
ERROR	Valeur par défaut : seules les erreurs sont journalisées.
WARNING	Ajoute les avertissements.
INFO	Ajoute les évènements de fonctionnement nominal.
DEBUG	Ajoute le détail utile au diagnostic.

Consultez les journaux des services annexes :

docker compose logs -f

[info] En phase de diagnostic, positionnez LOGGER_LEVEL=DEBUG dans le fichier .env, puis redémarrez le serveur.

Repartir d'un environnement propre

En développement uniquement, il est parfois plus rapide de réinitialiser complètement les services annexes et leurs données :

docker compose down -v
docker compose up -d
npm run migrate:dev

[warn] L'option -v supprime les volumes, donc l'intégralité des données persistées. Cette procédure ne doit jamais être appliquée à un environnement partagé.

Résumé

Une installation saine se vérifie en huit contrôles, du démarrage des services à l'exécution des tests ;

LOGGER_LEVEL=DEBUG et docker compose logs -f sont les deux premiers réflexes de diagnostic.