0492f06bfd
- Création POD/Intelligence/ML_Predictions_SaaS.md : architecture ML complète, flow ml_predictions_cache → ml_feedback_saas → paris → ROI dashboard, schéma données/jointures, décision duplication vs modification turf_scraper, documentation des 4 stratégies XGBoost, idempotence, usage CLI - Mise à jour DOCUMENTATION.md : ajout section Turf SaaS API v1 complète avec tous les endpoints documentés dont /api/v1/roi/* et /api/v1/ml/feedback/* (HRT-92 ROI backend + HRT-93 ML feedback loop) Co-Authored-By: Paperclip <noreply@paperclip.ing>
439 lines
11 KiB
Markdown
439 lines
11 KiB
Markdown
# 💸 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)*
|