# Diagrammes de Flux Métier

Ce document présente les diagrammes de séquence pour les principaux flux métier de l'application de création de groupes.

## Table des Matières

1. [Flux d'Authentification](#1-flux-dauthentification)
2. [Flux de Création et Gestion de Projet](#2-flux-de-création-et-gestion-de-projet)
3. [Flux de Gestion des Personnes](#3-flux-de-gestion-des-personnes)
4. [Flux de Création de Groupe](#4-flux-de-création-de-groupe)
   - [4.1 Création Manuelle](#41-création-manuelle)
   - [4.2 Création Automatique](#42-création-automatique)
5. [Flux de Collaboration en Temps Réel](#5-flux-de-collaboration-en-temps-réel)

## 1. Flux d'Authentification

Le flux d'authentification utilise OAuth 2.0 avec GitHub comme fournisseur d'identité.

```mermaid
sequenceDiagram
    participant User as Utilisateur
    participant Frontend as Frontend (Next.js)
    participant Backend as Backend (NestJS)
    participant GitHub as GitHub OAuth
    
    User->>Frontend: Clic sur "Se connecter avec GitHub"
    Frontend->>Backend: Redirection vers /auth/github
    Backend->>GitHub: Redirection vers GitHub OAuth
    GitHub->>User: Demande d'autorisation
    User->>GitHub: Accepte l'autorisation
    GitHub->>Backend: Redirection avec code d'autorisation
    Backend->>GitHub: Échange code contre token d'accès
    GitHub->>Backend: Retourne token d'accès
    Backend->>GitHub: Requête informations utilisateur
    GitHub->>Backend: Retourne informations utilisateur
    Backend->>Backend: Crée/Met à jour l'utilisateur en BDD
    Backend->>Backend: Génère JWT (access + refresh tokens)
    Backend->>Frontend: Redirection avec tokens JWT
    Frontend->>Frontend: Stocke les tokens
    Frontend->>User: Affiche interface authentifiée
```

## 2. Flux de Création et Gestion de Projet

Ce flux illustre le processus de création et de gestion d'un projet par un utilisateur.

```mermaid
sequenceDiagram
    participant User as Utilisateur
    participant Frontend as Frontend (Next.js)
    participant API as API (NestJS)
    participant DB as Base de données
    
    User->>Frontend: Accède au dashboard
    Frontend->>API: GET /api/projects
    API->>DB: Requête les projets de l'utilisateur
    DB->>API: Retourne les projets
    API->>Frontend: Retourne la liste des projets
    Frontend->>User: Affiche les projets existants
    
    User->>Frontend: Clic sur "Créer un nouveau projet"
    Frontend->>User: Affiche le formulaire de création
    User->>Frontend: Remplit le formulaire (nom, description)
    Frontend->>API: POST /api/projects
    API->>DB: Insère le nouveau projet
    DB->>API: Confirme la création
    API->>Frontend: Retourne les détails du projet créé
    Frontend->>User: Affiche la page du projet
    
    User->>Frontend: Modifie les détails du projet
    Frontend->>API: PATCH /api/projects/{id}
    API->>DB: Met à jour le projet
    DB->>API: Confirme la mise à jour
    API->>Frontend: Retourne les détails mis à jour
    Frontend->>User: Affiche les détails mis à jour
    
    User->>Frontend: Clic sur "Supprimer le projet"
    Frontend->>User: Demande confirmation
    User->>Frontend: Confirme la suppression
    Frontend->>API: DELETE /api/projects/{id}
    API->>DB: Supprime le projet et ses données associées
    DB->>API: Confirme la suppression
    API->>Frontend: Retourne confirmation
    Frontend->>User: Redirige vers le dashboard
```

## 3. Flux de Gestion des Personnes

Ce flux illustre le processus d'ajout et de gestion des personnes dans un projet.

```mermaid
sequenceDiagram
    participant User as Utilisateur
    participant Frontend as Frontend (Next.js)
    participant API as API (NestJS)
    participant DB as Base de données
    participant WS as WebSocket
    
    User->>Frontend: Accède à un projet
    Frontend->>API: GET /api/projects/{id}
    API->>DB: Requête les détails du projet
    DB->>API: Retourne les détails du projet
    API->>Frontend: Retourne les détails du projet
    Frontend->>User: Affiche la page du projet
    
    User->>Frontend: Clic sur "Gérer les personnes"
    Frontend->>API: GET /api/projects/{id}/persons
    API->>DB: Requête les personnes du projet
    DB->>API: Retourne les personnes
    API->>Frontend: Retourne la liste des personnes
    Frontend->>User: Affiche la liste des personnes
    
    User->>Frontend: Clic sur "Ajouter une personne"
    Frontend->>User: Affiche le formulaire d'ajout
    User->>Frontend: Remplit les attributs (prénom, nom, genre, niveau technique, etc.)
    Frontend->>API: POST /api/projects/{id}/persons
    API->>DB: Insère la nouvelle personne
    DB->>API: Confirme l'ajout
    API->>Frontend: Retourne les détails de la personne
    API->>WS: Émet événement "personAdded"
    WS->>Frontend: Notifie les clients connectés
    Frontend->>User: Met à jour la liste des personnes
    
    User->>Frontend: Modifie les attributs d'une personne
    Frontend->>API: PATCH /api/persons/{id}
    API->>DB: Met à jour la personne
    DB->>API: Confirme la mise à jour
    API->>Frontend: Retourne les détails mis à jour
    API->>WS: Émet événement "personUpdated"
    WS->>Frontend: Notifie les clients connectés
    Frontend->>User: Affiche les détails mis à jour
    
    User->>Frontend: Clic sur "Supprimer une personne"
    Frontend->>User: Demande confirmation
    User->>Frontend: Confirme la suppression
    Frontend->>API: DELETE /api/persons/{id}
    API->>DB: Supprime la personne
    DB->>API: Confirme la suppression
    API->>Frontend: Retourne confirmation
    API->>WS: Émet événement "personDeleted"
    WS->>Frontend: Notifie les clients connectés
    Frontend->>User: Met à jour la liste des personnes
    
    User->>Frontend: Ajoute un tag à une personne
    Frontend->>API: POST /api/persons/{id}/tags
    API->>DB: Associe le tag à la personne
    DB->>API: Confirme l'association
    API->>Frontend: Retourne la personne mise à jour
    API->>WS: Émet événement "personTagged"
    WS->>Frontend: Notifie les clients connectés
    Frontend->>User: Affiche la personne avec le tag
```

## 4. Flux de Création de Groupe

### 4.1 Création Manuelle

Ce flux illustre le processus de création manuelle de groupes.

```mermaid
sequenceDiagram
    participant User as Utilisateur
    participant Frontend as Frontend (Next.js)
    participant API as API (NestJS)
    participant DB as Base de données
    participant WS as WebSocket
    
    User->>Frontend: Accède à un projet
    Frontend->>API: GET /api/projects/{id}
    API->>DB: Requête les détails du projet
    DB->>API: Retourne les détails du projet
    API->>Frontend: Retourne les détails du projet
    Frontend->>User: Affiche la page du projet
    
    User->>Frontend: Clic sur "Créer des groupes"
    Frontend->>API: GET /api/projects/{id}/persons
    API->>DB: Requête les personnes du projet
    DB->>API: Retourne les personnes
    API->>Frontend: Retourne la liste des personnes
    Frontend->>User: Affiche l'interface de création de groupes
    
    User->>Frontend: Clic sur "Création manuelle"
    Frontend->>User: Affiche l'interface de glisser-déposer
    User->>Frontend: Crée un nouveau groupe
    Frontend->>API: POST /api/projects/{id}/groups
    API->>DB: Insère le nouveau groupe
    DB->>API: Confirme la création
    API->>Frontend: Retourne les détails du groupe
    API->>WS: Émet événement "groupCreated"
    WS->>Frontend: Notifie les clients connectés
    Frontend->>User: Affiche le groupe créé
    
    User->>Frontend: Glisse-dépose des personnes dans le groupe
    Frontend->>API: POST /api/groups/{id}/persons
    API->>DB: Associe les personnes au groupe
    DB->>API: Confirme l'association
    API->>Frontend: Retourne le groupe mis à jour
    API->>WS: Émet événement "personMoved"
    WS->>Frontend: Notifie les clients connectés
    Frontend->>User: Affiche le groupe avec les personnes
    
    User->>Frontend: Renomme le groupe
    Frontend->>API: PATCH /api/groups/{id}
    API->>DB: Met à jour le nom du groupe
    DB->>API: Confirme la mise à jour
    API->>Frontend: Retourne les détails mis à jour
    API->>WS: Émet événement "groupUpdated"
    WS->>Frontend: Notifie les clients connectés
    Frontend->>User: Affiche le groupe renommé
    
    User->>Frontend: Clic sur "Enregistrer les groupes"
    Frontend->>API: PUT /api/projects/{id}/groups/save
    API->>DB: Enregistre l'état final des groupes
    DB->>API: Confirme l'enregistrement
    API->>Frontend: Retourne confirmation
    Frontend->>User: Affiche message de confirmation
```

### 4.2 Création Automatique

Ce flux illustre le processus de création automatique de groupes équilibrés.

```mermaid
sequenceDiagram
    participant User as Utilisateur
    participant Frontend as Frontend (Next.js)
    participant API as API (NestJS)
    participant DB as Base de données
    participant Algorithm as Algorithme de Groupes
    participant WS as WebSocket
    
    User->>Frontend: Accède à un projet
    Frontend->>API: GET /api/projects/{id}
    API->>DB: Requête les détails du projet
    DB->>API: Retourne les détails du projet
    API->>Frontend: Retourne les détails du projet
    Frontend->>User: Affiche la page du projet
    
    User->>Frontend: Clic sur "Créer des groupes"
    Frontend->>API: GET /api/projects/{id}/persons
    API->>DB: Requête les personnes du projet
    DB->>API: Retourne les personnes
    API->>Frontend: Retourne la liste des personnes
    Frontend->>User: Affiche l'interface de création de groupes
    
    User->>Frontend: Clic sur "Création automatique"
    Frontend->>User: Affiche les options de génération
    User->>Frontend: Définit le nombre de groupes souhaités
    User->>Frontend: Sélectionne un preset (équilibré par niveau, etc.)
    Frontend->>API: POST /api/projects/{id}/groups/generate
    API->>Algorithm: Transmet les personnes et les paramètres
    Algorithm->>Algorithm: Exécute l'algorithme de répartition
    Algorithm->>API: Retourne les groupes générés
    API->>DB: Insère les groupes générés
    DB->>API: Confirme la création
    API->>Frontend: Retourne les groupes générés
    API->>WS: Émet événement "groupsGenerated"
    WS->>Frontend: Notifie les clients connectés
    Frontend->>User: Affiche les groupes générés
    
    User->>Frontend: Ajuste manuellement certains groupes
    Frontend->>API: PATCH /api/groups/{id}/persons
    API->>DB: Met à jour les associations
    DB->>API: Confirme la mise à jour
    API->>Frontend: Retourne les groupes mis à jour
    API->>WS: Émet événement "groupsUpdated"
    WS->>Frontend: Notifie les clients connectés
    Frontend->>User: Affiche les groupes ajustés
    
    User->>Frontend: Clic sur "Enregistrer les groupes"
    Frontend->>API: PUT /api/projects/{id}/groups/save
    API->>DB: Enregistre l'état final des groupes
    DB->>API: Confirme l'enregistrement
    API->>Frontend: Retourne confirmation
    Frontend->>User: Affiche message de confirmation
```

## 5. Flux de Collaboration en Temps Réel

Ce flux illustre le processus de collaboration en temps réel entre plusieurs utilisateurs travaillant sur le même projet.

```mermaid
sequenceDiagram
    participant User1 as Utilisateur 1
    participant Frontend1 as Frontend 1
    participant User2 as Utilisateur 2
    participant Frontend2 as Frontend 2
    participant API as API (NestJS)
    participant WS as WebSocket Gateway
    participant DB as Base de données
    
    User1->>Frontend1: Se connecte au projet
    Frontend1->>API: GET /api/projects/{id}
    API->>DB: Requête les détails du projet
    DB->>API: Retourne les détails du projet
    API->>Frontend1: Retourne les détails du projet
    Frontend1->>User1: Affiche la page du projet
    
    Frontend1->>WS: Connexion WebSocket
    Frontend1->>WS: Rejoint la salle "project:{id}"
    WS->>Frontend1: Confirme la connexion
    
    User2->>Frontend2: Se connecte au même projet
    Frontend2->>API: GET /api/projects/{id}
    API->>DB: Requête les détails du projet
    DB->>API: Retourne les détails du projet
    API->>Frontend2: Retourne les détails du projet
    Frontend2->>User2: Affiche la page du projet
    
    Frontend2->>WS: Connexion WebSocket
    Frontend2->>WS: Rejoint la salle "project:{id}"
    WS->>Frontend2: Confirme la connexion
    WS->>Frontend1: Notifie qu'un autre utilisateur a rejoint
    Frontend1->>User1: Affiche notification "Utilisateur 2 a rejoint"
    
    User1->>Frontend1: Crée un nouveau groupe
    Frontend1->>API: POST /api/projects/{id}/groups
    API->>DB: Insère le nouveau groupe
    DB->>API: Confirme la création
    API->>Frontend1: Retourne les détails du groupe
    API->>WS: Émet événement "groupCreated"
    WS->>Frontend2: Transmet l'événement "groupCreated"
    Frontend2->>User2: Met à jour l'interface avec le nouveau groupe
    
    User2->>Frontend2: Déplace une personne dans le groupe
    Frontend2->>API: PATCH /api/groups/{id}/persons
    API->>DB: Met à jour les associations
    DB->>API: Confirme la mise à jour
    API->>Frontend2: Retourne le groupe mis à jour
    API->>WS: Émet événement "personMoved"
    WS->>Frontend1: Transmet l'événement "personMoved"
    Frontend1->>User1: Met à jour l'interface avec le mouvement
    
    User1->>Frontend1: Renomme le groupe
    Frontend1->>API: PATCH /api/groups/{id}
    API->>DB: Met à jour le nom du groupe
    DB->>API: Confirme la mise à jour
    API->>Frontend1: Retourne les détails mis à jour
    API->>WS: Émet événement "groupUpdated"
    WS->>Frontend2: Transmet l'événement "groupUpdated"
    Frontend2->>User2: Met à jour l'interface avec le nouveau nom
    
    User2->>Frontend2: Se déconnecte du projet
    Frontend2->>WS: Quitte la salle "project:{id}"
    WS->>Frontend1: Notifie qu'un utilisateur a quitté
    Frontend1->>User1: Affiche notification "Utilisateur 2 a quitté"
```