Coltura/doc/audit-log.md

Audit Log — Specification technique

Objectif

Tracer l'historique de toutes les modifications BDD dans une table audit_log append-only. L'audit est opt-in via l'attribut #[Auditable] sur les entites, expose en lecture seule via API Platform (permission RBAC core.audit_log.view), et visualise dans le frontend via une page dediee et un composant timeline reutilisable.

Regle projet : toute entite (nouvelle ou existante) doit etre annotee #[Auditable] avec #[AuditIgnore] sur les champs sensibles. L'audit n'est pas optionnel — il est obligatoire sur toutes les entites metier.

---

Architecture

src/
  Shared/
    Domain/
      Attribute/
        Auditable.php              # Attribut classe — active le tracking
        AuditIgnore.php            # Attribut propriete — exclut un champ
  Module/
    Core/
      CoreModule.php               # + permission core.audit_log.view
      Application/
        DTO/
          AuditLogOutput.php       # DTO lecture seule
      Infrastructure/
        Audit/
          AuditLogWriter.php       # Ecrit via DBAL (pas Doctrine ORM)
          RequestIdProvider.php    # UUID v4 par requete HTTP
        Doctrine/
          AuditListener.php        # Listener onFlush/postFlush
          Migrations/              # (migration dans migrations/ racine — cf. bug tri FQCN)
        ApiPlatform/
          Resource/
            AuditLogResource.php   # ApiResource read-only
          State/
            Provider/
              AuditLogProvider.php  # Provider DBAL

frontend/
  shared/
    composables/
      useAuditLog.ts               # Composable partage (page + timeline)
    components/
      audit/
        AuditTimeline.vue          # Timeline verticale reutilisable
    types/
      index.ts                     # + AuditLogEntry, AuditLogFilters, HydraView
    utils/
      api.ts                       # + support hydra:view pagination
  modules/
    core/
      pages/
        admin/
          audit-log.vue            # Page globale admin

---

Table PostgreSQL audit_log

Table non geree par Doctrine ORM (pas d'entite). Ecriture via DBAL uniquement pour eviter la recursion des listeners.

Schema

Colonne	Type	Contrainte	Description
id	uuid	PK	UUID v7 genere en PHP (Uuid::v7()->toRfc4122()) — type natif PG (16 octets vs 36 en varchar)
entity_type	varchar(100)	NOT NULL	Format module.Entity (ex: core.User, commercial.Client) — evite les collisions inter-modules
entity_id	varchar(64)	NOT NULL	ID de l'entite (supporte int et UUID)
action	varchar(10)	NOT NULL	create, update, delete
changes	jsonb	NOT NULL DEFAULT '{}'	Changements (format selon action)
performed_by	varchar(100)	NOT NULL	Username denormalise (survit a la suppression du user)
performed_at	timestamptz	NOT NULL	Horodatage de l'action
ip_address	varchar(45)	NULL	Adresse IP (null en CLI)
request_id	varchar(36)	NULL	UUID v4 par requete HTTP (null en CLI)

Index

• idx_audit_entity_time : (entity_type, entity_id, performed_at) — recherche par entite
• idx_audit_performer : (performed_by, performed_at) — recherche par utilisateur
• idx_audit_time : (performed_at) — tri chronologique global

Regles

• Append-only : pas d'UPDATE, pas de DELETE
• Colonnes en minuscules (convention PostgreSQL du projet)
• Champs sensibles exclus : password, plainPassword, token, secret ne doivent jamais apparaitre dans changes
• performed_by denormalise : string, pas FK — le nom persiste meme si l'utilisateur est supprime
• Migration : dans migrations/ (namespace racine DoctrineMigrations) a cause du bug de tri alphabetique FQCN de Doctrine Migrations 3.x entre namespaces

Contrat : ce que audit_log garantit (et ne garantit pas)

audit_log enregistre les tentatives de modification capturees par le postFlush Doctrine, ecrites via une connexion DBAL dediee (audit_connection). Ce choix est intentionnel : les lignes d'audit survivent au rollback eventuel de la transaction metier principale, ce qui permet de tracer les tentatives meme en cas d'echec applicatif.

Conséquence à connaître : si un controller enveloppe plusieurs operations dans une transaction explicite sur la connexion default et que cette transaction outermost rollback apres un flush intermediaire reussi, la ligne audit correspondante persiste sur la connexion audit alors que la modification metier a ete annulee. L'audit log peut donc contenir des lignes decrivant un etat qui n'existe pas en base metier.

En pratique :

• Ce cas est rare dans un CRM interne (les rollbacks explicites outermost sont marginaux par rapport aux flushes atomiques).
• La ligne audit garde son request_id qui permet une correlation post-mortem avec les logs applicatifs pour distinguer une tentative avortee d'un commit reussi.
• Le comportement est volontaire — pas un bug. Pour un besoin de garantie « audit = reflet exact du commit outermost », il faudrait basculer l'audit sur la meme connexion que le metier (voir AuditLogWriter), au prix de perdre la resilience au rollback partiel.

L'audit est donc un journal des intentions appliquees par l'ORM, pas une source de verite transactionnelle sur l'etat final de la DB.

---

Composants backend

AuditLogWriter

Emplacement : src/Module/Core/Infrastructure/Audit/AuditLogWriter.php

Service responsable de l'ecriture dans audit_log via Connection::executeStatement().

Dependances :

• Doctrine\DBAL\Connection — connexion DBAL dediee audit (meme DSN, service separe) pour eviter l'entanglement transactionnel avec l'ORM. Config : doctrine.dbal.connections.audit dans doctrine.yaml. Injection via #[Autowire(service: 'doctrine.dbal.audit_connection')].
• Symfony\Bundle\SecurityBundle\Security
• Symfony\Component\HttpFoundation\RequestStack
• RequestIdProvider

Methode principale :

public function log(
    string $entityType,
    string $entityId,
    string $action,
    array $changes,
): void

Comportement :

• Genere id via Uuid::v7()->toRfc4122()
• performed_by = $security->getUser()?->getUserIdentifier() ?? 'system'
• ip_address = $requestStack->getCurrentRequest()?->getClientIp()
• request_id = $requestIdProvider->getRequestId()
• performed_at = new \DateTimeImmutable('now', new \DateTimeZone('UTC'))
• Filtre les cles sensibles (password, plainPassword, token, secret) de $changes
• INSERT SQL brut via DBAL

Necessite : composer require symfony/uid

RequestIdProvider

Emplacement : src/Module/Core/Infrastructure/Audit/RequestIdProvider.php

Service singleton qui genere un UUID v4 unique par requete HTTP principale.

Comportement :

• Ecoute kernel.request via #[AsEventListener]
• Ignore les sub-requests : if (!$event->isMainRequest()) return;
• Genere Uuid::v4()->toRfc4122() a chaque requete principale
• Expose getRequestId(): ?string (null en CLI)

Attributs #[Auditable] et #[AuditIgnore]

Emplacement : src/Shared/Domain/Attribute/ (dans Shared, pas Core — tous les modules doivent y acceder)

• #[Auditable] : attribut de classe, marqueur vide. Active le tracking sur l'entite.
• #[AuditIgnore] : attribut de propriete, marqueur vide. Exclut un champ du tracking.

AuditListener

Emplacement : src/Module/Core/Infrastructure/Doctrine/AuditListener.php

Listener Doctrine (pas EventSubscriber — deprecie Symfony 8) utilisant #[AsDoctrineListener].

Evenements :

• onFlush : collecte les changesets (aucune ecriture)
• postFlush : ecrit via AuditLogWriter (hors transaction Doctrine)

Dependances :

• AuditLogWriter
• LoggerInterface

Logique onFlush :

1. Recupere UnitOfWork
2. Parcourt insertions, updates, deletions
3. Pour chaque entite : verifie #[Auditable] via ReflectionClass::getAttributes()
4. Filtre les proprietes #[AuditIgnore] + blacklist hardcodee
5. Formate les changements :
   • create : snapshot complet de toutes les proprietes non-ignorees
   • update : {champ: {old: x, new: y}} via getEntityChangeSet()
   • delete : snapshot complet
6. ManyToOne : log l'ID via ?->getId() (null-safe pour les relations nullable), pas l'objet
7. Stocke dans $pendingLogs (propriete privee)

Logique postFlush — pattern swap-and-clear (protection contre flush re-entrant) :

1. Copie $pendingLogs dans variable locale, vide immediatement $this->pendingLogs = []
2. Pour chaque log copie → AuditLogWriter::log()
3. Try/catch : erreur → $logger->error(...), jamais de crash

Cas particuliers :

• Flush sans changement → rien
• Entite sans #[Auditable] → ignoree
• Batch (fixtures, import) → chaque entite auditee, groupees par request_id
• Console → performed_by = 'system', ip_address = null, request_id = null
• ManyToMany / OneToMany : tracees via UnitOfWork::getScheduledCollectionUpdates() et getScheduledCollectionDeletions() (cf. AuditListener::captureCollectionChange). Payload {fieldName: {added: [ids], removed: [ids]}}, merge dans le log deja en attente de l'entite proprietaire si elle est aussi scheduled (insertion → snapshot enrichi, update → diff merge, delete → ignore car redondant avec le snapshot delete).

---

API Platform — Lecture seule

AuditLogResource

Emplacement : src/Module/Core/Infrastructure/ApiPlatform/Resource/AuditLogResource.php

Operations :

• GET /api/audit-logs — collection paginee (30 items/page), tri performed_at DESC
• GET /api/audit-logs/{id} — detail

Securite : is_granted('core.audit_log.view') — permission RBAC, 403 sinon

Pas d'endpoints d'ecriture : POST, PUT, PATCH, DELETE → 405

AuditLogOutput

Emplacement : src/Module/Core/Application/DTO/AuditLogOutput.php

DTO readonly avec les champs : id, entityType, entityId, action, changes, performedBy, performedAt, ipAddress, requestId.

AuditLogProvider

Emplacement : src/Module/Core/Infrastructure/ApiPlatform/State/Provider/AuditLogProvider.php

Provider DBAL (pas Doctrine ORM).

Filtres (query params, combinables en AND) :

• entity_type : filtre exact
• entity_id : filtre exact
• action : filtre exact
• performed_by : filtre exact
• performed_at[after] : date minimum (incluse)
• performed_at[before] : date maximum (incluse)

Pagination : via un DbalPaginator implementant ApiPlatform\State\Pagination\PaginatorInterface (getCurrentPage(), getLastPage(), getTotalItems(), getItemsPerPage(), count(), getIterator()). Le provider retourne ce paginator — API Platform genere automatiquement hydra:view. Pas de construction manuelle de la pagination.

Permission RBAC

Ajouter dans CoreModule::permissions() :

• core.audit_log.view

---

Frontend

Composable useAuditLog.ts

Emplacement : frontend/shared/composables/useAuditLog.ts

Composable partage, reutilise par la page globale (ticket 4) et le composant timeline (ticket 5).

Methodes :

• fetchLogs(filters?: AuditLogFilters): Promise<HydraCollection<AuditLogEntry>>
• fetchLogById(id: string): Promise<AuditLogEntry>
• fetchEntityLogs(entityType: string, entityId: string, page?: number): Promise<HydraCollection<AuditLogEntry>>

Utilise useApi().get().

Si le composable maintient du state singleton (refs module-level pour cache), il doit exposer resetAuditLog() et etre reinitialise au logout (regle CLAUDE.md).

Types

Ajouter dans frontend/shared/types/index.ts :

export interface AuditLogEntry {
    id: string
    entityType: string
    entityId: string
    action: 'create' | 'update' | 'delete'
    changes: Record<string, unknown>
    performedBy: string
    performedAt: string
    ipAddress: string | null
    requestId: string | null
}

export interface AuditLogFilters {
    entityType?: string
    entityId?: string
    action?: string
    performedBy?: string
    performedAtAfter?: string
    performedAtBefore?: string
    page?: number
}

interface HydraView {
    'hydra:first'?: string
    'hydra:last'?: string
    'hydra:next'?: string
    'hydra:previous'?: string
}

Le type HydraView doit etre ajoute dans frontend/shared/utils/api.ts (a cote de HydraCollection) et HydraCollection doit etre etendu avec un champ optionnel 'hydra:view'?: HydraView.

Page admin/audit-log.vue

Emplacement : frontend/modules/core/pages/admin/audit-log.vue

Acces : permission RBAC core.audit_log.view (verifie via usePermissions().can('core.audit_log.view'))

Elements :

• Tableau pagine avec style projet (header bg-tertiary-500, rows hover)
• Filtres : plage dates, type entite (select), utilisateur (input), action (checkboxes), bouton reset
• Filtres persistes dans les query params URL
• Ligne expandable au clic :
  • update : tableau champ / ancienne valeur / nouvelle valeur
  • create/delete : snapshot complet
• Badges action :
  • create : bg-green-100 text-green-800
  • update : bg-yellow-100 text-yellow-800
  • delete : bg-red-100 text-red-800
• Pagination prev/next via hydra:view
• Etat vide : message i18n "Aucune activite enregistree"
• Chargement initial : 30 dernieres entrees sans filtre

Sidebar

Ajouter entree dans config/sidebar.php :

• Label : sidebar.core.audit_log
• Route : /admin/audit-log
• Icon : a definir (ex: mdi:clipboard-text-clock)
• Module : core
• Permission : core.audit_log.view — filtre automatiquement cote SidebarProvider

Composant AuditTimeline.vue

Emplacement : frontend/shared/components/audit/AuditTimeline.vue

Composant reutilisable, auto-importe par Nuxt.

Props :

• entityType: string
• entityId: string | number

Comportement :

• Garde permission : si !usePermissions().can('core.audit_log.view') → rendu vide, aucun appel API
• Timeline verticale : bordure gauche (border-l-2 border-gray-200) + dots colores par action
• Chaque entree : icone + date relative FR (Intl.RelativeTimeFormat('fr')) + date absolue en tooltip + utilisateur + resume
• Update : affiche old → new par champ
• Lazy loading : 10 items initiaux + bouton "Voir plus"
• Skeleton loader pendant le chargement
• Etat vide : "Aucun historique"

Premiere integration : sur la page admin/audit-log.vue

---

i18n

Cles a ajouter dans frontend/i18n/locales/fr.json :

Structure imbriquee (respecte le format existant de fr.json) :

{
    "sidebar": {
        "core": {
            "audit_log": "Journal d'audit"
        }
    },
    "audit": {
        "action": {
            "create": "Création",
            "update": "Modification",
            "delete": "Suppression"
        },
        "entity": {
            "user": "Utilisateur"
        },
        "empty": "Aucune activité enregistrée",
        "no_results": "Aucun résultat pour ces filtres",
        "timeline": {
            "empty": "Aucun historique",
            "load_more": "Voir plus"
        },
        "filters": {
            "reset": "Réinitialiser",
            "date_from": "Du",
            "date_to": "Au",
            "entity_type": "Type d'entité",
            "user": "Utilisateur",
            "action": "Action"
        },
        "detail": {
            "field": "Champ",
            "old_value": "Ancienne valeur",
            "new_value": "Nouvelle valeur"
        }
    }
}

---

Ordre d'implementation

Ticket 1 ────► Ticket 2 ────► Ticket 3 ────┬──► Ticket 4
  Table +        Attributs +     API           │    Page admin
  Writer         Listener        read-only     │
                                               └──► Ticket 5
                                                    Timeline
                                            (4 et 5 en parallele)

---

Decisions techniques (issues reviews)

• Connexion DBAL dediee : AuditLogWriter utilise une connexion separee audit (meme DSN) pour eviter l'entanglement transactionnel avec l'ORM en batch
• PaginatorInterface : le provider retourne un DbalPaginator implementant l'interface API Platform — pas de construction manuelle hydra:view
• Type natif uuid PG : 16 octets vs 36 en varchar, index 40% plus petit sur table append-only a croissance infinie
• Pattern swap-and-clear dans postFlush : protection contre flush re-entrant
• Blacklist exact-match sur noms de proprietes (password, plainPassword, token, secret) — en defense-in-depth avec #[AuditIgnore]
• Collections to-many auditees : tracees via getScheduledCollectionUpdates / getScheduledCollectionDeletions, payload {added, removed} merge dans le changeset de l'entite proprietaire (cf. AuditListener::captureCollectionChange)
• Erreur audit silencieuse : loguee, jamais propagee — pas de retry/dead-letter (acceptable pour CRM interne)
• entity_type format module.Entity : evite collisions si deux modules ont des entites de meme nom

Dependances externes

• symfony/uid : generation UUID v7 (id) et v4 (request_id)