# Guide Backend — Inventory

Guide complet du backend Symfony pour comprendre comment tout fonctionne, même si tu débutes.

## Table des matières

1. [Vue d'ensemble](#vue-densemble)
2. [Comment fonctionne une API REST](#comment-fonctionne-une-api-rest)
3. [Symfony + API Platform — les bases](#symfony--api-platform--les-bases)
4. [Les Entités (les modèles de données)](#les-entités)
5. [Les Controllers (les endpoints personnalisés)](#les-controllers)
6. [Le système d'audit](#le-système-daudit)
7. [L'authentification par session](#lauthentification-par-session)
8. [Les services](#les-services)
9. [Les migrations de base de données](#les-migrations)
10. [Les tests](#les-tests)
11. [Flux complet d'une requête](#flux-complet-dune-requête)
12. [Commandes Symfony utiles](#commandes-symfony-utiles)

---

## Vue d'ensemble

Le backend est une **API REST** construite avec :

- **Symfony 8** : le framework PHP (gère le routing, la sécurité, la config, etc.)
- **API Platform 4.2** : une surcouche qui génère automatiquement les endpoints CRUD à partir des entités
- **Doctrine ORM** : fait le lien entre les objets PHP et les tables PostgreSQL
- **PostgreSQL 16** : la base de données relationnelle

### Le principe

Au lieu d'écrire manuellement chaque endpoint (GET /machines, POST /machines, etc.), **API Platform** les génère automatiquement à partir des entités PHP. Tu déclares tes champs, tes relations, tes règles de sécurité directement sur la classe PHP, et API Platform fait le reste.

---

## Comment fonctionne une API REST

### C'est quoi une API REST ?

Une API REST c'est un serveur qui répond à des requêtes HTTP (comme un site web, mais au lieu de renvoyer du HTML, il renvoie du JSON).

### Les verbes HTTP

| Verbe | Action | Exemple |
|-------|--------|---------|
| `GET` | Lire des données | `GET /api/machines` → liste toutes les machines |
| `POST` | Créer une donnée | `POST /api/machines` + body JSON → crée une machine |
| `PUT` | Remplacer une donnée | `PUT /api/machines/123` + body JSON → remplace la machine 123 |
| `PATCH` | Modifier partiellement | `PATCH /api/machines/123` + body JSON → modifie certains champs |
| `DELETE` | Supprimer | `DELETE /api/machines/123` → supprime la machine 123 |

### Les codes de réponse HTTP

| Code | Signification | Quand |
|------|---------------|-------|
| `200` | OK | Requête réussie |
| `201` | Created | Ressource créée avec succès (POST) |
| `204` | No Content | Suppression réussie (DELETE) |
| `400` | Bad Request | Données invalides envoyées |
| `401` | Unauthorized | Pas connecté / session expirée |
| `403` | Forbidden | Connecté mais pas les permissions |
| `404` | Not Found | La ressource n'existe pas |
| `409` | Conflict | Doublon (ex: nom déjà pris) |
| `500` | Server Error | Bug côté serveur |

### Le format JSON-LD

L'API utilise **JSON-LD** (JSON Linked Data), une extension de JSON qui ajoute des métadonnées :

```json
{
  "@context": "/api/contexts/Machine",
  "@id": "/api/machines/cl1a2b3c4d5e6f7g8h9i0j1k",
  "@type": "Machine",
  "id": "cl1a2b3c4d5e6f7g8h9i0j1k",
  "name": "CNC Mazak 01",
  "reference": "CNM-001",
  "prix": "50000.00",
  "site": "/api/sites/cl9z8y7x6w5v4u3t2s1r0q",
  "createdAt": "2026-01-15T10:30:00+00:00"
}
```

Points importants :
- `@id` est l'**IRI** (Internationalized Resource Identifier) : c'est l'identifiant unique de la ressource dans l'API
- Les relations utilisent des IRIs : `"site": "/api/sites/cl9z8..."` au lieu d'un simple ID
- Les collections retournent un format hydra avec pagination :

```json
{
  "@context": "/api/contexts/Machine",
  "@id": "/api/machines",
  "@type": "hydra:Collection",
  "hydra:totalItems": 42,
  "hydra:member": [
    { "@id": "/api/machines/cl...", "name": "CNC 01", ... },
    { "@id": "/api/machines/cl...", "name": "Tour 02", ... }
  ]
}
```

---

## Symfony + API Platform — les bases

### La structure des fichiers

```
src/
├── Entity/          # Les classes PHP qui représentent les tables de la BDD
├── Controller/      # Les endpoints HTTP personnalisés (quand API Platform ne suffit pas)
├── EventSubscriber/ # Du code qui s'exécute automatiquement quand quelque chose se passe
├── Repository/      # Les requêtes SQL personnalisées
├── Service/         # La logique métier réutilisable
├── State/           # Les processeurs API Platform (interceptent le flux CRUD)
├── Security/        # L'authentification
├── Serializer/      # Personnalisation de la conversion entité ↔ JSON
├── Command/         # Commandes CLI (php bin/console app:xxx)
├── Enum/            # Les énumérations PHP (ex: catégories)
└── OpenApi/         # Personnalisation de la doc Swagger
```

### Comment Symfony traite une requête

```
Requête HTTP
    ↓
Symfony Router (quel code doit répondre ?)
    ↓
Sécurité (l'utilisateur a-t-il le droit ?)
    ↓
Controller ou API Platform (traitement)
    ↓
Doctrine ORM (lecture/écriture en BDD)
    ↓
Serializer (conversion entité → JSON)
    ↓
Réponse HTTP (JSON envoyé au frontend)
```

### Les attributs PHP 8

Le projet utilise les **attributs PHP 8** (les `#[...]`) au lieu des annotations (les `@...`). C'est la syntaxe moderne de PHP :

```php
// Attribut PHP 8 (ce qu'on utilise) ✅
#[ORM\Column(type: 'string', length: 255)]
private string $name;

// Annotation (ancien style, on ne l'utilise pas) ❌
/** @ORM\Column(type="string", length=255) */
```

---

## Les Entités

Les entités sont les classes PHP qui représentent les tables de la base de données. Chaque propriété de la classe correspond à une colonne.

### Anatomie d'une entité

Prenons un exemple simplifié :

```php
<?php
// src/Entity/Machine.php

namespace App\Entity;

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Metadata\Post;
use ApiPlatform\Metadata\Patch;
use ApiPlatform\Metadata\Delete;
use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Serializer\Attribute\Groups;

#[ORM\Entity(repositoryClass: MachineRepository::class)]    // ← Lié à une table en BDD
#[ORM\HasLifecycleCallbacks]                                  // ← Active les hooks PrePersist/PreUpdate
#[ApiResource(                                                // ← Génère les endpoints API
    operations: [
        new GetCollection(security: "is_granted('ROLE_VIEWER')"),     // GET /api/machines
        new Get(security: "is_granted('ROLE_VIEWER')"),               // GET /api/machines/{id}
        new Post(security: "is_granted('ROLE_GESTIONNAIRE')"),        // POST /api/machines
        new Patch(security: "is_granted('ROLE_GESTIONNAIRE')"),       // PATCH /api/machines/{id}
        new Delete(security: "is_granted('ROLE_GESTIONNAIRE')"),      // DELETE /api/machines/{id}
    ],
    normalizationContext: ['groups' => ['machine:read']],     // ← Quels champs exposer en lecture
    denormalizationContext: ['groups' => ['machine:write']],  // ← Quels champs accepter en écriture
    paginationItemsPerPage: 30,                               // ← 30 résultats par page
)]
class Machine
{
    #[ORM\Id]
    #[ORM\Column(type: 'string', length: 36)]
    #[Groups(['machine:read'])]                               // ← Exposé en lecture uniquement
    private string $id;

    #[ORM\Column(type: 'string', length: 255, unique: true)]
    #[Groups(['machine:read', 'machine:write'])]              // ← Exposé en lecture ET écriture
    private string $name;

    #[ORM\Column(type: 'decimal', precision: 10, scale: 2, nullable: true)]
    #[Groups(['machine:read', 'machine:write'])]
    private ?string $prix = null;

    #[ORM\ManyToOne(targetEntity: Site::class)]               // ← Relation : chaque machine appartient à un site
    #[ORM\JoinColumn(nullable: false, onDelete: 'CASCADE')]   // ← Obligatoire, supprimé en cascade
    #[Groups(['machine:read', 'machine:write'])]
    private Site $site;

    #[ORM\Column(type: 'datetime_immutable')]
    #[Groups(['machine:read'])]                               // ← Lecture seule (pas dans machine:write)
    private \DateTimeImmutable $createdAt;

    // ... getters et setters
}
```

### Décryptage des attributs importants

| Attribut | Signification |
|----------|--------------|
| `#[ORM\Entity]` | Cette classe est stockée en BDD |
| `#[ORM\Column]` | Cette propriété est une colonne |
| `#[ORM\Id]` | C'est la clé primaire |
| `#[ORM\ManyToOne]` | Relation N→1 (plusieurs machines → un site) |
| `#[ORM\OneToMany]` | Relation 1→N (un site → plusieurs machines) |
| `#[ORM\ManyToMany]` | Relation N→N (machines ↔ constructeurs) |
| `#[ApiResource]` | API Platform génère les endpoints CRUD |
| `#[Groups]` | Contrôle quels champs sont visibles/modifiables |
| `security: "is_granted('ROLE_X')"` | Qui a le droit d'utiliser cet endpoint |

### Le trait CuidEntityTrait

Toutes les entités utilisent un trait partagé qui génère les IDs et gère les timestamps :

```php
// src/Entity/Trait/CuidEntityTrait.php
trait CuidEntityTrait
{
    #[ORM\PrePersist]    // ← S'exécute automatiquement AVANT l'insertion en BDD
    public function generateId(): void
    {
        if (!isset($this->id)) {
            $this->id = 'cl' . bin2hex(random_bytes(12));    // ← Génère un ID unique de 26 chars
        }
        $this->createdAt = new \DateTimeImmutable();
        $this->updatedAt = new \DateTimeImmutable();
    }

    #[ORM\PreUpdate]     // ← S'exécute automatiquement AVANT une mise à jour
    public function updateTimestamp(): void
    {
        $this->updatedAt = new \DateTimeImmutable();
    }
}
```

### Les entités du projet

#### Entités "catalogue" (les éléments qu'on gère)

| Entité | Table | Champs clés | Relations |
|--------|-------|-------------|-----------|
| **Machine** | `machine` | name, reference, prix | → Site, ↔ Constructeur, → Documents |
| **Composant** | `composant` | name, reference, description, prix, structure (JSON) | → ModelType, → Product, ↔ Constructeur |
| **Piece** | `piece` | name, reference, description, prix, productIds (JSON) | → ModelType, → Product, ↔ Constructeur |
| **Product** | `product` | name, reference, supplierPrice | → ModelType, ↔ Constructeur |

#### Entités de classification

| Entité | Table | Champs clés | Rôle |
|--------|-------|-------------|------|
| **Site** | `site` | name, contactName, contactPhone, contactAddress | Regrouper les machines par lieu |
| **Constructeur** | `constructeur` | name, email, phone | Fournisseurs/fabricants partagés |
| **ModelType** | `model_type` | name, code, category (enum), skeletons (JSON) | Catégoriser composants/pièces/produits |

#### Entités de liaison hiérarchique (structure machine)

| Entité | Rôle | Relations |
|--------|------|-----------|
| **MachineComponentLink** | Lie un composant à une machine | → Machine, → Composant, → parent (self) |
| **MachinePieceLink** | Lie une pièce à une machine | → Machine, → Piece, → parent composant |
| **MachineProductLink** | Lie un produit à une machine | → Machine, → Product, → parent (flexible) |

Ces entités permettent la **structure arborescente** : un composant peut contenir des pièces, qui contiennent des produits.

#### Entités de métadonnées

| Entité | Rôle |
|--------|------|
| **CustomField** | Définition d'un champ personnalisé (nom, type, options) |
| **CustomFieldValue** | Valeur d'un champ personnalisé pour une entité donnée |
| **Document** | Fichier uploadé (PDF, image) rattaché à une entité |
| **AuditLog** | Entrée du journal d'audit (diff + snapshot) |
| **Comment** | Commentaire/ticket sur une fiche |
| **Profile** | Compte utilisateur (email, rôle, mot de passe hashé) |

### Les relations entre entités (schéma simplifié)

```
Site ──1:N──► Machine ──1:N──► MachineComponentLink ──► Composant
                │                      │
                │                      └──1:N──► MachinePieceLink ──► Piece
                │                                      │
                │                                      └──1:N──► MachineProductLink ──► Product
                │
                └──N:N──► Constructeur (via table de jointure)

ModelType ──1:N──► Composant / Piece / Product
                      │
                      └──► CustomField ──1:N──► CustomFieldValue

Machine / Composant / Piece / Product ──1:N──► Document
                                        ──1:N──► CustomFieldValue
```

---

## Les Controllers

API Platform génère automatiquement les endpoints CRUD standard. Les controllers personnalisés gèrent les cas plus complexes.

### Liste des controllers

#### Authentification (3 controllers)

**SessionProfileController** (`/api/session/profile`) — Login/Logout

```
POST   /api/session/profile      → Se connecter (payload: { profileId, password })
GET    /api/session/profile      → Récupérer le profil connecté
DELETE /api/session/profile      → Se déconnecter
```

**SessionProfilesController** (`/api/session/profiles`) — Liste des profils

```
GET    /api/session/profiles     → Liste tous les profils actifs (page de login)
```

**AdminProfileController** (`/api/admin/profiles`) — Administration des utilisateurs

```
GET    /api/admin/profiles                    → Liste tous les profils (ADMIN only)
POST   /api/admin/profiles                    → Créer un profil
PUT    /api/admin/profiles/{id}/role          → Changer le rôle d'un profil
PUT    /api/admin/profiles/{id}/password      → Réinitialiser un mot de passe
PUT    /api/admin/profiles/{id}/deactivate    → Désactiver un profil
```

#### Données et logique métier

**MachineStructureController** — Structure hiérarchique des machines

```
GET    /api/machines/{id}/structure           → Récupérer l'arborescence complète
PATCH  /api/machines/{id}/structure           → Modifier l'arborescence
POST   /api/machines/{id}/clone               → Cloner une machine avec toute sa structure
```

**MachineCustomFieldsController** — Champs personnalisés machines

```
POST   /api/machines/{id}/custom-fields/init  → Initialiser les champs personnalisés manquants
```

**EntityHistoryController** — Historique d'audit par entité

```
GET    /api/{entityType}/{id}/history         → 200 derniers événements d'audit
```

**ActivityLogController** — Journal d'activité global

```
GET    /api/activity-log                      → Liste paginée avec filtres (entityType, action)
```

**CommentController** — Commentaires/tickets

```
POST   /api/comments                          → Créer un commentaire
PATCH  /api/comments/{id}/resolve             → Résoudre un commentaire
GET    /api/comments/unresolved-count         → Nombre de commentaires non résolus
```

**CustomFieldValueController** — Valeurs de champs personnalisés

```
POST   /api/custom-field-values               → Créer/mettre à jour une valeur (upsert)
DELETE /api/custom-field-values/{id}           → Supprimer une valeur
```

#### Fichiers

**DocumentQueryController** — Requêter les documents par entité

```
GET    /api/documents/by-site/{id}            → Documents d'un site
GET    /api/documents/by-machine/{id}         → Documents d'une machine
GET    /api/documents/by-composant/{id}       → Documents d'un composant
GET    /api/documents/by-piece/{id}           → Documents d'une pièce
GET    /api/documents/by-product/{id}         → Documents d'un produit
```

**DocumentServeController** — Servir les fichiers

```
GET    /api/documents/{id}/file               → Afficher le fichier (inline)
GET    /api/documents/{id}/download           → Télécharger le fichier (attachment)
```

#### Monitoring

**HealthCheckController** — Vérification de santé

```
GET    /api/health                            → Version, latence BDD, mémoire, version PHP
```

### Exemple de controller commenté

```php
<?php
// src/Controller/CommentController.php

namespace App\Controller;

use App\Entity\Comment;
use Doctrine\ORM\EntityManagerInterface;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\Routing\Attribute\Route;

class CommentController extends AbstractController
{
    #[Route('/api/comments', methods: ['POST'])]    // ← Définit l'URL et le verbe HTTP
    public function create(
        Request $request,                            // ← La requête HTTP entrante
        EntityManagerInterface $em,                  // ← Pour écrire en BDD (injecté automatiquement)
    ): JsonResponse {
        $this->denyAccessUnlessGranted('ROLE_VIEWER');  // ← Vérifie que l'utilisateur est connecté

        $data = json_decode($request->getContent(), true);  // ← Parse le body JSON

        $comment = new Comment();
        $comment->setContent($data['content']);
        $comment->setEntityType($data['entityType']);
        $comment->setEntityId($data['entityId']);
        // ... autres champs

        $em->persist($comment);   // ← Dit à Doctrine "je veux sauvegarder ça"
        $em->flush();             // ← Exécute réellement le INSERT SQL

        return $this->json($comment, 201);  // ← Renvoie le commentaire créé avec le code 201
    }
}
```

---

## Le système d'audit

Chaque modification sur les entités principales est automatiquement enregistrée dans un journal d'audit. C'est un des points forts de l'application.

### Comment ça marche ?

Les **Event Subscribers** de Doctrine interceptent les opérations de base de données **avant** qu'elles soient exécutées (événement `onFlush`).

```
L'utilisateur modifie une machine
    ↓
Doctrine détecte le changement
    ↓
onFlush se déclenche
    ↓
Le subscriber calcule le diff (ancien → nouveau)
    ↓
Le subscriber crée un AuditLog avec :
  - entityType : "machine"
  - entityId : "cl1a2b3c..."
  - action : "update"
  - diff : { "name": { "from": "CNC 01", "to": "CNC 02" } }
  - snapshot : { état complet de la machine }
  - actorProfileId : "cl9z8y7x..." (qui a fait la modif)
    ↓
Les deux (machine + audit log) sont sauvegardés en même temps
```

### Le diff

Le diff capture exactement ce qui a changé :

```json
{
  "name": { "from": "CNC Mazak 01", "to": "CNC Mazak 02" },
  "prix": { "from": "45000.00", "to": "50000.00" },
  "constructeurIds": {
    "from": ["cl111...", "cl222..."],
    "to": ["cl111...", "cl333..."]
  }
}
```

### Le snapshot

Le snapshot capture l'état complet de l'entité au moment de la modification :

```json
{
  "id": "cl1a2b3c...",
  "name": "CNC Mazak 02",
  "reference": "CNM-001",
  "prix": "50000.00",
  "siteId": "cl9z8y7x...",
  "constructeurIds": ["cl111...", "cl333..."]
}
```

### Les subscribers d'audit

| Subscriber | Entité | Type |
|------------|--------|------|
| MachineAuditSubscriber | Machine | Complex (avec constructeurs + custom fields) |
| ComposantAuditSubscriber | Composant | Complex |
| PieceAuditSubscriber | Piece | Complex |
| ProductAuditSubscriber | Product | Complex |
| ConstructeurAuditSubscriber | Constructeur | Simple |
| DocumentAuditSubscriber | Document | Simple |
| ModelTypeAuditSubscriber | ModelType | Simple |

**Simple** = suit seulement les champs de l'entité
**Complex** = suit aussi les relations ManyToMany (constructeurs) et les champs personnalisés

### AbstractAuditSubscriber

La classe de base qui contient toute la logique partagée :

```php
abstract class AbstractAuditSubscriber implements EventSubscriber
{
    // Méthode à implémenter par chaque subscriber
    abstract protected function getEntityClass(): string;       // Ex: Machine::class
    abstract protected function getEntityType(): string;        // Ex: 'machine'
    abstract protected function buildSnapshot($entity): array;  // Construit le snapshot

    // Deux chemins d'exécution :
    // 1. onFlushSimple() : pour les entités sans collections ManyToMany
    // 2. onFlushComplex() : pour les entités avec constructeurs (détecte les ajouts/suppressions)
}
```

### Autres subscribers

| Subscriber | Rôle |
|------------|------|
| **PieceProductSyncSubscriber** | Synchronise le champ `productIds` sur Piece quand un Product est lié/délié |
| **UniqueConstraintSubscriber** | Capture les erreurs de doublon PostgreSQL et renvoie un message clair |

---

## L'authentification par session

### Le flux complet

```
1. GET /api/session/profiles
   → Retourne la liste des profils actifs (nom, prénom, email, hasPassword)
   → Le frontend affiche la page de login avec les profils disponibles

2. POST /api/session/profile
   Body: { "profileId": "cl...", "password": "secret" }
   → Le backend vérifie le mot de passe
   → Si OK : stocke profileId dans la session PHP, retourne le profil
   → Si KO : retourne 401

3. GET /api/session/profile (à chaque chargement de page)
   → Le navigateur envoie le cookie de session automatiquement
   → Le backend retrouve le profil via la session
   → Retourne le profil connecté ou 401

4. DELETE /api/session/profile
   → Supprime le profileId de la session
   → L'utilisateur est déconnecté
```

### La sécurité sur les endpoints

Chaque endpoint API Platform a une règle de sécurité :

```php
new GetCollection(security: "is_granted('ROLE_VIEWER')")   // Lecture → minimum ROLE_VIEWER
new Post(security: "is_granted('ROLE_GESTIONNAIRE')")       // Création → minimum ROLE_GESTIONNAIRE
```

Les controllers personnalisés utilisent :
```php
$this->denyAccessUnlessGranted('ROLE_VIEWER');
```

### La hiérarchie des rôles

Grâce à la hiérarchie, un ADMIN a automatiquement tous les rôles inférieurs :

```
ROLE_ADMIN ─── a aussi ──► ROLE_GESTIONNAIRE ──► ROLE_VIEWER ──► ROLE_USER
```

Donc `is_granted('ROLE_VIEWER')` accepte aussi les GESTIONNAIRES et les ADMINS.

---

## Les services

### DocumentStorageService

Gère le stockage des fichiers sur le système de fichiers :

```php
// Stocker un fichier uploadé
$path = $storageService->store($uploadedFile, $entityType, $entityId);

// Supprimer un fichier
$storageService->delete($path);
```

Les fichiers sont stockés dans `var/documents/{entityType}/{entityId}/{filename}`.

### PdfCompressorService

Compresse les fichiers PDF via Ghostscript pour réduire leur taille :

```php
$compressorService->compress($filePath);
```

### ModelTypeCategoryConversionService

Permet de convertir la catégorie d'un ModelType (ex: transformer un type "composant" en type "pièce").

---

## Les migrations

Les migrations sont des scripts SQL qui modifient la structure de la base de données. Elles sont dans le dossier `migrations/`.

### Principe

Quand tu ajoutes un champ à une entité, il faut créer une migration pour mettre à jour la BDD :

```bash
# Générer une migration à partir des changements détectés
make shell
php bin/console doctrine:migrations:diff

# Appliquer les migrations
php bin/console doctrine:migrations:migrate
```

### Particularités PostgreSQL

Les migrations utilisent du **SQL brut** avec des gardes pour l'idempotence :

```sql
-- On peut relancer la migration sans erreur
ALTER TABLE machine ADD COLUMN IF NOT EXISTS description TEXT;
DROP INDEX IF EXISTS idx_machine_name;
CREATE UNIQUE INDEX IF NOT EXISTS idx_machine_name ON machine (name);
```

**Attention aux noms de colonnes** : PostgreSQL stocke tout en **minuscules**. Donc `typePieceId` en PHP devient `typepieceid` en SQL. Toujours utiliser des noms lowercase dans le SQL brut.

---

## Les tests

### Stack de test

- **PHPUnit 12** : framework de test PHP
- **API Platform Test** : utilitaires pour tester des endpoints API
- **DAMA DoctrineTestBundle** : wrappe chaque test dans une transaction avec rollback automatique (pas besoin de nettoyer la BDD entre les tests)

### Structure

```
tests/
├── AbstractApiTestCase.php    # Classe de base avec helpers
└── Api/
    └── Entity/
        ├── MachineTest.php    # Tests des endpoints machine
        ├── SiteTest.php       # Tests des endpoints site
        └── ...
```

### Exemple de test

```php
class MachineTest extends AbstractApiTestCase
{
    public function testCreateMachine(): void
    {
        // Créer un client HTTP connecté en tant que gestionnaire
        $client = $this->createGestionnaireClient();

        // Créer un site (prérequis)
        $site = $this->createSite();

        // Envoyer une requête POST pour créer une machine
        $client->request('POST', '/api/machines', [
            'json' => [
                'name' => 'Machine Test',
                'reference' => 'MT-001',
                'site' => '/api/sites/' . $site->getId(),
            ],
        ]);

        // Vérifier que la réponse est 201 Created
        $this->assertResponseStatusCodeSame(201);

        // Vérifier le contenu de la réponse
        $this->assertJsonContains([
            'name' => 'Machine Test',
            'reference' => 'MT-001',
        ]);
    }
}
```

### Helpers disponibles dans AbstractApiTestCase

| Méthode | Description |
|---------|-------------|
| `createViewerClient()` | Client HTTP connecté avec ROLE_VIEWER |
| `createGestionnaireClient()` | Client HTTP connecté avec ROLE_GESTIONNAIRE |
| `createAdminClient()` | Client HTTP connecté avec ROLE_ADMIN |
| `createProfile()` | Crée un profil utilisateur en BDD |
| `createSite()` | Crée un site en BDD |
| `createMachine()` | Crée une machine en BDD |

### Lancer les tests

```bash
make test                                              # Tous les tests
make test FILES=tests/Api/Entity/MachineTest.php       # Un fichier
make test-setup                                        # (Re)créer la BDD de test
```

---

## Flux complet d'une requête

### Exemple : créer une machine

```
1. Le frontend envoie :
   POST /api/machines
   Content-Type: application/ld+json
   Cookie: PHPSESSID=abc123
   {
     "name": "CNC Mazak 01",
     "reference": "CNM-001",
     "prix": "50000.00",
     "site": "/api/sites/cl9z8y7x..."
   }

2. Symfony reçoit la requête
   → Le routeur identifie : c'est un endpoint API Platform (POST sur Machine)

3. Sécurité
   → Vérifie le cookie de session → retrouve le profil connecté
   → Vérifie is_granted('ROLE_GESTIONNAIRE') → OK

4. Désérialisation (JSON → objet PHP)
   → API Platform convertit le JSON en objet Machine
   → Le champ "site" (IRI) est résolu en objet Site
   → Seuls les champs du groupe 'machine:write' sont acceptés

5. Validation
   → Vérifie les contraintes (name non vide, site existe, etc.)

6. Persistence (objet PHP → BDD)
   → Doctrine déclenche PrePersist (CuidEntityTrait)
     → Génère l'ID : "cl" + 24 hex chars aléatoires
     → Set createdAt et updatedAt
   → Doctrine détecte l'INSERT à faire

7. Audit (onFlush)
   → MachineAuditSubscriber détecte la nouvelle machine
   → Crée un AuditLog avec action='create', diff, snapshot
   → L'AuditLog est aussi ajouté à la transaction

8. Flush
   → Doctrine exécute les requêtes SQL :
     INSERT INTO machine (id, name, reference, ...) VALUES (...)
     INSERT INTO audit_log (id, entity_type, entity_id, action, diff, snapshot, ...) VALUES (...)

9. Sérialisation (objet PHP → JSON)
   → API Platform convertit la Machine en JSON-LD
   → Seuls les champs du groupe 'machine:read' sont inclus

10. Réponse
    HTTP/1.1 201 Created
    {
      "@context": "/api/contexts/Machine",
      "@id": "/api/machines/cl1a2b3c...",
      "@type": "Machine",
      "id": "cl1a2b3c...",
      "name": "CNC Mazak 01",
      ...
    }
```

---

## Commandes Symfony utiles

Lancer ces commandes dans le conteneur Docker (`make shell` pour y entrer) :

| Commande | Description |
|----------|-------------|
| `php bin/console debug:router` | Voir toutes les routes disponibles |
| `php bin/console debug:config api_platform` | Voir la config API Platform |
| `php bin/console doctrine:schema:validate` | Vérifier que les entités sont synchronisées avec la BDD |
| `php bin/console doctrine:migrations:diff` | Générer une migration à partir des changements |
| `php bin/console doctrine:migrations:migrate` | Appliquer les migrations |
| `php bin/console cache:clear` | Vider le cache (résout beaucoup de problèmes) |
| `php bin/console app:compress-pdf` | Compresser les PDFs existants |
| `php bin/console app:create-profile` | Créer un profil utilisateur |

---

## Résumé des points clés pour un débutant

1. **API Platform génère les endpoints CRUD automatiquement** à partir des entités — tu n'as pas besoin d'écrire de controllers pour les opérations standard
2. **Les attributs PHP 8** (`#[...]`) remplacent les annotations et configurent tout : BDD, API, sérialisation, sécurité
3. **Les groupes de sérialisation** (`machine:read`, `machine:write`) contrôlent quels champs sont visibles/modifiables
4. **L'audit est automatique** : chaque modification est tracée sans rien avoir à faire manuellement
5. **L'authentification est par session (cookies)**, pas par tokens JWT
6. **Les IDs sont des CUID** (chaînes aléatoires), pas des auto-increment
7. **PostgreSQL stocke les noms en minuscules** : attention dans le SQL brut
8. **Les tests utilisent des transactions** : chaque test est isolé et la BDD est nettoyée automatiquement