backend-fastapi

name: backend-fastapi description: "OBLIGATOIRE pour: tout travail dans /Users/happi/App/API/FASTAPI/ — endpoints FastAPI, modèles SQLAlchemy, migrations Alembic, schémas Pydantic, requirements.txt, debug API prod. Déclencheurs: backend, API Python, migration, alembic, endpoint, SQLAlchemy, PostgreSQL, Docker audace_api. NE PAS utiliser pour: appeler l'API depuis le frontend (clients Axios = module-development)."

Backend FastAPI — RadioManager

PRIMARY RESPONSIBILITY

Règles de développement du repo backend séparé (/Users/happi/App/API/FASTAPI/) : environnement venv, imports, SQLAlchemy, migrations Alembic, dépendances, checklist pré-push.

USE THIS SKILL WHEN

On crée/modifie un endpoint, un modèle, un schéma Pydantic, une permission backend.
Une migration de base de données est nécessaire.
On débogue l'API en production (conteneur Docker audace_api).
On ajoute une dépendance Python.

DO NOT USE THIS SKILL WHEN

On consomme l'API depuis le frontend React (clients api/, hooks → skill module-development).
On cherche seulement la liste des routes (→ docs/reference/BACKEND_API.md, sans charger ce skill).
On committe le frontend (→ release-version).

TRIGGERS

backend, FastAPI, endpoint, route API, SQLAlchemy, modèle, migration, alembic, Pydantic, requirements.txt, PostgreSQL, audace_api, venv.

OWNED DIRECTORIES

/Users/happi/App/API/FASTAPI/ (repo Git séparé — ne pas y toucher sans demande explicite)

REQUIRED DEPENDENCIES

venv Python 3.11 : /Users/happi/App/API/FASTAPI/venv/bin/{python,pip,alembic} — jamais les binaires globaux
PostgreSQL 16 local (brew), DB fastapi

OPTIONAL DEPENDENCIES

docs/reference/AUTH_SECURITY.md — si le travail touche JWT/refresh/2FA
Mémoire projet api-domain-cloud — domaine prod et déploiement Dokploy

Imports — RÈGLE CRITIQUE

Imports internes avec préfixe app. :

from app.db.database import get_db      # ✅
from db.database import get_db          # ❌ crash en prod (Docker exécute depuis /app/)

Vérifier l'existant avant d'écrire : grep "from app" routeur/emission_route.py | head -5

SQLAlchemy — pièges

back_populates explicite des deux côtés (pas backref).
Index préfixés par module : ix_logistics_vehicle_company, PAS ix_vehicle_company.
FK croisées bidirectionnelles : remote_side=[id] côté "one" (évite "both of the same direction MANYTOONE").
FK circulaires : créer les tables sans les FK, puis op.add_column + op.create_foreign_key.
cascade='all, delete-orphan' uniquement côté parent du one-to-many.

Alembic — INTERDICTION ABSOLUE de migration manuelle

Ne JAMAIS créer/écrire un fichier alembic/versions/*.py à la main ni inventer un revision ID. Seule exception : corriger l'ordre des FK dans une migration autogénérée.

Modifier les modèles (app/models/) ; mettre à jour app/models/__init__.py et les permissions si applicable.
cd /Users/happi/App/API/FASTAPI && venv/bin/alembic revision --autogenerate -m "description"
Vérifier le fichier généré : ordre des tables, noms d'index, FK circulaires.
venv/bin/alembic upgrade head localement.
Committer/pousser — le Dockerfile applique upgrade head au démarrage.
Vérifier en prod : sudo docker logs audace_api --tail 30.

Si Can't locate revision identified by 'xxx' en prod : UPDATE alembic_version SET version_num = '<dernière_révision_valide>'; puis autogénérer.

Dépendances Python

Toute dépendance importée DOIT être dans requirements.txt (manquante = crash prod). Tester dans le venv. Idem pour les imports dans lifespan() de maintest.py.

maintest.py (point d'entrée)

Routes : app.include_router(xxx_route.router). lifespan() : seed data + schedulers.

Checklist pré-push

grep "from db\." routeur/*.py                          # → 0 résultats
venv/bin/python -c "from app.models import *"          # → pas d'erreur
venv/bin/alembic upgrade head                          # → OK localement
grep <nouveau_package> requirements.txt                # → présent