band-hub

Imported from Ezekiel056/band-hub (AGENTS.md). Install upstream with npx skills add Ezekiel056/band-hub. Copyright stays with the author.

Guide des agents — BandHub

Portée et objectif

Ces instructions s'appliquent à tout le dépôt. BandHub est une application web de gestion de groupes de musique : répertoire, morceaux, pistes d'accompagnement, setlists, membres et avis.

• Conserver l'interface et les messages utilisateur en français.
• Préserver les modifications déjà présentes dans le dépôt ; ne pas reformater ni refactoriser des fichiers hors du périmètre demandé.
• Chercher la cause d'un problème avant de modifier le code, puis limiter le changement au strict nécessaire.

Stack et structure

• docker-compose.yaml : environnement de référence (Apache/PHP 8.4, MySQL 8, MongoDB, Mailpit, phpMyAdmin et DbGate).
• app/ : racine de l'application Symfony 8.
• app/src/Entity/ et app/src/Repository/ : modèle principal Doctrine ORM stocké dans MySQL.
• app/src/Document/Review.php et ReviewRepository : avis stockés séparément dans MongoDB via Doctrine ODM.
• app/src/Controller/App/ : contrôleurs métier destinés à l'espace authentifié. Ils héritent normalement de AppController.
• app/src/Form/, Service/, Security/, EventListener/ et EventSubscriber/ : formulaires, logique applicative et sécurité.
• app/templates/ : vues Twig ; app/assets/ : CSS, JavaScript et contrôleurs Stimulus.
• app/migrations/ : migrations Doctrine ; app/tests/TestCase/ : tests unitaires ; app/tests/WebTestCase/ : tests fonctionnels.
• database/merise/ : documents de modélisation. Les données MySQL/MongoDB locales ne font pas partie du code source.

Le front utilise Twig, Turbo, Stimulus, AssetMapper/Importmap et Tailwind CSS 4. Il n'y a pas de chaîne de bundling JavaScript Node classique.

Environnement de développement

Exécuter les commandes d'infrastructure depuis la racine du dépôt. app/.env.local contient la configuration Docker locale et ne doit jamais être commité ni affiché dans les logs.

make docker-up-build
docker compose --env-file app/.env.local exec php composer install
make migrate

Services locaux par défaut : application sur http://localhost:8080, phpMyAdmin sur http://localhost:8081, Mailpit sur http://localhost:8025 et DbGate sur le port DBGATE_PORT (8082 par défaut).

Commandes courantes :

make docker-up          # démarrer les conteneurs
make docker-down        # les arrêter sans supprimer les volumes
make bash               # shell dans le conteneur PHP
make migration          # générer une migration après un changement d'entité
make migrate            # appliquer les migrations
make fixtures           # recharge les fixtures ; destructif pour la base ciblée
make tailwind           # compilation Tailwind en mode watch

Le conteneur PHP est l'environnement de référence, notamment parce qu'il fournit l'extension MongoDB. Une commande bin/console locale peut échouer si cette extension n'est pas installée.

Règles métier et sécurité

L'application est multi-groupe. Le groupe courant est stocké en session sous current_band_id et résolu par CurrentBandResolver.

• Toute lecture ou mutation d'une ressource appartenant à un groupe doit être filtrée par le groupe courant.
• Ne jamais faire confiance à un identifiant de route seul. Utiliser les voters (SongVoter, SetlistVoter) ou ajouter une autorisation équivalente avant toute lecture, modification, suppression ou diffusion de média.
• Les requêtes de repository portant sur des données de groupe doivent accepter un Band et inclure explicitement ce filtre.
• Les routes app_* nécessitent par défaut un groupe courant via RequireBandListener. Toute nouvelle exclusion doit être justifiée et ajoutée à config/packages/band_context.yaml.
• L'authentification protège /app avec ROLE_USER. Les rôles spécifiques au groupe sont portés par BandMember, pas uniquement par l'utilisateur global.
• Placer toute nouvelle route authentifiée sous /app/... ou lui appliquer explicitement un contrôle équivalent : le dossier PHP et le nom de route ne suffisent pas à déclencher la règle access_control.
• Les fichiers audio sont privés dans var/uploads/backingtracks/ et servis par MediaController après contrôle d'accès. Ne pas les déplacer dans public/ ni exposer directement leur chemin.
• Les images d'artistes sont publiques dans public/uploads/artists/. Passer par les services d'upload existants et valider type, taille et nom de fichier.

Conventions d'implémentation

PHP et Symfony

• Respecter PSR-4 (App\ dans app/src/) et l'indentation de 4 espaces définie par app/.editorconfig.
• Utiliser l'injection de dépendances et l'autowiring ; éviter de récupérer des services globalement.
• Déclarer les routes avec les attributs #[Route], leurs méthodes HTTP et, si nécessaire, une contrainte numérique sur les identifiants.
• Pour les pages authentifiées, étendre AppController afin de fournir currentBand et selectedTab aux vues.
• Utiliser AppMenuTabs dans l'option de route selected_tab pour synchroniser la navigation.
• Garder la logique métier réutilisable dans un service ou un repository, pas dans Twig ni dans un contrôleur volumineux.
• Utiliser les Form Types et les contraintes Validator pour les entrées utilisateur. Conserver la protection CSRF sur toute mutation issue d'un formulaire.
• Après une modification du modèle ORM, générer une nouvelle migration et la relire. Ne pas réécrire une migration déjà partagée sauf demande explicite.
• Maintenir les deux côtés des associations Doctrine lorsque l'entité fournit des méthodes add*/remove*.

Twig, Stimulus et styles

• Respecter l'indentation de 2 espaces pour Twig, JavaScript, YAML et CSS.
• Réutiliser les layouts, composants et partials présents dans templates/app/components/ avant d'introduire une nouvelle variante.
• Garder les contrôleurs Stimulus petits et pilotés par data-controller, data-action, targets et values.
• Ajouter les dépendances JavaScript gérées par AssetMapper dans app/importmap.php; ne pas introduire un bundler sans besoin explicite.
• Modifier les sources dans app/assets/styles/, puis reconstruire Tailwind. app/var/tailwind/app.built.css est un artefact généré mais suivi par Git : l'inclure lorsqu'un changement CSS modifie sa sortie.
• Conserver les flux Turbo/frames existants. Les réponses de modales utilisent notamment AppController::TurboRefreshRoute().

Persistance

• Utiliser Doctrine ORM/MySQL pour les entités du domaine et Doctrine ODM/MongoDB uniquement pour les documents sous src/Document/.
• Ne pas mélanger EntityManagerInterface et DocumentManager dans un repository ou une opération sans raison métier explicite.
• Éviter les requêtes N+1 sur les pages de listes ; utiliser les repositories pour les jointures, filtres et agrégations.

Tests et validation

Ajouter ou adapter un test pour tout changement de comportement :

• test unitaire dans app/tests/TestCase/ pour services, voters, subscribers et logique isolée ;
• test fonctionnel dans app/tests/WebTestCase/ pour routes, sécurité, formulaires et rendu HTML ;
• les tests fonctionnels chargent AppFixtures avec LiipTestFixturesBundle et modifient la base de test.

Depuis la racine, avec Docker démarré :

make run-tests-unit
make run-tests-fonctionnal
make run-tests

Attention : make test génère un squelette de test Symfony ; cette cible n'exécute pas les tests.

Pour cibler rapidement un test :

docker compose --env-file app/.env.local exec php bin/phpunit tests/TestCase/Security/Voter/SongVoterTest.php
docker compose --env-file app/.env.local exec php bin/phpunit --filter testName

Avant de terminer, exécuter au minimum les tests les plus proches du changement. Pour un changement transversal, exécuter toute la suite. Contrôles complémentaires utiles dans le conteneur :

composer validate --no-check-publish
find src tests -name '*.php' -print0 | xargs -0 -n1 php -l
php bin/console lint:twig templates
php bin/console lint:yaml config
php bin/console lint:container

Pour les tests fonctionnels, vérifier que MySQL et MongoDB sont disponibles et que l'environnement test pointe vers des bases dédiées. Ne jamais lancer les fixtures sur une base contenant des données à conserver.

Fichiers à ne pas modifier manuellement

• app/vendor/, node_modules/, app/var/cache/ et app/public/assets/ sont générés.
• database/mysql/, database/mongodb/, app/public/uploads/ et les fichiers audio locaux sont des données d'exécution.
• Les fichiers .env.local et .env.*.local sont propres à la machine et peuvent contenir des secrets.
• composer.lock et package-lock.json ne doivent changer que lorsqu'une dépendance change intentionnellement.

Dans le compte rendu final, indiquer les fichiers modifiés, les migrations éventuelles, les tests exécutés et toute vérification impossible à réaliser localement.