budget-tracker/.specify/memory/plan.md

Plan d'Implémentation — Budget Tracker

Feature : 003-budget-tracker-core Date : 2026-03-15 Durée estimée : 13 jours de travail Stack : FastAPI + SQLAlchemy 2.0 async + Alembic / React 18 + Vite + Tailwind + Recharts / PostgreSQL 16 / Docker Compose

---

Vérification Constitution

Principe	Conformité	Notes
I. API-First	✅	Endpoints définis dans contracts/api.md, Pydantic pour la validation
II. Data Integrity	✅	Montants en centimes (int), soft-delete, transactions ACID
III. Test Coverage	✅	pytest backend, Vitest frontend, ≥80% logique métier
IV. Simplicity	✅	Monolithe, pas de microservices, librairies standard
V. Docker-First	✅	docker-compose.yml, migrations auto au démarrage, build statique nginx

---

Phase 0 — Setup & Infrastructure (1 jour)

Objectif

Disposer d'un environnement de développement fonctionnel avec hot-reload.

Tâches

1. Init repo Git : .gitignore, README.md, structure dossiers (backend/, frontend/, docker/)
2. Docker Compose dev :
   • Service db : PostgreSQL 16, volume persistant, init script
   • Service backend : Python 3.12, hot-reload uvicorn, montage code source
   • Service frontend : Node 22, Vite dev server, montage code source
3. Backend scaffold :
   • FastAPI app factory (backend/app/main.py)
   • Config via Pydantic Settings (.env → backend/app/config.py)
   • SQLAlchemy 2.0 async engine + session factory
   • Alembic init (backend/alembic/)
   • Ruff config (pyproject.toml)
   • requirements.txt avec versions pinned
4. Frontend scaffold :
   • npm create vite@latest avec template React + TypeScript
   • Tailwind CSS setup
   • Prettier config
   • Structure dossiers (src/components/, src/pages/, src/api/, src/hooks/)
5. .env.example avec toutes les variables documentées
6. Smoke test : docker compose up → backend répond GET /health, frontend affiche une page

Livrables

• docker-compose.yml + docker-compose.override.yml (dev)
• Backend qui démarre, frontend qui affiche, PostgreSQL qui tourne
• Premier commit : chore: initial project setup

Critères de validation

• docker compose up fonctionne sans erreur
• GET /health retourne {"status": "ok"}
• Frontend accessible sur localhost:5173
• Ruff et Prettier passent sans erreur

---

Phase 1 — Backend Core (3 jours)

Objectif

API REST fonctionnelle avec auth, transactions et catégories.

Jour 1 : Modèles & Auth

1. Modèles SQLAlchemy : User, Category, Transaction, Budget, RefreshToken
   • UUIDs, created_at/updated_at auto, deleted_at pour soft-delete
   • amount_cents INTEGER, contrainte CHECK > 0
2. Migrations Alembic : alembic revision --autogenerate -m "initial models"
3. Auth JWT :
   • Endpoint POST /auth/register (hash bcrypt, validation email unique)
   • Endpoint POST /auth/login (access token 15min + refresh token 7j)
   • Endpoint POST /auth/refresh
   • Endpoint POST /auth/logout (invalidation refresh token)
   • Middleware get_current_user pour les routes protégées
4. Seed catégories par défaut : Alimentation, Transport, Logement, Santé, Loisirs, Divers (dépenses) + Salaire, Freelance, Remboursement (revenus)

Jour 2 : CRUD Transactions & Catégories

1. Transactions :
   • GET /transactions : pagination, filtres (mois, catégorie, type), tri par date desc
   • POST /transactions : validation Pydantic, isolation par user_id
   • PUT /transactions/{id} : vérification ownership
   • DELETE /transactions/{id} : soft-delete (set deleted_at)
2. Catégories :
   • GET /categories : catégories user + catégories système (is_default)
   • POST /categories : personnalisées uniquement
   • PUT /categories/{id} : pas de modif des catégories système
   • DELETE /categories/{id} : refus 409 si transactions liées actives
3. Services layer : séparer la logique métier des routes (pas de requêtes SQL dans les endpoints)

Jour 3 : Tests Backend

1. Fixtures pytest : base de test PostgreSQL (ou SQLite async pour la vitesse), factory pour User/Transaction/Category
2. Tests unitaires :
   • Calcul de solde (revenu - dépense, centimes)
   • Soft-delete : la transaction n'apparaît plus mais existe en base
   • Validation montant > 0, date pas dans le futur (si décidé)
3. Tests d'intégration :
   • Auth : register → login → token valide → accès protégé
   • CRUD transactions : create → list → update → delete → list vérifie absence
   • Filtrage par mois et catégorie
   • Isolation multi-user : user A ne voit pas les transactions de user B
4. CI : pytest --cov=app/services --cov-fail-under=80

Livrables

• API complète (auth + transactions + catégories)
• Suite de tests avec coverage ≥80% services
• Documentation OpenAPI auto (/docs)

---

Phase 2 — Frontend Core (3 jours)

Objectif

SPA React fonctionnelle avec auth et gestion des transactions.

Jour 4 : Auth & Layout

1. Client API : module src/api/client.ts avec intercepteur Axios/fetch, gestion auto du refresh token
2. Auth store : Context React ou Zustand léger (user, tokens, login/logout)
3. Pages auth : Login, Register avec validation côté client
4. Layout principal : Sidebar navigation (Dashboard, Transactions, Budgets, Historique), header avec nom user + logout
5. Route guard : redirect vers login si non authentifié

Jour 5 : Liste & Formulaire Transactions

1. Page Transactions :
   • Tableau avec colonnes : date, description, catégorie (badge couleur), montant, type (icône revenu/dépense)
   • Pagination
   • Filtres : mois (date picker), catégorie (select), type (toggle)
   • Bouton supprimer avec confirmation
2. Formulaire Transaction (modal ou page) :
   • Champs : montant (€, converti en centimes), date, type (toggle revenu/dépense), catégorie (select), description
   • Validation temps réel
   • Mode création et édition
3. TanStack Query : cache serveur, invalidation après mutation

Jour 6 : Catégories & Polish

1. Gestion catégories : page settings ou modal, CRUD catégories personnalisées avec couleur et icône
2. Feedback UI : toasts de confirmation (ajout, suppression), skeleton loading, états vides
3. Responsive : mobile-first, sidebar collapsible sur mobile
4. Tests Vitest : composants critiques (formulaire transaction, affichage montant centimes→euros)

Livrables

• SPA complète : auth + transactions + catégories
• Responsive mobile/desktop
• Tests composants critiques

---

Phase 3 — Features Avancées (4 jours)

Jour 7 : Dashboard & Graphiques

1. Endpoints backend :
   • GET /dashboard?month=YYYY-MM : solde, totaux, répartition par catégorie, tendance 6 mois, alertes budget
2. Page Dashboard :
   • Cards KPI : solde courant, revenus du mois, dépenses du mois, solde net
   • Graphique camembert : répartition dépenses par catégorie (Recharts PieChart)
   • Graphique barres : tendance revenus/dépenses sur 6 mois (Recharts BarChart)
   • Alertes budgets dépassés (badges warning/danger)
3. Navigation mensuelle : boutons mois précédent/suivant sur le dashboard

Jour 8 : Budgets (Enveloppes)

1. Endpoints backend :
   • GET /budgets?month=YYYY-MM : budgets avec calcul spent_cents et remaining_cents
   • POST /budgets : création avec contrainte unicité (user, category, month)
   • PUT /budgets/{id}, DELETE /budgets/{id}
2. Page Budgets :
   • Liste des enveloppes du mois avec barre de progression (vert/orange/rouge)
   • Formulaire ajout/édition budget (catégorie, limite en €)
   • Copie des budgets du mois précédent (bouton "Reconduire")
3. Tests : calcul consommation budget, reconduction, alertes seuil

Jour 9 : Historique Mensuel

1. Endpoint backend : GET /history?year=YYYY → résumé par mois
2. Page Historique :
   • Tableau annuel : mois, revenus, dépenses, solde, nb transactions
   • Clic sur un mois → redirige vers Dashboard du mois sélectionné
   • Sélecteur d'année
3. Graphique annuel : courbe revenus/dépenses sur 12 mois (Recharts LineChart)

Jour 10 : Export CSV & PDF

1. Endpoint CSV : GET /export/csv?month=YYYY-MM → streaming CSV avec headers
2. Endpoint PDF : GET /export/pdf?month=YYYY-MM → WeasyPrint, template Jinja2 rapport mensuel
   • En-tête avec titre + mois + date d'export
   • Tableau des transactions
   • Résumé par catégorie
   • Solde
3. Boutons export dans la page Transactions et le Dashboard
4. Tests : validité CSV (parsable), PDF non vide

Livrables

• Dashboard avec graphiques interactifs
• Budgets enveloppes avec alertes
• Historique annuel navigable
• Export CSV + PDF fonctionnels

---

Phase 4 — Finalisation & Production (2 jours)

Jour 11 : Docker Production

1. Dockerfile backend : multi-stage (build deps → runtime slim)
2. Dockerfile frontend : multi-stage (build Vite → nginx:alpine)
3. docker-compose.prod.yml :
   • Backend : gunicorn + uvicorn workers
   • Frontend : nginx avec compression gzip, cache headers
   • PostgreSQL avec backup volume
   • Health checks sur tous les services
4. Entrypoint backend : exécute alembic upgrade head au démarrage
5. Sécurité : CORS restrictif, rate limiting (slowapi), HTTPS-ready headers

Jour 12 : Documentation & Qualité

1. README.md complet :
   • Description du projet
   • Prérequis (Docker, Docker Compose)
   • Quick start : cp .env.example .env && docker compose up
   • Architecture (schéma simplifié)
   • Endpoints API (lien vers /docs)
2. OpenAPI : vérifier que la doc auto est complète et lisible
3. Tests e2e légers : script Bash qui lance le stack, crée un user, ajoute une transaction, vérifie le dashboard
4. Cleanup : supprimer code mort, vérifier tous les TODO, linting final

Livrables

• Docker Compose production-ready
• README complet
• Suite complète de tests (unit + integ + e2e)
• Projet prêt à déployer

---

Artefacts générés

Fichier	Description
spec.md	Spécification fonctionnelle (7 user stories, 20 exigences)
research.md	Décisions techniques avec rationale
data-model.md	5 entités, index, contraintes
contracts/api.md	Contrats API REST (21 endpoints)
plan.md	Ce plan d'implémentation

Risques identifiés

Risque	Impact	Mitigation
WeasyPrint lourd en Docker	Image backend volumineuse	Multi-stage build, layer caching
Performances dashboard sur gros volume	Requêtes lentes >10k transactions	Index dédiés (voir data-model.md), pagination
Complexité auth JWT refresh	Bugs de déconnexion intempestive	Tests d'intégration auth exhaustifs
Recharts bundle size	Frontend lourd	Tree-shaking Vite, lazy loading des pages graphiques

Prochaines étapes

1. /speckit.tasks — Découper ce plan en tâches atomiques assignables
2. /speckit.implement — Lancer l'implémentation phase par phase