Import en masse & audit

À quoi ça sert

Ce module permet à un administrateur d'importer en une seule fois les données de référence d'un tenant depuis un classeur Excel multi-onglets (avec simulation avant exécution et possibilité d'annulation), et de consulter la piste d'audit de toutes les actions sensibles réalisées dans le tenant.

Prérequis

Prérequis

• Modules sous licence : HR
• Permissions : import.template, import.upload, import.view, import.execute, import.rollback, audit.read
• Rôles : ORG_ADMIN, HR_MANAGER

Comment ça marche

1. Télécharger le modèle d'import

1. Ouvrez Administration → Import (/dashboard/admin/import) et cliquez sur Télécharger le modèle.

2. Le classeur Excel généré contient 8 onglets, dans un ordre de dépendance strict (chaque onglet peut référencer les données des onglets précédents) :

   Ordre	Onglet	Contenu
   1	01_Organisations	Entités (holding/filiale/succursale)
   2	02_Departements	Départements, rattachés à une entité et éventuellement à un département parent
   3	03_Employes	Fiches employés
   4	04_Calendrier_Conges	Soldes/calendrier de congés initiaux
   5	05_Types_Ressources	Types de ressources réservables (salles, matériel)
   6	06_Ressources	Ressources réservables elles-mêmes
   7	07_Contrats	Contrats de travail
   8	08_Paie	Données de paie

2. Charger le fichier et vérifier la structure

1. Cliquez sur Importer un fichier, sélectionnez le classeur complété. Une session d'import est créée (BulkImportSession).
2. Le fichier est d'abord validé structurellement : colonnes attendues présentes, types de données corrects, cohérence entre onglets (ex. un département référencé dans 03_Employes doit exister dans 02_Departements), détection de cycles dans les hiérarchies (ex. un département qui serait son propre parent indirect).
3. Les lignes en erreur sont listées avec leur numéro de ligne, l'onglet concerné et le message d'erreur précis ; corrigez le fichier source et rechargez si nécessaire.

3. Simuler l'import (dry-run)

Cliquez sur Simuler : le moteur exécute la logique métier complète (règles de validation, calculs de paie, détection de doublons) sans rien écrire en base, et affiche pour chaque onglet le nombre de lignes qui seraient créées, mises à jour, ignorées, ou en erreur. C'est l'étape à examiner attentivement avant de lancer l'exécution réelle.

4. Exécuter l'import

1. Une fois la simulation jugée satisfaisante, cliquez sur Exécuter. Les onglets sont traités dans l'ordre de dépendance (organisations → départements → employés → congés → types de ressources → ressources → contrats → paie), chaque exécuteur dédié appliquant ses propres règles métier.
2. Un rapport d'import est généré (téléchargeable, lien pré-signé) détaillant ligne par ligne ce qui a été créé, mis à jour ou ignoré.

5. Annuler un import (rollback)

Si un import exécuté s'avère problématique, ouvrez la session correspondante et cliquez sur Annuler l'import : les enregistrements créés par cette session sont retirés (rollback), dans l'ordre inverse de leur création, afin de respecter les dépendances entre onglets.

6. Consulter la piste d'audit

1. Ouvrez Administration → Audit (/dashboard/admin/audit) : recherche globale des événements d'audit du tenant, filtrable par type d'entité, action, utilisateur et période.
2. Depuis la fiche d'un objet métier (une demande de congé, une candidature, un contrat, une facture…), l'onglet Historique affiche directement l'audit spécifique à cet enregistrement (créations, modifications, changements de statut, avec l'auteur et l'horodatage de chaque action) — l'accès à cet historique dépend de la permission propre à ce type d'entité (ex. il faut leave.approve/leave.manage/leave.create pour consulter l'audit d'une demande de congé).

Qui peut faire quoi

Permission requise	Rôles concernés
import.template	ORG_ADMIN, HR_MANAGER
import.upload	ORG_ADMIN, HR_MANAGER
import.view	ORG_ADMIN, HR_MANAGER
import.execute	ORG_ADMIN, HR_MANAGER
import.rollback	ORG_ADMIN, HR_MANAGER
audit.read	ORG_ADMIN, HR_MANAGER

Permission	Donne accès à
import.template	Télécharger le modèle Excel vierge
import.upload	Charger un nouveau fichier et créer une session d'import
import.view	Consulter les sessions d'import, leurs lignes de détail et leur rapport
import.execute	Lancer la simulation et l'exécution réelle d'un import
import.rollback	Annuler (rollback) un import déjà exécuté
audit.read	Consulter la recherche globale d'événements d'audit (/audit/events)

L'audit par entité suit la permission de son propre module

L'historique d'audit rattaché à un enregistrement précis (/audit/{entityType}/{entityId}) n'exige pas audit.read : il vérifie dynamiquement que l'appelant détient la permission de lecture propre à ce type d'entité (ex. contract.read pour un contrat, recruitment.application.read pour une candidature). audit.read ne couvre que la recherche globale et transverse.

Rôle système	Accès
ORG_ADMIN	Toutes les actions (permission globale)
HR_MANAGER	audit.read

Détails techniques

Entités import : BulkImportSession (BulkImportStatus), BulkImportLine (BulkImportLineAction : création/mise à jour/ignoré/erreur) — package app.jigi.admin.bulkimport.

Endpoints (BulkImportController, base /admin/import) :

• GET /admin/import/template (import.template) — génère le classeur vierge (ExcelTemplateService)
• GET /admin/import/sessions (import.view) — liste des sessions
• POST /admin/import/upload (import.upload) — dépôt du fichier, parsing (ExcelParserService) et validation structurelle
• GET /admin/import/sessions/{id} / /lines (import.view) — détail de session et de ses lignes
• POST /admin/import/sessions/{id}/simulate (import.execute) — dry-run complet
• POST /admin/import/sessions/{id}/execute (import.execute) — exécution réelle, onglet par onglet
• GET /admin/import/sessions/{id}/report (import.view) — redirection vers une URL pré-signée du rapport
• POST /admin/import/sessions/{id}/rollback (import.rollback) — annulation

Exécuteurs par onglet (package execution/) : OrganisationImportExecutor (01_Organisations), DepartmentImportExecutor (02_Departements), EmployeeImportExecutor (03_Employes), LeaveCalendarImportExecutor (04_Calendrier_Conges), ResourceTypeImportExecutor (05_Types_Ressources), ResourceImportExecutor (06_Ressources), ContractImportExecutor (07_Contrats), PayrollImportExecutor (08_Paie).

Validation : StructuralValidationService/BaseStructuralValidator (colonnes, types), CrossSheetValidationService (références inter-onglets), HierarchyCycleDetector (cycles dans les hiérarchies de départements), BusinessRuleValidator/PayrollArithmeticValidator (règles métier et calculs de paie), chaque erreur portant une Severity.

Entités audit : AuditEntityType (énumération centrale associant chaque type auditable à sa permission de lecture requise et à ses préfixes d'événement/action) — package app.jigi.audit.

Endpoints audit (AuditController) : GET /audit/events (audit.read, recherche transverse) ; GET /audit/{entityType}/{entityId} (permission dynamique résolue via AuditEntityType.getRequiredPermission()).

Cas d'erreur et FAQ

Que se passe-t-il si mon fichier contient une erreur sur l'onglet Employés mais que les Organisations et Départements sont corrects ? La validation structurelle et la simulation identifient précisément les lignes en erreur sur l'onglet concerné ; les autres onglets valides peuvent tout de même être exécutés, mais il est recommandé de corriger l'intégralité du fichier avant de lancer l'exécution réelle pour garder une session cohérente.

Pourquoi dois-je toujours simuler avant d'exécuter ? La simulation exécute la même logique métier que l'import réel (calculs de paie, détection de doublons, règles de validation) sans rien écrire en base — c'est le seul moyen de vérifier l'impact exact avant de modifier les données réelles du tenant.

Peut-on annuler un import partiellement, uniquement sur un onglet ? Non, le rollback annule l'ensemble des enregistrements créés par la session, dans l'ordre inverse des dépendances (paie → contrats → ressources → types de ressources → congés → employés → départements → organisations), pour garantir la cohérence référentielle.

Un manager peut-il consulter l'historique d'audit d'une demande de congé de son équipe ? Oui, s'il détient leave.approve ou leave.create sur cette demande, sans avoir besoin de la permission transverse audit.read — l'accès à l'audit par entité suit la permission propre au module concerné.

Où trouver le rapport détaillé après une exécution ? Depuis la fiche de la session d'import, le bouton Télécharger le rapport génère un lien pré-signé temporaire vers le fichier détaillé ligne par ligne.

Voir aussi

• Employés & contrats
• Organisation
• Guide RH