HabitForge/android-companion/README.md

# 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

```powershell
# 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
```powershell
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"