208 lines
12 KiB
Markdown
208 lines
12 KiB
Markdown
# 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](docs/DEVELOPPEMENT.md).
|
||
|
||
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.4 — build Android ✅, **lint vert** ✅, **140 tests unitaires** ✅ (118 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](docs/CHANGELOG.md)
|
||
- **Guide utilisateur** : [docs/GUIDE_INSTALLATION.md](docs/GUIDE_INSTALLATION.md)
|
||
- **Doc de développement** (architecture, maths, décisions, bugs) : [docs/DEVELOPPEMENT.md](docs/DEVELOPPEMENT.md)
|
||
- **Montre / Gadgetbridge** : [docs/MONTRE-GADGETBRIDGE.md](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](https://transfemscience.org/misc/injectable-e2-simulator/),
|
||
[article](https://transfemscience.org/articles/injectable-e2-meta-analysis/)),
|
||
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 début du graphique** mais ÉTEND la fenêtre
|
||
jusqu'à la prochaine dose (v1.4.4) et la projection se parcourt en tirant
|
||
vers la gauche, jusqu'à **1 an**
|
||
- **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.
|
||
|
||
```bash
|
||
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 # 140 tests (118 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](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.4`) et **deux APK par release** (depuis v1.2.5)
|
||
(téléchargeables sans compiler, cf [docs/DEVELOPPEMENT.md §16.bis](docs/DEVELOPPEMENT.md)) :
|
||
`-release.apk` (**recommandé**, optimisé R8, 2,4 Mo) et `-debug.apk` (20 Mo) :
|
||
|
||
```bash
|
||
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](docs/DEVELOPPEMENT.md).
|
||
|
||
## 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](https://transfemscience.org/articles/injectable-e2-meta-analysis/)).
|
||
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](docs/DEVELOPPEMENT.md))
|
||
- 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
|
||
|
||
- [x] 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](docs/MONTRE-GADGETBRIDGE.md))
|
||
|
||
## Licence
|
||
|
||
**GPL-3.0** — voir [LICENSE](LICENSE). Cohérent avec l'écosystème Gadgetbridge.
|
||
Les modèles PK appartiennent à leurs autrices respectives
|
||
([Estrannaise](https://estrannaise.github.io/), [Transfem Science](https://transfemscience.org)).
|