326 lines
12 KiB
Markdown
326 lines
12 KiB
Markdown
# 🏋️ HabitForge
|
|
|
|
> Plateforme auto-hébergée de suivi d'habitudes, de santé et de fitness avec companion app Android
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
## 📖 Vue d'Ensemble
|
|
|
|
HabitForge est bien plus qu'un simple tracker d'habitudes. C'est une plateforme complète qui combine :
|
|
|
|
- 🎯 **Suivi d'habitudes** avec défis personnalisables (reps, minutes, km, pages...)
|
|
- 📊 **Dashboard santé** connecté à Health Connect (Android) et Zepp/Amazfit
|
|
- 📱 **Companion app Android** pour synchronisation automatique des données de santé
|
|
- 🧠 **Analytics avancés** : readiness score, corrélations, tendances
|
|
- 🏗️ **Architecture scalable** : SQLite pour le dev, PostgreSQL pour la prod
|
|
|
|
---
|
|
|
|
## ✨ Fonctionnalités
|
|
|
|
### 🎯 Challenges & Habitudes
|
|
- **Défis flexibles** : quotidien, hebdomadaire (jours spécifiques), mensuel, annuel
|
|
- **Multi-unités** : reps, minutes, pages, kilomètres
|
|
- **Jours de repos** configurables
|
|
- **15 exercices animés** (GIFs) comme références visuelles
|
|
- **Icônes FontAwesome** personnalisables
|
|
- **Drag & drop** pour réorganiser les priorités
|
|
- **Statistiques** : streak, taux de complétion, reps totales
|
|
- **Heatmap de consistance** (vue calendrier)
|
|
|
|
### 📊 Dashboard Santé
|
|
- **Widgets interactifs** avec jauges semi-circulaires (Canvas API)
|
|
- Steps quotidiens
|
|
- Calories brûlées
|
|
- Fréquence cardiaque (min/max/repos)
|
|
- SpO2
|
|
- Poids (lbs/kg) & BMI avec tendances
|
|
- **Décomposition du sommeil** : profond, léger, REM, éveillé
|
|
- **Graphiques d'historique** (Chart.js) : 7j, 30j, 365j
|
|
- **Readiness Score** quotidien basé sur HRV, RHR et sommeil
|
|
- **Contexte subjectif** : humeur, tags, notes
|
|
|
|
### 📱 Android Companion App
|
|
- **Lecture native Health Connect** (tous les types de données)
|
|
- **Sync automatique** configurable (1h, 3h, 6h, 12h, 24h)
|
|
- **15 types de données brutes** synchronisées (steps, HR, sleep stages, SpO2, poids, nutrition...)
|
|
- **Historique des synchronisations** avec stats détaillées
|
|
- **Test de connexion** serveur avec temps de réponse
|
|
- **Validation de schéma** des données avant sync
|
|
- **Indicateur de statut** serveur en temps réel
|
|
|
|
### 🔄 Intégrations
|
|
- **Health Connect** (Android) — sync native via companion app
|
|
- **Zepp/Amazfit** — import CSV des données exportées
|
|
- **Architecture Provider** — extensible pour futures sources (Google Fit, Apple Health, Garmin...)
|
|
- **Agrégation on-demand** — calcul des métriques à partir des données brutes
|
|
|
|
### 🎨 UX/UI
|
|
- **Mobile-First** design (Tailwind CSS)
|
|
- **Dark Mode** avec persistance
|
|
- **Jauges animées** Canvas pour poids et BMI
|
|
- **Modales** pour détails des métriques
|
|
- **Navigation par onglets** fluide
|
|
|
|
---
|
|
|
|
## 🛠 Stack Technique
|
|
|
|
### Backend
|
|
| Composant | Technologie |
|
|
|:---|:---|
|
|
| Framework | FastAPI 0.141 |
|
|
| ORM | SQLAlchemy 2.0 |
|
|
| Auth | JWT (OAuth2 Password Flow) + Argon2 |
|
|
| Validation | Pydantic 2.0 |
|
|
| Rate Limiting | SlowAPI |
|
|
| Migrations | Alembic |
|
|
| Server | Uvicorn (dev) / Gunicorn + Uvicorn Workers (prod) |
|
|
|
|
### Frontend
|
|
| Composant | Technologie |
|
|
|:---|:---|
|
|
| Core | Vanilla JavaScript (ES6+) |
|
|
| CSS | Tailwind CSS (CDN) |
|
|
| Charts | Chart.js |
|
|
| Icons | FontAwesome 6 |
|
|
| Animations | Anime.js + Canvas API |
|
|
| Drag & Drop | SortableJS |
|
|
|
|
### Android
|
|
| Composant | Technologie |
|
|
|:---|:---|
|
|
| Langage | Kotlin |
|
|
| HTTP Client | Retrofit |
|
|
| Health SDK | Android Health Connect API |
|
|
| UI | Jetpack + Material Design |
|
|
| Auth | JWT token management |
|
|
|
|
### Infrastructure
|
|
| Environnement | Configuration |
|
|
|:---|:---|
|
|
| Dev simple | `docker-compose.yml` — SQLite |
|
|
| Dev complet | `docker-compose.dev.yml` — PostgreSQL + CloudBeaver |
|
|
| Production | `docker-compose.prod.yml` — Nginx + Gunicorn + Backup auto |
|
|
|
|
---
|
|
|
|
## 🚀 Démarrage Rapide
|
|
|
|
### Prérequis
|
|
- Docker & Docker Compose
|
|
- Git LFS (pour les GIFs)
|
|
|
|
### Dev complet (PostgreSQL + interface DB)
|
|
```bash
|
|
git clone https://git.dracodev.net/Projets/HabitForge.git
|
|
cd HabitForge
|
|
docker compose -f docker-compose.dev.yml up -d --build
|
|
```
|
|
|
|
**Accès :**
|
|
- 🌐 App : http://localhost:8000
|
|
- 🗄️ CloudBeaver (DB GUI) : http://localhost:8978 (admin/admin)
|
|
- 📖 API Docs : http://localhost:8000/docs
|
|
|
|
### Mode simple (SQLite)
|
|
```bash
|
|
docker compose up -d --build
|
|
```
|
|
|
|
### Production (Nginx + backup auto)
|
|
```bash
|
|
# Configurer .env.production d'abord
|
|
docker compose -f docker-compose.prod.yml up -d --build
|
|
```
|
|
|
|
---
|
|
|
|
## 📂 Structure du Projet
|
|
|
|
```
|
|
HabitForge/
|
|
├── backend/ # API FastAPI
|
|
│ ├── api/v1/ # Routes REST
|
|
│ │ ├── auth.py # Authentification JWT
|
|
│ │ ├── challenges.py # CRUD Challenges + Tracking
|
|
│ │ ├── health.py # Stats santé + Workouts
|
|
│ │ ├── health_connect.py # Sync Health Connect (legacy)
|
|
│ │ ├── health_connect_raw.py# Sync données brutes (15 types)
|
|
│ │ └── health_analytics.py # Analytics + Readiness Score
|
|
│ ├── core/config.py # Configuration (pydantic-settings)
|
|
│ ├── models/ # 25 modèles SQLAlchemy
|
|
│ │ ├── user.py # Comptes utilisateurs
|
|
│ │ ├── challenge.py # Défis
|
|
│ │ ├── tracking.py # Suivi quotidien
|
|
│ │ ├── daily_health_metrics.py # Métriques agrégées legacy
|
|
│ │ ├── daily_context.py # Contexte subjectif (mood)
|
|
│ │ ├── workout_session.py # Sessions manuelles
|
|
│ │ ├── health_connect.py # Sync logs + métriques HC
|
|
│ │ └── health_connect_raw.py# 15 tables raw HC
|
|
│ ├── services/ # Couche métier
|
|
│ │ ├── auth_service.py
|
|
│ │ ├── challenge_service.py
|
|
│ │ ├── health_service.py
|
|
│ │ └── aggregation_service.py # Agrégation on-demand
|
|
│ ├── integrations/ # Providers données santé
|
|
│ │ ├── health_provider.py # Interface abstraite
|
|
│ │ ├── health_connect_provider.py
|
|
│ │ └── import_zepp.py # Import CSV Zepp
|
|
│ ├── schemas/ # Validation Pydantic
|
|
│ ├── repositories/ # Data access layer
|
|
│ └── database.py # Engine + Session
|
|
├── frontend/ # SPA vanilla JS
|
|
│ ├── index.html # Dashboard principal
|
|
│ ├── login.html # Page login
|
|
│ ├── app.js # Logique applicative (4300+ lignes)
|
|
│ └── static/ # 15 GIFs d'exercices (LFS)
|
|
├── android-companion/ # App Android Kotlin
|
|
│ └── app/src/main/java/com/habitforge/companion/
|
|
│ ├── MainActivity.kt # UI principale
|
|
│ ├── HealthConnectManager.kt # Lecture Health Connect
|
|
│ ├── SyncService.kt # Service background
|
|
│ ├── RawDataSyncService.kt# Sync données brutes
|
|
│ ├── HabitForgeApi.kt # Client Retrofit
|
|
│ └── ... # 17 fichiers Kotlin au total
|
|
├── alembic/ # Migrations DB (9 versions)
|
|
├── nginx/ # Config Nginx + SSL
|
|
├── scripts/ # Utilitaires
|
|
│ ├── import_zepp_data.py # Import données Zepp
|
|
│ ├── migrate_to_postgres.py # Migration SQLite → PostgreSQL
|
|
│ └── backup_db.sh # Backup automatique PostgreSQL
|
|
├── docker-compose.yml # Dev simple (SQLite)
|
|
├── docker-compose.dev.yml # Dev complet (PostgreSQL + CloudBeaver)
|
|
├── docker-compose.prod.yml # Production (Nginx + Gunicorn + Backup)
|
|
├── Dockerfile # Image Python 3.10-slim
|
|
├── requirements.txt # Dépendances Python
|
|
├── DATABASE_SCHEMA.md # Schémas Mermaid
|
|
└── ROADMAP.md # Roadmap & état du projet
|
|
```
|
|
|
|
---
|
|
|
|
## 🔌 API — Principaux Endpoints
|
|
|
|
| Méthode | Endpoint | Description |
|
|
|:---|:---|:---|
|
|
| `POST` | `/api/auth/register` | Créer un compte |
|
|
| `POST` | `/api/auth/token` | Obtenir un JWT |
|
|
| `POST` | `/api/auth/refresh` | Rafraîchir le JWT |
|
|
| `GET` | `/api/auth/me` | Profil utilisateur |
|
|
| `GET/POST/PUT/DELETE` | `/api/challenges[/{id}]` | CRUD Challenges |
|
|
| `POST` | `/api/tracking` | Logger une répétition |
|
|
| `GET` | `/api/health` | Health check DB |
|
|
| `GET` | `/api/health/stats` | Statistiques santé (période) |
|
|
| `GET` | `/api/health/workouts` | Sessions d'entraînement |
|
|
| `POST` | `/api/health-connect/sync-raw` | Sync données brutes (15 types) |
|
|
| `GET` | `/api/analytics/daily` | Analytics quotidien (avec readiness) |
|
|
| `GET` | `/api/analytics/range` | Analytics plage de dates |
|
|
| `POST` | `/api/analytics/context` | Mise à jour mood/tags |
|
|
|
|
📖 **Documentation interactive** : http://localhost:8000/docs (Swagger) | http://localhost:8000/redoc
|
|
|
|
---
|
|
|
|
## 📊 Schéma de Base de Données
|
|
|
|
Le projet contient **25 tables** organisées en 3 couches :
|
|
|
|
| Couche | Tables | Description |
|
|
|:---|:---:|:---|
|
|
| **Core** | 6 | users, challenges, tracking, daily_health_metrics, daily_context, workout_sessions |
|
|
| **Health Connect Aggregated** | 3 | sync_logs, daily_metrics, exercise_sessions |
|
|
| **Health Connect Raw** | 15 | steps, heart_rate + samples, resting_hr, sleep_sessions + stages, distance, calories, spo2, weight, height, body_fat, exercise_sessions, nutrition, hydration, hrv_rmssd |
|
|
|
|
➡️ Voir [`DATABASE_SCHEMA.md`](./DATABASE_SCHEMA.md) pour les diagrammes Mermaid complets.
|
|
|
|
---
|
|
|
|
## 🗺️ Roadmap
|
|
|
|
➡️ Voir [`ROADMAP.md`](./ROADMAP.md) pour l'état détaillé des fonctionnalités et la vision future.
|
|
|
|
### Priorités actuelles
|
|
- 🔴 Tests automatisés (pytest)
|
|
- 🔴 Cache d'agrégation (performances)
|
|
- 🟡 Badges & Achievements
|
|
- 🟡 Export de données
|
|
|
|
---
|
|
|
|
## 🔧 Configuration
|
|
|
|
Copier le fichier d'exemple et adapter :
|
|
|
|
```bash
|
|
cp .env.example .env.development
|
|
```
|
|
|
|
### Variables principales
|
|
|
|
| Variable | Description | Défaut |
|
|
|:---|:---|:---|
|
|
| `SECRET_KEY` | Clé de chiffrement JWT | *À définir* |
|
|
| `DATABASE_URL` | Chaîne de connexion DB | `sqlite:///./data/habitforge.db` |
|
|
| `CORS_ORIGINS` | Origines autorisées | `http://localhost:8000` |
|
|
| `GOOGLE_CLIENT_ID` | OAuth Google | `""` |
|
|
| `HEALTH_PROVIDER` | Provider santé | `"health_connect"` |
|
|
| `RATE_LIMIT_ENABLED` | Rate limiting | `true` |
|
|
| `DEBUG` | Mode debug | `true` |
|
|
|
|
---
|
|
|
|
## 📱 Companion App Android
|
|
|
|
L'application Android se synchronise avec votre instance HabitForge pour importer automatiquement vos données Health Connect.
|
|
|
|
### Build
|
|
```bash
|
|
cd android-companion
|
|
./gradlew assembleDebug
|
|
# APK dans app/build/outputs/apk/debug/
|
|
```
|
|
|
|
### Données synchronisées
|
|
Steps • Distance • Calories • Fréquence cardiaque • FC repos • Sommeil (phases) • SpO2 • Poids • Taille • Masse grasse • Sessions d'exercice • Nutrition • Hydratation • HRV
|
|
|
|
➡️ Voir [`android-companion/README.md`](./android-companion/README.md) pour la documentation complète.
|
|
|
|
---
|
|
|
|
## 📥 Import Zepp/Amazfit
|
|
|
|
Si vous utilisez une montre Zepp/Amazfit, vous pouvez importer vos données :
|
|
|
|
```bash
|
|
# Placer l'export dans export-zepp/
|
|
docker compose -f docker-compose.dev.yml exec web python scripts/import_zepp_data.py
|
|
```
|
|
|
|
➡️ Voir [`ZEPP_IMPORT.md`](./ZEPP_IMPORT.md) pour les détails.
|
|
|
|
---
|
|
|
|
## 🤝 Contribuer
|
|
|
|
1. Fork le projet
|
|
2. Branche feature : `git checkout -b feature/AmazingFeature`
|
|
3. Commit : `git commit -m 'Add AmazingFeature'`
|
|
4. Push : `git push origin feature/AmazingFeature`
|
|
5. Pull Request
|
|
|
|
Le projet utilise **ruff** pour le linting Python et **pre-commit** pour les hooks.
|
|
|
|
---
|
|
|
|
## 📄 Licence
|
|
|
|
MIT License — voir le fichier `LICENSE`.
|