Inventory/CLAUDE.md

CLAUDE.md — Inventory Project

Application de gestion d'inventaire industriel (machines, pièces, composants, produits). Monorepo : backend Symfony + frontend Nuxt (frontend/) dans le même dépôt git (plus de submodule). Un seul commit/push couvre backend + frontend.

Stack

Layer	Tech	Version
Backend	Symfony + API Platform	8.0 / ^4.2
PHP	PHP	>=8.4
Database	PostgreSQL	16
Frontend	Nuxt (SPA, SSR off)	4
UI	Vue 3 Composition API + TypeScript	3.5 / 5.7
CSS	TailwindCSS 4 + DaisyUI 5
Auth	Session-based (cookies, pas JWT)
Containers	Docker Compose

Documentation détaillée (lire à la demande, ne pas dupliquer ici)

Vu la complexité du projet, le détail vit dans docs/ — y aller plutôt que de deviner :

• docs/FONCTIONNEMENT.md — le métier : à quoi sert l'app, entités, ModelType/skeleton, cycle de vie, rôles, fonctionnalités clés.
• docs/GLOSSAIRE_METIER.md — glossaire complet, correspondance métier ↔ code (le « pourquoi »).
• docs/BACKEND.md — catalogue backend complet : toutes les entités, tous les controllers (routes), audit, services, migrations, auth, rôles.
• docs/FRONTEND.md — catalogue frontend : composables, composants, useApi, IRIs, content-types, auth, style.
• docs/REVIEW_ARCHITECTURE.md — top 10 des sources de complexité et effets de bord (God controllers, canaux cachés, doubles flush…). À consulter avant tout refacto.

Project Structure

Inventory/                      # Backend Symfony (repo principal)
├── src/Entity/ (+ Trait/)      # Entités Doctrine (attributs PHP 8), CuidEntityTrait
├── src/Controller/             # Controllers custom (session, comments, audit, structure…)
├── src/EventSubscriber/        # Audit (onFlush) + sync/contraintes
├── src/Service/ (+ Sync/)      # Services métier (sync, conversion, storage, versions…)
├── src/Enum/ src/DTO/ src/Filter/ src/Command/
├── config/ migrations/ docker/ scripts/ fixtures/ tests/
├── makefile  VERSION           # VERSION = source unique de version (semver)
└── frontend/                   # ← Frontend Nuxt (MÊME repo, pas un submodule)
    └── app/{pages,components,composables,shared,middleware,services}/

Key Commands

# Docker
make start / make stop          # Démarrer / arrêter les containers
make shell                      # Shell interactif (nécessite un TTY)
make install                    # Install complet (composer + npm + build)

# Backend
make test                       # PHPUnit (tous)
make test FILES=tests/Api/Entity/MachineTest.php   # Un test
make test-setup                 # Créer/MAJ le schéma de test
make php-cs-fixer-allow-risky   # Linter PHP
docker exec -u www-data php-inventory-apache php bin/console doctrine:migrations:migrate

# Frontend (dans frontend/)
npm run dev                     # Dev server (port 3001)
npm run lint:fix                # ESLint fix
npx nuxi typecheck              # TypeScript check (0 erreur attendu)

# Database / Fixtures
make db-reset                   # Reset DB (drop + recreate schema)
make fixtures-reset             # Reset DB + recharger fixtures SQL
make import-data                # Importer les dumps SQL normalisés
make cache-clear

# Import fournisseurs (non destructif : find-or-create par nom normalisé)
docker exec -u www-data php-inventory-apache php bin/console app:import-fournisseurs          # dry-run
docker exec -u www-data php-inventory-apache php bin/console app:import-fournisseurs --force  # applique

# Release
./scripts/release.sh patch      # Bump version (patch/minor/major)

Git Conventions

• Branches : master (prod), develop (cible des PR), feat/* fix/* refactor/*.
• Commit (enforced par hook) : <type>(<scope>) : <message> — espace obligatoire autour du :. Types : build chore ci docs feat fix perf refactor revert style test wip.
  • Ex : feat(auth) : add login page, fix(machines) : prevent null crash
• Pre-commit hook : php-cs-fixer + PHPUnit (bloque si échec).
• Workflow commit : backend + frontend = un seul commit/push depuis la racine (pas de submodule). Le hook étant lent, committer avec git commit --no-verify. Push rejeté → git pull --rebase puis git push.
• Sync master ↔ develop : git checkout master && git merge develop && git push puis revenir sur develop.

Pièges & patterns non-évidents

Le catalogue complet est dans docs/BACKEND.md / docs/FRONTEND.md. Ci-dessous uniquement ce qui n'est pas évident en lisant le code.

Backend

• IDs CUID : strings 'cl' + bin2hex(random_bytes(12)), pas d'auto-increment.
• Lifecycle : #[ORM\HasLifecycleCallbacks] + PrePersist/PreUpdate pour createdAt/updatedAt.
• Sécurité : security: "is_granted('ROLE_...')" sur chaque opération API Platform. Hiérarchie : ROLE_ADMIN → ROLE_GESTIONNAIRE → ROLE_VIEWER → ROLE_USER.
• Audit : subscribers Doctrine onFlush (diff + snapshot complet).
• Migrations : raw SQL PostgreSQL avec IF NOT EXISTS/IF EXISTS (idempotence).
• Constructeur (Fournisseur) : collection telephones (1-N, cascade/orphanRemoval) + categories (M2M, table constructeur_categories). ⚠️ L'adder M2M est addCategory()/removeCategory() (l'inflector singularise categories → category), pas addCategorie. Groupes API constructeur:read / constructeur:write.
• Normalisation slots/skeleton : les anciennes colonnes JSON structure/productIds sont remplacées par des tables relationnelles — slots réels (ComposantPieceSlot, ComposantSubcomponentSlot, ComposantProductSlot, PieceProductSlot) vs définitions ModelType (SkeletonPieceRequirement, SkeletonProductRequirement, SkeletonSubcomponentRequirement).
• Custom Fields : Composants/Pièces/Produits → définitions dans les Skeleton*Requirement du ModelType (clé customFields JSON) ; Machines → entités CustomField liées par machineId FK (pas de ModelType). Les deux partagent l'entité CustomFieldValue pour les valeurs.
• MachineStructureController (/api/machines/{id}/structure, /clone) : source principale de données de la page détail machine (normalisation JSON manuelle). Cf. REVIEW_ARCHITECTURE.md (God controller).

PostgreSQL — ATTENTION

• Noms de colonnes TOUJOURS EN MINUSCULES en PG. Doctrine camelCase (typePieceId) → PG typepieceid. Le SQL brut doit être lowercase.
• Tables de jointure M2M : colonnes a et b (ex : _piececonstructeurs).

Frontend

• Composables : interface Deps { ... } + export function useXxx(deps: Deps).
• Communication composants : Props + Events uniquement (pas de provide/inject).
• API : useApi.ts wrappe fetch avec credentials: 'include'. ⚠️ useApi() préfixe déjà /api → appeler sans /api au début. Ex : api.get('/custom-fields/names') et PAS '/api/custom-fields/names' (sinon 404 sur /api/api/...).
• Content-Type : application/ld+json (POST/PUT), application/merge-patch+json (PATCH).
• Auth : useProfileSession + middleware global profile.global.ts. Permissions : usePermissions.ts (miroir de la hiérarchie backend).
• Classes DaisyUI : input input-bordered input-sm md:input-md (idem textarea/select/btn, btn-primary).

Règles Importantes

Avant de modifier du code

1. Lire le fichier avant de l'éditer.
2. Reproduire le pattern existant (noms, indentation, structure).
3. Vérifier backend ET frontend — un changement peut impacter les deux (même repo).

Après chaque modification

1. Backend PHP : make php-cs-fixer-allow-risky
2. Frontend TS : npm run lint:fix puis npx nuxi typecheck

Ne jamais faire

• Features non demandées, code mort, abstractions prématurées
• provide/inject (le code utilise Props + Events) · JWT/tokens (auth session-based)
• SQL en camelCase (PG = lowercase)
• Committer sans demande explicite · force push sans confirmation · modifier la config git

Maintenir ce fichier

Mettre à jour quand une nouvelle convention/pattern/décision archi est établie. Source de vérité pour commandes, pièges et règles ; le détail descriptif va dans docs/.

Tests

• PHPUnit 12 + API Platform Test (ApiTestCase), env test, même PG.
• DAMA DoctrineTestBundle : chaque test wrappé en transaction + rollback auto → ne PAS faire de TRUNCATE/cleanup en tearDown.
• Hériter de AbstractApiTestCase (helpers auth + factories create*()).
• Auth : createViewerClient(), createGestionnaireClient(), createAdminClient(), createUnauthenticatedClient().

URLs Locales

• API Symfony : http://localhost:8081/api · Nuxt dev : http://localhost:3001
• Adminer : http://localhost:5050 · PG direct : localhost:5433 (user/pass root, db inventory)

Délégation Codex

Pour les tâches mécaniques (tests, boilerplate, renommages, refacto répétitif), déléguer à Codex via le plugin codex (junior rapide/pas cher). Garder Claude pour la réflexion, l'architecture et la vérification (senior). Meilleur ratio qualité/crédits.