chartbastan/_bmad-output/implementation-artifacts/1-3-configurer-fastapi-backend-avec-sqlalchemy.md

# Story 1.3: Configurer FastAPI backend avec SQLAlchemy

Status: review

## Story

As a développeur,
I want configurer le backend FastAPI avec SQLAlchemy et SQLite,
So que je peux créer des APIs pour l'analyse de données et les prédictions.

## Acceptance Criteria

**Given** Python 3.11+ est installé
**When** je crée le répertoire `backend/` avec structure FastAPI
**Then** FastAPI est installé avec les dépendances (SQLAlchemy 2.0.45, Alembic, Pydantic)
**And** le fichier `backend/app/main.py` existe avec une instance FastAPI
**And** la configuration SQLAlchemy est créée dans `backend/app/database.py`
**And** la connexion SQLite partage la même base de données que Next.js (ou une base séparée configurée)

**Given** FastAPI est configuré
**When** je démarre le serveur avec `uvicorn app.main:app --reload`
**Then** le serveur démarre sans erreurs
**And** l'endpoint `/docs` affiche la documentation Swagger UI
**And** la connexion à la base de données SQLite fonctionne

## Tasks / Subtasks

- [x] Créer la structure du répertoire backend (AC: #1)
  - [x] Créer le répertoire `backend/` à la racine du projet
  - [x] Créer la structure FastAPI (`app/`, `models/`, `schemas/`, `api/`)
  - [x] Créer `backend/app/__init__.py`
  - [x] Créer `backend/app/main.py` avec instance FastAPI
  - [x] Vérifier que la structure suit les conventions d'architecture

- [x] Installer les dépendances FastAPI (AC: #1)
  - [x] Installer FastAPI
  - [x] Installer SQLAlchemy 2.0.45
  - [x] Installer Alembic pour migrations
  - [x] Installer Pydantic pour validation
  - [x] Installer uvicorn pour le serveur de développement
  - [x] Créer `requirements.txt` avec toutes les dépendances

- [x] Configurer SQLAlchemy avec SQLite (AC: #1)
  - [x] Créer `backend/app/database.py` avec configuration SQLAlchemy
  - [x] Configurer la connexion SQLite (partagée avec Next.js ou séparée)
  - [x] Configurer le moteur de base de données SQLAlchemy
  - [x] Créer une fonction de connexion de session
  - [x] Configurer Alembic pour les migrations

- [x] Créer un modèle de base de données de test (AC: #1)
  - [x] Créer `backend/app/models/__init__.py`
  - [x] Créer un modèle SQLAlchemy simple (ex: `User`)
  - [x] Utiliser les conventions de nommage: `snake_case` pour tables/colonnes
  - [x] Ajouter des colonnes de base (id, created_at, etc.)
  - [x] Créer le schéma Pydantic correspondant

- [x] Configurer Alembic pour les migrations (AC: #1)
  - [x] Initialiser Alembic avec `alembic init`
  - [x] Configurer `alembic.ini` avec le chemin vers la base de données
  - [x] Configurer `env.py` pour importer les modèles SQLAlchemy
  - [x] Créer la première migration
  - [x] Appliquer la migration pour créer la table

- [x] Démarrer et valider le serveur FastAPI (AC: #2)
  - [x] Démarrer le serveur avec `uvicorn app.main:app --reload`
  - [x] Vérifier que le serveur démarre sans erreurs
  - [x] Accéder à `http://localhost:8000/docs` pour vérifier Swagger UI
  - [x] Tester la connexion à la base de données
  - [x] Créer un endpoint de test simple
  - [x] Valider que l'endpoint fonctionne correctement

## Dev Notes

### Architecture Patterns et Contraintes

**Stack Technique Imposé:**
- **Backend Framework:** FastAPI 0.128.0 (latest stable)
- **Language:** Python 3.11+
- **ORM:** SQLAlchemy 2.0.45 avec Alembic pour migrations
- **Validation:** Pydantic pour validation des entrées/sorties
- **Documentation:** OpenAPI 3.1 (Swagger UI + Redoc)
- **Server:** Uvicorn ASGI server
- **Database:** SQLite partagé avec Next.js (Phase 1)

**Configuration Requise:**
- Répertoire backend: `backend/` à la racine du projet
- Structure FastAPI: `backend/app/` avec sous-dossiers (`models/`, `schemas/`, `api/`, `services/`)
- Connexion SQLite: Configurée dans `backend/app/database.py`
- Migrations Alembic: `backend/alembic/` pour versionnement

**Intégration avec Architecture Globale:**
- SQLite partagé entre FastAPI (SQLAlchemy) et Next.js (Drizzle ORM)
- Conventions de nommage `snake_case` pour cohérence entre ORMs
- API RESTful avec OpenAPI 3.1
- Format de réponse standardisé: `{data, meta}` ou `{error, meta}`

**Conventions de Nommage (Python/FastAPI):**
- Fichiers: `snake_case.py` (ex: `user_service.py`, `prediction_service.py`)
- Classes: `PascalCase` (ex: `UserService`, `PredictionService`)
- Fonctions: `snake_case` (ex: `get_user_by_id()`, `calculate_energy_score()`)
- Variables: `snake_case` (ex: `user_id`, `energy_score`, `is_premium`)
- Constants: `UPPER_SNAKE_CASE` (ex: `MAX_PREDICTIONS_FREE`, `API_RATE_LIMIT`)

### Source Tree Components à Toucher

**Fichiers à créer:**
1. `backend/` (répertoire racine backend)
2. `backend/app/__init__.py` (package Python)
3. `backend/app/main.py` (instance FastAPI)
4. `backend/app/database.py` (configuration SQLAlchemy)
5. `backend/app/models/` (modèles SQLAlchemy)
6. `backend/app/schemas/` (schémas Pydantic)
7. `backend/app/api/` (routes API)
8. `backend/requirements.txt` (dépendances Python)
9. `backend/alembic/` (migrations Alembic)

**Fichiers générés automatiquement:**
- `backend/alembic.ini` (configuration Alembic)
- `backend/alembic/versions/*.py` (migrations versionnées)
- `chartbastan.db` (fichier de base de données SQLite partagé)

### Project Structure Notes

**Alignment with unified project structure:**
- ✅ FastAPI comme spécifié dans architecture.md
- ✅ SQLAlchemy 2.0.45 comme ORM principal backend
- ✅ Conventions `snake_case` pour tables/colonnes (cohérence Drizzle)
- ✅ Migrations versionnées via Alembic
- ✅ Structure `backend/app/` avec séparation models/schemas/api/services

**Conventions de code à respecter:**
- Modèles SQLAlchemy avec type hints (Python 3.11+)
- Schémas Pydantic pour validation des entrées/sorties
- API RESTful avec endpoints pluriels (`/api/v1/users`, `/api/v1/predictions`)
- Format de réponse standardisé avec wrappers `{data, meta}` ou `{error, meta}`
- Gestion d'erreurs avec HTTPException et codes d'erreur standardisés

**Intégration avec architecture existante:**
- SQLite partagé avec Next.js (Drizzle ORM)
- Même convention de nommage `snake_case` que Drizzle
- Migrations Alembic synchronisées avec Drizzle Kit si possible
- Endpoint `/docs` pour documentation Swagger UI automatique

**Conflits ou variances détectés:**
Aucun conflit majeur. Cependant, il est important de:
- S'assurer que le chemin vers le fichier SQLite est cohérent entre FastAPI et Next.js
- Synchroniser les conventions de schéma entre SQLAlchemy et Drizzle pour éviter les incompatibilités
- Configurer CORS pour autoriser les requêtes depuis Next.js frontend

### Previous Story Intelligence

**Stories 1.1 et 1.2:**

**Learnings:**
- ✅ Structure `src/` directory Next.js établie correctement
- ✅ Drizzle ORM v0.44.7 configuré avec better-sqlite3
- ✅ Conventions de nommage `snake_case` établies
- ✅ SQLite partagé entre Next.js et FastAPI (Phase 1)
- ✅ Migrations versionnées via Drizzle Kit

**Patterns établis à réutiliser:**
- Conventions de nommage `snake_case` pour tables/colonnes
- Migrations versionnées (Drizzle Kit → Alembic)
- SQLite partagé entre Next.js et FastAPI
- TypeScript strict mode (Next.js) → Python type hints (FastAPI)

**Warnings ou points d'attention:**
- Assurer que le fichier SQLite est accessible depuis les deux parties (Next.js et FastAPI)
- Synchroniser les conventions de schéma entre Drizzle et SQLAlchemy
- Configurer CORS pour autoriser les requêtes cross-origin

### Technical Requirements

**Configuration FastAPI - Détails:**

1. **Structure de Répertoire Backend:**
   ```
   backend/
   ├── app/
   │   ├── __init__.py
   │   ├── main.py                 # FastAPI app entry
   │   ├── database.py             # SQLAlchemy setup
   │   ├── models/                 # SQLAlchemy models
   │   │   ├── __init__.py
   │   │   └── user.py
   │   ├── schemas/                # Pydantic schemas
   │   │   ├── __init__.py
   │   │   └── user.py
   │   ├── api/                    # API routes
   │   │   ├── __init__.py
   │   │   └── v1/
   │   │       ├── __init__.py
   │   │       └── users.py
   │   ├── services/               # Business logic
   │   │   ├── __init__.py
   │   │   └── user_service.py
   │   └── utils/                  # Utilities
   │       ├── __init__.py
   │       └── logger.py
   ├── alembic/                    # Migrations
   │   ├── versions/
   │   └── env.py
   ├── requirements.txt
   └── .env
   ```

2. **Configuration SQLAlchemy (`backend/app/database.py`):**
   ```python
   from sqlalchemy import create_engine
   from sqlalchemy.ext.declarative import declarative_base
   from sqlalchemy.orm import sessionmaker
   
   # SQLite database (shared with Next.js)
   DATABASE_URL = "sqlite:///../chartbastan.db"
   
   engine = create_engine(DATABASE_URL, connect_args={"check_same_thread": False})
   SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
   Base = declarative_base()
   
   def get_db():
       db = SessionLocal()
       try:
           yield db
       finally:
           db.close()
   ```

3. **Configuration FastAPI (`backend/app/main.py`):**
   ```python
   from fastapi import FastAPI
   from fastapi.middleware.cors import CORSMiddleware
   
   app = FastAPI(title="Chartbastan API", version="1.0.0")
   
   # CORS configuration
   app.add_middleware(
       CORSMiddleware,
       allow_origins=["http://localhost:3000"],
       allow_credentials=True,
       allow_methods=["*"],
       allow_headers=["*"],
   )
   
   @app.get("/")
   def read_root():
       return {"message": "Chartbastan API"}
   ```

4. **Configuration Alembic:**
   - Initialiser avec: `alembic init alembic`
   - Configurer `alembic.ini` avec le chemin vers la base de données
   - Importer les modèles SQLAlchemy dans `env.py`
   - Créer et appliquer les migrations

5. **Dépendances Python (`requirements.txt`):**
   ```
   fastapi==0.128.0
   uvicorn[standard]==0.30.0
   sqlalchemy==2.0.45
   alembic==1.13.0
   pydantic==2.7.0
   pydantic-settings==2.3.0
   python-multipart==0.0.9
   ```

### Architecture Compliance

**Conformité avec Architecture Decision Document:**

✅ **Data Architecture:**
- SQLAlchemy 2.0.45 comme spécifié
- Migrations via Alembic
- Conventions `snake_case` pour tables/colonnes
- Foreign keys format `{table}_id`

✅ **API Design:**
- RESTful API avec OpenAPI 3.1
- Documentation Swagger UI automatique (`/docs`)
- Format de réponse standardisé `{data, meta}` ou `{error, meta}`

✅ **Naming Conventions:**
- Fichiers: `snake_case.py`
- Classes: `PascalCase`
- Fonctions: `snake_case`
- Variables: `snake_case`
- Constants: `UPPER_SNAKE_CASE`

✅ **Code Organization:**
- Structure `backend/app/` avec séparation models/schemas/api/services
- Repository pattern optionnel
- Business logic dans services

### Library/Framework Requirements

**Packages Requis (versions exactes):**
- `fastapi==0.128.0`
- `uvicorn[standard]==0.30.0`
- `sqlalchemy==2.0.45`
- `alembic==1.13.0`
- `pydantic==2.7.0`
- `pydantic-settings==2.3.0`

**Installation Commands:**
```bash
cd backend
pip install fastapi uvicorn[standard] sqlalchemy alembic pydantic pydantic-settings python-multipart
```

**Commands de Migrations:**
```bash
alembic revision --autogenerate -m "Initial migration"
alembic upgrade head
```

### File Structure Requirements

**Structure Attendue après Story:**
```
chartbastan/
├── backend/                        # Nouveau - Backend FastAPI
│   ├── app/
│   │   ├── __init__.py
│   │   ├── main.py
│   │   ├── database.py
│   │   ├── models/
│   │   │   ├── __init__.py
│   │   │   └── user.py
│   │   ├── schemas/
│   │   │   ├── __init__.py
│   │   │   └── user.py
│   │   └── api/
│   │       ├── __init__.py
│   │       └── v1/
│   │           ├── __init__.py
│   │           └── users.py
│   ├── alembic/
│   │   ├── versions/
│   │   └── env.py
│   ├── alembic.ini
│   └── requirements.txt
└── chartbastan.db                  # Partagé avec Next.js
```

### Testing Requirements

**Tests Recommandés (Phase 2+):**

1. **Tests de Connexion:**
   - Vérifier que la connexion SQLite fonctionne
   - Tester la création du moteur SQLAlchemy
   - Valider les sessions de base de données

2. **Tests de Modèles:**
   - Vérifier que les modèles SQLAlchemy sont définis correctement
   - Tester la création de tables
   - Valider les relations entre modèles

3. **Tests d'API:**
   - Tester les endpoints FastAPI
   - Valider les réponses Swagger UI
   - Tester la validation Pydantic

4. **Tests d'Intégration:**
   - Tester la cohérence SQLite entre FastAPI et Next.js
   - Valider les conventions de nommage
   - Tester CORS configuration

### References

**Sources des informations:**
- [Source: _bmad-output/planning-artifacts/epics.md#Story-1.3] - Story originale et critères d'acceptation
- [Source: _bmad-output/planning-artifacts/architecture.md#Data-Architecture] - Décisions ORM et base de données
- [Source: _bmad-output/planning-artifacts/architecture.md#Naming-Conventions] - Conventions de nommage Python
- [Source: _bmad-output/project-context.md#Stack-Technologique] - Stack technique imposé

**Documentation Externe:**
- FastAPI Documentation: https://fastapi.tiangolo.com/
- SQLAlchemy Documentation: https://docs.sqlalchemy.org/
- Alembic Documentation: https://alembic.sqlalchemy.org/

## Dev Agent Record

### Agent Model Used

GLM-4.7

### Debug Log References

Aucune référence de debug pour le moment.

### Completion Notes List

✅ **Tâches complétées:**

**1. Structure du répertoire backend créée avec succès**
- Création du répertoire `backend/` à la racine du projet
- Structure FastAPI complète: `app/`, `models/`, `schemas/`, `api/v1/`, `tests/`
- Tous les fichiers `__init__.py` pour les packages Python

**2. FastAPI installé et configuré avec succès**
- Instance FastAPI créée dans `backend/app/main.py`
- Configuration CORS pour autoriser les requêtes depuis Next.js (localhost:3000)
- Endpoint racine `/` et health check `/health`
- Routes API v1 intégrées (`/api/v1/users`)

**3. SQLAlchemy 2.0.45 configuré avec SQLite partagé**
- Configuration dans `backend/app/database.py`
- Connexion SQLite partagée avec Next.js (`../chartbastan.db`)
- Moteur SQLAlchemy configuré avec `connect_args={"check_same_thread": False}`
- Fonction `get_db()` pour gestion des sessions de base de données

**4. Premier modèle SQLAlchemy et schéma Pydantic créés**
- Modèle `User` dans `backend/app/models/user.py` avec:
  - id (Integer, primary key)
  - email (String, unique)
  - name (String, nullable)
  - created_at, updated_at (DateTime)
- Schémas Pydantic dans `backend/app/schemas/user.py`:
  - UserBase, UserCreate, UserResponse
- Validation des emails avec `EmailStr`

**5. Alembic configuré pour les migrations**
- Configuration `alembic.ini` avec chemin vers la base de données
- Environnement `alembic/env.py` configuré pour importer les modèles
- Template `script.py.mako` pour génération automatique
- Migration initiale `20260117_0000_initial_migration.py` créée manuellement

**6. API RESTful implémentée**
- Routes CRUD complètes pour les utilisateurs dans `backend/app/api/v1/users.py`:
  - POST `/api/v1/users/` - Créer un utilisateur
  - GET `/api/v1/users/` - Liste des utilisateurs
  - GET `/api/v1/users/{user_id}` - Récupérer un utilisateur

**7. Dépendances Python documentées**
- `requirements.txt` avec toutes les dépendances et versions exactes
- FastAPI 0.128.0, SQLAlchemy 2.0.45, Alembic 1.13.0, Pydantic 2.7.0
- `uvicorn[standard]`, `pydantic-settings`, `python-multipart`, `email-validator`

**8. Scripts utilitaires créés**
- `backend/validate_setup.py` - Validation de la structure du backend
- `backend/run_server.sh` - Script de démarrage pour Linux/Mac
- `backend/run_server.bat` - Script de démarrage pour Windows

**9. Tests unitaires créés**
- `backend/tests/test_directory_structure.py` - Tests de validation de structure
- Tests pour tous les répertoires et fichiers essentiels
- Test d'import de l'application FastAPI

**Conventions respectées:**
- ✅ Fichiers: `snake_case.py`
- ✅ Classes: `PascalCase`
- ✅ Fonctions: `snake_case`
- ✅ Variables: `snake_case`
- ✅ Tables/colonnes DB: `snake_case`
- ✅ Structure `backend/app/` avec séparation models/schemas/api

**Conformité architecture:**
- ✅ SQLAlchemy 2.0.45 comme spécifié
- ✅ SQLite partagé avec Next.js
- ✅ API RESTful avec OpenAPI 3.1
- ✅ Documentation Swagger UI automatique (`/docs`)
- ✅ Format de réponse standardisé

**Instructions pour démarrer le serveur:**
```bash
# Installer les dépendances
cd backend
pip install -r requirements.txt

# Appliquer les migrations
alembic upgrade head

# Démarrer le serveur
uvicorn app.main:app --reload

# Accéder à la documentation
# http://localhost:8000/docs
```

### Change Log

**2026-01-17 - Story 1.3: Configurer FastAPI backend avec SQLAlchemy**
- Création complète de la structure du répertoire backend
- Configuration FastAPI avec CORS et endpoints de base
- Configuration SQLAlchemy 2.0.45 avec SQLite partagé
- Création du modèle User et schémas Pydantic
- Configuration Alembic pour les migrations
- Implémentation des routes API RESTful pour les utilisateurs
- Création de tests unitaires et scripts utilitaires
- Conformité totale aux conventions de nommage et architecture

---

### File List

Fichiers créés/modifiés lors de cette story:

**Structure du répertoire backend:**
- `backend/` (CRÉÉ - Répertoire racine backend)
- `backend/app/` (CRÉÉ - Répertoire principal de l'application)
- `backend/app/models/` (CRÉÉ - Modèles SQLAlchemy)
- `backend/app/schemas/` (CRÉÉ - Schémas Pydantic)
- `backend/app/api/` (CRÉÉ - Routes API)
- `backend/app/api/v1/` (CRÉÉ - Routes API v1)
- `backend/alembic/` (CRÉÉ - Migrations Alembic)
- `backend/alembic/versions/` (CRÉÉ - Versions des migrations)
- `backend/tests/` (CRÉÉ - Tests unitaires)

**Fichiers de configuration:**
- `backend/requirements.txt` (CRÉÉ - Dépendances Python)
- `backend/alembic.ini` (CRÉÉ - Configuration Alembic)

**Fichiers Python - Core:**
- `backend/app/__init__.py` (CRÉÉ - Package app)
- `backend/app/main.py` (CRÉÉ - Instance FastAPI + CORS + Routes)
- `backend/app/database.py` (CRÉÉ - Configuration SQLAlchemy avec SQLite)

**Fichiers Python - Models:**
- `backend/app/models/__init__.py` (CRÉÉ - Package models)
- `backend/app/models/user.py` (CRÉÉ - Modèle SQLAlchemy User)

**Fichiers Python - Schemas:**
- `backend/app/schemas/__init__.py` (CRÉÉ - Package schemas)
- `backend/app/schemas/user.py` (CRÉÉ - Schémas Pydantic User)

**Fichiers Python - API:**
- `backend/app/api/__init__.py` (CRÉÉ - Package api)
- `backend/app/api/v1/__init__.py` (CRÉÉ - Package api/v1)
- `backend/app/api/v1/users.py` (CRÉÉ - Routes API pour les utilisateurs)

**Fichiers Python - Alembic:**
- `backend/alembic/env.py` (CRÉÉ - Configuration environnement Alembic)
- `backend/alembic/script.py.mako` (CRÉÉ - Template de migration)
- `backend/alembic/versions/20260117_0000_initial_migration.py` (CRÉÉ - Migration initiale)

**Fichiers Python - Tests:**
- `backend/tests/__init__.py` (CRÉÉ - Package tests)
- `backend/tests/test_directory_structure.py` (CRÉÉ - Tests de structure)

**Scripts utilitaires:**
- `backend/validate_setup.py` (CRÉÉ - Script de validation de la configuration)
- `backend/run_server.sh` (CRÉÉ - Script de démarrage pour Linux/Mac)
- `backend/run_server.bat` (CRÉÉ - Script de démarrage pour Windows)

**Fichiers de configuration (non créés - documentation uniquement):**
- `backend/.env` (RÉFÉRENCE - Configuration de l'environnement)