Audit trail

L'audit trail est l'historique des actions importantes. Il permet de comprendre ce qui s'est passé, qui a agi, quand, sur quel objet et avec quel résultat.

Pourquoi l'audit existe

• Répondre aux demandes support.
• Comprendre une erreur ou un blocage.
• Vérifier une décision admin.
• Prouver une validation, un refus ou une modification.
• Contrôler les actions sensibles.
• Alimenter la conformité et les contrôles internes.

Workflow d'audit

flowchart TD
  action["Action importante"] --> contexte["Capturer auteur, organisation, objet et date"]
  contexte --> details["Ajouter action, résultat, motif et métadonnées"]
  details --> sensible{"Trace sensible ?"}
  sensible -->|Oui| protection["Restreindre la lecture aux profils autorisés"]
  sensible -->|Non| stockage["Stocker la trace"]
  protection --> stockage
  stockage --> consultation["Recherche support, audit ou conformité"]
  stockage --> export["Export rapport ou synchronisation analytique"]

Actions à historiser

Contenu attendu d'une trace

L'ancienne et la nouvelle valeur ne sont pas des colonnes dédiées: elles sont stockées dans les métadonnées libres de la trace uniquement quand le code qui déclenche l'événement choisit de les fournir (ex. un changement d'email consigne previousEmail/newEmail). Un événement qui ne fournit pas ces clés ne laisse pas de comparatif avant/après.

Règles

• Une trace ne doit pas être modifiée comme une donnée ordinaire.
• Les traces sensibles doivent rester réservées aux profils autorisés.
• Une action automatique doit être distinguée d'une action humaine.
• L'audit doit permettre de reconstituer un workflow important.
• La consultation de l'audit trail est réservée aux comptes admin: pas d'accès self-service, et le contrôle porte sur le statut admin, pas sur un profil admin particulier (finance, support, compliance…).

Ce qui est implémenté

• Une trace d'audit contient un événement, une organisation, une personne, une IP, des métadonnées libres (meta) et une liste d'entités liées (related, ex. { type: "item", shortId }).
• Les traces peuvent être recherchées par identifiant de trace, par personne, ou par type + identifiant d'entité liée (la recherche par entité liée couvre aussi la personne elle-même).
• Un filtre par période (dernière heure, aujourd'hui, semaine, mois, année) n'est appliqué que sur une recherche par entité liée de type personne; il n'existe pas pour les autres types d'entité.
• Sans filtre (ni identifiant de trace, ni personne, ni entité liée), la recherche est bornée aux 500 traces les plus récentes pour éviter un parcours complet de la table.
• Les résultats d'audit sont triés du plus récent au plus ancien.
• Un enrichissement optionnel (include: person) permet de renvoyer email, prénom et nom de la personne concernée avec chaque trace.
• La création d'une enchère crée une trace BID_CREATED avec le détail de l'offre (organisation, personne, montant, lot) en métadonnées.
• Un refus d'autorisation d'accès à une vente crée une trace SALE_AUTHORIZATION avec le statut et la raison; elle n'est créée que lorsque l'accès est refusé, pas à chaque contrôle réussi.
• Autres événements observés dans le code: PERSON_LOGIN, USER_VALIDATION, PERSON_CHANGE_EMAIL, PERSON_CHANGE_ORGANISATION, ADD_USER_TO_ORGANISATION, ADDED_BY_ADMIN_TO_ORGANISATION, ACCEPTED_INVITATION, ORGANISATION_REGISTERING, USER_CGV_ACCEPTED, PERSON_BLACKLISTED/PERSON_UNBLACKLISTED, ORGANISATION_BLACKLISTED/ORGANISATION_UNBLACKLISTED, ORGANISATION_KYB_INTERNAL_VALIDATED/ORGANISATION_KYB_INTERNAL_REFUSED.
• Correctif: une précédente version de cette page affirmait que le service exposait aussi des opérations de mise à jour et de suppression de traces. Vérification faite sur le contrat API réel (packages/api-sdk/src/api/contract/audit-trail.contract.ts) et sur le service qui porte le modèle (auctelia/reporting, table auditTrails, sans colonne deletedAt): seules la lecture par identifiant/personne/entité liée et une recherche paginée sont exposées. Aucune route de création, modification ou suppression d'une trace n'a été retrouvée; une trace d'audit apparaît donc en pratique immuable une fois créée.
• Aucune purge ni politique de rétention automatique des traces n'a été identifiée, ni côté front (tars-monorepo) ni dans les services backend consultés (auctelia/reporting, auctelia/api, auctelia/jobs, auctelia/crons-service): à vérifier auprès de l'équipe si une contrainte de conservation existe ailleurs (infra, conformité, purge en base directe).
• Les exports analytiques peuvent synchroniser les traces créées ou supprimées.