# 💸 Dépenses Trello - Application de Gestion des Dépenses

## 📝 Description

**Dépenses Trello** est une application web de gestion des dépenses personnelles avec synchronisation automatique vers Trello. Créée pour simplifier le suivi des dépenses au quotidien.

---

## ✨ Fonctionnalités

### Gestion des Dépenses
- ➕ **Ajout rapide** de dépenses (prénom, date, libellé, montant, catégorie)
- ✏️ **Modification** des dépenses existantes
- 🗑️ **Suppression** de dépenses
- 📤 **Export CSV** pour Excel/comptabilité
- 📥 **Import CSV** pour récupérer des données
- 📄 **Export PDF** pour les relevés

### Catégories Automatiques
- 🚗 **Transport** (essence, gazole, parking)
- 🛒 **Courses** (Carrefour, Lidl, Auchan)
- 🎰 **Loisirs** (loto, bar, café, cinéma)
- 🏠 **Maison** (lumière, loyer, brico)
- ❤️ **Santé** (pharmacie, contrôle technique)
- 📦 **Autre** (divers)

### Graphiques & Statistiques
- 📊 **Bar chart** - visualisation classique
- 🥧 **Camembert** - répartition par catégorie
- 👤 **Par personne** - suivi par membre du foyer
- 📅 **Par mois** - évolution dans le temps

### Budget
- 💰 **Budget mensuel** configurable
- ⚠️ **Alerte** automatique quand le budget est dépassé

### Dépenses Récurrentes
- 🔄 **Loyer**, EDF, téléphone - automatiquement listés

### Synchronisation Trello
- 🟦 **Envoi automatique** des dépenses vers une liste Trello
- ✅ **Suivi du statut** (En attente / Envoyé)

---

## 🛠️ Stack Technique

| Composant | Technologie |
|-----------|--------------|
| **Backend** | Python Flask |
| **Base de données** | SQLite |
| **Frontend** | HTML5, Vanilla JavaScript |
| **Graphiques** | Chart.js |
| **PDF** | jsPDF |
| **Hébergement** | VPS (Linux) |

---

## 📋 Spécifications

- **Port**: 8769
- **URL**: http://178.18.250.53:8769/
- **API REST**: /api/depenses, /api/config, /api/budget, /api/recurring
- **Données**: 21+ dépenses en base (extensible)
- **Utilisateurs**: Multi-utilisateurs (via prénom)

---

## 🚀 Installation

```bash
# Cloner le projet
git clone http://178.18.250.53:3000/admin/Perso.git

# Installer les dépendances
pip install flask requests

# Lancer l'application
python app.py
```

---

## 💼 Potentiel Commercial

### Cible
- 👨‍👩‍👧 **Particuliers** gestion budget familial
- 💼 **Auto-entrepreneurs** frais professionnels
- 🏢 **Petites entreprises** suivi dépenses

### Arguments de Vente
1. ✅ **Simple** - interface épurée, pas de formation
2. ✅ **Complet** - catégories, graphiques, budget, PDF
3. ✅ **Automatisé** - synchronisation Trello
4. ✅ **Pas d'abonnement** - hébergement propre
5. ✅ **Open Source** - customisable

### Prix Recommandés
| Offre | Prix |
|-------|------|
| Usage personnel | 19€ |
| Usage pro | 49€ |
| Installation + config | 29€ |
| Support mensuel | 9€/mois |

---

## 📱 Captures d'Écran

### Page Saisie
- Formulaire rapide avec catégories auto
- Liste des dernières dépenses
- Boutons Envoyer tout / Export

### Page Dashboard
- Graphiques Bar / Camembert
- Filtres Mois / Personne / Catégorie
- Total en temps réel

### Page Config
- Gestion des prénoms
- Personnalisation des catégories
- Configuration Trello (API Key, Token, List ID)
- Budget mensuel

---

## 🔧 Configuration Trello

1. Créer un Power-Up sur https://trello.com/power-ups/admin
2. Générer une API Key
3. Générer un Token (avec permissions write)
4. Copier le List ID cible
5. Coller dans Config

---

## 📝 Roadmap Future

- [ ] Application mobile (PWA)
- [ ] Mode hors-ligne
- [ ] Catégories personnalisées illimitées
- [ ] Rapports mensuels par email
- [ ] Intégration Slack/Discord
- [ ] Multi-devises

---

## 📞 Contact

**Développé par**: H3R7Tech
**Date**: Mars 2026
**Version**: 1.6

---

*Document généré automatiquement - Dépenses Trello*

---

---

# Turf SaaS — Documentation API v1

**Mise à jour** : 2026-04-30 (HRT-96 — ML Predictions + ROI + Feedback)  
**URL SaaS** : https://turf-saas-kolifee.duckdns.org  
**Port local** : 8792  
**Base de données** : `/home/h3r7/turf_saas/turf_saas.db`

---

## Stack Technique Turf SaaS

| Composant | Technologie |
|---|---|
| Backend | Python Flask + Blueprints |
| Auth | JWT (access + refresh tokens) |
| Base de données | SQLite (`turf_saas.db`) |
| ML | XGBoost v1 (prédictions courses PMU) |
| Frontend | HTML5 + Chart.js |
| Hébergement | VPS Linux — https://turf-saas-kolifee.duckdns.org |

---

## Plans d'accès

| Plan | Accès |
|---|---|
| `free` | health, auth, courses/today, predictions/top3 (1/jour) |
| `premium` | + predictions/all, valuebets, metrics, roi (complet), feedback/stats |
| `pro` | + backtest, export/csv, historique illimité, orgs |

---

## Endpoints API v1

### Authentification

| Méthode | Path | Auth | Description |
|---|---|---|---|
| POST | `/api/v1/auth/register` | Non | Créer un compte (plan=free) |
| POST | `/api/v1/auth/login` | Non | Login — retourne access_token + refresh_token |
| POST | `/api/v1/auth/refresh` | Non | Renouveler l'access token |
| POST | `/api/v1/auth/logout` | Oui | Révoquer le refresh token |

### Système

| Méthode | Path | Auth | Description |
|---|---|---|---|
| GET | `/api/v1/health` | Non | Healthcheck public |
| GET | `/api/v1/docs` | Non | Swagger UI (Flasgger) |

### Courses

| Méthode | Path | Plan | Description |
|---|---|---|---|
| GET | `/api/v1/courses/today` | free+ | Courses du jour (paginé) |
| GET | `/api/v1/courses/{id}/predictions` | free+ | Prédictions ML pour une course |

`{id}` format : `{num_reunion}-{num_course}` ex: `1-3`  
Query params `courses/today` : `filter=[all|quinte|trot|plat]`, `limit`, `offset`

### Prédictions ML

| Méthode | Path | Plan | Description |
|---|---|---|---|
| GET | `/api/v1/predictions/top3` | free+ | Top 3 chevaux du jour |
| GET | `/api/v1/predictions/all` | premium+ | Toutes les prédictions XGBoost |

Query params : `date=YYYY-MM-DD`, `limit`, `offset`

Source des données : table `ml_predictions_cache` (modèle `xgboost_v1`)

### Value Bets

| Méthode | Path | Plan | Description |
|---|---|---|---|
| GET | `/api/v1/valuebets` | premium+ | Value bets du jour (`is_value_bet=1`) |

Query params : `date`, `min_odds` (défaut 2.0), `limit`, `offset`

### Métriques ML

| Méthode | Path | Plan | Description |
|---|---|---|---|
| GET | `/api/v1/metrics` | premium+ | Métriques perf ML (precision, ROI, top-3 rate) |

Query params : `days` (int, défaut 30, max 365)

### ROI par Modèle/Stratégie (HRT-92)

| Méthode | Path | Plan | Description |
|---|---|---|---|
| GET | `/api/v1/roi/by-model` | premium+ | ROI calculé par stratégie ML XGBoost |

**Query params** :
- `strategy` : filtrer par stratégie (`xgboost_sg`, `xgboost_value`, `xgboost_sp`, `xgboost_2sur4`)
- `days` : période en jours (défaut 30, max 365)

**Réponse** :
```json
{
  "period": {"start": "2026-04-01", "end": "2026-04-30", "days": 30},
  "models": [
    {
      "model_source": "xgboost_sg",
      "nb_paris": 42,
      "mise": 42.0,
      "gain": 51.3,
      "roi_pct": 22.1,
      "win_rate": 28.6
    }
  ]
}
```

**Jointures** : `paris` ← `pmu_partants` (résultats) ← `pmu_rapports` (dividendes)

**Accès plan** : Free = 1 stratégie max, Premium/Pro = complet + historique illimité

### ML Feedback Loop (HRT-93)

| Méthode | Path | Plan | Description |
|---|---|---|---|
| POST | `/api/v1/ml/feedback/run` | Admin | Déclencher ml_feedback_saas.py manuellement |
| GET | `/api/v1/ml/feedback/stats` | premium+ | Stats paris par stratégie XGBoost |

**POST `/api/v1/ml/feedback/run`** — Corps optionnel :
```json
{"date": "2026-04-29"}
```
ou
```json
{"backfill": "2026-04-20"}
```

**GET `/api/v1/ml/feedback/stats`** — Réponse :
```json
{
  "stats": [
    {
      "source_reco": "xgboost_sg",
      "nb_paris": 42,
      "nb_gagnes": 12,
      "win_rate_pct": 28.6,
      "mise_totale": 42.0,
      "gain_total": 51.3,
      "roi_pct": 22.1
    }
  ],
  "last_run": "2026-04-29T18:30:00"
}
```

**Stratégies XGBoost** :
| Stratégie | Type pari | Condition | Mise |
|---|---|---|---|
| `xgboost_sg` | simple_gagnant | top1 ML, ml_score >= 70 | 1€ |
| `xgboost_value` | simple_gagnant | is_value_bet = 1 | 1€ |
| `xgboost_sp` | simple_place | top1 ML, ml_score >= 50 | 1€ |
| `xgboost_2sur4` | deux_sur_quatre | top4 ML, 6 combos | 6€ |

### Backtest

| Méthode | Path | Plan | Description |
|---|---|---|---|
| GET | `/api/v1/backtest` | pro | Résultats historiques des paris |

Query params : `start`, `end` (YYYY-MM-DD), `limit`, `offset`

### Export

| Méthode | Path | Plan | Description |
|---|---|---|---|
| GET | `/api/v1/export/csv` | pro | Export CSV |

Query params : `type=[predictions|bets]`, `date`, `start`, `end`

### Historique

| Méthode | Path | Plan | Description |
|---|---|---|---|
| GET | `/api/v1/history` | free+ | Historique prédictions ML |

Limites : Free = 7j, Premium = 90j, Pro = illimité

### Organisations

| Méthode | Path | Plan | Description |
|---|---|---|---|
| GET | `/api/v1/org/` | pro | Détails de l'organisation |
| POST | `/api/v1/org/` | pro | Créer une organisation |
| POST | `/api/v1/org/invite` | pro | Inviter un membre (max 5) |
| DELETE | `/api/v1/org/members/{id}` | pro | Retirer un membre |

### Utilisateur & Tokens

| Méthode | Path | Plan | Description |
|---|---|---|---|
| GET | `/api/v1/user/profile` | free+ | Profil utilisateur |
| PUT | `/api/v1/user/alerts` | premium+ | Config alertes Telegram |
| GET | `/api/v1/user/api-token` | pro | Token API personnel |
| POST | `/api/v1/user/api-token` | pro | Générer/régénérer token API |
| GET | `/api/v1/user/webhook` | pro | Config webhook |
| PUT | `/api/v1/user/webhook` | pro | Modifier webhook |

### Billing (Stripe)

| Méthode | Path | Auth | Description |
|---|---|---|---|
| POST | `/api/v1/billing/checkout` | Oui | Créer session Stripe Checkout |
| POST | `/api/v1/billing/portal` | Oui | Portail Stripe (gestion abonnement) |
| GET | `/api/v1/billing/status` | Oui | Statut abonnement actuel |
| POST | `/api/v1/billing/webhook` | Non | Webhook Stripe (events) |

---

## Format de réponse uniforme

**Erreurs** :
```json
{
  "status": "error",
  "message": "Description de l'erreur",
  "code": 400
}
```

**Listes paginées** :
```json
{
  "pagination": {
    "total": 150,
    "limit": 20,
    "offset": 0,
    "has_more": true
  }
}
```

---

## Architecture ML — Résumé

```
ml_predictions_cache (XGBoost v1)
    → ml_feedback_saas.py
        → table paris (source_reco = xgboost_*)
            → /api/v1/roi/by-model  (ROI calculé)
            → /api/v1/ml/feedback/stats (stats)
                → dashboard_saas.html (Section Performance & ROI)
```

Voir documentation complète : `POD/Intelligence/ML_Predictions_SaaS.md`

---

## Démarrage

```bash
cd /home/h3r7/turf_saas
source venv/bin/activate
python app_v1.py
# ou via gunicorn
gunicorn -w 2 -b 0.0.0.0:8792 app_v1:app
```

## Tests

```bash
cd /home/h3r7/turf_saas
source venv/bin/activate
python -m pytest tests/ -v
```

---

*Turf SaaS — H3R7Tech — Mise à jour 2026-04-30 (HRT-96)*