Coltura/CLAUDE.md

Coltura

CRM/ERP. Monorepo Symfony 8 (API Platform 4) + Nuxt 4.

Stack

• Backend : PHP 8.4, Symfony 8.0, API Platform 4, Doctrine ORM, PostgreSQL 16
• Frontend : Nuxt 4 (SSR off / SPA), Vue 3, Pinia, Tailwind CSS, @malio/layer-ui, nuxt-toast, @nuxtjs/i18n, @nuxt/icon
• Auth : JWT HTTP-only cookie (lexik/jwt-authentication-bundle), login a /login_check, cookie BEARER
• Docker : PHP-FPM + Node 24, Nginx (port 8083), PostgreSQL (port 5436)

Structure

src/Entity/          # Entites Doctrine (User)
src/ApiResource/     # Ressources API Platform decouples (AppVersion)
src/State/           # Providers et Processors API Platform (MeProvider, AppVersionProvider, UserPasswordHasherProcessor)
src/Service/         # Services metier
src/Repository/      # Repositories Doctrine
src/DataFixtures/    # Fixtures
config/              # Config Symfony (security, api_platform, lexik_jwt, nelmio_cors, doctrine)
config/jwt/          # Cles JWT (private.pem, public.pem)
migrations/          # Migrations Doctrine
infra/dev/           # Config Docker dev (Dockerfile, nginx, php.ini, xdebug)
infra/prod/          # Config Docker prod (Dockerfile multi-stage, nginx, php-prod.ini)
frontend/            # App Nuxt 4
frontend/pages/      # Pages (index, login)
frontend/layouts/    # Layouts (default)
frontend/components/ # Composants Vue
frontend/composables/# Composables (useApi, useAppVersion)
frontend/stores/     # Stores Pinia (auth, ui)
frontend/services/   # Services API (auth)
frontend/services/dto/ # Types TypeScript
frontend/i18n/locales/ # Fichiers de traduction

Commandes

make start           # Demarrer les containers
make stop            # Arreter les containers
make restart         # Redemarrer les containers
make install         # Install complet (composer, migrations, fixtures, build Nuxt)
make reset           # Tout supprimer et reinstaller (supprime la BDD)
make dev-nuxt        # Dev server Nuxt (hot reload, port 3003)
make shell           # Shell dans le container PHP
make shell-root      # Shell root dans le container PHP
make cache-clear     # Vider le cache Symfony
make migration-migrate # Lancer les migrations
make fixtures        # Charger les fixtures
make db-reset        # Reset BDD + migrations + fixtures
make test            # PHPUnit
make php-cs-fixer-allow-risky # Fix code style PHP
make logs-dev        # Tail logs Symfony

Conventions

Commits

Format : <type>(<scope optionnel>) : <message> (espace avant et apres :)

Types autorises (minuscules) : build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test

Exemples : feat : add login page, fix(auth) : prevent null token crash

Tags & Versioning

• La version de l'app est dans config/version.yaml (parametre app.version)
• A chaque creation de tag, toujours mettre a jour config/version.yaml avec la meme version
• Faire un commit separe de bump : chore : bump version to v<X.Y.Z>
• Puis creer le tag et pusher : git tag v<X.Y.Z> && git push origin develop --tags

Backend

• Toujours declare(strict_types=1) en haut des fichiers PHP
• API Platform : utiliser ApiResource, Providers (src/State/), Processors — pas de controllers
• Routes API prefixees /api (via config/routes/api_platform.yaml)
• Le login (/login_check) est hors prefix /api, nginx reecrit REQUEST_URI vers /login_check
• PHP CS Fixer : regles Symfony + PSR-12 + strict types
• Roles : ROLE_ADMIN, ROLE_USER — hierarchie dans security.yaml
• PostgreSQL : noms de colonnes toujours en minuscules dans le SQL brut
• Controllers custom sous /api/ : ajouter priority: 1 sur #[Route] pour eviter le conflit avec API Platform {id}
• Serialization : pour embarquer une relation (pas IRI), ajouter le groupe du parent aux proprietes de l'entite cible
• Upload fichiers : utiliser $file->getMimeType() (pas getClientMimeType()) pour valider cote serveur

Frontend

• TypeScript strict
• Composable useApi() pour tous les appels API (gere cookies, erreurs, toasts, i18n)
• Stores Pinia : useAuthStore (auth), useUiStore (ui)
• Middleware global auth.global.ts protege les routes
• Traductions dans frontend/i18n/locales/
• 4 espaces d'indentation

Nginx

• /api/* -> Symfony (via try_files + index.php)
• /api/login_check -> location exact match, fastcgi direct avec REQUEST_URI reecrit en /login_check
• / -> SPA frontend (frontend/dist/)

Docker

• Container PHP : php-coltura-fpm
• Container Nginx : nginx-coltura
• Container DB : PostgreSQL sur port 5436 (interne et externe)
• Config Docker dev : infra/dev/.env.docker (override local : infra/dev/.env.docker.local)
• Config Docker prod : infra/prod/ (Dockerfile multi-stage, docker-compose.prod.yml)
• Apres modif nginx : docker restart nginx-coltura

Fixtures

• User admin : admin / admin (ROLE_ADMIN)
• Users internes : alice / alice, bob / bob (ROLE_USER)