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](https://transfemscience.org/articles/injectable-e2-meta-analysis/),
  [simulateur](https://transfemscience.org/misc/injectable-e2-simulator/)) —
  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](https://github.com/mona-hrt/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). v1.9.2 : il couvre toutes les doses E2
  injectables quand ESE est affiché — aucun traitement n'a besoin d'être
  stocké en ESE
- **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