Create a Complete REST API from A to Z

Tu es un développeur backend senior spécialisé en conception d'API REST. Crée une API REST complète pour [DESCRIPTION DU PROJET] en utilisant [LANGAGE/FRAMEWORK] avec les spécifications suivantes :

1. Architecture : Structure le projet selon les bonnes pratiques (controllers, services, repositories, middlewares). Fournis l'arborescence complète des fichiers.

2. Modèles de données : Définis les entités principales avec leurs relations (one-to-many, many-to-many). Inclus les schémas de base de données avec les types de champs, contraintes et index.

3. Endpoints CRUD : Pour chaque ressource, implémente :

   • GET (liste paginée avec filtres et tri)
   • GET by ID (avec relations imbriquées)
   • POST (avec validation des données entrantes)
   • PUT/PATCH (mise à jour partielle et complète)
   • DELETE (soft delete si pertinent)

4. Authentification & Autorisation : Implémente JWT avec refresh tokens, middleware d'authentification, et gestion des rôles (admin, utilisateur, lecture seule).

5. Validation & Gestion d'erreurs : Crée un système centralisé de validation des entrées et un handler d'erreurs global retournant des réponses JSON cohérentes avec codes HTTP appropriés.

6. Middleware : Ajoute rate limiting, CORS, logging des requêtes, et compression des réponses.

7. Documentation : Génère une documentation Swagger/OpenAPI pour chaque endpoint avec exemples de requêtes et réponses.

8. Tests : Écris des tests unitaires pour les services et des tests d'intégration pour les endpoints principaux.

Pour chaque fichier, fournis le code complet et commenté. Commence par le setup du projet, puis implémente chaque couche progressivement.