HabitForge/android-companion

HabitForge Android Companion App

Application Android permettant de synchroniser les données de Health Connect avec votre serveur HabitForge.

🆕 Nouvelles Fonctionnalités

Suivi des Synchronisations

• Historique complet : Visualisez l'historique de toutes les synchronisations
• Statistiques : Nombre de syncs réussies/échouées, métriques totales synchronisées
• Détails : Chaque sync affiche le temps de traitement, les données transférées et les erreurs

Connectivité Serveur

• Indicateur en temps réel : Voyez immédiatement si le serveur est en ligne
• Test de connexion : Bouton dédié pour tester la connexion et l'authentification
• Temps de réponse : Affichage du temps de réponse du serveur

Validation des Données

• Vérification de compatibilité : Validez que vos données Health Connect sont compatibles avec le schéma HabitForge
• Aperçu des données : Prévisualisation des données avant synchronisation
• Diagnostic : Identification des problèmes potentiels de mapping

Configuration Avancée

• Période de sync configurable : Choisissez la fréquence de synchronisation automatique
  • Toutes les heures
  • Toutes les 3 heures
  • Toutes les 6 heures (par défaut)
  • Toutes les 12 heures
  • Une fois par jour

Prérequis

• Android Studio (version 2024.2.1 ou plus récente)
• JDK 17
• Un appareil Android avec Android 9+ (API 28+)
• Health Connect installé sur l'appareil

Structure du projet

android-companion/
├── app/
│   ├── src/main/
│   │   ├── java/com/habitforge/companion/
│   │   │   ├── HabitForgeApp.kt              # Application class
│   │   │   ├── MainActivity.kt               # UI principale
│   │   │   ├── HealthConnectManager.kt       # Lecture des données Health Connect
│   │   │   ├── SyncService.kt                # Service de sync en arrière-plan
│   │   │   ├── SyncHistoryManager.kt         # Gestion de l'historique des syncs
│   │   │   ├── ServerConnectionManager.kt    # Test de connectivité serveur
│   │   │   ├── DataCompatibilityValidator.kt # Validation schéma de données
│   │   │   ├── HabitForgeApi.kt              # API Retrofit pour le backend
│   │   │   └── PrivacyPolicyActivity.kt      # Page de politique de confidentialité
│   │   ├── res/
│   │   │   ├── layout/                       # Layouts XML
│   │   │   ├── values/                       # Couleurs, strings, thèmes
│   │   │   └── drawable/                     # Icônes et indicateurs de status
│   │   └── AndroidManifest.xml               # Permissions Health Connect
│   └── build.gradle.kts                      # Dépendances
├── build.gradle.kts                          # Configuration root
├── settings.gradle.kts                       # Settings Gradle
└── gradle.properties                         # Propriétés Gradle

Données synchronisées

L'application lit les données suivantes depuis Health Connect :

Métriques quotidiennes

• Pas (Steps)
• Distance parcourue
• Calories brûlées
• Fréquence cardiaque (moyenne, min, max, repos)
• Sommeil (durée, phases : profond, léger, REM, éveillé)
• Poids
• SpO2

Sessions d'exercice

• Type d'exercice (Running, Walking, Cycling, Swimming, Weight Training, etc.)
• Durée
• Heure de début/fin
• Notes

Compilation

Option 1 : Via Android Studio

1. Ouvrir Android Studio
2. File > Open > Sélectionner le dossier android-companion
3. Attendre que Gradle synchronise
4. Build > Build Bundle(s) / APK(s) > Build APK(s)

Option 2 : Via ligne de commande

# Se placer dans le dossier du projet
cd c:\dev\git\python\HabitForge\android-companion

# Compiler en mode debug
.\gradlew assembleDebug

# Le fichier APK sera dans :
# app\build\outputs\apk\debug\app-debug.apk

# Compiler en mode release (nécessite une signature)
.\gradlew assembleRelease

Installation sur téléphone

Via ADB

adb install app\build\outputs\apk\debug\app-debug.apk

Via Android Studio

• Connecter le téléphone en USB (Mode débogage activé)
• Cliquer sur "Run" (bouton vert)

Configuration

1. Installer Health Connect sur le téléphone (Play Store)
2. Ouvrir HabitForge Companion
3. Accorder les permissions quand demandé
4. Se connecter à votre compte :
   • Cliquez sur "Login"
   • Entrez l'URL du serveur (ex: http://192.168.x.x:8000)
   • Utilisez les mêmes identifiants que l'interface web HabitForge
5. Tester la connexion : Utilisez le bouton "Test Connection" pour vérifier
6. Valider les données : Cliquez sur "Validate Data Schema"
7. Configurer la fréquence : Choisissez l'intervalle de sync souhaité
8. Synchroniser manuellement ou laisser l'auto-sync

Interface Utilisateur

Cartes de l'écran principal

Carte	Description
Health Connect	Statut de Health Connect, bouton pour l'ouvrir
Permissions	Permissions accordées/requises, bouton pour les demander
Server	Configuration serveur, indicateur de disponibilité, test de connexion
Sync Settings	Fréquence de sync, dernière sync, bouton Sync Now
Data Compatibility	Validation du schéma, aperçu des données
Sync History	Historique récent, statistiques, bouton historique complet

Indicateurs de Status Serveur

Indicateur	Signification
🟢 Online	Serveur accessible et connecté
🟠 Auth needed	Serveur accessible mais non connecté
🟠 Timeout	Serveur lent à répondre
🔴 Offline	Serveur inaccessible
⚫ Unknown	Statut non vérifié

Dépannage

"Health Connect not available"

• L'appareil doit être sous Android 9+
• Installer Health Connect depuis le Play Store

"Permissions not granted"

• Réouvrir l'app et cliquer sur "Grant Permissions"
• S'assurer que Health Connect a des données (d'autres apps comme Google Fit)

"Login failed" / "Invalid username or password"

• Vérifier que le serveur HabitForge est accessible (utilisez "Test Connection")
• Vérifier que les identifiants sont corrects (mêmes que l'interface web)
• Consulter les logs via adb logcat | grep HabitForge

"Sync failed"

• Vérifier que vous êtes bien connecté
• Vérifier l'historique des syncs pour voir le message d'erreur

"Connection timeout"

• Vérifier que le serveur est démarré
• Vérifier la connexion réseau
• Si sur le même réseau local, utiliser l'IP locale (ex: 192.168.x.x)

"Data validation issues"

• Cliquez sur "Validate Data Schema" pour diagnostiquer
• Vérifiez que Health Connect contient des données récentes
• Accordez toutes les permissions demandées

API Backend requise

L'application nécessite les endpoints suivants sur votre serveur HabitForge :

Endpoint	Méthode	Description
/api/health	GET	Health check (retourne {"status": "healthy"})
/api/auth/token	POST	Authentification (OAuth2 form: username, password)
/api/auth/me	GET	Récupérer les infos utilisateur connecté
/api/health-connect/sync	POST	Réception des données synchronisées

Sécurité

• L'authentification utilise les mêmes identifiants que l'interface web
• Les tokens JWT sont stockés dans SharedPreferences (mode privé)
• Toutes les connexions utilisent HTTPS en production
• Les données ne quittent jamais l'appareil sauf vers votre serveur configuré
• L'historique des syncs est stocké localement uniquement
• Déconnexion possible via le bouton "Logout"