benevoles/BLUEPRINT.md

BLUEPRINT — Socle réutilisable

Ce fichier capture la philosophie, la stack, l'architecture, le style et les conventions de l'application « Gestion des bénévoles », débarrassés de son domaine métier (festival, créneaux, cotisations…). Il sert de point de départ pour une nouvelle application construite sur les mêmes bases.

Mode d'emploi pour une nouvelle appli :

1. Copier ce fichier dans le nouveau dépôt.
2. Le donner à Claude avec le brief métier : « Crée l'appli X sur les bases de BLUEPRINT.md ».
3. La première étape produit un CLAUDE.md propre au nouveau projet (même plan que celui de benevoles : glossaire, modèle, règles, périmètre, arborescence, commandes, conventions, déploiement, journal des étapes), qui devient ensuite le contrat de travail.

Les passages marqués ⟨à adapter⟩ dépendent du métier ; tout le reste est le socle à reprendre tel quel.

---

1. Philosophie

• Un outil pour une petite organisation réelle (association, 50–200 personnes), pas une plateforme générique. On résout le besoin concret, sans sur-ingénierie, mais avec un vrai niveau de qualité (tests, sécurité, RGPD, déploiement automatisé).
• Le métier parle français, le code parle anglais. Un glossaire FR ↔ EN fige les noms une fois pour toutes ; aucun nom métier français dans le code, aucun texte d'interface en dur nulle part.
• CLAUDE.md est le contrat de travail. Il décrit le modèle, les règles, les choix et leurs raisons. Il est mis à jour à chaque étape, en même temps que le code. Quand un bug est corrigé, la cause et la règle qui l'empêche de revenir y sont notées (« bug corrigé une fois — faire Y recréerait la même classe de bug »).
• Étapes courtes et validées. Une étape = une fonctionnalité cohérente, montrée à l'utilisateur, puis validée avant de continuer. Un commit atomique par étape, message en français. Le journal des étapes (§ 10 du CLAUDE.md) garde l'historique des décisions.
• Le cœur métier est pur et testé d'abord. Les règles critiques vivent dans un module isolé, sans base de données ni HTTP (fonction pure : entrée typée → résultat typé), écrit en TDD : un cas passant + un cas déclenchant par règle. Un loader.py est le seul point de contact avec la base.
• L'outil assiste, l'humain décide. Les calculs « intelligents » (solveur, suggestions) proposent ; ils ne persistent jamais rien d'eux-mêmes. La validation reste seule juge au moment de l'écriture.
• Erreurs = codes, pas phrases. Le backend renvoie {"detail": {"code": "domaine.raison", ...params}} ; la traduction se fait côté locales. Les violations de règles sont typées (BLOCKING / WARNING) avec des paramètres structurés.
• Simplicité assumée et documentée. Quand on simplifie (ex. « vérifié seulement contre l'existant, pas entre deux suggestions »), on l'écrit explicitement comme simplification assumée.
• Retirer est une fonctionnalité. On n'hésite pas à supprimer un concept devenu inutile (table, règle, écran) — migration, API, front et doc nettoyés ensemble, plutôt que de laisser du code mort.
• Aucune dépendance locale hors Docker. Tout se lance, se teste et se migre via docker compose.

---

2. Stack technique

Backend

Rôle	Choix
Langage	Python 3.12
Gestion des dépendances	uv (pyproject.toml, groupe dev)
API	FastAPI + Uvicorn
ORM / schémas	SQLModel (SQLAlchemy + Pydantic)
Base	PostgreSQL 16 (driver psycopg[binary] v3)
Migrations	Alembic (autogenerate + alembic check pour vérifier modèle ↔ migrations)
Configuration	pydantic-settings (app/config.py, valeurs réelles dans .env non versionné)
Auth	pyjwt (HS256) + bcrypt
Tests	pytest + pytest-cov, vraie base PostgreSQL de test
Lint / format	ruff (line-length 100, règles E F I UP B)
Outils ponctuels	openpyxl (import/export Excel), reportlab + pypdf (PDF), pillow (validation d'images), httpx (API tierces), ortools (optimisation) — ⟨à adapter⟩ selon le besoin

Frontend

Rôle	Choix
Framework	React 18 + TypeScript (strict)
Build	Vite 5
Style	Tailwind CSS 3 (thème étendu, aucune lib de composants)
Données serveur	TanStack React Query 5 (hooks centralisés dans src/api/hooks.ts)
Routing	React Router 6
Graphiques	SVG maison (components/charts.tsx), aucune bibliothèque
Qualité	ESLint 9 + tsc --noEmit + script smoke (rendu headless via tsx)

Dépendances runtime volontairement minimales : react, react-dom, react-router-dom, @tanstack/react-query. Rien d'autre sans bonne raison.

Infra

• Docker Compose en dev (db + backend en hot reload + frontend Vite).
• Production : images backend (uvicorn) et frontend (build statique servi par nginx), ports exposés uniquement sur 127.0.0.1, Caddy du VPS en reverse proxy HTTPS (/api/* → backend avec préfixe retiré, le reste → frontend).
• Dépôt Gitea auto-hébergé + Gitea Actions (act_runner) : tests → build des images (registre Gitea) → SSH sur le VPS → pull → alembic upgrade head → up -d.
• Fuseau horaire : TZ=Europe/Paris + tzdata dans le conteneur.

---

3. Architecture

Arborescence type

.
├── CLAUDE.md                  # contrat de travail (tenu à jour à chaque étape)
├── README.md
├── Makefile                   # make demo / make blank / make down / make logs
├── docker-compose.yml         # dev
├── .env.example               # toutes les variables, sans vraies valeurs
├── .gitea/workflows/ci-cd.yml
├── deploy/                    # docker-compose.prod.yml, bloc Caddyfile, README de mise en service
├── docker/postgres-init/      # crée la base de test au premier démarrage
├── backend/
│   ├── pyproject.toml · Dockerfile · alembic.ini
│   ├── app/
│   │   ├── main.py            # instance FastAPI, montage des routers
│   │   ├── config.py          # Settings (pydantic-settings), get_settings() en cache
│   │   ├── db.py              # engine + get_session
│   │   ├── logging_config.py  # logs sans PII + identifiant de requête
│   │   ├── request_logging.py # middleware : une ligne par requête, X-Request-ID, 500 tracées
│   │   ├── api/               # un router par ressource + schemas.py + deps.py
│   │   ├── auth/              # passwords, magic_link, tokens (JWT), deps (rôles), rate_limit
│   │   ├── email/             # sender (SMTP), templates (texte), html (rendu thémé), check (diagnostic)
│   │   ├── models/            # enums.py, base.py (TimestampMixin, local_now), domain.py
│   │   ├── validation/        # cœur métier pur : models.py, engine.py, loader.py
│   │   ├── <module_métier>/   # même découpage pour chaque calcul isolé ⟨à adapter⟩
│   │   ├── i18n/              # t(key, **params) + locales/fr.json
│   │   ├── bootstrap.py       # instance vierge : 1re entité racine + 1er compte admin
│   │   ├── seed.py            # jeu de démonstration réaliste et déterministe
│   │   └── migrations/
│   └── tests/                 # conftest.py (vraie base), factories.py, test_<module>.py
└── frontend/
    ├── Dockerfile · Dockerfile.prod · nginx.conf
    ├── tailwind.config.js     # palette et primitives du design
    ├── scripts/smoke.tsx      # rendu headless + vérifications structurelles
    └── src/
        ├── api/               # types.ts (interface Api), schema.ts (miroir des schémas backend),
        │                      # http-client.ts, mock/ (même surface, en mémoire), hooks.ts, session.ts
        ├── app/               # AppShell.tsx, router.tsx
        ├── auth/              # auth-context, RequireAuth, roles (homePath par rôle)
        ├── components/        # ui.tsx (primitives), state.tsx (chargement/erreur), charts.tsx
        ├── i18n/              # t(key, params) + locales/fr.json
        ├── lib/               # logique pure testable (calculs, dates, env, cx)
        └── pages/             # un écran par fichier, sous-dossiers si gros écran

Principes d'architecture backend

• Multi-tenant par une entité racine (ici Edition) : toute entité métier porte son <racine>_id, toutes les routes sont préfixées /<racines>/{id}/... et la dépendance get_<racine> renvoie 404 error.not_found si elle n'existe pas. ⟨à adapter⟩ (organisation, projet, saison…).
• Clés primaires UUID, champs d'audit created_at/updated_at sur toutes les tables sauf associations (TimestampMixin).
• Énumérations en VARCHAR + CHECK (native_enum=False), jamais d'ENUM natif PostgreSQL (migrations plus simples).
• ON DELETE CASCADE au niveau base sur les liens vers la racine et entre entités : la suppression RGPD d'une personne est un vrai hard delete qui emporte tout ce qui la concerne.
• Dates naïves en heure locale (local_now()), interprétées Europe/Paris. Pas de mélange UTC/local.
• Modules isolés pour la logique non triviale : models.py (types purs, dataclasses), engine.py (fonction pure), loader.py (seul accès base). Testés sans HTTP.
• Un router par ressource, schémas Pydantic XCreate / XRead / XUpdate dans api/schemas.py. En PATCH : None/absent = inchangé, [] = vider une liste.
• Secrets jamais renvoyés par l'API (xxx_set: bool à la place ; chaîne vide en écriture = effacer).
• Tâches de fond (BackgroundTasks) pour les emails, en best effort : un échec SMTP est journalisé mais ne fait jamais échouer l'appel HTTP.
• Nettoyage paresseux plutôt que tâches planifiées (purge des données périmées au passage d'une requête), tant que le volume le permet.
• Instance vierge et démo : bootstrap.py (CLI, crée la racine + le 1er compte) et seed.py (jeu réaliste avec des cas intéressants : trous, conflits, données de chaque fonctionnalité).

Principes d'architecture frontend

• Une interface Api unique, deux implémentations : client HTTP réel et mock en mémoire de même surface (VITE_API_MODE=mock|http). Le front se développe et se démontre sans backend ; passer de l'un à l'autre ne change aucun écran. Le mock calcule les mêmes résultats que le backend.
• schema.ts = miroir de backend/app/api/schemas.py, gardé synchrone à la main.
• Toutes les données serveur passent par React Query (hooks.ts), jamais de fetch dans les pages.
• Logique pure dans src/lib/, souvent miroir d'une fonction backend (ex. festivalDay ↔ day_boundary) : la règle est écrite à l'identique des deux côtés et le CLAUDE.md le signale.
• Auth : JWT en localStorage, Authorization: Bearer, une 401 déconnecte ; <RequireAuth> sur toutes les pages métier ; page d'accueil et onglets visibles selon le rôle.
• Variables Vite figées au build (VITE_*) : l'image de prod est construite pour un environnement donné.
• Téléchargements (PDF, Excel) : blob → <a download> généré côté client.
• Chaque erreur affiche sa référence (X-Request-ID) sous le message, pour retrouver la ligne de log correspondante.

---

4. Sécurité et RGPD (non négociables)

• Deux systèmes d'authentification, une même session JWT :
  • mot de passe (bcrypt, ≥ 10 caractères) pour les administrateurs ;
  • lien magique (jeton aléatoire haché SHA-256 en base, usage unique, TTL court) pour les autres comptes ; réponse 202 constante, sans jamais révéler si un compte existe.
• Rôles appliqués côté backend par endpoint, documentés dans une matrice ressource × rôle dans le CLAUDE.md. ⟨à adapter⟩ (ici COORDINATOR / LEAD / VOLUNTEER).
• Limiteurs de tentatives en mémoire (connexion, lien magique, formulaires publics, sondages vers API tierces) — 429 error.too_many_requests.
• Démarrage refusé en production avec un JWT_SECRET par défaut, vide ou trop court.
• Pages publiques protégées par jeton dans l'URL (secrets.token_urlsafe, comparaison secrets.compare_digest, 404 générique), régénérable pour révoquer un lien qui a fuité ; hCaptcha optionnel (désactivé si la clé est absente).
• Fichiers importés revalidés (décodage réel d'image avec PIL, pas seulement le Content-Type) ; exports Excel protégés contre l'injection de formule (CWE-1236).
• Aucune donnée nominative dans les logs (ni nom, ni email, ni téléphone, ni sujet d'email personnalisable) : on logue des identifiants. Journal d'accès d'uvicorn désactivé (il écrivait les query strings, donc les jetons).
• Logs de diagnostic : une ligne par requête (méthode, route modèle
  • identifiants, statut, durée, code d'erreur métier, compte) ; WARNING en 4xx, ERROR + trace complète en 5xx ; X-Request-ID propagé jusque dans les tâches de fond. Erreur 422 : emplacement + type, jamais la valeur saisie.
• Rétention paramétrable des données nominatives sur l'entité racine ; endpoint de suppression complète d'une personne.
• En-têtes de sécurité dans nginx et Caddy ; backend et frontend n'écoutent que sur 127.0.0.1.
• Emails : SMTP auto-hébergé, EMAIL_ENABLED=false en dev/tests (simple journalisation), multipart/alternative (texte brut = source de vérité des tests + HTML au thème de l'appli, tableaux et styles en ligne, logo en pièce jointe inline par Content-ID plutôt qu'une URL qui fuiterait un jeton). Commande de diagnostic SMTP dédiée.

---

5. Style visuel (design « néo-brutaliste »)

Identité forte, lisible, sans bibliothèque de composants : bordures franches noires, ombres portées dures sans flou, libellés en capitales, fond crème, accents saturés.

Palette (tailwind.config.js)

Jeton	Valeur	Usage
cream	#F5EFE1	fond général
ink	#14110E	encre, bordures, ombres
paper	#FFFDF7	panneaux, cartes
sand / sand-line / sand-dark	#EFE8D6 / #E0D8C4 / #E7E0CE	barres secondaires, séparateurs
yellow / yellow-soft / yellow-hover	#FFD23F / #FFE68A / #FFDF77	action principale, état incomplet
orange / orange-dark	#FF5C39 / #E0421F	urgence, danger
green	#0E9F6E	succès, survol de l'action principale
blue / blue-strong	#A8C4FF / #2A6BFF	information
mauve / mauve-hover	#CBA6E3 / #BE93D9	dépassement / surplus

Typographie

• font-display : Archivo (400 → 900), titres et boutons en font-black/font-extrabold, uppercase, tracking-wide, petites tailles (11–12 px).
• font-mono : DM Mono, pour les heures, chiffres, codes.
• Chargées depuis Google Fonts dans index.html.

Primitives (components/ui.tsx)

• Ombres : shadow-brutal-sm (2 px), brutal (3 px), brutal-md (4 px), brutal-lg (6 px) — toutes Npx Npx 0 #14110E.
• Panel : border-[3px] border-ink bg-paper + ombre portée.
• PanelHeader : bandeau bg-ink text-cream en capitales (variante hachurée bg-hatch-ink text-yellow).
• Btn : border-2 border-ink, capitales, variantes solid (jaune → vert au survol), ghost (crème → jaune), danger (crème → orange), dark (encre → jaune).
• Trames d'état en backgroundImage : hachures orange (critique), mauve (surplus), encre (brouillon), sable (fermé), pointillés.
• Infobulles (HelpTip) en position: fixed positionnées par JS (useTooltipPosition), bornées à l'écran — jamais en absolute dans un conteneur qui défile.
• Graphiques SVG maison, palette vérifiée daltonisme/contraste sur paper, chaque graphique doublé d'une vue tableau.
• Écrans mobiles dédiés aux rôles « terrain » (consultation simple), écrans denses pour l'administration.

Aucun texte dans les primitives : les libellés viennent toujours de l'i18n.

---

6. Conventions de code

• Code, base, fichiers en anglais ; français uniquement dans les locales, les commentaires de contexte métier et les commits.
• i18n partout, même en monolingue : backend app.i18n.t(key, **params) (str.format), frontend t(key, params) ({nom}).
• Commentaires qui expliquent le pourquoi (contraintes, bug évité, choix non évident), pas le quoi.
• Tests backend : vraie base PostgreSQL (créée par docker/postgres-init), chaque test dans une transaction annulée (savepoints, join_transaction_mode="create_savepoint"), fixtures autouse qui coupent le SMTP et réinitialisent les limiteurs, factories.py pour les données. Un fichier test_<module>.py par module ou router ; tests d'autorisation dédiés (test_authz.py).
• Tests frontend : typecheck + lint + smoke (rendu SSR des écrans avec le mock, et vérifications structurelles quand un bug visuel a déjà eu lieu — ex. positions de grille rendues).
• Migrations numérotées (0001, 0002…), une par étape qui touche le modèle, vérifiées par alembic check.
• Pas de nouvelle dépendance sans raison écrite (commentaire dans pyproject.toml si contrainte de version).

---

7. Commandes types

Action	Commande
Tout lancer avec la démo	make demo
Instance vierge	make blank EMAIL=… PASSWORD=… NAME=…
Dev	docker compose up --build (API : http://localhost:8000/docs, front : http://localhost:5173)
Tests backend	docker compose run --rm backend uv run pytest
Lint / format	docker compose run --rm backend uv run ruff check . / ruff format .
Migration	docker compose run --rm backend uv run alembic revision --autogenerate -m "…"
Appliquer / vérifier	… alembic upgrade head puis … alembic check
Front	npm run typecheck && npm run lint && npm run smoke

---

8. Méthode de travail avec Claude

1. Étape 1 — squelette : monorepo, Docker Compose, backend qui démarre (/health), frontend vide, CI/CD, CLAUDE.md initial avec glossaire.
2. Étape 2 — modèle de données complet + migration initiale.
3. Ensuite : import des données existantes (analyse puis exécution, mode simulation, rapport ligne par ligne, détection de doublons), CRUD, cœur métier en TDD, seed de démo, authentification, puis fonctionnalités une par une.
4. À chaque étape : code + tests + migration + mise à jour du CLAUDE.md (modèle, règles, journal) + front (mock compris) → montrer le résultat → attendre la validation → commit atomique en français.
5. Revues de sécurité régulières avant toute ouverture au public, notées comme étapes à part entière.