Add initial project

2026-07-30 23:25:20 -04:00
commit cff6aa8289
164 changed files with 26672 additions and 0 deletions
@@ -0,0 +1,203 @@
+# 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"