feat(catalog) : add Category and CategoryType entities with Timestampable+Blamable pattern

- Category : ApiResource (5 ops), #[Auditable], TimestampableBlamableTrait +
  interfaces, asserts (NotBlank/Length sur name, NotNull sur categoryType),
  soft delete via deletedAt, groupes category:read/category:write + default:read
- CategoryType : referentiel statique en lecture seule (GetCollection + Get),
  embarque dans Category via le groupe category:read
- Repositories : interfaces Domain + impl Doctrine pour les deux entites
- doctrine.yaml : mapping ORM Catalog inconditionnel (miroir Sites) pour que
  l'ORM reconnaisse les entites ; declaration du module = ticket 0.5
- EntitiesAreTimestampableBlamableTest : CategoryType ajoute a EXCLUDED (RG-1.17)
- Index nommes declares sur les entites (match migration) ; index unique partiel
  uq_category_name_type_active possede par la migration seule

.claude/rules/backend.md

@@ -40,6 +40,27 @@ Format obligatoire : `module.resource[.subresource].action` en snake_case.
 - Audit ManyToMany : trace automatiquement `{fieldName: {added: [ids], removed: [ids]}}` — aucune action supplementaire
 - Spec complete : @doc/audit-log.md
 
+## Timestampable + Blamable (obligatoire pour entites metier)
+
+Toute **nouvelle** entite metier sous `src/Module/*/Domain/Entity/` doit porter les 4 colonnes `created_at` / `updated_at` / `created_by` / `updated_by`, remplies automatiquement. Trois lignes a ajouter a l'entite :
+
+```php
+use App\Shared\Domain\Contract\BlamableInterface;
+use App\Shared\Domain\Contract\TimestampableInterface;
+use App\Shared\Domain\Trait\TimestampableBlamableTrait;
+
+class MyEntity implements TimestampableInterface, BlamableInterface
+{
+    use TimestampableBlamableTrait; // porte les 4 props + getters/setters
+    // ... reste metier
+}
+```
+
+- Le `TimestampableBlamableSubscriber` (`Shared/Infrastructure/Doctrine/`) remplit les colonnes au `prePersist` / `preUpdate`. Hors contexte HTTP (CLI, cron, migration), le blame reste `null` (libelle « Systeme » cote front).
+- La migration de l'entite doit creer les 4 colonnes (`created_at` / `updated_at` NOT NULL, `created_by` / `updated_by` nullable `ON DELETE SET NULL`).
+- **Garde-fou CI** : `tests/Architecture/EntitiesAreTimestampableBlamableTest` echoue si une entite oublie le pattern. Un referentiel statique justifie (ex: `CategoryType`) doit etre explicitement whiteliste dans la constante `EXCLUDED` avec un commentaire.
+- Spec complete : @docs/specs/M0-categories/spec-back.md § 2.8 + § 2.8.bis
+
 ## Serialization
 
 Pour embarquer une relation dans le JSON (au lieu d'un IRI Hydra), ajouter le groupe du parent sur les proprietes de l'entite cible.

.gitea/workflows/pull-request.yml

@@ -60,14 +60,9 @@ jobs:
           coverage: none
           tools: composer:v2
 
-      - name: Cache Composer
+      # Cache Composer retire : meme cause que cote front — le backend de cache
-        uses: actions/cache@v4
+      # du runner Gitea est injoignable (ETIMEDOUT) et fait timeouter le step
-        with:
+      # ~4 min 30. A re-activer si le serveur de cache du runner est repare.
-          path: ~/.composer/cache
-          key: composer-${{ hashFiles('composer.lock') }}
-          restore-keys: |
-            composer-
-
       - name: Install PHP dependencies
         run: composer install --no-interaction --no-progress --prefer-dist
 
@@ -99,12 +94,15 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
+      # Pas de `cache: npm` : le backend de cache du runner Gitea est injoignable
+      # (ETIMEDOUT) et chaque tentative de restauration attend ~4 min 30 avant de
+      # timeout — c'est ce qui plombait le job. Node 22 est deja dans le
+      # tool-cache du runner (install instantane), et `npm ci` a froid ne prend
+      # que ~30s. A re-activer si le serveur de cache du runner est repare.
       - name: Setup Node 22
         uses: actions/setup-node@v4
         with:
           node-version: '22'
-          cache: npm
-          cache-dependency-path: frontend/package-lock.json
 
       - name: Install Node dependencies
         run: npm ci
@@ -115,5 +113,8 @@ jobs:
       - name: Unit tests (Vitest)
         run: npm run test
 
+      # `nuxt build` (et non `build:dist`/`nuxt generate`) : l'app est en SSR off
+      # (SPA), le prerender de generate n'apporte rien a une quality gate — on
+      # veut seulement valider que le bundle compile.
       - name: Build production (nuxt build)
-        run: npm run build:dist
+        run: npm run build

config/packages/doctrine.yaml

@@ -33,6 +33,10 @@ doctrine:
         # `App\Module\Sites\Domain\Entity\Site` dans User.php.
         resolve_target_entities:
             App\Shared\Domain\Contract\SiteInterface: App\Module\Sites\Domain\Entity\Site
+            # Cible des ManyToOne created_by / updated_by du TimestampableBlamableTrait.
+            # Permet a Shared de referencer UserInterface dans ses ORM mappings sans
+            # importer la classe concrete du module Core (cf. spec-back M0 § 2.8).
+            Symfony\Component\Security\Core\User\UserInterface: App\Module\Core\Domain\Entity\User
         mappings:
             Core:
                 type: attribute
@@ -50,6 +54,18 @@ doctrine:
                 dir: '%kernel.project_dir%/src/Module/Sites/Domain/Entity'
                 prefix: 'App\Module\Sites\Domain\Entity'
                 alias: Sites
+            # Mapping inconditionnel du module Catalog (meme logique que Sites) :
+            # la structure DB (category, category_type) existe meme si
+            # CatalogModule::class n'est pas encore wire dans config/modules.php
+            # (declaration du module = ticket 0.5 / ERP-47). L'ORM doit connaitre
+            # les entites pour que le schema soit en phase ; l'activation
+            # fonctionnelle passe exclusivement par config/modules.php.
+            Catalog:
+                type: attribute
+                is_bundle: false
+                dir: '%kernel.project_dir%/src/Module/Catalog/Domain/Entity'
+                prefix: 'App\Module\Catalog\Domain\Entity'
+                alias: Catalog
         controller_resolver:
             auto_mapping: false
 

docs/specs/M0-categories/spec-back.md

@@ -441,6 +441,21 @@ final class EntitiesAreTimestampableBlamableTest extends TestCase
 
 Coût d'écriture : 1h. Coût en CI : ~50ms. Bénéfice : 0 oubli possible. À écrire dans le ticket 0.0.
 
+#### Décision M0 sur la whitelist `EXCLUDED` (ERP-52)
+
+Au moment d'introduire le pattern (ticket 0.0), 4 entités préexistantes vivent déjà sous `src/Module/*/Domain/Entity/` : `User`, `Role`, `Permission` (Core) et `Site` (Sites). Aucune n'implémente le pattern. Le test L3 les détecterait et passerait au rouge.
+
+**Décision** : on **whiteliste explicitement ces 4 entités** dans `EntitiesAreTimestampableBlamableTest::EXCLUDED` avec une justification par entrée, plutôt que de les rétrofiter dans ERP-52 :
+
+| Entité | Justification du `EXCLUDED` |
+|---|---|
+| `User` | Référentiel d'authentification ; `createdAt` géré manuellement dans le constructeur. Rétrofit non trivial : impose de trancher la récursion Blamable (un `User` créé par un `User`) et casse des tests existants → **HP-9**. |
+| `Role` | Référentiel RBAC synchronisé via `app:sync-permissions`, pas de traçabilité user-driven nécessaire. |
+| `Permission` | Idem `Role` (synchronisé, pas piloté utilisateur). |
+| `Site` | Référentiel admin-managed, rétrofit à intégrer dans un futur module Sites v2 → **HP-10**. |
+
+**Règle dure pour la suite** : toute **nouvelle** entité métier (`Category` au M0, puis `Client`, `Fournisseur`, `Prestataire`, etc.) **doit** implémenter `TimestampableInterface` + `BlamableInterface` via le Trait. La whitelist `EXCLUDED` est réservée aux référentiels statiques justifiés (ex : `CategoryType` au ticket 0.2) — toute nouvelle entrée doit être documentée.
+
 #### Tests Subscriber
 
 Tests unitaires du Subscriber : créer une entité de test minimale (fixture interne aux tests) qui `use` le Trait + implements les interfaces, vérifier que `prePersist` + `preUpdate` remplissent les 4 colonnes. À écrire dans le ticket 0.0.
@@ -979,6 +994,8 @@ Les deux mécanismes sont indépendants : on peut désactiver `#[Auditable]` (pa
 - **HP-6** : **Filtres avancés / recherche serveur** dans la liste. Pas pertinent à 300 entrées (pagination front).
 - **HP-7** : **Catégories hiérarchiques** (parent / enfant). Pas demandé. Si besoin futur → migration ajout colonne `parent_id` + spec dédiée.
 - **HP-8** : **Création des rôles métier Bureau / Compta / Commerciale / Usine.** Ces rôles font partie du modèle MALIO mais leur seed initial dans `role` + leur attribution aux users est hors du périmètre M0 (probablement un M-RBAC dédié, ou seedés dans `AppFixtures` / `SeedE2ECommand` au fil des modules).
+- **HP-9** : **Rétrofit de `User` vers Timestampable + Blamable.** L'entité `User` est whitelistée dans `EntitiesAreTimestampableBlamableTest::EXCLUDED` au M0 (cf. § 2.8.bis). Son rétrofit nécessite une **décision archi dédiée** : récursion Blamable (un `User` créé/modifié par un `User`, FK auto-référente `created_by` / `updated_by` sur la table `user`), impact sur le `createdAt` déjà géré dans le constructeur, et migration des données existantes. À traiter dans un ticket scopé hors M0.
+- **HP-10** : **Rétrofit de `Site` vers Timestampable + Blamable.** Même logique que HP-9 pour le référentiel `Site` (whitelisté `EXCLUDED`). À intégrer dans un futur module Sites v2, avec la migration ajoutant les 4 colonnes + FK `user`.
 
 ## 10. Liens & dépendances
 

migrations/Version20260527164000.php

@@ -0,0 +1,90 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DoctrineMigrations;
+
+use Doctrine\DBAL\Schema\Schema;
+use Doctrine\Migrations\AbstractMigration;
+
+/**
+ * M0 — Catalog : creation des tables `category_type` (referentiel) et `category`.
+ *
+ * Le referentiel `category_type` est cree vide ; ses valeurs seront seedees
+ * ulterieurement (cf. spec-back M0 § 9 HP-1).
+ *
+ * Index unique partiel sur (LOWER(name), category_type_id) WHERE deleted_at
+ * IS NULL : permet la recreation d'une categorie apres suppression logique
+ * (cf. RG-1.07). Postgres supporte nativement le `CREATE UNIQUE INDEX ... WHERE`.
+ *
+ * Les 4 colonnes Timestampable/Blamable (`created_at`, `updated_at`,
+ * `created_by`, `updated_by`) materialisent le pattern Shared (cf. ERP-52,
+ * spec-back M0 § 2.8) : NOT NULL pour les dates (remplies par le subscriber),
+ * nullable + ON DELETE SET NULL pour les FK user (creation hors contexte HTTP
+ * et suppression d'un user sans bloquer les categories existantes).
+ *
+ * Migration placee au namespace racine `DoctrineMigrations` (regle ABSOLUE
+ * Starseed n°11) : avec plusieurs migrations_paths, Doctrine Migrations 3.x
+ * trie par FQCN alphabetique et non par version timestamp → l'init des tables
+ * d'un module doit vivre au namespace racine pour garantir l'ordre sur base
+ * vide.
+ */
+final class Version20260527164000 extends AbstractMigration
+{
+    public function getDescription(): string
+    {
+        return 'M0 Catalog : tables category_type et category, index unique partiel.';
+    }
+
+    public function up(Schema $schema): void
+    {
+        $this->addSql(<<<'SQL'
+            CREATE TABLE category_type (
+                id INT GENERATED BY DEFAULT AS IDENTITY NOT NULL,
+                code VARCHAR(40) NOT NULL,
+                label VARCHAR(120) NOT NULL,
+                PRIMARY KEY (id)
+            )
+            SQL);
+        $this->addSql('CREATE UNIQUE INDEX uq_category_type_code ON category_type (code)');
+
+        $this->addSql(<<<'SQL'
+            CREATE TABLE category (
+                id INT GENERATED BY DEFAULT AS IDENTITY NOT NULL,
+                name VARCHAR(120) NOT NULL,
+                category_type_id INT NOT NULL,
+                deleted_at TIMESTAMP(0) WITHOUT TIME ZONE DEFAULT NULL,
+                created_at TIMESTAMP(0) WITHOUT TIME ZONE NOT NULL,
+                updated_at TIMESTAMP(0) WITHOUT TIME ZONE NOT NULL,
+                created_by INT DEFAULT NULL,
+                updated_by INT DEFAULT NULL,
+                PRIMARY KEY (id),
+                CONSTRAINT fk_category_type
+                    FOREIGN KEY (category_type_id) REFERENCES category_type (id) ON DELETE RESTRICT,
+                CONSTRAINT fk_category_created_by
+                    FOREIGN KEY (created_by) REFERENCES "user" (id) ON DELETE SET NULL,
+                CONSTRAINT fk_category_updated_by
+                    FOREIGN KEY (updated_by) REFERENCES "user" (id) ON DELETE SET NULL
+            )
+            SQL);
+
+        // Unicite (name, type) case-insensitive, seulement sur les non-soft-deleted.
+        $this->addSql(<<<'SQL'
+            CREATE UNIQUE INDEX uq_category_name_type_active
+            ON category (LOWER(name), category_type_id)
+            WHERE deleted_at IS NULL
+            SQL);
+
+        $this->addSql('CREATE INDEX idx_category_deleted_at ON category (deleted_at)');
+        $this->addSql('CREATE INDEX idx_category_type_id ON category (category_type_id)');
+        $this->addSql('CREATE INDEX idx_category_created_by ON category (created_by)');
+        $this->addSql('CREATE INDEX idx_category_updated_by ON category (updated_by)');
+    }
+
+    public function down(Schema $schema): void
+    {
+        // Ordre important : `category` porte les FK vers `category_type`.
+        $this->addSql('DROP TABLE category');
+        $this->addSql('DROP TABLE category_type');
+    }
+}

src/Module/Catalog/Domain/Entity/Category.php

@@ -0,0 +1,152 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Module\Catalog\Domain\Entity;
+
+use ApiPlatform\Metadata\ApiResource;
+use ApiPlatform\Metadata\Delete;
+use ApiPlatform\Metadata\Get;
+use ApiPlatform\Metadata\GetCollection;
+use ApiPlatform\Metadata\Patch;
+use ApiPlatform\Metadata\Post;
+use App\Module\Catalog\Infrastructure\Doctrine\DoctrineCategoryRepository;
+use App\Shared\Domain\Attribute\Auditable;
+use App\Shared\Domain\Contract\BlamableInterface;
+use App\Shared\Domain\Contract\TimestampableInterface;
+use App\Shared\Domain\Trait\TimestampableBlamableTrait;
+use DateTimeImmutable;
+use Doctrine\ORM\Mapping as ORM;
+use Symfony\Component\Serializer\Attribute\Groups;
+use Symfony\Component\Validator\Constraints as Assert;
+
+/**
+ * Categorie : referentiel metier classifiant les futurs tiers (clients,
+ * fournisseurs, prestataires). Porte un `name` libre et un `categoryType`
+ * (FK vers le referentiel statique CategoryType).
+ *
+ * - Soft delete via `deletedAt` (pas de hard delete) : la liste exclut par
+ *   defaut les categories supprimees (cf. CategoryProvider, ticket 0.3).
+ * - Timestampable + Blamable via le Trait Shared : les 4 colonnes
+ *   created_at / updated_at / created_by / updated_by sont remplies
+ *   automatiquement par le TimestampableBlamableSubscriber.
+ * - `#[Auditable]` : chaque create / update / delete (soft) est trace dans
+ *   audit_log par l'AuditListener du module Core.
+ *
+ * Les Provider (filtre soft-delete) et Processor (trim, soft delete, 409)
+ * seront branches au ticket 0.3 (ERP-45). Au ticket 0.2, les operations
+ * utilisent les state Doctrine par defaut d'API Platform.
+ */
+#[ApiResource(
+    operations: [
+        new GetCollection(
+            security: "is_granted('catalog.categories.view')",
+            normalizationContext: ['groups' => ['category:read', 'default:read']],
+        ),
+        new Get(
+            security: "is_granted('catalog.categories.view')",
+            normalizationContext: ['groups' => ['category:read', 'default:read']],
+        ),
+        new Post(
+            security: "is_granted('catalog.categories.manage')",
+            normalizationContext: ['groups' => ['category:read', 'default:read']],
+            denormalizationContext: ['groups' => ['category:write']],
+        ),
+        new Patch(
+            security: "is_granted('catalog.categories.manage')",
+            normalizationContext: ['groups' => ['category:read', 'default:read']],
+            denormalizationContext: ['groups' => ['category:write']],
+        ),
+        new Delete(
+            security: "is_granted('catalog.categories.manage')",
+        ),
+    ],
+)]
+#[ORM\Entity(repositoryClass: DoctrineCategoryRepository::class)]
+#[ORM\Table(name: 'category')]
+// Index nommes pour matcher la migration (cf. Role/Permission/Site). L'index
+// unique partiel `uq_category_name_type_active` (LOWER(name), category_type_id
+// WHERE deleted_at IS NULL) reste possede par la seule migration : Doctrine ORM
+// ne sait pas exprimer un index fonctionnel + partiel via attribut.
+#[ORM\Index(name: 'idx_category_deleted_at', columns: ['deleted_at'])]
+#[ORM\Index(name: 'idx_category_type_id', columns: ['category_type_id'])]
+#[ORM\Index(name: 'idx_category_created_by', columns: ['created_by'])]
+#[ORM\Index(name: 'idx_category_updated_by', columns: ['updated_by'])]
+#[Auditable]
+class Category implements TimestampableInterface, BlamableInterface
+{
+    // === Timestampable + Blamable ===
+    // Les 4 colonnes (created_at, updated_at, created_by, updated_by) + leurs
+    // getters/setters viennent du Trait Shared. Le TimestampableBlamableSubscriber
+    // les remplit automatiquement au prePersist / preUpdate. Aucune redeclaration
+    // manuelle de ces proprietes ici.
+    use TimestampableBlamableTrait;
+
+    #[ORM\Id]
+    #[ORM\GeneratedValue]
+    #[ORM\Column]
+    #[Groups(['category:read'])]
+    private ?int $id = null;
+
+    #[ORM\Column(length: 120)]
+    #[Assert\NotBlank(message: 'Le nom est obligatoire.')]
+    #[Assert\Length(min: 2, max: 120)]
+    #[Groups(['category:read', 'category:write'])]
+    private ?string $name = null;
+
+    #[ORM\ManyToOne(targetEntity: CategoryType::class)]
+    #[ORM\JoinColumn(name: 'category_type_id', referencedColumnName: 'id', nullable: false, onDelete: 'RESTRICT')]
+    #[Assert\NotNull(message: 'Type de catégorie obligatoire.')]
+    #[Groups(['category:read', 'category:write'])]
+    private ?CategoryType $categoryType = null;
+
+    /**
+     * Soft delete : null = active, valeur = supprimee logiquement le {date}.
+     * Pas exposee en ecriture (groupe category:write exclu) : seul le DELETE,
+     * via le CategoryProcessor (ticket 0.3), pose la valeur.
+     */
+    #[ORM\Column(name: 'deleted_at', type: 'datetime_immutable', nullable: true)]
+    #[Groups(['category:read'])]
+    private ?DateTimeImmutable $deletedAt = null;
+
+    public function getId(): ?int
+    {
+        return $this->id;
+    }
+
+    public function getName(): ?string
+    {
+        return $this->name;
+    }
+
+    public function setName(string $name): static
+    {
+        $this->name = $name;
+
+        return $this;
+    }
+
+    public function getCategoryType(): ?CategoryType
+    {
+        return $this->categoryType;
+    }
+
+    public function setCategoryType(?CategoryType $categoryType): static
+    {
+        $this->categoryType = $categoryType;
+
+        return $this;
+    }
+
+    public function getDeletedAt(): ?DateTimeImmutable
+    {
+        return $this->deletedAt;
+    }
+
+    public function setDeletedAt(?DateTimeImmutable $deletedAt): static
+    {
+        $this->deletedAt = $deletedAt;
+
+        return $this;
+    }
+}

src/Module/Catalog/Domain/Entity/CategoryType.php

@@ -0,0 +1,87 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Module\Catalog\Domain\Entity;
+
+use ApiPlatform\Metadata\ApiResource;
+use ApiPlatform\Metadata\Get;
+use ApiPlatform\Metadata\GetCollection;
+use App\Module\Catalog\Infrastructure\Doctrine\DoctrineCategoryTypeRepository;
+use Doctrine\ORM\Mapping as ORM;
+use Symfony\Component\Serializer\Attribute\Groups;
+
+/**
+ * Type de categorie : referentiel statique classifiant les Category
+ * (ex: MATIERE, PRODUIT, SERVICE). Cree vide par la migration M0 ; son seed
+ * initial et son CRUD admin sont hors perimetre M0 (cf. spec-back § 9 HP-1).
+ *
+ * Lecture seule au M0 : seules les operations GetCollection et Get sont
+ * exposees, sous la meme permission que Category (catalog.categories.view).
+ *
+ * Referentiel statique : pas de Timestampable/Blamable (whiteliste dans
+ * EntitiesAreTimestampableBlamableTest::EXCLUDED). Le groupe `category:read`
+ * est ajoute sur chaque propriete pour que le type soit embarque dans la
+ * reponse d'une Category (cf. .claude/rules/backend.md § Serialization).
+ */
+#[ApiResource(
+    operations: [
+        new GetCollection(
+            security: "is_granted('catalog.categories.view')",
+            normalizationContext: ['groups' => ['category_type:read']],
+        ),
+        new Get(
+            security: "is_granted('catalog.categories.view')",
+            normalizationContext: ['groups' => ['category_type:read']],
+        ),
+    ],
+)]
+#[ORM\Entity(repositoryClass: DoctrineCategoryTypeRepository::class)]
+#[ORM\Table(name: 'category_type')]
+// Contrainte d'unicite nommee pour matcher la migration (cf. Role/Permission).
+#[ORM\UniqueConstraint(name: 'uq_category_type_code', columns: ['code'])]
+class CategoryType
+{
+    #[ORM\Id]
+    #[ORM\GeneratedValue]
+    #[ORM\Column]
+    #[Groups(['category_type:read', 'category:read'])]
+    private ?int $id = null;
+
+    #[ORM\Column(length: 40)]
+    #[Groups(['category_type:read', 'category:read'])]
+    private ?string $code = null;
+
+    #[ORM\Column(length: 120)]
+    #[Groups(['category_type:read', 'category:read'])]
+    private ?string $label = null;
+
+    public function getId(): ?int
+    {
+        return $this->id;
+    }
+
+    public function getCode(): ?string
+    {
+        return $this->code;
+    }
+
+    public function setCode(string $code): static
+    {
+        $this->code = $code;
+
+        return $this;
+    }
+
+    public function getLabel(): ?string
+    {
+        return $this->label;
+    }
+
+    public function setLabel(string $label): static
+    {
+        $this->label = $label;
+
+        return $this;
+    }
+}

src/Module/Catalog/Domain/Repository/CategoryRepositoryInterface.php

@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Module\Catalog\Domain\Repository;
+
+use App\Module\Catalog\Domain\Entity\Category;
+
+interface CategoryRepositoryInterface
+{
+    public function findById(int $id): ?Category;
+
+    public function save(Category $category): void;
+}

src/Module/Catalog/Domain/Repository/CategoryTypeRepositoryInterface.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Module\Catalog\Domain\Repository;
+
+use App\Module\Catalog\Domain\Entity\CategoryType;
+
+interface CategoryTypeRepositoryInterface
+{
+    public function findById(int $id): ?CategoryType;
+
+    /**
+     * @return list<CategoryType>
+     */
+    public function findAllOrderedByLabel(): array;
+}

src/Module/Catalog/Infrastructure/Doctrine/DoctrineCategoryRepository.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Module\Catalog\Infrastructure\Doctrine;
+
+use App\Module\Catalog\Domain\Entity\Category;
+use App\Module\Catalog\Domain\Repository\CategoryRepositoryInterface;
+use Doctrine\Bundle\DoctrineBundle\Repository\ServiceEntityRepository;
+use Doctrine\Persistence\ManagerRegistry;
+
+/**
+ * @extends ServiceEntityRepository<Category>
+ */
+class DoctrineCategoryRepository extends ServiceEntityRepository implements CategoryRepositoryInterface
+{
+    public function __construct(ManagerRegistry $registry)
+    {
+        parent::__construct($registry, Category::class);
+    }
+
+    public function findById(int $id): ?Category
+    {
+        return $this->find($id);
+    }
+
+    public function save(Category $category): void
+    {
+        $this->getEntityManager()->persist($category);
+        $this->getEntityManager()->flush();
+    }
+}

src/Module/Catalog/Infrastructure/Doctrine/DoctrineCategoryTypeRepository.php

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Module\Catalog\Infrastructure\Doctrine;
+
+use App\Module\Catalog\Domain\Entity\CategoryType;
+use App\Module\Catalog\Domain\Repository\CategoryTypeRepositoryInterface;
+use Doctrine\Bundle\DoctrineBundle\Repository\ServiceEntityRepository;
+use Doctrine\Persistence\ManagerRegistry;
+
+/**
+ * @extends ServiceEntityRepository<CategoryType>
+ */
+class DoctrineCategoryTypeRepository extends ServiceEntityRepository implements CategoryTypeRepositoryInterface
+{
+    public function __construct(ManagerRegistry $registry)
+    {
+        parent::__construct($registry, CategoryType::class);
+    }
+
+    public function findById(int $id): ?CategoryType
+    {
+        return $this->find($id);
+    }
+
+    /**
+     * @return list<CategoryType>
+     */
+    public function findAllOrderedByLabel(): array
+    {
+        return $this->findBy([], ['label' => 'ASC']);
+    }
+}

src/Shared/Domain/Contract/BlamableInterface.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Shared\Domain\Contract;
+
+use Symfony\Component\Security\Core\User\UserInterface;
+
+/**
+ * Contrat lu par le TimestampableBlamableSubscriber.
+ *
+ * Toute entite qui l'implemente voit ses colonnes `created_by` / `updated_by`
+ * remplies automatiquement avec l'utilisateur authentifie (ou laissees a null
+ * hors contexte HTTP : CLI, cron, migration).
+ *
+ * Le type-hint cible `Symfony\Component\Security\Core\User\UserInterface`
+ * (deja implementee par App\Module\Core\Domain\Entity\User) pour eviter de
+ * coupler Shared a Module/Core. La classe concrete est resolue par Doctrine
+ * via `resolve_target_entities` (cf. config/packages/doctrine.yaml).
+ */
+interface BlamableInterface
+{
+    public function getCreatedBy(): ?UserInterface;
+
+    public function setCreatedBy(?UserInterface $user): void;
+
+    public function getUpdatedBy(): ?UserInterface;
+
+    public function setUpdatedBy(?UserInterface $user): void;
+}

src/Shared/Domain/Contract/TimestampableInterface.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Shared\Domain\Contract;
+
+use DateTimeImmutable;
+
+/**
+ * Contrat lu par le TimestampableBlamableSubscriber.
+ *
+ * Toute entite qui l'implemente voit ses colonnes `created_at` / `updated_at`
+ * remplies automatiquement au prePersist / preUpdate. Le porteur des colonnes
+ * et des accesseurs est le TimestampableBlamableTrait.
+ */
+interface TimestampableInterface
+{
+    public function getCreatedAt(): ?DateTimeImmutable;
+
+    public function setCreatedAt(DateTimeImmutable $createdAt): void;
+
+    public function getUpdatedAt(): ?DateTimeImmutable;
+
+    public function setUpdatedAt(DateTimeImmutable $updatedAt): void;
+}

src/Shared/Domain/Trait/TimestampableBlamableTrait.php

@@ -0,0 +1,83 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Shared\Domain\Trait;
+
+use DateTimeImmutable;
+use Doctrine\ORM\Mapping as ORM;
+use Symfony\Component\Security\Core\User\UserInterface;
+use Symfony\Component\Serializer\Attribute\Groups;
+
+/**
+ * Trait Doctrine qui porte les 4 colonnes Timestampable + Blamable.
+ *
+ * Usage : `use TimestampableBlamableTrait;` dans l'entite, +
+ * `implements TimestampableInterface, BlamableInterface`. Le
+ * TimestampableBlamableSubscriber remplit les colonnes automatiquement
+ * au prePersist / preUpdate.
+ *
+ * Les Groups Serializer utilisent une convention `default:read` agregee :
+ * pour exposer les 4 colonnes dans une reponse API d'une entite X, ajouter
+ * `default:read` au normalizationContext aux cotes du groupe `x:read`.
+ */
+trait TimestampableBlamableTrait
+{
+    #[ORM\Column(name: 'created_at', type: 'datetime_immutable')]
+    #[Groups(['default:read'])]
+    private ?DateTimeImmutable $createdAt = null;
+
+    #[ORM\Column(name: 'updated_at', type: 'datetime_immutable')]
+    #[Groups(['default:read'])]
+    private ?DateTimeImmutable $updatedAt = null;
+
+    #[ORM\ManyToOne(targetEntity: UserInterface::class)]
+    #[ORM\JoinColumn(name: 'created_by', referencedColumnName: 'id', nullable: true, onDelete: 'SET NULL')]
+    #[Groups(['default:read'])]
+    private ?UserInterface $createdBy = null;
+
+    #[ORM\ManyToOne(targetEntity: UserInterface::class)]
+    #[ORM\JoinColumn(name: 'updated_by', referencedColumnName: 'id', nullable: true, onDelete: 'SET NULL')]
+    #[Groups(['default:read'])]
+    private ?UserInterface $updatedBy = null;
+
+    public function getCreatedAt(): ?DateTimeImmutable
+    {
+        return $this->createdAt;
+    }
+
+    public function setCreatedAt(DateTimeImmutable $createdAt): void
+    {
+        $this->createdAt = $createdAt;
+    }
+
+    public function getUpdatedAt(): ?DateTimeImmutable
+    {
+        return $this->updatedAt;
+    }
+
+    public function setUpdatedAt(DateTimeImmutable $updatedAt): void
+    {
+        $this->updatedAt = $updatedAt;
+    }
+
+    public function getCreatedBy(): ?UserInterface
+    {
+        return $this->createdBy;
+    }
+
+    public function setCreatedBy(?UserInterface $user): void
+    {
+        $this->createdBy = $user;
+    }
+
+    public function getUpdatedBy(): ?UserInterface
+    {
+        return $this->updatedBy;
+    }
+
+    public function setUpdatedBy(?UserInterface $user): void
+    {
+        $this->updatedBy = $user;
+    }
+}

src/Shared/Infrastructure/Doctrine/TimestampableBlamableSubscriber.php

@@ -0,0 +1,65 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Shared\Infrastructure\Doctrine;
+
+use App\Shared\Domain\Contract\BlamableInterface;
+use App\Shared\Domain\Contract\TimestampableInterface;
+use DateTimeImmutable;
+use Doctrine\Bundle\DoctrineBundle\Attribute\AsDoctrineListener;
+use Doctrine\ORM\Event\PrePersistEventArgs;
+use Doctrine\ORM\Event\PreUpdateEventArgs;
+use Doctrine\ORM\Events;
+use Symfony\Bundle\SecurityBundle\Security;
+use Symfony\Component\Security\Core\User\UserInterface;
+
+/**
+ * Listener Doctrine global qui remplit automatiquement les colonnes
+ * Timestampable + Blamable.
+ *
+ * Pattern aligne sur AuditListener (cf.
+ * src/Module/Core/Infrastructure/Doctrine/AuditListener.php) : declare via
+ * #[AsDoctrineListener], auto-wire par le DoctrineBundle.
+ *
+ * Regle Blamable : si aucun utilisateur n'est authentifie (CLI, cron,
+ * migration), les FK `created_by` / `updated_by` restent a null. L'affichage
+ * front gere le libelle « Systeme » pour null.
+ */
+#[AsDoctrineListener(event: Events::prePersist)]
+#[AsDoctrineListener(event: Events::preUpdate)]
+final class TimestampableBlamableSubscriber
+{
+    public function __construct(private readonly Security $security) {}
+
+    public function prePersist(PrePersistEventArgs $args): void
+    {
+        $entity = $args->getObject();
+        $now    = new DateTimeImmutable();
+        $user   = $this->security->getUser();
+
+        if ($entity instanceof TimestampableInterface) {
+            $entity->setCreatedAt($now);
+            $entity->setUpdatedAt($now);
+        }
+
+        if ($entity instanceof BlamableInterface && $user instanceof UserInterface) {
+            $entity->setCreatedBy($user);
+            $entity->setUpdatedBy($user);
+        }
+    }
+
+    public function preUpdate(PreUpdateEventArgs $args): void
+    {
+        $entity = $args->getObject();
+        $user   = $this->security->getUser();
+
+        if ($entity instanceof TimestampableInterface) {
+            $entity->setUpdatedAt(new DateTimeImmutable());
+        }
+
+        if ($entity instanceof BlamableInterface && $user instanceof UserInterface) {
+            $entity->setUpdatedBy($user);
+        }
+    }
+}

tests/Architecture/EntitiesAreTimestampableBlamableTest.php

@@ -0,0 +1,128 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Architecture;
+
+use App\Module\Catalog\Domain\Entity\CategoryType;
+use App\Module\Core\Domain\Entity\Permission;
+use App\Module\Core\Domain\Entity\Role;
+use App\Module\Core\Domain\Entity\User;
+use App\Module\Sites\Domain\Entity\Site;
+use App\Shared\Domain\Contract\BlamableInterface;
+use App\Shared\Domain\Contract\TimestampableInterface;
+use Doctrine\ORM\Mapping\Entity;
+use PHPUnit\Framework\TestCase;
+use ReflectionClass;
+use Symfony\Component\Finder\Finder;
+
+use function in_array;
+
+/**
+ * Garde-fou architecture (niveau L3 de la spec § 2.8.bis).
+ *
+ * Scanne toutes les entites Doctrine sous `src/Module/<module>/Domain/Entity/`
+ * et verifie qu'elles implementent TimestampableInterface ET BlamableInterface
+ * (via TimestampableBlamableTrait). Empeche tout oubli du pattern sur une
+ * nouvelle entite metier : la CI passe au rouge.
+ *
+ * @internal
+ */
+final class EntitiesAreTimestampableBlamableTest extends TestCase
+{
+    /**
+     * Entites explicitement exemptees du pattern.
+     *
+     * Au M0, on whiteliste les 4 entites preexistantes du noyau (creees avant
+     * l'introduction du pattern) : leur retrofit est une decision archi a part
+     * entiere, hors scope ERP-52.
+     *
+     * - User : referentiel d'authentification, createdAt gere manuellement dans
+     *   le constructeur. Retrofit hors scope M0 (cf. HP-9) : impose de trancher
+     *   la recursion Blamable (un User cree par un User) + casse des tests
+     *   existants.
+     * - Role : referentiel RBAC synchronise via `app:sync-permissions`, pas de
+     *   tracabilite user-driven necessaire.
+     * - Permission : idem Role (synchronise, pas pilote utilisateur).
+     * - Site : referentiel admin-managed, a integrer dans un futur module Sites
+     *   v2 (cf. HP-10).
+     * - CategoryType : referentiel statique (codes de typage des categories),
+     *   pas de besoin de tracabilite user-driven (cree par migration/seed,
+     *   pas pilote utilisateur au M0). Cf. spec-back § 2.8.bis + RG-1.17.
+     *
+     * Les futurs referentiels statiques s'ajoutent ici avec une justification.
+     */
+    private const EXCLUDED = [
+        User::class,
+        Role::class,
+        Permission::class,
+        Site::class,
+        CategoryType::class,
+    ];
+
+    public function testAllBusinessEntitiesImplementBothInterfaces(): void
+    {
+        // Garde : chaque entree de la whitelist doit pointer sur une classe
+        // reelle. Empeche un FQCN errone de masquer silencieusement un oubli.
+        foreach (self::EXCLUDED as $excluded) {
+            self::assertTrue(class_exists($excluded), sprintf('Classe whitelistee inexistante : %s', $excluded));
+        }
+
+        $finder = new Finder()
+            ->files()
+            ->in(__DIR__.'/../../src/Module')
+            ->path('Domain/Entity')
+            ->name('*.php')
+        ;
+
+        // Garde : si le scan ne trouve rien, le chemin est casse — le test
+        // deviendrait un faux positif vert. On verifie qu'il a du grain a moudre.
+        self::assertNotEmpty(iterator_to_array($finder), 'Aucune entite scannee : chemin src/Module invalide ?');
+
+        foreach ($finder as $file) {
+            $fqcn = $this->extractFqcn($file->getRealPath());
+            if (null === $fqcn || in_array($fqcn, self::EXCLUDED, true)) {
+                continue;
+            }
+
+            $reflection = new ReflectionClass($fqcn);
+            // On ignore les classes abstraites et tout ce qui n'est pas une
+            // entite Doctrine (value objects, embeddables non mappes, etc.).
+            if ($reflection->isAbstract() || [] === $reflection->getAttributes(Entity::class)) {
+                continue;
+            }
+
+            self::assertTrue(
+                $reflection->implementsInterface(TimestampableInterface::class)
+                && $reflection->implementsInterface(BlamableInterface::class),
+                sprintf(
+                    'L\'entite %s doit implementer TimestampableInterface ET BlamableInterface '
+                    .'(utiliser TimestampableBlamableTrait). Si c\'est un referentiel statique '
+                    .'justifie, l\'ajouter dans EntitiesAreTimestampableBlamableTest::EXCLUDED.',
+                    $fqcn,
+                ),
+            );
+        }
+    }
+
+    /**
+     * Extrait le FQCN (namespace + classe) d'un fichier PHP par lecture du
+     * source, sans charger le fichier.
+     */
+    private function extractFqcn(string $path): ?string
+    {
+        $source = file_get_contents($path);
+        if (false === $source) {
+            return null;
+        }
+
+        if (
+            1 !== preg_match('/^namespace\s+([^;]+);/m', $source, $nsMatch)
+            || 1 !== preg_match('/^(?:final\s+|abstract\s+|readonly\s+)*class\s+(\w+)/m', $source, $classMatch)
+        ) {
+            return null;
+        }
+
+        return trim($nsMatch[1]).'\\'.$classMatch[1];
+    }
+}

tests/Shared/Infrastructure/Doctrine/TimestampableBlamableSubscriberTest.php

@@ -0,0 +1,159 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Shared\Infrastructure\Doctrine;
+
+use App\Shared\Domain\Contract\BlamableInterface;
+use App\Shared\Domain\Contract\TimestampableInterface;
+use App\Shared\Domain\Trait\TimestampableBlamableTrait;
+use App\Shared\Infrastructure\Doctrine\TimestampableBlamableSubscriber;
+use DateTimeImmutable;
+use Doctrine\ORM\EntityManagerInterface;
+use Doctrine\ORM\Event\PrePersistEventArgs;
+use Doctrine\ORM\Event\PreUpdateEventArgs;
+use PHPUnit\Framework\TestCase;
+use Symfony\Bundle\SecurityBundle\Security;
+use Symfony\Component\Security\Core\User\UserInterface;
+
+/**
+ * Tests unitaires du TimestampableBlamableSubscriber.
+ *
+ * On exerce directement prePersist / preUpdate avec un EntityManager et une
+ * Security stubbes — aucun boot de kernel, aucun acces BDD. Les entites de test
+ * sont des fixtures internes (cf. bas de fichier).
+ *
+ * @internal
+ */
+final class TimestampableBlamableSubscriberTest extends TestCase
+{
+    public function testPrePersistWithUser(): void
+    {
+        $user       = $this->createStub(UserInterface::class);
+        $subscriber = new TimestampableBlamableSubscriber($this->securityReturning($user));
+        $entity     = new FullAuditableFixture();
+
+        $subscriber->prePersist($this->prePersistArgs($entity));
+
+        // Les 4 colonnes sont remplies : dates posees, blame = user courant.
+        self::assertInstanceOf(DateTimeImmutable::class, $entity->getCreatedAt());
+        self::assertInstanceOf(DateTimeImmutable::class, $entity->getUpdatedAt());
+        self::assertSame($entity->getCreatedAt(), $entity->getUpdatedAt());
+        self::assertSame($user, $entity->getCreatedBy());
+        self::assertSame($user, $entity->getUpdatedBy());
+    }
+
+    public function testPrePersistWithoutUser(): void
+    {
+        $subscriber = new TimestampableBlamableSubscriber($this->securityReturning(null));
+        $entity     = new FullAuditableFixture();
+
+        $subscriber->prePersist($this->prePersistArgs($entity));
+
+        // Hors contexte HTTP (CLI / cron) : dates remplies, blame laisse a null.
+        self::assertInstanceOf(DateTimeImmutable::class, $entity->getCreatedAt());
+        self::assertInstanceOf(DateTimeImmutable::class, $entity->getUpdatedAt());
+        self::assertNull($entity->getCreatedBy());
+        self::assertNull($entity->getUpdatedBy());
+    }
+
+    public function testPreUpdate(): void
+    {
+        $user       = $this->createStub(UserInterface::class);
+        $subscriber = new TimestampableBlamableSubscriber($this->securityReturning($user));
+
+        // On simule une entite deja persistee : createdAt fige dans le passe,
+        // createdBy positionne par une creation anterieure.
+        $createdAt = new DateTimeImmutable('2020-01-01 10:00:00');
+        $entity    = new FullAuditableFixture();
+        $entity->setCreatedAt($createdAt);
+        $entity->setUpdatedAt($createdAt);
+
+        $subscriber->preUpdate($this->preUpdateArgs($entity));
+
+        // updatedAt avance, createdAt reste fige, updatedBy = user courant.
+        self::assertSame($createdAt, $entity->getCreatedAt());
+        self::assertGreaterThan($createdAt, $entity->getUpdatedAt());
+        self::assertSame($user, $entity->getUpdatedBy());
+    }
+
+    public function testPartialEntityTimestampableOnly(): void
+    {
+        $user       = $this->createStub(UserInterface::class);
+        $subscriber = new TimestampableBlamableSubscriber($this->securityReturning($user));
+        $entity     = new TimestampableOnlyFixture();
+
+        // Entite Timestampable mais NON Blamable : seules les dates sont posees,
+        // aucun appel de blame (et aucune erreur).
+        $subscriber->prePersist($this->prePersistArgs($entity));
+
+        self::assertInstanceOf(DateTimeImmutable::class, $entity->getCreatedAt());
+        self::assertInstanceOf(DateTimeImmutable::class, $entity->getUpdatedAt());
+    }
+
+    /**
+     * Security stubbee renvoyant l'utilisateur fourni (ou null).
+     */
+    private function securityReturning(?UserInterface $user): Security
+    {
+        $security = $this->createStub(Security::class);
+        $security->method('getUser')->willReturn($user);
+
+        return $security;
+    }
+
+    private function prePersistArgs(object $entity): PrePersistEventArgs
+    {
+        return new PrePersistEventArgs($entity, $this->createStub(EntityManagerInterface::class));
+    }
+
+    private function preUpdateArgs(object $entity): PreUpdateEventArgs
+    {
+        $changeSet = [];
+
+        return new PreUpdateEventArgs($entity, $this->createStub(EntityManagerInterface::class), $changeSet);
+    }
+}
+
+/**
+ * Fixture interne : entite metier complete (Timestampable + Blamable) via le
+ * Trait reel teste.
+ *
+ * @internal
+ */
+final class FullAuditableFixture implements TimestampableInterface, BlamableInterface
+{
+    use TimestampableBlamableTrait;
+}
+
+/**
+ * Fixture interne : entite Timestampable seule (sans Blamable), pour verifier
+ * la dissociation des deux contrats par le Subscriber.
+ *
+ * @internal
+ */
+final class TimestampableOnlyFixture implements TimestampableInterface
+{
+    private ?DateTimeImmutable $createdAt = null;
+    private ?DateTimeImmutable $updatedAt = null;
+
+    public function getCreatedAt(): ?DateTimeImmutable
+    {
+        return $this->createdAt;
+    }
+
+    public function setCreatedAt(DateTimeImmutable $createdAt): void
+    {
+        $this->createdAt = $createdAt;
+    }
+
+    public function getUpdatedAt(): ?DateTimeImmutable
+    {
+        return $this->updatedAt;
+    }
+
+    public function setUpdatedAt(DateTimeImmutable $updatedAt): void
+    {
+        $this->updatedAt = $updatedAt;
+    }
+}