2026-02-01 09:31:38 +01:00

20 KiB

Raw Blame History

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

Créer la structure du répertoire backend (AC: #1)
- Créer le répertoire backend/ à la racine du projet
- Créer la structure FastAPI (app/, models/, schemas/, api/)
- Créer backend/app/__init__.py
- Créer backend/app/main.py avec instance FastAPI
- Vérifier que la structure suit les conventions d'architecture
Installer les dépendances FastAPI (AC: #1)
- Installer FastAPI
- Installer SQLAlchemy 2.0.45
- Installer Alembic pour migrations
- Installer Pydantic pour validation
- Installer uvicorn pour le serveur de développement
- Créer requirements.txt avec toutes les dépendances
Configurer SQLAlchemy avec SQLite (AC: #1)
- Créer backend/app/database.py avec configuration SQLAlchemy
- Configurer la connexion SQLite (partagée avec Next.js ou séparée)
- Configurer le moteur de base de données SQLAlchemy
- Créer une fonction de connexion de session
- Configurer Alembic pour les migrations
Créer un modèle de base de données de test (AC: #1)
- Créer backend/app/models/__init__.py
- Créer un modèle SQLAlchemy simple (ex: User)
- Utiliser les conventions de nommage: snake_case pour tables/colonnes
- Ajouter des colonnes de base (id, created_at, etc.)
- Créer le schéma Pydantic correspondant
Configurer Alembic pour les migrations (AC: #1)
- Initialiser Alembic avec alembic init
- Configurer alembic.ini avec le chemin vers la base de données
- Configurer env.py pour importer les modèles SQLAlchemy
- Créer la première migration
- Appliquer la migration pour créer la table
Démarrer et valider le serveur FastAPI (AC: #2)
- Démarrer le serveur avec uvicorn app.main:app --reload
- Vérifier que le serveur démarre sans erreurs
- Accéder à http://localhost:8000/docs pour vérifier Swagger UI
- Tester la connexion à la base de données
- Créer un endpoint de test simple
- 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:

backend/ (répertoire racine backend)
backend/app/__init__.py (package Python)
backend/app/main.py (instance FastAPI)
backend/app/database.py (configuration SQLAlchemy)
backend/app/models/ (modèles SQLAlchemy)
backend/app/schemas/ (schémas Pydantic)
backend/app/api/ (routes API)
backend/requirements.txt (dépendances Python)
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:

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

Configuration SQLAlchemy (backend/app/database.py):

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()

Configuration FastAPI (backend/app/main.py):

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

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

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:

cd backend
pip install fastapi uvicorn[standard] sqlalchemy alembic pydantic pydantic-settings python-multipart

Commands de Migrations:

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+):

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
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
Tests d'API:
- Tester les endpoints FastAPI
- Valider les réponses Swagger UI
- Tester la validation Pydantic
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:

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

20 KiB Raw Blame History