turf_saas/DOCUMENTATION.md

💸 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

# 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 :

{
  "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 :

{"date": "2026-04-29"}

ou

{"backfill": "2026-04-20"}

GET /api/v1/ml/feedback/stats — Réponse :

{
  "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 :

{
  "status": "error",
  "message": "Description de l'erreur",
  "code": 400
}

Listes paginées :

{
  "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

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

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

---

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