# Consignes de développement du coeur VitiCore

Toujours répondre en français.

Ce fichier complète `AGENTS.md` lorsque la demande porte explicitement sur le développement du coeur VitiCore. Pour une personnalisation d'un projet hôte, rester sur les règles d'utilisation et ne pas modifier le coeur.

## Périmètre

- Travailler dans le coeur uniquement si la demande mentionne VitiCore, le bundle, une fonctionnalité partagée ou une correction à porter dans tous les projets.
- Garder les changements compatibles avec les projets hôtes.
- Ne pas déplacer de logique projet spécifique dans le coeur.
- Respecter les conventions existantes avant d'ajouter une abstraction.

## Commandes

Quand le coeur est utilisé dans un projet hôte avec `docker-compose.yml`, lancer les commandes depuis le conteneur applicatif du projet hôte, généralement `php`.

Exemples :

```bash
docker compose exec php php -l vendor/cpcreation/viti-core/src/Bridge/Symfony/Bundle/Twig/Components/Shop/ProductCard.php
docker compose exec php php bin/console lint:container
docker compose exec php php bin/console lint:twig vendor/cpcreation/viti-core/src/Bridge/Symfony/Bundle/Resources/views
docker compose exec php php bin/console cache:warmup --env=dev
docker compose exec php php vendor/bin/php-cs-fixer fix --dry-run --diff
```

## Migrations

- Les migrations du coeur doivent être placées dans `src/Bridge/Doctrine/Migrations`.
- Leur namespace doit être `CpCreation\VitiCore\Bridge\Doctrine\Migrations`.
- Ne pas créer de migration VitiCore dans le dossier `migrations/` du projet hôte.
- Les migrations liées au projet hôte, et non au coeur VitiCore, doivent être placées dans `src/Migrations`.
- Après une migration, vérifier son application via `doctrine:migrations:status` ou une requête ciblée sur `doctrine_migration_versions`.

## Administration

- Garder les libellés admin en français.
- Eviter les validations qui remontent une erreur SQL brute ; préférer des contraintes Symfony explicites.
- Pour les formulaires à collections imbriquées, vérifier l'affichage des erreurs pour éviter les doublons.
- Pour les champs ordonnés, garder une donnée persistée claire, généralement `position`, et une UI qui permet de modifier cette valeur directement.

## Composants

- Pour un comportement commun à plusieurs LiveComponents, préférer un trait ou un service partagé plutôt qu'une duplication.
- Les LiveComponents VitiCore doivent conserver `template` comme `LiveProp` quand ils supportent une vue personnalisée par instance.
- Tout composant Twig ou UX basé sur une collection VitiCore doit utiliser une prop explicite `collection`, contenant le code administrable de la collection.
- Le `code` d'une collection est saisi à la main dans l'admin ; ne pas le générer automatiquement.

## Infrastructure de thèmes surchargeables

- Toute fonctionnalité partagée destinée à un thème réutilisable doit conserver une interface de surcharge étroite et stable. Le projet hôte doit pouvoir modifier une zone courante sans recopier le template complet.
- Utiliser des blocs Twig sémantiques pour les zones de markup qui varient réellement, des props ou composants pour les modules réutilisables, et la configuration, les traductions ou les données administrables pour les valeurs simples.
- Ne pas multiplier les blocs atomiques. Les noms de blocs, props et templates surchargeables constituent une interface publique et ne doivent pas être renommés sans stratégie de compatibilité.
- Un bloc placé dans un template chargé avec `include` ne peut pas être redéfini depuis le template parent. Lorsqu'un projet doit étendre partiellement un partial du thème actif, cette capacité appartient à `cpcreation/viti-theme-bundle`, qui doit exposer le template original sous le namespace stable `@viti_theme`.
- `@viti_theme` doit contourner les templates du projet hôte afin d'éviter qu'une surcharge étende son propre chemin et entre en récursion. La résolution Twig non nommée conserve la priorité projet, thème actif, puis thème par défaut.
- Vérifier le contrat avec `debug:twig` et un rendu réel : créer une surcharge projet minimale qui étend `@viti_theme/...`, redéfinit un bloc, appelle `parent()`, puis confirmer le HTML obtenu.
- Implémenter l'infrastructure de résolution dans la source de `viti-theme-bundle`, jamais dans `vendor/` ni par un chemin absolu propre à un projet.

## Qualité

Avant de terminer une modification du coeur, vérifier au minimum ce qui est concerné :

```bash
docker compose exec php php -l <fichier.php>
docker compose exec php php bin/console lint:container
docker compose exec php php bin/console doctrine:schema:validate --skip-sync
docker compose exec php php bin/console cache:warmup --env=dev
docker compose exec php php vendor/bin/php-cs-fixer fix --dry-run --diff
```

Avant de lancer PHPStan avec `phpstan/phpstan-symfony`, vérifier que le container XML Symfony référencé par `phpstan.neon` existe. Si l'erreur indique que `var/cache/dev/App_KernelDevDebugContainer.xml` est absent, réchauffer le cache dev dans le conteneur applicatif avant PHPStan :

```bash
docker compose exec php php bin/console cache:warmup --env=dev
docker compose exec php php vendor/bin/phpstan analyse -c phpstan.neon
```

Pour les templates :

```bash
docker compose exec php php bin/console lint:twig vendor/cpcreation/viti-core/src/Bridge/Symfony/Bundle/Resources/views
```
