feat: budget-tracker — spec, constitution, data-model, API contracts, plan

.specify/memory/research.md

@@ -0,0 +1,100 @@
+# Recherche & Décisions Techniques — Budget Tracker
+
+## Authentification
+- **Décision** : JWT (tokens access 15min + refresh 7j) via `python-jose` + `passlib[bcrypt]`
+- **Rationale** : stateless, compatible SPA React, aucune session serveur à gérer, facile à dockeriser
+- **Alternatives** :
+  - Session cookies (plus simple mais couplé au serveur, complexe en CORS)
+  - OAuth2 externe / Keycloak (overkill pour usage personnel)
+  - FastAPI-Users (bibliothèque haut niveau — ajoute de la magie, préférence pour la transparence)
+
+## Base de données
+- **Décision** : PostgreSQL 16
+- **Rationale** : ACID natif (critique pour données financières), types UUID, ENUM, support transactionnel, standard de l'industrie
+- **Alternatives** :
+  - SQLite (suffisant en dev, mais limité en concurrence et types)
+  - MySQL (moins bon support UUID/ENUM natif)
+
+## ORM & Migrations
+- **Décision** : SQLAlchemy 2.0 (mode async) + Alembic
+- **Rationale** : async natif pour FastAPI, migrations versionées et réversibles, mature et bien documenté
+- **Alternatives** :
+  - Tortoise ORM (async natif mais moins mature, moins d'intégrations)
+  - SQLModel (wrapper SQLAlchemy+Pydantic — moins de contrôle sur les modèles)
+  - Prisma (Node.js uniquement)
+
+## Framework Backend
+- **Décision** : FastAPI 0.111+
+- **Rationale** : OpenAPI/Swagger auto-généré (conforme principe I de la Constitution), validation Pydantic intégrée, async natif, typage strict
+- **Alternatives** :
+  - Django REST Framework (sync-first, plus lourd)
+  - Flask (pas d'async natif, validation manuelle)
+
+## Framework Frontend
+- **Décision** : React 18 + TypeScript + Vite
+- **Rationale** : écosystème riche, SPA adaptée à une app de gestion, typage fort réduit les erreurs sur les montants financiers
+- **Alternatives** :
+  - Next.js (SSR inutile pour usage authentifié perso)
+  - Vue 3 (viable mais écosystème plus réduit)
+
+## Styling Frontend
+- **Décision** : Tailwind CSS 3 + shadcn/ui
+- **Rationale** : utilitaires CSS rapides, shadcn/ui fournit composants accessibles (formulaires, modales, tableaux) sans dépendance lourde
+- **Alternatives** :
+  - MUI / Ant Design (plus lourds, style moins personnalisable)
+  - CSS Modules (trop verbeux pour une SPA)
+
+## Graphiques Frontend
+- **Décision** : Recharts
+- **Rationale** : composants React purs (pas de D3 direct), bon support responsive, Tailwind-compatible, léger (~180 ko gzip)
+- **Alternatives** :
+  - Chart.js + react-chartjs-2 (moins idiomatic React, state management externe)
+  - Nivo (très complet mais plus lourd, over-engineering pour 2 types de graphiques)
+  - Victory (moins maintenu)
+
+## Gestion d'état Frontend
+- **Décision** : TanStack Query (React Query) v5
+- **Rationale** : cache serveur, invalidation automatique après mutations (soldes recalculés), gestion loading/error intégrée — évite un store global Redux pour des données essentiellement serveur
+- **Alternatives** :
+  - Redux Toolkit (overkill, état global inutile si les données viennent de l'API)
+  - SWR (moins de fonctionnalités sur les mutations)
+  - Zustand (utile pour état local UI uniquement, complémentaire)
+
+## Export CSV
+- **Décision** : module `csv` Python stdlib
+- **Rationale** : aucune dépendance additionnelle, suffisant pour colonnes tabulaires de transactions, streaming possible via `StreamingResponse` FastAPI
+- **Alternatives** :
+  - pandas (overkill, dépendance lourde)
+
+## Export PDF
+- **Décision** : WeasyPrint
+- **Rationale** : rendu HTML→PDF côté serveur, templates Jinja2 réutilisables, CSS support correct, rendu fidèle
+- **Alternatives** :
+  - ReportLab (API bas niveau, verbeux pour des tableaux)
+  - pdfkit (dépendance système wkhtmltopdf, difficile à dockeriser)
+  - Reportlab + xhtml2pdf (moins stable)
+
+## Stockage des montants
+- **Décision** : entiers en centimes (`amount_cents INTEGER`)
+- **Rationale** : conforme au principe II de la Constitution — élimine toute erreur d'arrondi IEEE 754 sur les opérations financières (ex : 0.1 + 0.2 ≠ 0.3 en float)
+- **Règle** : la conversion euros↔centimes se fait uniquement aux frontières (serialisation Pydantic et affichage React)
+
+## Soft Delete
+- **Décision** : champ `deleted_at TIMESTAMP NULL` sur `Transaction` et `Category`
+- **Rationale** : conforme au principe II (tracabilité historique), permet l'audit et la restauration éventuelle
+- **Implémentation** : filtre `WHERE deleted_at IS NULL` systématique dans les requêtes ; index partiel recommandé
+
+## Conteneurisation
+- **Décision** : Docker Compose (backend + frontend + PostgreSQL)
+- **Rationale** : conforme au principe V de la Constitution, reproductibilité dev/prod, un seul `docker compose up`
+- **Structure** :
+  - `backend/` — image Python 3.12-slim
+  - `frontend/` — build Vite servi par Nginx
+  - `db/` — PostgreSQL 16 officiel
+
+## Tests Backend
+- **Décision** : pytest + httpx (client async) + pytest-asyncio + base de données de test dédiée
+- **Rationale** : conforme au principe III (80% coverage services/), tests d'intégration sur vraie BDD (pas de mock SQLAlchemy)
+- **Alternatives** :
+  - unittest (moins expressif)
+  - mocks SQLAlchemy (rejeté — risque de divergence mock/prod)