HormoneTrack/docs/GUIDE_INSTALLATION.md

HormoneTrack — Guide d'installation et d'utilisation

App Android de suivi de THS : courbes estimées heure par heure (E2 + T), log des doses, analyses de sang avec calibration, rappels affichés sur la Huawei Watch GT 3.

⚠️ Important : les courbes sont des estimations pharmacocinétiques, pas des mesures. Fie-toi toujours à tes prises de sang et aux consignes de ton endocrinologue.

---

1. Installer les outils (une seule fois)

1. Télécharge Android Studio (Ladybug ou plus récent) : https://developer.android.com/studio
2. Installe-le, lance-le une première fois et accepte l'installation du SDK Android (assistant de setup par défaut, tout coché).
3. Il te faut ~10 Go d'espace disque libre.

Tu n'as pas besoin d'installer Gradle ni le JDK séparément : Android Studio s'en charge.

1.bis Option SANS compilation : télécharger l'APK depuis les releases

Chaque version taguée est publiée en release Gitea avec les APK prêts à installer — pas besoin d'Android Studio ni de faire un build :

1. Va sur Releases du dépôt Gitea (onglet « Releases » à droite) : https://gitea.cloudyfy.fr/Siphonight/HormoneTrack/releases (miroir équivalent : https://gitea.farewell.dev/Siphonight/HormoneTrack/releases)
2. Deux APK par release :

Fichier	Quoi	Pour qui
HormoneTrack-vX.Y.Z-release.apk	Optimisé (R8 : code minifié/compacté, ressources shrinkées) — 2,4 Mo au lieu de 20 Mo, démarrage et fluidité meilleurs	Recommandé — usage quotidien
HormoneTrack-vX.Y.Z-debug.apk	Non optimisé, hookable par un debugger — 20 Mo	Diagnostic/développement uniquement

3. Installe : télécharge l'APK → ouvre-le → accepte « installer une application inconnue » (une seule fois). Mise à jour : installe la nouvelle version par-dessus l'ancienne — données conservées (les deux APK sont signés avec la même clé debug, donc interchangeables dans les deux sens sans perte).

⚠️ Après l'installation d'un APK release (optimisé R8), fais un test rapide une fois : export/import d'un backup JSON + graphiques — R8 n'est pas vérifiable par les tests automatisés.

2. Ouvrir le projet

1. Android Studio → Open → sélectionne le dossier ~/projects/HormoneTrack
2. Laisse le Gradle Sync se terminer (première fois : téléchargements, 5–15 min)
   • La barre du bas affiche la progression ; attends « Gradle sync finished ».
3. (v1.9.0) Le modèle Estrannaise est analytique : l'ancienne table pk_profiles.json n'est plus embarquée dans l'APK (elle ne sert qu'aux tests de fidélité, dans app/src/test/assets/).

3. Préparer ton téléphone

1. Paramètres → À propos du téléphone → tape 7 fois sur « Numéro de build » → « Mode développeur activé »
2. Paramètres → Système → Options développeur → active Débogage USB
3. Branche le téléphone en USB → accepte la fenêtre « Autoriser le débogage USB »

4. Installer l'app

1. Dans Android Studio, sélectionne ton téléphone dans la liste d'appareils (en haut)
2. Clique sur Run ▶️
3. L'app s'installe (pas de Play Store nécessaire) — au premier lancement :
   • Autorise les notifications (Android 13+)
   • Dans Paramètres → Rappels & alarmes : bouton « Accorder les alarmes exactes » (sinon les rappels peuvent être en retard de quelques minutes)

5. Voir les rappels sur la Watch GT 3

Les notifications de l'app remontent automatiquement sur la montre via Huawei Santé :

1. Vérifie que la montre est jumelée à Huawei Santé
2. Dans Huawei Santé → Montre → Notifications :
   • Autorise les notifications d'applications
   • L'app « Suivi Hormonal / HormoneTrack » doit être dans la liste autorisée
3. Test : programme un rappel 2 min à l'avance → la notif doit apparaître au poignet avec les boutons « Pris » et « Reporter 1 h »

Quand le rappel sonne-t-il ? (v1.4.0) : si le traitement a une Posologie (intervalle en jours) et un historique de prises, le rappel sonne uniquement le jour du créneau à l'heure choisie (ex. : injection tous les samedis, rappel 18 h → notification le samedi à 18 h, pas les autres jours). Après « Pris », le rappel suivant se cale sur le créneau d'après. Sans Posologie (gel, oral) → rappel quotidien.

Sur la GT 3, on ne peut pas installer d'app au poignet facilement (Lite Wearable, sideload via DevEco Assistant). La v1 utilise la montre comme écran de notifications, ce qui est fiable et sans maintenance. Une mini-app au poignet reste possible en Phase 2 si tu veux.

6. Premiers pas dans l'app

1. Traitements → + → choisis un preset (ex : Injection EV — Estrannaise)
   • Tu as changé d'ester ? Crée (ou garde) le traitement de l'ancien ester et passe-le inactif (switch « Actif ») : il disparaît de la saisie et de tes rappels, mais son historique reste simulé et calibré sur les graphiques — parfait pour une transition valerate → enanthate
   • Agenda : active « Événement d'agenda récurrent » (sous Rappels) → une fois la permission accordée et le traitement sauvegardé, un événement se répétant tous les N jours (Posologie) apparaît dans le calendrier « HormoneTrack » de ton téléphone (≥ v1.3.5 ; en v1.3.4 la création du calendrier échouait — retour dans le guide si besoin : re-sauvegarde avec le switch activé)
   • Ester (EV / EU / EEn) + modèle (Estrannaise / Transfem Science) = les courbes du .ods
   • Pour gel/patch/oral : paramètres Bateman (temps au pic, demi-vie, biodispo)
2. Doses → + → logue tes injections passées
   • L'accueil affiche la prochaine dose en jours quand elle est à plus de 24 h (ex. « 5 j 2 h · sam. 6 18:00 »), en heures/minutes sinon
   • La carte « Niveau actuel » compare ton taux estimé à il y a 6 h (flèche ↗/↘) — autour d'un ester lent comme l'énanthate, cette variation reste faible : la courbe d'équilibre est naturellement plate, la remontée après une injection se voit sur 3-4 jours (pic vers J+6,5), pas en 6 h
   • Astuce mise à jour : l'app affiche les nouveautés de chaque version au démarrage (fermable) ; la version installée et le lien des releases sont dans Paramètres (date/heure exactes, dose en mg)
   • Astuce : tu peux changer l'ester par injection (comme dans ton tableur)
   • Modifier une dose existante : appuie simplement sur sa ligne dans l'écran Doses (traitement, dose, date/heure, notes et ester tout ça éditable) — pas besoin de supprimer/recréer
3. Analyses → + → une prise de sang complète en une entrée : E2 et/ou T (chacune optionnelle), date/heure commune, notes — les deux s'affichent côte à côte dans la liste
   • Modifier : appuie sur la ligne ; si la prise contient E2 et T, un sélecteur te demande laquelle modifier
   • Supprimer : la corbeille retire la prise entière (E2 + T ensemble)
   • Choisis bien l'unité : elle est convertie automatiquement pour l'affichage et la calibration (E2 en pg/mL ; T en ng/mL, ng/dL, ng/L, nmol/L)
   • Prochaine prise de sang (suggestion, v1.8.0 ; v1.8.1 : aussi sur l'Accueil) : si ton traitement E2 injectable actif a une Posologie, la page te suggère quand faire la prochaine analyse — au creux estimé, juste avant l'injection suivante (moment le plus comparable), au premier creux où ton ester est stabilisé (~5 demi-vies après le dernier changement). Sans Posologie : la page t'invite à en renseigner une (Traitements → éditer) pour activer la suggestion. C'est une estimation du modèle, pas un avis médical
4. Calibration (dans l'édition d'un traitement E2) → « Calibrer avec les analyses »
   • Paramètres → Logs de diagnostic : « Exporter » ouvre le gestionnaire de fichiers → choisis où enregistrer le .txt → un message de confirmation (ou d'erreur) s'affiche en haut de Paramètres — utile pour joindre les logs à un rapport de bug (≥ v1.3.4 ; les versions 1.3.1–1.3.3 faisaient planter ce bouton) → calcule le facteur d'échelle = médiane(lab ÷ prédiction), comme le « Scale factor » du .ods
5. Paramètres :
   • Langue : Système / Français / English
   • Seuils d'alerte (v1.4.2) : limites hautes/basses optionnelles E2 (pg/mL) et T (ng/mL) — l'accueil affiche un avertissement (et une notification toutes les 15 min, canal dédié réglable) quand ton taux ESTIMÉ franchit une limite. Champ vide = alerte désactivée ; haut > bas requis. C'est une estimation du modèle, pas une mesure
   • Estimation T : modèle T = plancher + (base − plancher) ÷ (1 + k·E2) (ng/mL), calibrable avec tes résultats T
   • Sauvegarde JSON : Export / Import (traitements + doses + analyses + réglages T + paramètres : langue, auto-calibration, seuils d'alerte — v1.4.2)
   • Sauvegarde automatique quotidienne (v1.7.0, opt-in) : active-la, choisis le dossier une seule fois (ex. un dossier Owncloud synchronisé) → chaque jour un backup JSON complet y est écrit, avec les copies les plus récentes conservées (réglable, défaut 7) — tes exports manuels et tes autres fichiers ne sont jamais touchés. Un premier backup est écrit dès l'activation ; le statut (OK/ÉCHEC + date) s'affiche dans la carte

7. Les modèles mathématiques

• Estrannaise (v1.9.0 : analytique) : forme close 3C publiée par estrannaise.js — les anciennes tables du tableur en étaient l'échantillonnage (fidélité vérifiée à l'identique) ; 6 esters injectables couverts (EV, EU, EEn, EC, EB + EUCS en suspension cristalline)
• Transfem Science (v1.4.0) : la méta-analyse officielle à 3 compartiments (article, simulateur) — courbe calculée en forme close, 7 esters disponibles (EV, EU, EEn, EB, EC, EC suspension, PEP)
• WHSAH (v1.4.6) : un 3ᵉ fit indépendant (« license-free », publié par le WHSAH Collective dans l'app Mona) — montée plus rapide à J+1 et décroissance plus longue sur certains esters ; superposable avec les deux autres dans le graphique (vert). 6 esters (sans PEP)

Pics de référence (dose unique de 5 mg, IM) :

Profil	Source	Cmax (pg/mL)	Tmax	t½ terminale
EV	Estrannaise	— tables ODS	~45 h	—
EEn	Estrannaise	— tables ODS	~152 h	—
EV	Transfem Science	295	2,1 j	3,0 j
EEn	Transfem Science	160	6,5 j	4,6 j
EB	Transfem Science	971	0,65 j	1,2 j
EC (huile)	Transfem Science	155	4,3 j	6,7 j
EC (susp.)	Transfem Science	241	1,2 j	5,1 j
PEP	Transfem Science	34 (à 32,5 mg)	18 j	28,4 j

• Superposition : chaque injection contribue dose_mg × profil(dt) ; les courbes s'additionnent
• Calibration : facteur d'échelle par traitement (médiane des ratios lab/prédiction)
• Courbe T : dérivée de l'E2 estimé (modèle empirique, calibrable) — indicative seulement
• Unités T acceptées : ng/mL, ng/dL, ng/L, nmol/L (conversion automatique)

8. Fonctions du graphique (v1.2)

• Panoramique : fais glisser le graphique vers la droite pour remonter dans le passé (toute ta fenêtre d'historique) ; bouton « Revenir à maintenant » pour revenir
• Toggles Estrannaise / Transfem Science : les deux courbes peuvent être affichées simultanément (Estrannaise = bleu, Transfem Science = turquoise) pour comparer
• Prévision : configure la Posologie (intervalle en jours) dans un traitement (section « Fréquence ») puis active le chip « Prévision » → les doses à venir sont simulées et dessinées après la ligne « maintenant » (jamais sauvegardées). Activer le chip étend le graphique jusqu'à ta prochaine dose (sans déplacer l'historique visible) — v1.4.4 : le chip a un effet immédiat ; tire vers la GAUCHE pour parcourir la projection dans le futur (jusqu'à 1 an selon la Posologie) ; « Revenir à maintenant » pour revenir. Si tu désactives le chip alors que tu es dans le futur, l'app revient automatiquement à maintenant
• Toggles pré-cochés selon tes traitements (v1.4.7) : au chargement du graphique, seuls les modèles utilisés par tes traitements (injections, en cours ou passés) sont affichés — les autres s'activent au tap ; et TOUTES les courbes affichées suivent ta calibration (labs), quel que soit le modèle
• Pan fluide sur la vue 24 h (v1.4.10) : le glisser horizontal fonctionne sur toutes les échelles, y compris 24 h (les petits mouvements de doigt s'accumulent jusqu'à franchir une heure entière)
• Marqueurs de doses (v1.4.5) : les doses projetées sont marquées par une ligne verticale pointillée avec leur heure ; tes prises enregistrées par un petit triangle discret au bas du graphique — plus d'ambiguïté sur « où » la prochaine injection est simulée
• Fuseau horaire du graphique (v1.4.5) : Paramètres → « Fuseau horaire du graphique » — les jours s'alignent sur minuit du fuseau choisi (vide = celui du téléphone)
• Nuage d'incertitude (v1.9.0, exclusif ESE) : chip Nuage (actif seulement quand Estrannaise est affiché) → nuage diffus de courbes du posterior MCMC d'Estrannaise montrant la plage d'imprécision du modèle (comme sur le site estrannaise)
• Unités sur les axes (v1.7.0) : l'axe gauche affiche « pg/mL » (E2) et l'axe droit « ng/mL » (T, avec le toggle T) au sommet des colonnes de labels — plus besoin de deviner l'unité des nombres
• Pics / creux (chip sur le graphique) : triangles ▲▼ aux extrema estimés de chaque courbe (E2 et T, les deux modèles) — pratique pour visualiser d'un coup d'œil les hauts et les bas entre deux injections
• Tracé labs (chip Tracé labs, off par défaut) : une courbe E2 qui suit la forme du modèle PK MAIS passe EXACTEMENT par chacune de tes prises de sang — la trajectoire que tes labs tracent, avec la dynamique du modèle entre deux analyses (rose pointillé). Entre le 1er et le dernier lab seulement : la courbe ne s'invente pas de niveau. Prolonger (chip, off par défaut — actif seulement quand Tracé labs est on) : la courbe se PROLONGE après ton dernier lab : le modèle (dosages, esters injectés depuis, pics et descentes classiques) × le ratio mesuré à ton dernier lab. La partie prolongée est dessinée en rose ATTÉNUÉ avec sa légende (« estimation, plus ancrée ») et un AVERTISSEMENT : c'est une simple simulation sans garantie de correspondre au réel, extrapolée à partir de tes résultats de laboratoire — qui peuvent eux-mêmes être erronés. Elle s'arrête quand le modèle lui-même s'éteint. Compare-la à ta prochaine prise de sang, et fie-toi à elle plutôt qu'à cette courbe
• Calibration automatique (Paramètres, désactivée par défaut) : quand activée, les facteurs d'échelle et le modèle T sont ajustés en continu depuis tes labs — pour l'affichage seulement, tes réglages stockés ne changent pas. Chaque ester est calibré avec les labs faits pendant sa période : si tu étais sous valerate avant d'être sous enanthate, tes labs valerate calibrent les doses valerate (E2 et la suppression T), et inversement pour l'enanthate. Calibration par modèle (v1.4.8) : chaque modèle affiché dans le graphique (Estrannaise / Transfem Science / WHSAH) reçoit SES propres facteurs calculés sur tes labs — les courbes superposées collent toutes à tes résultats, quelle que soit leur forme

9. Dépannage

Problème	Solution
« SDK not found » au sync	Android Studio → Settings → Languages & Frameworks → Android SDK → vérifier/installer la plateforme 37 (le build AGP peut la télécharger automatiquement)
Pas de téléphone détecté	Réactive le Débogage USB, change de câble (données, pas charge seule)
Notif absente sur la montre	Huawei Santé → Notifications → autorise l'app ; redémarre la montre
Rappels en retard	Paramètres → « Accorder les alarmes exactes » + désactive l'optimisation de batterie pour l'app
Import JSON échoué	Le fichier doit venir d'un export de l'app même version (IDs conservés)
L'export des logs ou JSON a planté (versions ≤ 1.3.3)	Mettre à jour vers la v1.3.4+ (fixons confirmés sur émulateur) — le message de confirmation doit apparaître en haut de Paramètres

10. Données & vie privée

• Tout est local : base Room sur le téléphone, aucun serveur, aucun compte
• Sauvegarde = fichier JSON que tu choisis où stocker (Owncloud, etc.)
• L'auto-backup quotidien (v1.7.0) n'écrit QUE dans le dossier que tu as choisi (sélecteur système, permission révocable dans les réglages) — rien ne part ailleurs
• La désinstallation supprime les données → pense à exporter régulièrement