Dépannage — Backstage

Cette page regroupe les pannes rencontrées par les administrateurs SUPER_ADMIN et GOVERNANCE dans Backstage. Chaque entrée suit le modèle Symptôme → Cause probable → Solution.

Erreur 403 en accédant à Backstage

Symptôme : L'URL /backstage renvoie 403 Forbidden ou redirige vers la page publique.

Cause probable : Votre rôle n'est pas SUPER_ADMIN ou GOVERNANCE, ou votre session a expiré sans refresh du token.

Solution :

1. Vérifier votre rôle courant dans Profil > Mon compte
2. Se déconnecter complètement puis se reconnecter
3. Vider le cookie medguru_session
4. Demander à un SUPER_ADMIN de confirmer votre rôle

Escalade

Si le rôle est correct mais le 403 persiste, contactez Marie Dupont avec votre user ID et l'heure de tentative.

Extraction de rate card en échec

Symptôme : Après upload d'un PDF de grille tarifaire, le statut reste failed ou extracted_0_lines.

Cause probable : PDF scanné (image non OCR), structure atypique non couverte par le prompt actif, ou timeout d'appel Claude.

Solution :

1. Vérifier que le PDF est un PDF texte et non un scan (copier-coller un prix doit marcher)
2. Si scan, passer par un OCR préalable (ocrmypdf recommandé)
3. Consulter le log d'extraction dans Rate Cards > Fiche > Log
4. Tester un autre prompt en staging via Prompt Studio sur le même PDF
5. Si le prompt manque de robustesse, forker et améliorer puis activer

Escalade

Contactez Marie Dupont avec l'ID de la rate card, le nom du prompt actif et un extrait du log d'erreur.

Synchronisation PIGES échoue

Symptôme : Le panneau PIGES Sync affiche last_sync_failed et les validateurs ne voient pas les nouvelles publicités.

Cause probable : Service Streamlit down, crédentials expirés, ou lock DB côté PIGES.

Solution :

1. Tester l'accès direct à l'app PIGES (URL interne)
2. Vérifier les crédentials dans Backstage > Config > PIGES (rotation tous les 90 jours)
3. Lancer une synchro manuelle via le bouton Force sync
4. Consulter les logs piges-sync dans le monitoring VPS

Escalade

Si l'app PIGES est inaccessible, contactez l'équipe infrastructure en premier. Si elle est accessible mais que la sync échoue, contactez Marie Dupont avec le log complet.

Catalogue : format non trouvé

Symptôme : Lors du triage d'une ligne rate card, le matching échoue bien que le format existe visiblement au catalogue.

Cause probable : Alias manquant, typo dans le nom, ou format archivé (is_active = false).

Solution :

1. Ouvrir la fiche format dans Catalogue > Formats
2. Vérifier le statut is_active
3. Lister les alias existants, comparer avec le libellé reçu
4. Ajouter un nouvel alias si besoin (ex. 1/2P HORIZ → DEMI_PAGE_HORIZONTAL)
5. Relancer le triage IA sur la ligne concernée

Activation d'un prompt bloquée

Symptôme : Le bouton Activer en production dans Prompt Studio est grisé ou renvoie une erreur silencieuse.

Cause probable : Tests de validation manquants, un autre prompt est en cours d'activation (lock), ou la version est marquée draft.

Solution :

1. Vérifier que le prompt a été testé avec au moins 10 samples (badge validated)
2. Confirmer que son statut est ready_for_prod, pas draft
3. Attendre que l'activation concurrente se termine (visible dans Prompt Studio > Activity)
4. Rafraîchir la page et réessayer

Escalade

Si le lock reste actif plus de 15 minutes sans activité concurrente visible, contactez Marie Dupont — un nettoyage manuel du lock DB peut être nécessaire.

Migration Prisma en état pending

Symptôme : Un déploiement indique que la migration est pending et bloque l'application.

Cause probable : Migration partielle interrompue, conflit de schéma, ou absence de droits DB.

Solution :

1. Consulter la table _prisma_migrations pour identifier la ligne pending
2. Vérifier les logs de déploiement (journalctl -u medguru-api)
3. Si la migration est idempotente, relancer via prisma migrate deploy
4. Sinon, contacter l'équipe dev pour décision de rollback ou correction manuelle

Escalade

Ne jamais forcer prisma migrate resolve sans consulter Marie Dupont — risque de désynchro schéma/DB.

Permissions incohérentes entre users

Symptôme : Deux utilisateurs avec le même rôle voient des fonctionnalités différentes dans Backstage.

Cause probable : Cache de session obsolète, rôle modifié sans logout forcé, ou override au niveau utilisateur (champ permissions_override).

Solution :

1. Demander aux deux utilisateurs de se déconnecter/reconnecter
2. Vérifier les champs role et permissions_override dans Users > Détail
3. Réaligner les overrides si un deny ou grant custom a été posé
4. Tester avec un troisième utilisateur du même rôle pour valider

Escalade

Si la différence persiste après re-login et alignement, contactez Marie Dupont avec les IDs des deux users et les URLs où la différence est visible.

Contacter le support

Pour toute panne non listée : ouvrir une issue sur GitHub avec logs, IDs, timestamps, ou contacter Marie Dupont directement.