docs : update CLAUDE.md with custom controllers, fields architecture and factories

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

CLAUDE.md

@@ -99,7 +99,7 @@ Le frontend est un submodule git. Lors d'un commit frontend :
 ## Architecture Backend
 
 ### Entités Principales
-`Machine`, `Piece`, `Composant`, `Product`, `Constructeur`, `Site`, `TypeMachine`, `ModelType`, `CustomField`, `CustomFieldValue`, `Document`, `AuditLog`, `Comment`, `Profile`
+`Machine`, `Piece`, `Composant`, `Product`, `Constructeur`, `Site`, `ModelType`, `CustomField`, `CustomFieldValue`, `Document`, `AuditLog`, `Comment`, `Profile`, `MachineComponentLink`, `MachinePieceLink`, `MachineProductLink`
 
 ### Patterns
 - **IDs** : CUID-like strings (`'cl' + bin2hex(random_bytes(12))`), pas d'auto-increment
@@ -109,6 +109,16 @@ Le frontend est un submodule git. Lors d'un commit frontend :
 - **Audit** : Subscribers Doctrine `onFlush` capturent diff + snapshot complet
 - **Migrations** : Raw SQL PostgreSQL avec `IF NOT EXISTS`/`IF EXISTS` pour idempotence
 
+### Custom Controllers (pas API Platform)
+- `MachineStructureController` — `/api/machines/{id}/structure` (GET/PATCH) : hiérarchie complète machine avec normalisation JSON manuelle (pas Symfony Serializer). Source principale de données pour la page détail machine.
+- `MachineCustomFieldsController` — `/api/machines/{id}/add-custom-fields` (POST) : initialise les CustomFieldValue manquants pour une machine.
+- `CustomFieldValueController` — `/api/custom-fields/values/*` : CRUD + upsert pour les valeurs de champs perso.
+
+### Custom Fields — Architecture
+- **Composants/Pièces/Produits** : définitions dans le JSON `structure` du ModelType
+- **Machines** : définitions = entités `CustomField` liées directement via `machineId` FK (pas de ModelType)
+- Les deux partagent la même entité `CustomFieldValue` pour stocker les valeurs
+
 ### Rôles (hiérarchie)
 ```
 ROLE_ADMIN → ROLE_GESTIONNAIRE → ROLE_VIEWER → ROLE_USER
@@ -175,16 +185,15 @@ Quand les branches `master` et `develop` divergent sur l'un des deux repos, **to
 - Base de test : même PG, env `test`
 
 ### Commandes
+Voir section "Key Commands". Commande additionnelle :
 ```bash
-make test                     # Tous les tests
-make test FILES=tests/Api/Entity/MachineTest.php   # Un fichier spécifique
 make test-setup               # Créer/mettre à jour le schéma test
 ```
 
 ### Pattern de test
 - Hériter de `AbstractApiTestCase` (helpers auth + factories)
 - Ne PAS faire de TRUNCATE/cleanup dans tearDown — DAMA s'en occupe par rollback
-- Factories : `createProfile()`, `createMachine()`, `createSite()`, etc.
+- Factories : `createProfile()`, `createMachine()`, `createSite()`, `createComposant()`, `createPiece()`, `createProduct()`, `createCustomField()`, `createCustomFieldValue()`, `createModelType()`, `createMachineComponentLink()`, `createMachinePieceLink()`, `createMachineProductLink()`
 - Auth : `createViewerClient()`, `createGestionnaireClient()`, `createAdminClient()`
 
 ## URLs Locales