ficheagent/plan.md

Génère l’architecture complète d’une application Laravel 12 pour gérer un workflow d’intégration d’agents dans une collectivité territoriale.

Stack obligatoire : Laravel 12, PHP 8.3, MySQL 8, Vue 3, Inertia, Tailwind, Spatie Permission.

    L’application doit inclure :
    Gestion agents
    Workflow basé sur machine à états
    Génération automatique de tâches par service
    SLA + relances automatiques
    Checklists dynamiques
    Tableaux de bord par rôle
    Notifications
    Journal d’audit
    Offboarding

    Respecter :
    Architecture propre (Services, Actions, DTO, Policies)
    Pas de logique métier dans controllers
    Tests unitaires
    Code maintenable

    Génère :
    Migrations
    Models avec relations
    Services métier
    Enums
    Exemple de controllers
    Structure Vue 3 + Inertia
    Scheduler SLA
    Seeders de rôles

1. Contexte Projet

Objectif
Développer une application interne en Laravel 12 permettant de gérer le processus d’intégration d’un nouvel agent dans une collectivité territoriale.

L’application doit :
Centraliser les demandes d’intégration
Générer automatiquement les tâches par service
Permettre la validation indépendante des services
Suivre les statuts globaux
Gérer des checklists dynamiques
Intégrer un système de rôles
Fournir des tableaux de bord par service
Gérer des SLA et relances automatiques

2. Stack Technique Imposée
Laravel 12
PHP 8.3+
MySQL 8+
Vue 3
Inertia.js
TailwindCSS
Spatie Laravel Permission
Laravel Notifications
Laravel Queues
Laravel Policies
Laravel Form Requests

3. Architecture Logique Globale
Architecture en couches
App/
 ├── Actions/
 ├── DTOs/
 ├── Enums/
 ├── Events/
 ├── Http/
 │    ├── Controllers/
 │    ├── Requests/
 │    └── Resources/
 ├── Models/
 ├── Notifications/
 ├── Policies/
 ├── Services/
 ├── States/
 └── Jobs/

4. Modèle de Données Détaillé
Standard Laravel + Spatie

    4.2 Table services
    Représente :
    - DSI
    - Bâtiment
    - Parc Auto
    - RH

        id
        name
        code (dsi, batiment, parc_auto, rh)
        is_active
        timestamps

    4.3 Table agents
        id
        first_name
        last_name
        email
        position
        department
        arrival_date
        integration_status (enum)
        created_by
        validated_by_rh_at
        timestamps

    4.4 Table integration_requests
        id
        agent_id
        template_id (nullable)
        status (enum)
        global_deadline
        completed_at
        timestamps

    4.5 Table service_tasks
        id
        integration_request_id
        service_id
        status (enum)
        sla_deadline
        started_at
        completed_at
        validated_by
        timestamps

    4.6 Table task_items
        id
        service_task_id
        label
        is_mandatory
        is_completed
        completed_at
        completed_by
        timestamps

    4.7 Table integration_templates
        id
        name
        description
        is_active
        timestamps

    4.8 Table template_service_items
        id
        template_id
        service_id
        label
        is_mandatory

5. Machine à États (State Pattern)
Utiliser un système basé sur Enum + Classes d'état.

    Enum IntegrationStatus
        Draft
        PendingRHValidation
        InProgress
        WaitingServices
        Completed
        Cancelled
        Rejected

    Enum ServiceTaskStatus
        Pending
        InProgress
        WaitingValidation
        Completed
        Rejected

Implémentation
    Créer :
    App/States/Integration/
    App/States/ServiceTask/

Chaque état doit :
    Autoriser certaines transitions
    Bloquer les transitions invalides
    Déclencher des événements

6. Logique Métier (Service Layer)

    6.1 IntegrationService

    Responsabilités :
        Créer une demande
        Générer les tâches automatiquement
        Calculer les deadlines SLA
        Vérifier si toutes les tâches sont complètes
        Clôturer l’intégration

    6.2 ServiceTaskManager

        Démarrer tâche
        Valider tâche
        Refuser tâche
        Ajouter commentaire

7. Système de Notifications
À implémenter :
    Notification quand RH valide
    Notification quand tâche assignée
    Relance automatique si SLA dépassé
    Notification fin intégration

Utiliser :
    Notifications database
    Email
    Queue

8. Gestion des SLA
Créer :
    Job CheckSlaDeadlines
    Planifié via scheduler :
    $schedule->job(CheckSlaDeadlines::class)->everyHour();

Logique :
    Cherche tâches en retard
    Envoie notification
    Marque comme "overdue"

9. Gestion des Rôles
Avec Spatie :

    Rôles :
        Admin
        RH
        DSI
        Batiment
        ParcAuto
        Prescripteur

    Permissions :
        create integration
        validate rh
        manage dsi tasks
        manage batiment tasks
        manage parc auto tasks
        view dashboard
        export reports      

10. Dashboards
    Dashboard RH
        Intégrations en attente validation
        Retards
        Statistiques mensuelles

    Dashboard Service
        Tâches assignées
        Tâches urgentes
        Tâches en retard

    Dashboard Admin
        Vue globale
        KPI
        Temps moyen d’intégration
        Répartition par service

🎨 11. Frontend (Vue 3 + Inertia)
    Pages :
        Integration/Index
        Integration/Create
        Integration/Show
        Dashboard/RH
        Dashboard/Service
        Dashboard/Admin
        Templates/Index
        Templates/Edit

    Composants :
        StatusBadge
        ChecklistComponent
        ServiceTaskCard
        TimelineComponent
        SlaIndicator
        ConfirmationModal

12. Journal d’Audit
    Créer table :     
    activity_logs
        id
        user_id
        subject_type
        subject_id
        action
        description
        properties (json)
        created_at

    Ou utiliser :
        Spatie Activitylog

13. Offboarding
    Même structure que intégration :
    Ajouter colonne :  
        type (onboarding / offboarding)

14. Sécurité
    Authentification : Laravel Sanctum
    Autorisation : Laravel Policies
    Protection CSRF
    Rate limiting
    Validation des entrées
    Protection contre XSS
    Protection contre SQL Injection

15. Standards de Développement
    Respecter SOLID
    Utiliser FormRequest
    Utiliser Policies
    Pas de logique métier dans les controllers
    Couvrir les transitions avec tests PHPUnit
    Générer factories
    Générer seeders

16. Tests Obligatoires
    Test création intégration
    Test génération tâches auto
    Test transition statut
    Test clôture automatique
    Test dépassement SLA