Aller au contenu principal

Guide de Dépannage et Résolution des Anomalies

Ce guide rassemble les solutions éprouvées pour diagnostiquer et corriger rapidement les anomalies transversales pouvant survenir lors de l'exploitation de TkushPatch.

1. Anomalies Liées au CLI et à la Compilation​

Erreur : shorebird.yaml not found ou Missing app_id​

  • Symptôme : Lors de l'exécution de tk-ota-push release ou tk-ota-push patch, le CLI affiche une erreur indiquant l'absence du fichier de configuration.
  • Cause : La commande est exécutée depuis un sous-dossier ou le projet n'a pas été initialisé.
  • Solution :
    1. Placez-vous à la racine exacte de votre projet Flutter contenant pubspec.yaml.
    2. Exécutez tk-ota-push init pour régénérer le fichier shorebird.yaml.
    3. Vérifiez la présence des deux clés obligatoires : 
      app_id: "VOTRE-APP-UUID"
      base_url: "https://api.tkushpatch.domaine.cm"

Erreur : Patch rejected: Native code modified (native_bridge_ok: false)​

  • Symptôme : La commande tk-ota-push patch échoue en signalant une modification du code natif sous-jacent.
  • Cause : Des dépendances ajoutées dans pubspec.yaml incluent du code C++, Java/Kotlin ou Swift non présent dans la release Store de base.
  • Solution :
    • Un patch OTA ne peut contenir que du code Dart pur.
    • Si vous avez ajouté des packages natifs (ex. nouveau plugin d'appareil photo ou Bluetooth), vous devez obligatoirement créer une nouvelle release de base Store (tk-ota-push release android) et la soumettre aux magasins d'applications.

2. Anomalies de Distribution et Statut des Patchs​

Symptôme : Le patch est publié mais le smartphone ne le télécharge pas​

Vérifiez méthodiquement les 5 causes classiques :

Arbre de décision pour la résolution d'anomalies
  • Le patch est au statut STAGED ? ➔ Rendez-vous dans le menu Approbations de la Console Web pour valider le correctif.
  • Le patch est au statut ROLLED_BACK ? ➔ Le correctif a été révoqué. Publiez un nouveau patch correctif incrémental.
  • L'appareil ne reçoit pas la mise à jour ? ➔ Vérifiez que le terminal correspond au canal configuré, aux pays ciblés et au pourcentage de déploiement actif.

Erreur HTTP 429 Too Many Requests​

  • Symptôme : Les requêtes mobiles renvoient une erreur 429 avec l'en-tête Retry-After: 60.
  • Cause : Le Rate-Limiter Token Bucket (DataPlaneRateLimitFilter) a détecté plus de 120 requêtes par minute depuis l'adresse IP cliente.
  • Solution :
    • Si tous vos terminaux mobiles sortent via la même passerelle proxy d'entreprise, activez l'en-tête de confiance dans application.properties du serveur : 
      ota.rate-limit.trust-forwarded-header=true
      ota.rate-limit.capacity-per-minute=300

3. Cryptographie et Signature moteur cryptographique​

Erreur : RSA signature verification failed (ring::error::Unspecified)​

  • Symptôme : Le smartphone télécharge le patch mais le rejette immédiatement avec une erreur dans les logs Android/iOS adb logcat.
  • Cause 1 : La clé publique intégrée dans l'application au moment du build Store ne correspond pas à la clé privée utilisée pour signer le patch.
    • Vérification : Avez-vous compilé l'application avec un compte développeur différent ou ciblé par mégarde une instance de pré-production ?
  • Cause 2 : Incompatibilité du format de signature. Le serveur doit signer l'ASCII hexadécimal de 64 caractères du digest SHA-256 (hash.toLowerCase().getBytes(US_ASCII)), et non les octets bruts.

Erreur Console : Service de signature indisponible (HTTP 503)​

  • Symptôme : Impossible d'approuver ou de signer un patch sur l'écran /approvals.
  • Cause : Le conteneur moteur cryptographique a redémarré et se trouve dans l'état scellé (Sealed).
  • Solution :
    1. Connectez-vous au serveur moteur de signature.
    2. Procédez au déverrouillage avec vos clés Shamir : Contactez l'administrateur système pour réactiver le service de signature.
    3. Dès que sealed: false, rechargez la console pour reprendre les signatures.

4. Comportement Mobile Runtime et Désobfuscation​

Symptôme : Le patch est téléchargé mais les changements ne s'affichent pas​

  • Cause : Par défaut, le moteur Flutter applique le patch au prochain redémarrage à froid de l'application pour ne pas perturber l'expérience utilisateur en pleine session.
  • Solution :
    1. Fermez complètement l'application (tuez le processus dans le sélecteur d'applications).
    2. Relancez-la. La modification doit apparaître immédiatement.
    3. Pour forcer un redémarrage instantané, utilisez l'option TkOtaPush.restartApp() fournie par le SDK dans vos écrans de mise à jour bloquante.

Symptôme : L'application plante au lancement puis revient à l'ancienne version​

  • Cause : Le mécanisme de sécurité Rollback 2-Crashs a détecté une exception fatale non interceptée au démarrage avec le nouveau patch.
  • Solution pour diagnostiquer :
    1. Rendez-vous sur la console /symbols.
    2. Récupérez la trace de crash depuis adb logcat ou votre outil de crash-reporting.
    3. Collez la trace obfusquée dans le désobfuscateur pour identifier la ligne exacte de code Dart ayant provoqué l'exception : 
      #00 abs 00000072a3194 binaire d'application + 0x12a3194
      => package:mon_app/services/api_service.dart:42:15 in fetchData()
    4. Corrigez le bug Dart et publiez un Patch #2 correctif.