Diagnostic technique

Un diagnostic efficace commence par identifier la frontière en échec. Conservez l’heure, l’URL, la commande et le premier message d’erreur ; anonymisez toute preuve partagée.

Vérification rapide

# état des dépôts
make status

# backend joignable
curl --fail http://127.0.0.1:8090/api/hello

# validations déterministes
make verify

Si le health check échoue, ne cherchez pas d’abord dans un composant Svelte. Si l’API répond mais la page échoue, inspectez le load serveur, le BFF et le mapping.

Port déjà utilisé

Vérifiez le processus qui écoute sur 5173, 8090, 6006 ou 4321. Arrêtez uniquement le processus que vous avez identifié. Ne tuez pas une liste de PID ou tous les processus Node/Go.

Backend ne démarre pas

1. Vérifiez go version et .go-version.
2. Exécutez go mod download.
3. Lisez la première erreur de migration ou de configuration.
4. Vérifiez que PB_DATA_DIR cible le répertoire voulu.
5. Lancez make test-integration si l’erreur concerne le schéma.

Une clé de chiffrement changée peut rendre les secrets TOTP ou URL iCalendar existants illisibles. Restaurez la clé attendue ; ne reseedez pas ou ne supprimez pas les données avant d’avoir confirmé le diagnostic.

Seed en échec

make seed doit afficher l’upsert du superutilisateur et terminer exactement par Seeding complete.. Vérifiez :

• e-mail et mot de passe non vides ;
• droits d’écriture dans PB_DATA_DIR ;
• compatibilité des migrations ;
• absence d’un backend concurrent utilisant le même répertoire.

Le seed est idempotent. Un doublon indique une clé métier ou un upsert incorrect, pas un besoin de supprimer toute la base.

Frontend ne compile pas

npm run i18n:compile
npx svelte-kit sync
npm run check

Un avertissement sur .svelte-kit/tsconfig.json avant la synchronisation signifie souvent que les types générés n’existent pas encore. La CI exécute la synchronisation via npm run check.

Si Paraglide ne génère plus certaines fonctions, vérifiez d’abord le téléchargement de ses plugins et la présence de la clé dans tous les catalogues. Ne modifiez pas les fichiers générés.

Page back-office redirigée vers login

1. Vérifiez le cookie de session sans en copier la valeur.
2. Confirmez que API_BASE_URL cible le backend attendu.
3. Appelez /api/back-office/auth/me côté serveur avec un token de test autorisé.
4. Vérifiez que le compte est actif et possède un rôle connu.
5. Inspectez l’expiration ou la rotation de la session.

Une boucle de redirection vient souvent d’un token refusé par le backend puis supprimé par hooks.server.ts.

Réponse 401, 403, 404 ou 409

• 401 : session absente, expirée ou token invalide ;
• 403 : identité valide mais rôle insuffisant ;
• 404 : ressource/slug absent ou visibilité publique insuffisante ;
• 409 : version concurrente ou transition d’état interdite.

Ne transformez pas tous ces statuts en 500 ou en tableau vide : chacun demande une réponse utilisateur différente.

Bad gateway en preview

Vérifiez dans l’ordre :

1. conteneur réellement démarré ;
2. port d’écoute interne conforme à Dokploy ;
3. service lié au domaine de preview ;
4. health check accessible depuis le réseau du proxy ;
5. variables runtime présentes ;
6. logs du processus après le build.

Un build réussi ne prouve pas que le serveur écoute sur la bonne interface ou le bon port.

Carte vide

PUBLIC_MAPTILER_KEY est lue au démarrage du frontend. Vérifiez sa présence dans l’environnement Dokploy et les domaines autorisés chez MapTiler. Une clé valide en local peut être refusée sur une URL de preview différente.

SSE de notifications interrompu

Contrôlez l’endpoint /api/back-office/notifications/stream, la session, les timeouts du proxy et le buffering. Une connexion SSE est longue et ne doit pas être traitée comme une requête HTTP courte. Le client doit pouvoir se reconnecter sans dupliquer l’état.

Import média bloqué

Vérifiez format, taille, statut du job, stockage disponible et logs du worker. Distinguez l’échec de l’original de celui d’une variante WebP/AVIF. Ne relancez pas plusieurs imports identiques en parallèle.

Calendrier externe non synchronisé

Vérifiez accès réseau, validité du feed, clé de chiffrement, intervalle, dernière erreur et libellés non associés. Ne journalisez pas l’URL complète : elle peut contenir un token.

Documentation en échec

HARMONY_BACKEND_DIR=../backend npm run docs:check
HARMONY_BACKEND_DIR=../backend npm run docs:build

Si aucune source OpenAPI n’est lisible, définissez HARMONY_BACKEND_DIR ou une URL immuable. Une image manquante vient généralement d’un chemin relatif calculé depuis le fichier Markdown.

Rapport de bug technique

Incluez : SHA, branche, environnement, versions Node/Go, commande, première erreur, étapes de reproduction, résultat attendu, résultat réel et logs anonymisés. Excluez cookies, tokens, mots de passe, URLs iCalendar privées, données client et clés fournisseur.