Étape 1 : squelette du projet

- Monorepo backend/ + frontend/ + deploy/
- Backend FastAPI/SQLModel/Alembic/uv qui démarre (health check, config,
  i18n, base de test PostgreSQL, pytest)
- docker-compose de développement (db + backend hot-reload)
- Chaîne CI/CD GitHub Actions : lint + tests, build image, push GHCR,
  déploiement SSH sur le VPS à chaque push main
- CLAUDE.md : vocabulaire du domaine, conventions, commandes

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017uUsRg7XzopkCPWimwg9ZM

backend/app/api/health.py

@@ -0,0 +1,19 @@
+from fastapi import APIRouter
+from sqlalchemy import text
+
+from app.db import engine
+from app.i18n import t
+
+router = APIRouter(tags=["health"])
+
+
+@router.get("/health")
+def health() -> dict[str, str]:
+    return {"status": "ok", "message": t("health.ok")}
+
+
+@router.get("/health/db")
+def health_db() -> dict[str, str]:
+    with engine.connect() as conn:
+        conn.execute(text("SELECT 1"))
+    return {"status": "ok"}

backend/app/config.py

@@ -0,0 +1,36 @@
+from functools import lru_cache
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """Configuration applicative, alimentée par l'environnement."""
+
+    model_config = SettingsConfigDict(
+        env_file=".env", env_file_encoding="utf-8", extra="ignore"
+    )
+
+    environment: str = "development"
+
+    database_url: str = (
+        "postgresql+psycopg://benevoles:benevoles@localhost:5432/benevoles"
+    )
+    test_database_url: str = (
+        "postgresql+psycopg://benevoles:benevoles@localhost:5432/benevoles_test"
+    )
+
+    # Utilisés par l'étape authentification (lien magique). Pas encore actifs.
+    jwt_secret: str = "dev-only-change-me"
+    magic_link_ttl_minutes: int = 30
+
+    log_level: str = "INFO"
+    cors_origins: list[str] = ["http://localhost:5173"]
+
+    @property
+    def is_production(self) -> bool:
+        return self.environment == "production"
+
+
+@lru_cache
+def get_settings() -> Settings:
+    return Settings()

backend/app/db.py

@@ -0,0 +1,17 @@
+from collections.abc import Iterator
+
+from sqlmodel import Session, create_engine
+
+from app.config import get_settings
+
+engine = create_engine(
+    get_settings().database_url,
+    echo=False,
+    pool_pre_ping=True,
+)
+
+
+def get_session() -> Iterator[Session]:
+    """Dépendance FastAPI : une session par requête."""
+    with Session(engine) as session:
+        yield session

backend/app/i18n/__init__.py

@@ -0,0 +1,22 @@
+import json
+from functools import lru_cache
+from pathlib import Path
+
+_LOCALE_DIR = Path(__file__).parent / "locales"
+DEFAULT_LOCALE = "fr"
+
+
+@lru_cache
+def _catalog(locale: str) -> dict[str, str]:
+    path = _LOCALE_DIR / f"{locale}.json"
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def t(key: str, locale: str = DEFAULT_LOCALE, **params: object) -> str:
+    """Traduit une clé. Aucun texte visible par l'utilisateur ne doit être
+    écrit en dur ailleurs que dans les fichiers `locales/*.json`."""
+    template = _catalog(locale).get(key, key)
+    try:
+        return template.format(**params)
+    except (KeyError, IndexError):
+        return template

backend/app/i18n/locales/fr.json

@@ -0,0 +1,7 @@
+{
+  "health.ok": "Service opérationnel",
+  "error.not_found": "Ressource introuvable",
+  "error.forbidden": "Accès refusé",
+  "error.unauthorized": "Authentification requise",
+  "error.validation_failed": "La validation a échoué"
+}

backend/app/logging_config.py

@@ -0,0 +1,15 @@
+import logging
+
+from app.config import get_settings
+
+# RGPD — RÈGLE STRICTE
+# Ne jamais journaliser de données nominatives : pas de nom, prénom, email ni
+# téléphone dans les logs. On journalise des identifiants (UUID/entier) et des
+# codes. Toute nouvelle instruction de log doit respecter cette règle.
+
+
+def configure_logging() -> None:
+    logging.basicConfig(
+        level=get_settings().log_level,
+        format="%(asctime)s %(levelname)s %(name)s %(message)s",
+    )

backend/app/main.py

@@ -0,0 +1,22 @@
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from app.api.health import router as health_router
+from app.config import get_settings
+from app.logging_config import configure_logging
+
+configure_logging()
+
+settings = get_settings()
+
+app = FastAPI(title="Gestion des bénévoles", version="0.1.0")
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.cors_origins,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+app.include_router(health_router)

backend/app/migrations/env.py

@@ -0,0 +1,50 @@
+from logging.config import fileConfig
+
+from alembic import context
+from sqlalchemy import engine_from_config, pool
+from sqlmodel import SQLModel
+
+from app import models  # noqa: F401  (enregistre les métadonnées des tables)
+from app.config import get_settings
+
+config = context.config
+config.set_main_option("sqlalchemy.url", get_settings().database_url)
+
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+target_metadata = SQLModel.metadata
+
+
+def run_migrations_offline() -> None:
+    context.configure(
+        url=config.get_main_option("sqlalchemy.url"),
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+        compare_type=True,
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    connectable = engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+    with connectable.connect() as connection:
+        context.configure(
+            connection=connection,
+            target_metadata=target_metadata,
+            compare_type=True,
+        )
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

backend/app/migrations/script.py.mako

@@ -0,0 +1,26 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from collections.abc import Sequence
+
+from alembic import op
+import sqlalchemy as sa
+import sqlmodel
+${imports if imports else ""}
+
+revision: str = ${repr(up_revision)}
+down_revision: str | None = ${repr(down_revision)}
+branch_labels: str | Sequence[str] | None = ${repr(branch_labels)}
+depends_on: str | Sequence[str] | None = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    ${downgrades if downgrades else "pass"}

backend/app/models/__init__.py

@@ -0,0 +1,6 @@
+"""Tables SQLModel du domaine.
+
+Vide à ce stade : le modèle de données est ajouté à l'étape suivante. Ce module
+est importé par Alembic (`app/migrations/env.py`) et par les tests pour
+enregistrer les métadonnées.
+"""

backend/app/validation/__init__.py

@@ -0,0 +1,5 @@
+"""Moteur de validation des affectations — cœur du produit.
+
+Implémenté à l'étape 4, en TDD : les tests précèdent le code, chaque règle est
+couverte par un cas passant et un cas déclenchant. Voir CLAUDE.md § 3.
+"""