HormoneTrack/README.md

HormoneTrack

🤖 Développé avec l'IA : ce projet a été conçu et codé avec un assistant IA. La contribution humaine a été essentielle : feedback continu, retours utilisateur (tests sur vrai téléphone, rapports de bugs accompagnés d'exports réels), suggestions d'améliorations et validation de chaque release. Le détail session par session est documenté dans docs/DEVELOPPEMENT.md §2.

Suivi de thérapie hormonale (THS) sur Android, avec courbes estimées heure par heure d'estradiol (E2) et de testostérone (T), calibration sur les prises de sang, rappels affichés sur smartwatch (Huawei Watch GT 3 via Gadgetbridge ou Huawei Health) et sauvegarde JSON. 100 % local, aucun compte, aucun serveur.

⚠️ Avertissement médical : les courbes sont des estimations pharmacocinétiques à titre informatif — ce ne sont pas des mesures. Fie-toi toujours à tes analyses de sang et aux consignes de ton endocrinologue.

• Statut : v1.4.2 — build Android ✅, lint vert ✅, 129 tests unitaires ✅ (111 sans les données de test locales ; 3 régressions épinglées sur données réelles non versionnées), intégration montre = notifications ✅, dépôt Gitea privé + releases avec APK ✅
• Journal des versions : docs/CHANGELOG.md
• Guide utilisateur : docs/GUIDE_INSTALLATION.md
• Doc de développement (architecture, maths, décisions, bugs) : docs/DEVELOPPEMENT.md
• Montre / Gadgetbridge : docs/MONTRE-GADGETBRIDGE.md

Fonctionnalités

• Courbes estimées heure par heure : E2 (pg/mL) et T (ng/mL), vue 24 h / 7 j / 30 j, panoramique (glisser pour remonter dans le passé), zoom (pinch ou boutons − / +, 6 h → 300 j, échantillonnage adaptatif), pics & creux affichables avec leurs valeurs estimées (triangles ▲▼ aux extrema locaux, toggle)
• Deux modèles PK au choix, superposables : Estrannaise (EstraNase) (tables horaires du .ods) et Transfem Science — depuis v1.4.0, le modèle TFS est la méta-analyse officielle à 3 compartiments (forme close exacte, params du simulateur TFS, article), avec les 7 esters : EV, EU, EEn, EB, EC (huile), EC (suspension), PEP, affichés côte à côte avec toggles indépendants
• Modèle Bateman paramétrable (temps au pic, demi-vie, biodisponibilité) pour gel, patch et voie orale
• Simulation prévisionnelle : configurer la posologie (intervalle en jours) sur un traitement → projection des doses à venir sur le graphique (jamais sauvegardées) ; l'activation ne déplace pas le graphique et la projection se parcourt en tirant vers la gauche, jusqu'à 1 an (v1.4.1)
• Log des doses avec date/heure exacte, dose en mg, ester par injection (switch EV↔EU↔EEn comme dans le tableur), éditable (tap sur une ligne dans Doses), intervalle en jours entre dosages affiché
• Traitements inactifs : un traitement archivé n'apparaît plus dans la saisie ni dans les rappels, mais tout son historique reste simulé et calibré — utile pour une transition valerate → enanthate
• Analyses de sang : E2 + T en une seule entrée (chacune optionnelle), affichées côte à côte quand elles partagent la même date/heure, éditables (tap → choix de l'entrée) ; unités T : ng/mL, ng/dL, ng/L, nmol/L
• Calibration : facteur d'échelle par traitement = médiane(lab ÷ prédiction du modèle), calculé automatiquement (« Scale factor » du .ods, automatisé) — ou calibration automatique permanente (option, désactivée par défaut) qui calibre chaque ester avec les labs de sa période (labs valerate → doses valerate, labs enanthate → doses enanthate) et recalibre le modèle T
• Estimation T empirique T = plancher + (base − plancher) ÷ (1 + k·E2), avec k calibré par période d'ester (la suppression T diffère valerate vs enanthate), contre l'E2 déjà calibrée — unités T acceptées : ng/mL, ng/dL, ng/L, nmol/L
• Rappels quotidiens avec actions « Pris » / « Reporter 1 h » dans la notification ; les notifications remontent sur la Watch GT 3 (Gadgetbridge ou Huawei Health) ; les rappels suivent la Posologie (v1.4.0) : un traitement injecté tous les 7 jours ne sonne que le jour d'injection, pas tous les jours
• Seuils d'alerte configurables (v1.4.2) : limites hautes/basses E2 (pg/mL) et T (ng/mL) dans Paramètres → carte d'avertissement sur l'accueil + notification toutes les 15 min même app fermée (WorkManager, anti-spam, canal dédié) — évaluées sur le taux estimé, opt-in
• Sauvegarde JSON complète : traitements + doses + analyses + réglages T + paramètres (langue, auto-calibration, seuils d'alerte) (v1.4.2)
• Nouveautés à chaque mise à jour : dialog de changelog automatique (fermé = ne réapparaît pas avant la prochaine version)
• Temps sous THS affiché en haut de la page Doses (depuis la 1re prise) ; prochaine dose en jours sur l'accueil quand elle est à plus de 24 h (v1.4.1)
• Logs de diagnostic exportables (Paramètres) — utile pour le support
• Événements d'agenda : les rappels de prises peuvent créer un événement récurrent (posologie) dans un calendrier « HormoneTrack » de ton téléphone
• Sauvegarde/Restauration JSON complète (traitements + doses + analyses + réglages T + paramètres, v1.4.2)
• FR + EN (langue par app, indépendante du système)
• UI Jetpack Compose récente (BOM 2026.08, Material You) ; 100 % local, aucun compte

Démarrage rapide (build depuis les sources)

Prérequis : JDK 17+ (Java 21 OK), Android SDK (la plateforme 37 sera auto-téléchargée par AGP si les licences sont signées). Le wrapper télécharge Gradle 9.7.1.

git clone <repo> && cd HormoneTrack
echo "sdk.dir=/chemin/vers/android-sdk" > local.properties   # ou ANDROID_HOME
./gradlew assembleDebug            # APK : app/build/outputs/apk/debug/app-debug.apk
./gradlew testDebugUnitTest        # 129 tests (111 sans les données locales)
./gradlew lint                     # lint vert obligatoire avant release

Installation sur un téléphone : mode développeur + Débogage USB, puis Android Studio (Run ▶️) ou adb install -r app/build/outputs/apk/debug/app-debug.apk. Pas de Play Store : l'app est sideloadée. Détails pas-à-pas : docs/GUIDE_INSTALLATION.md.

Git

Dépôts : gitea.cloudyfy.fr et gitea.farewell.dev (miroir) — Siphonight/HormoneTrack sur les deux (privé), avec releases taguées (v1.1.0 → v1.4.2) et deux APK par release (depuis v1.2.5) (téléchargeables sans compiler, cf docs/DEVELOPPEMENT.md §16.bis) : -release.apk (recommandé, optimisé R8, 2,4 Mo) et -debug.apk (20 Mo) :

git tag            # lister les releases
git log --oneline  # historique par couches (toolchain / moteur / UI / docs)
git push -u origin main --tags

Chaque commit de release passe ./gradlew testDebugUnitTest (vert obligatoire) et est taggué annoté. Voir docs/DEVELOPPEMENT.md §16.

Les modèles en bref

Chaque injection contribue dose_mg × profil(dt) où profil est la réponse normalisée (pg/mL par mg) ; les contributions se superposent. Estrannaise = tables horaires du .ods (8001 h) ; Transfem Science = méta-analyse à 3 compartiments (V3C, forme close, article). Pics de référence (pg/mL par mg) :

Profil	Modèle	Pic (pg/mL/mg)	Tmax
EV	Estrannaise	61,1	~45 h
EU	Estrannaise	3,4	~55 h (plateau long)
EEn	Estrannaise	31,4	~152 h
EV	Transfem Science	59,0	~51 h
EU	Transfem Science	10,1	~198 h
EEn	Transfem Science	32,0	~156 h
EB	Transfem Science	194,2	~16 h
EC (huile)	Transfem Science	31,1	~103 h
PEP	Transfem Science	1,03 (dose ~6,5×)	~18 j

La calibration (facteur d'échelle par traitement, calibré par tes labs) ajuste le modèle à ton corps, exactement comme la colonne « Scale factor » de la feuille d'origine.

Vie privée

• L'app est 100 % locale : base de données Room sur le téléphone, aucun serveur, aucune télémétrie ; compat Gadgetbridge (FOSS) sans dépendance à Huawei Health
• Le dépôt ne contient aucune donnée de santé : le code et la doc sont génériques ; les tests de régression qui utilisent des exports réels chargent leurs données depuis local-test-data/ (gitignoré, hors dépôt — et l'historique a été nettoyé avant le premier push, cf docs/DEVELOPPEMENT.md §8.bis)
• Sauvegarde = fichier JSON que tu stockes où tu veux (Owncloud, etc.)
• allowBackup=false (données sensibles) ; verrou biométrique prévu en Phase 2
• Le dépôt est privé : les releases APK se téléchargent en étant connecté ; passer le dépôt en public rend les APK téléchargeables sans compte (sans risque de données, cf ci-dessus)

Structure du dépôt

HormoneTrack/
├── README.md                     ← ce fichier
├── docs/
│   ├── GUIDE_INSTALLATION.md     guide utilisateur (téléphone + montre)
│   ├── DEVELOPPEMENT.md          doc de dev complète (architecture, maths, bugs, tests)
│   ├── CHANGELOG.md              journal détaillé des versions
│   └── MONTRE-GADGETBRIDGE.md    montre Huawei GT 3 : options + limites
├── scripts/
│   ├── gitea-release.py            publie le corps d'une release (CHANGELOG + APK)
│   ├── publish-release.py          publie les 2 APK d'un tag (vérification par téléchargement)
│   └── seed-emulator.py            injecte un backup JSON dans la DB d'un émulateur (cf §16.ter)
├── local-test-data/              ← gitignoré : backups réels pour les tests
│                                   de régression (JAMAIS dans le dépôt, cf §8.bis)
├── build.gradle.kts              config Gradle racine (AGP/Kotlin/KSP épinglés)
├── settings.gradle.kts
├── gradle.properties
├── gradle/wrapper/               wrapper Gradle 9.7.1 (jar + properties)
├── gradlew / gradlew.bat
└── app/
    ├── build.gradle.kts          dépendances (Compose, Room, DataStore, Gson…)
    ├── proguard-rules.pro
    └── src/
        ├── main/
        │   ├── AndroidManifest.xml
        │   ├── assets/pk_profiles.json          ← tables horaires (Estrannaise/TFS)
        │   ├── java/com/hormonetrack/
        │   │   ├── data/         (Room : models, DAOs, repository, backup)
        │   │   ├── pk/           (moteur pharmacocinétique + profils)
        │   │   ├── reminder/     (alarmes exactes, notifs + actions, boot, worker alertes)
        │   │   ├── settings/     (DataStore : TConfig, langue)
        │   │   ├── ui/           (Compose : screens, components, theme)
        │   │   ├── HormoneTrackApp.kt
        │   │   └── MainActivity.kt
        │   └── res/              (strings FR/EN, thème, icônes)
        └── test/java/com/hormonetrack/          ← tests unitaires JVM
            ├── pk/               (moteur + profils)
            └── data/backup/      (round-trip Gson)

Feuille de route

• v1 : courbes E2/T, log doses, labs + calibration, rappels, backup JSON, FR/EN
• Tests UI Compose + compilation release signée
• Verrou biométrique, widget, export CSV
• Phase 2 montre : watchface personnalisée et/ou mini-app Lite Wearable (voir docs/MONTRE-GADGETBRIDGE.md)

Licence

GPL-3.0 — voir LICENSE. Cohérent avec l'écosystème Gadgetbridge. Les modèles PK appartiennent à leurs autrices respectives (Estrannaise, Transfem Science).