API Workflow Plaintes

L'API Workflow Plaintes permet de gérer le cycle de vie et les transitions de phase des plaintes.

Vue d'ensemble

Endpoint	Méthode	Description
/api/plaintes/{id}/workflow	GET	Timeline du workflow
/api/plaintes/{id}/workflow/initier	POST	Initialiser le workflow
/api/plaintes/{id}/avancer-phase	POST	Passer à la phase suivante
/api/plaintes/{id}/valider-conditions	GET	Valider les conditions
/api/plaintes/en-retard	GET	Plaintes en retard
/api/plaintes/workflow/stats	GET	Statistiques workflow

Authentification

Tous les endpoints nécessitent ROLE_USER minimum.

---

Phases du workflow

Phase	Description	Délai
reception	Réception et enregistrement	1 jour
tri	Tri et classification	2 jours
investigation	Investigation et analyse	5 jours
resolution	Résolution proposée	3 jours
validation	Validation de la résolution	2 jours
cloture	Clôture et archivage	1 jour

---

Timeline du workflow

Endpoint

GET /api/plaintes/{id}/workflow

Réponse

{
  "success": true,
  "data": {
    "phaseActuelle": "investigation",
    "phaseLabel": "Investigation et analyse",
    "dateDebutPhase": "2025-03-10T08:00:00+00:00",
    "dateEcheance": "2025-03-15T08:00:00+00:00",
    "estEnRetard": false,
    "joursRestants": 2,
    "timeline": [
      {
        "phase": "reception",
        "label": "Réception",
        "statut": "complete",
        "dateDebut": "2025-03-08T10:30:00+00:00",
        "dateFin": "2025-03-08T14:00:00+00:00",
        "duree": "3h30m",
        "user": {
          "id": "...",
          "nom": "Agent Accueil"
        }
      },
      {
        "phase": "tri",
        "label": "Tri et classification",
        "statut": "complete",
        "dateDebut": "2025-03-08T14:00:00+00:00",
        "dateFin": "2025-03-10T08:00:00+00:00",
        "duree": "1j18h",
        "user": {
          "id": "...",
          "nom": "Superviseur"
        },
        "notes": "Classé comme plainte de paiement"
      },
      {
        "phase": "investigation",
        "label": "Investigation",
        "statut": "en_cours",
        "dateDebut": "2025-03-10T08:00:00+00:00",
        "dateEcheance": "2025-03-15T08:00:00+00:00",
        "user": {
          "id": "...",
          "nom": "Agent Investigation"
        }
      },
      {
        "phase": "resolution",
        "label": "Résolution",
        "statut": "a_venir"
      },
      {
        "phase": "validation",
        "label": "Validation",
        "statut": "a_venir"
      },
      {
        "phase": "cloture",
        "label": "Clôture",
        "statut": "a_venir"
      }
    ],
    "historique": [
      {
        "date": "2025-03-08T10:30:00+00:00",
        "action": "creation",
        "description": "Plainte créée",
        "user": "Agent Accueil"
      },
      {
        "date": "2025-03-08T14:00:00+00:00",
        "action": "avancement_phase",
        "description": "Passage en phase Tri",
        "user": "Agent Accueil"
      },
      {
        "date": "2025-03-10T08:00:00+00:00",
        "action": "avancement_phase",
        "description": "Passage en phase Investigation",
        "user": "Superviseur"
      }
    ]
  }
}

---

Initialiser le workflow

Endpoint

POST /api/plaintes/{id}/workflow/initier

Description

Initialise le workflow pour une plainte nouvellement créée. Place la plainte en phase "réception".

Contraintes

• Le workflow ne doit pas être déjà initialisé

Réponse

{
  "success": true,
  "message": "Workflow initialisé",
  "data": {
    "phase": "reception",
    "phaseLabel": "Réception et enregistrement",
    "dateEcheancePhase": "2025-03-16T10:30:00+00:00"
  }
}

Erreur si déjà initialisé

{
  "success": false,
  "error": "Le workflow est déjà initialisé pour cette plainte"
}

---

Avancer à la phase suivante

Endpoint

POST /api/plaintes/{id}/avancer-phase

Corps de la requête

{
  "commentaire": "Investigation terminée, prêt pour résolution"
}

Contraintes

• Le workflow doit être initialisé
• Les conditions de la phase actuelle doivent être remplies

Réponse succès

{
  "success": true,
  "message": "Phase avancée avec succès",
  "data": {
    "anciennePhase": "investigation",
    "nouvellePhase": "resolution",
    "phaseLabel": "Résolution proposée",
    "dateEcheancePhase": "2025-03-18T10:30:00+00:00"
  }
}

Erreur si conditions non remplies

{
  "success": false,
  "error": "Impossible d'avancer à la phase suivante",
  "conditionsManquantes": [
    "Un responsable doit être assigné",
    "Au moins un commentaire d'investigation requis"
  ]
}

---

Valider les conditions de phase

Endpoint

GET /api/plaintes/{id}/valider-conditions

Réponse

{
  "success": true,
  "data": {
    "phaseActuelle": "investigation",
    "peutAvancer": true,
    "conditions": [
      {
        "condition": "Responsable assigné",
        "valide": true
      },
      {
        "condition": "Catégorie définie",
        "valide": true
      },
      {
        "condition": "Au moins un commentaire d'investigation",
        "valide": true
      }
    ],
    "prochainePhase": "resolution"
  }
}

---

Plaintes en retard

Endpoint

GET /api/plaintes/en-retard

Réponse

{
  "success": true,
  "data": {
    "total": 12,
    "parPhase": {
      "tri": 2,
      "investigation": 7,
      "resolution": 3
    },
    "plaintes": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "reference": "PLT-2025-001234",
        "objet": "Paiement non reçu",
        "phase": "investigation",
        "phaseLabel": "Investigation",
        "dateEcheance": "2025-03-12T08:00:00+00:00",
        "joursRetard": 3,
        "responsable": {
          "id": "...",
          "nom": "Agent Investigation"
        },
        "equipe": {
          "id": "...",
          "nom": "Équipe Paiements"
        }
      }
    ]
  }
}

---

Statistiques workflow

Endpoint

GET /api/plaintes/workflow/stats

Réponse

{
  "success": true,
  "data": {
    "totalPlaintes": 1500,
    "parPhase": {
      "reception": 15,
      "tri": 25,
      "investigation": 120,
      "resolution": 45,
      "validation": 20,
      "cloture": 5,
      "termine": 1270
    },
    "enRetard": {
      "total": 12,
      "pourcentage": 5.8
    },
    "tempsTraitementMoyen": {
      "global": 8.5,
      "parPhase": {
        "reception": 0.5,
        "tri": 1.2,
        "investigation": 4.0,
        "resolution": 2.0,
        "validation": 0.8
      },
      "unite": "jours"
    },
    "tendance": {
      "semainePrecedente": {
        "nouvelles": 45,
        "resolues": 52,
        "enRetard": 8
      },
      "semaineCourante": {
        "nouvelles": 38,
        "resolues": 41,
        "enRetard": 12
      }
    },
    "performance": {
      "tauxResolutionDansDelai": 94.2,
      "tauxEscalade": 8.5,
      "satisfactionMoyenne": 4.2
    }
  }
}

---

Conditions par phase

Phase Réception → Tri

• Plainte enregistrée avec toutes les informations obligatoires
• Plaignant identifié ou anonymat validé

Phase Tri → Investigation

• Catégorie assignée
• Priorité définie
• Équipe ou responsable assigné

Phase Investigation → Résolution

• Au moins un commentaire d'investigation
• Cause identifiée
• Documentation complète si requise

Phase Résolution → Validation

• Proposition de résolution documentée
• Accord du plaignant (si applicable)
• Actions correctives listées

Phase Validation → Clôture

• Résolution validée par le superviseur
• Notification au plaignant envoyée
• Satisfaction recueillie (si applicable)