Matching instantané

Voir aussi : Reservation Admin — réservation par un admin (30 min), même affichage rouge. Modèle de données : voir entities/instant_matching.md — tables instant_matching_reservation et algo_matching_trace.

Vue d'ensemble

Le matching instantané permet de réserver un jeune + 3 bénévoles ensemble pendant 15 minutes. Pendant ce temps, ces 4 profils ne sont matchables par personne (ni admin, ni autre jeune). Le jeune dispose de 15 minutes pour choisir un des 3 mentors proposés ; sa sélection déclenche la création du binôme.

Accès jeune (canAccess)

Un jeune peut accéder au matching instantané si toutes les conditions suivantes sont remplies :

Implémentation alignée front/back : front/services/reservation.js et InstantMatchingService.canAccess.

Le programme (EL, PP, PNP, etc.) et la région scolaire ne conditionnent plus l'accès.

Extraction LLM (student_pivot)

Le champ libre jeune.precision n’existe plus dans l’inscription / onboarding V2. Pendant l’onboarding mentoré, juste avant la page genre, dema1n concatène les champs ouverts puis appelle POST {LLM_EXTRACT_SERVICE_URL}/student_pivot. La page secteurs n’est pas un point de passage fiable : elle est sautée quand les secteurs sont déjà remplis à l’inscription.

Pas d’extraction depuis le BO ni le profil, et pas de cron de rattrapage. Skip si user.sandbox === 'MVLS' ou si la concaténation est vide. Code : buildStudentPivotText, JeuneService.extractStudentPivotIfNeeded (déclenché par OnboardingService.extractStudentPivotBeforeGenre quand POST /onboarding/next renvoie le panel /onboarding/jeune/genre).

Microservice de matching

Le service MatchingAlgoService appelle un microservice externe pour le matching personnalisé.

Body envoyé au microservice

Chaque champ est construit à partir de la table jeune ou de jeune_extrait_precisions. Aucune valeur de repli : si la source est vide, on envoie '' (string) ou [] (array).

Format niveau1 / niveau2 : tableaux d'objets { niveau1: string, niveau2: string }, jusqu'à 3 paires par champ. Exemple :

"jeune_secteur_vise_llm": [
  { "niveau1": "Santé / Social / Environnement", "niveau2": "Santé" },
  { "niveau1": "Santé / Social / Environnement", "niveau2": "Social" }
]

jeune_besoin : si objectif_1 est renseigné, on l'envoie. Sinon, mapJeuneBesoin(jeune) dérive depuis jeune.besoins : slug study → "Atteindre un objectif d'études" (subs orienter/resultats/concours) ou "Définir mon projet d'études" ; slug pro → "Atteindre un objectif d'insertion pro" (subs candidate/interview/seek) ou "Définir mon projet pro" ; autre → BESOINS_MAP[slug] ou "Définir mon projet d'études".

Code : back/src/binomes/services/matching-algo.service.ts (buildRequestBody, epToLegacyFormat, mapJeuneBesoin).

Méthodes

Catégories du microservice

La réponse contient des clés : femmes, non_femmes, generalistes. Pour le matching instantané côté jeune, on prend le premier disponible de chaque catégorie, puis on mélange l'ordre.

Fallback microservice indisponible

Si le microservice est inaccessible (timeout 30 s, erreur réseau ou HTTP) :

• getPersonnalizedBenevolesOnePerCategory : 1 tentative sans retry → retourne []
• getPersonnalizedBenevoles : 1 tentative + 1 retry (même timeout 30 s) → retourne []

Dans les deux cas, le service bascule sur le fallback local via getTopBenevolesForJeune(jeune, 3) :

1. Charge tous les bénévoles matchables depuis la DB locale (loadMatchableBenevoles)
2. Calcule un score de rating classique (ratingService.calculateBinomeRating) pour chacun
3. Exclut les bénévoles avec score -99 (disqualifiés)
4. Retourne les top 3 par score décroissant

Les mentors proposés ne sont pas aléatoires — c'est un classement déterministe par score. Le champ type_mentor est NULL sur les réservations créées via ce fallback (pas de catégorie femmes/non_femmes/generalistes).

Les bénévoles avec excluInstantMatching = true (réservés pour le matching manuel) sont exclus à la récupération :

• résultats du microservice (checkBenevoleDisponible dans MatchingAlgoService)
• fallback local Dema1n (loadMatchableBenevoles)
• refresh / disponibilité (isBenevoleStillAvailableForJeune)

Ils restent matchables par un admin via le matching BO classique (le nouvel algo BO les écarte aussi).

Ce fallback s'applique aussi au refresh quand au moins un bénévole est devenu indisponible.

Logs

Appels logués avec préfixe [matching-algo] : body envoyé, réponse brute, mentors parsés, bénévoles exclus, résultat final. En cas d'erreur (ex. 500), le body est inclus dans le log.

Logique métier

Durée : 15 minutes

Une réservation est active si :

deletedAt IS NULL AND reservationDate + 15 minutes > NOW()

Expiration

Aucune action automatique (pas de cron). Les réservations expirées restent en base et sont ignorées via le filtrage à la lecture.

Profil non matchable

Un jeune ou un bénévole est non matchable si :

1. Il a une AdminReservation active (30 min), OU
2. Il apparaît dans une InstantMatchingReservation active (15 min)

Les deux systèmes se cumulent.

Implémentation backend

1. postBinome (BinomeController) : Bloque la création si le jeune ou le bénévole est en matching instantané actif.
2. Listes de matching (RatingController) : jeuneList et benevoleList excluent les profils en matching instantané actif.
3. Listes BO (JeuneRepository, BenevoleRepository) : findAndFilter exclut les jeunes et bénévoles en matching instantané actif.

Affichage frontend (BO)

L'affichage du matching instantané réutilise celui de la réservation admin :

Condition de masquage du bouton Matcher :

!(item.resa || item.instantMatchingResa);

Le bouton Matcher n’apparaît que pour un jeune APTE (création de binôme, vivier BO, matching de masse inclus). La liste BO des jeunes exclut par défaut INSCRIT, NON_DISPONIBLE et SORTI.

Choix de l'algorithme de matching (jeunes uniquement)

Pour les jeunes, le bouton "Matcher" est un menu déroulant proposant 2 choix :

Disponibilité du nouvel algo

L'endpoint GET /rating/benevoleList/:jeuneId accepte ?algo=new (appel microservice). GET /rating/jeuneList/:benevoleId utilise toujours l'algo classique.

Assignation d'un admin

L'inscription jeune n'assigne plus de CD. Un jeune n'a un adminId que s'il passe par le matching instantané, ou par une assignation manuelle.

Tous les admins membres d'une équipe peuvent recevoir des binômes MI (plus de case « Matching instant »).

Lors de createBinomeInstant, un admin de suivi est sélectionné :

Bénévoles éligibles : sans admin associé

Réservation pour le matching manuel (excluInstantMatching)

Un admin peut marquer un mentor exclu MI depuis la fiche BO (/bo/benevoles/:id, toggle sous le nom). Champ benevole.exclu_instant_matching, défaut false.

• Toast à l’activation : « Ce mentor est maintenant exclu du MI »
• Filtre liste mentors : Exclu MI Oui / Non
• Le matching instantané n’inclut plus ce mentor (algo + fallback Dema1n)
• Le matching BO classique (liste depuis une fiche jeune, algo classique) le laisse disponible pour un appariement manuel

La page /bo/jeunes/:id/matching affiche un v-chip indiquant l'algorithme actif (?algo=new → "Nouvel algo - bêta", sinon "Algo classique").

Type de binôme et traçabilité

binome.type

binome.typeAlgo

Indique si le score vient du nouvel algo (v2) ou du rating classique (classic). v2 si la réservation porte un score microservice, classic si score legacy.

Commentaire automatique sur le binôme

• Parcours jeune (validate → createBinomeInstant) : Matching instantané - nouvel algo - {DD/MM/YYYY} (score v2) ou Matching instantané - algo classique - {DD/MM/YYYY} (score legacy)
• Parcours BO (postBinome avec isInstantMatching) : texte basé sur le query param algo

Filtre "Matching" sur la liste des binômes

Indicateur visuel "déjà proposé en matching instantané"

Sur les pages de matching (BO), si un profil a déjà été dans une réservation avec le profil en cours (même expirée/terminée) :

• Page liste (/matching/index.vue) : fond grisé sur la card du profil déjà proposé
• Page confirmation (/matching/:id) : message gris "{Prénom mentor} a déjà été proposé à {Prénom jeune} lors du matching instantané"

Le contrôle porte sur toutes les réservations passées (y compris expirées et soft-deleted).

Endpoints backend associés

• GET /rating/benevoleList/:jeuneId : chaque bénévole enrichi d'un flag wasProposedInInstantMatching: boolean
• GET /rating/jeuneList/:benevoleId : idem pour les jeunes
• GET /rating/wasPreviouslyProposed?jeuneId=X&benevoleId=Y → { wasProposed: boolean } — appelé directement par les pages de confirmation (pas via query param, pour éviter la falsification par URL)

Endpoints API (côté jeune)

Architecture : InstantMatchingController — auth (JwtAuthGuard) + vérification propriété (getAuthenticatedJeune) + délégation à InstantMatchingService.

Collection Bruno : back/bruno/instant-matching/.

Mise en forme des bénévoles proposés

Quand : Fin d'inscription du jeune (après finishInscriptionJeune, jeune APTE). Également à chaque chargement de la page de sélection.

Entrée : { jeuneId: string }

Comportement idempotent :

Logique (première fois, contexte front_jeune) :

1. Vérifier jeune existant, req.user propriétaire, état APTE et Autonome
2. Vérifier via findCurrentForJeune — si réservations existantes, les renvoyer avec flag expired
3. Appel microservice getPersonnalizedBenevolesOnePerCategory() — 1 bénévole matchable par catégorie ; si microservice indisponible → fallback local top 3 par rating classique (type_mentor = NULL)
4. Mélange aléatoire en préservant la paire (bénévole + type_mentor)
5. Créer 3 lignes InstantMatchingReservation avec orderIndex 0/1/2, etat: 'proposé', score, type_mentor
6. Retourner les 3 bénévoles avec expired: false

Contexte back_office : top 3 via getTopBenevolesForJeune() ; type_mentor = NULL.

Sortie :

{
  success: boolean;
  expired: boolean;
  expiresAt?: string;
  reservations: {
    benevoleId: string;
    firstName: string;
    lastName: string;
    etat: 'proposé' | 'sélectionné' | 'autre selectionné' | 'refusé' | 'desactivation';
    rating: number;
    ratingDetails: string;
    department: string;
    region: string;
    secteurs: string[];
    postes: string[];
    cursus: string[];
    filieres: string[];
    diplomes: string[];
    experience: string;
    passions: string;
    alternance: boolean;
  }[];
}

Cas particuliers :

• Moins de 3 bénévoles disponibles : retourner ce qui est disponible, ou success: false si aucun
• Réservations soft-deleted → erreur 400 "Le matching instantané a déjà été proposé.", sauf s'il existe un binôme ANNULE ou TERMINE dont creationDate est postérieure au début (reservationDate) de la dernière session MI : un nouveau lot est alors créé (les mêmes mentors peuvent ressortir).

Endpoint 2 : POST /instant-matching/refresh

Quand : Jeune revient sur la page (rechargement, retour, timer proche de l'expiration).

Entrée : { jeuneId: string }

Logique :

1. Vérifier jeune + ownership
2. Récupérer réservations non-supprimées via findCurrentForJeune
3. Si aucune → { success: true, reservations: null }
4. Vérifier disponibilité de chaque bénévole : pas MATCHE (sauf multibinome), Autonome, pas de réservation admin active, pas de réservation instant matching pour un autre jeune, pas excluInstantMatching
5. Tous disponibles : 3 nouvelles lignes avec mêmes score / type_mentor
6. Au moins un indisponible : appel microservice getPersonnalizedBenevolesOnePerCategory() pour 3 nouveaux (fallback getTopBenevolesForJeune() si microservice indisponible → type_mentor = NULL)
7. Soft-delete anciennes réservations, créer 3 nouvelles (historique conservé)

Sortie :

{
  success: boolean;
  reservations: { ... }[] | null;
}

Endpoint 3 : POST /instant-matching/confirm-selection

Quand : Le jeune clique sur "Confirmer mon choix".

Entrée : { jeuneId: string, benevoleId: string }

Logique :

1. Vérifier jeune + ownership
2. Vérifier que le bénévole fait partie des réservations actuelles
3. updateEtatForValidate(jeuneId, benevoleId) — sélectionné → sélectionné, autres → autre selectionné
4. Pas de soft-delete, pas de création de binôme

Sortie : { success: boolean }

Erreur : bénévole non trouvé dans les réservations → 400

Endpoint 4 : POST /instant-matching/validate

Quand : Le jeune clique sur "Envoyer et valider le binôme".

Entrée : { jeuneId: string, benevoleId: string, firstMessageJeune?: string }

firstMessageJeune = concaténation des 3 champs du formulaire (présentation, objectifs, dispos) séparés par \n.

Logique :

1. Vérifier jeune + ownership
2. Vérifier que le bénévole est dans les réservations actives
3. Validations de sécurité : jeune pas déjà MATCHE, jeune et bénévole Autonome, bénévole non-multibinome pas MATCHE, limites binômes, onlyOneBinome, PNP/partenaire, PNP/VIP, même sandbox
4. updateEtatForValidate(jeuneId, benevoleId, true) — sélectionné → matché, autres → autre selectionné
5. Soft-delete des 3 réservations
6. createBinomeInstant() : type = instant, typeAlgo = v2/classic, status EN_ATTENTE, firstMessageJeune stocké
7. Mails : événement instant.binome.created → instant.benevole-0 et instant.jeune-0 ; lastStepDone=0, nextStepDate = +15 jours
8. Statuts : jeune → MATCHE, bénévole → MATCHE
9. Commentaire automatique sur le binôme
10. Si sandbox MVLS : mvlsService.publishBinomeMessage
11. Si sandbox non-MVLS : création des todo lists (besoins sans slug valide ignorés)

Sortie : { success: boolean, binomeId: string }

Erreurs :

• Bénévole non trouvé dans les réservations actives → 400
• Bénévole plus disponible / multibinome max atteint / onlyOneBinome → 409 Conflict
• Jeune déjà matché, non autonome, PNP+partenaire/VIP, sandbox différente → 400

Endpoint 5 : POST /instant-matching/refuse

Quand : Le jeune ne souhaite aucun des 3 bénévoles.

Entrée : { jeuneId: string, comment?: string }

Logique :

1. Vérifier jeune + ownership
2. updateEtatForJeune(jeuneId, 'refusé')
3. Soft-delete via softDeleteAllCurrentForJeune
4. Commentaire individuel : "Matching instantané refusé" ou "Matching instantané refusé - {comment}" (adminId: null)
5. jeune.matchingInstantaneRefuse = true (filtre BO « Matching instantané refusé »)
6. Le jeune reste APTE

Sortie : { success: boolean }

Le flag matchingInstantaneRefuse est remis à NULL dès que le jeune passe MATCHE (changeStatusJeune). Chaque changement du flag est journalisé dans log-matching-instantane-refuse (visible sur /bo/jeunes/:id/logs). L’historique BO (colonne Refusés) n’affiche que les vagues etat = 'refusé' ; s’il y a plus de commentaires que de vagues, seuls les N commentaires les plus récents sont associés (raison + date).

Endpoint 6 : POST /instant-matching/cancel

Quand : Le jeune annule et ne veut plus être disponible.

Entrée : { jeuneId: string }

Logique :

1. Vérifier jeune + ownership
2. updateEtatForJeune(jeuneId, 'desactivation')
3. Soft-delete via softDeleteAllCurrentForJeune
4. Commentaire individuel : "Matching instantané - désactivation"
5. changeStatusJeune(jeuneId, 'NON_DISPONIBLE', 'MATCHING_INSTANTANE') + logs

Sortie : { success: boolean }

Mise en forme des bénévoles proposés (formatBenevoleResponse)

formatBenevoleResponse (instant-matching.service.ts) transforme un Benevole avec ses relations en objet plat pour l'affichage côté jeune. Fusionne données CF (champ fermé) et LLM (BenevoleExtraitPrecision).

Sources de données

Déduplication des secteurs

1. Valeurs CF depuis Benevole.secteurMetier + PosteBenevole[].secteur (déduplication case-insensitive)
2. Chaque valeur CF traduite en { niveau1, niveau2 } via taxonomie_secteurs_professions.json (comparaison uniquement, jamais pour affichage)
3. Si la traduction correspond à une entrée LLM → l'entrée LLM est "couverte", on affiche la valeur CF d'origine
4. Entrées LLM non couvertes affichées par niveau1 uniquement
5. Ordre : valeurs CF d'abord, puis niveau1 LLM non couverts

Fichiers : back/src/binomes/utils/merge-secteurs.ts (mergeSecteurs, mergePostes, mergeCursus, mergeFilieres) ; back/src/binomes/imports-files/taxonomie_secteurs_professions.json.

Les champs sont affichés en chips dans front/pages/compte/jeune/mentors/MentorCard.vue.

Flux fonctionnel

Création de la réservation

1. Jeune termine l'inscription → POST /instant-matching/propose
2. Sélection des 3 bénévoles : microservice (1 par catégorie) ou fallback local avec calculateBinomeRating
3. Création de 3 lignes InstantMatchingReservation avec type_mentor = clé mentors ou NULL (fallback/BO)
4. Affichage des 3 bénévoles au jeune

Pendant 15 minutes

• Jeune et 3 bénévoles visibles dans les listes BO mais exclus de findMatchable
• Bouton Matcher masqué, icône "i" rouge
• Recharge page → /propose renvoie les mêmes 3 bénévoles sans toucher au timer (expired: false)

Après expiration (> 15 min)

• Profils redeviennent matchables dans les listes BO
• /propose renvoie les mêmes 3 avec expired: true
• Le front appelle /refresh pour renouveler et remplacer les indisponibles

Affichage selon l'état (page /compte/jeune/mentors)

Flux :

1. propose/refresh → réservations avec champ etat
2. etat === 'sélectionné' → picked défini, affichage formulaire
3. Clic "Confirmer" → POST /instant-matching/confirm-selection
4. Clic "Valider" → POST /instant-matching/validate

Libération

Création du binôme : createBinomeInstant

Fonction dédiée (pas createBinome) avec les spécificités suivantes :

Admin : CD de la région, disponible, membre d'une équipe, jauge la plus basse (préférence STEM si le jeune est STEM) ; null si aucun éligible (log admin vide conservé). L'inscription seule n'assigne pas d'admin.

Mails (événement instant.binome.created) :

• instant.benevole-0 (Brevo #4347) : PRENOM, PRENOM_admin, PRENOM_JEUNE, schoolCursus, filiereJeune, texte_matching, objectif_du_moment_mentor (phrase à la 3e personne : prénom du jeune + verbe, contrairement au dashboard jeune qui utilise « tu »)
• instant.jeune-0 : PRENOM, PRENOM_admin, PRENOM_mentor

Comportements spécifiques

Popup d'expiration côté jeune

Quand le timer expire sur /compte/jeune/mentors, deux modales distinctes selon l'écran :

Cas 1 — écran 3 mentors (picked = null) :

Cas 2 — écran 1er contact (picked défini) :

check-availability :

• Mentor toujours dispo → renewCurrentReservations(), toast « {prénom} est toujours disponible ! », reste sur l'écran 1er contact
• Mentor indisponible → refresh(), toast « {prénom} n'est plus disponible… », retour écran 3 mentors après quelques secondes
• Erreur API → toast d'erreur, on reste sur l'écran 1er contact (on ne redescend pas au choix des 3 mentors)

Une réservation IM / admin expirée (timer écoulé, ligne encore en base) ne rend pas le mentor indisponible. Seules les réservations actives d'un autre jeune (ou d'un admin) bloquent.

Fermeture de page : beforeunload natif tant que le jeune est dans le parcours (réservation active, binôme non créé).

Si le jeune recharge avec une réservation expirée, propose restitue d'abord l'etat (sélectionné → cas 2, sinon cas 1) puis ouvre la modale adaptée.

Protections back-office

Conditions de disponibilité lors d'un refresh

Un bénévole est maintenu si :

• status === 'APTE' OU (status === 'MATCHE' ET multibinome ET activeBinomeCount < 2)
• state === 'Autonome'
• Pas de réservation admin active (30 min)
• Pas de réservation instant matching active pour un autre jeune (15 min) — une réservation expirée ne bloque pas
• excluInstantMatching est faux (mentor non réservé pour le matching manuel)

Régions et onboarding (champ "about")

Constante INSTANT_MATCHING_REGIONS (front/services/reservation.js) :

['Île-de-France'];

Cette constante ne conditionne pas l'accès au matching instantané. Le champ "about" reste visible dans la page profil et en back-office.

Modifications de l'onboarding jeune

Étape "Situation" (id: 43)

Carrousel d'aide

Le composant HelpCarousel (front/components/inscription/widgets/v2/helpCarousel.vue) remplace le panneau statique. Header : "Besoin d'aide pour remplir ce champ ?", 3 exemples en carrousel.

Comparaison avec AdminReservation

Auto-annulation mentor post-MER (48h)

Feature toggle : mentor_post_mer_48h (admin BO → Feature toggles). Désactivé par défaut.

Dans les 48h suivant la création d'un binôme, le mentor peut agir depuis son tableau de bord (/compte/benevole/dashboard) :

• Log non-dispo mentor : origin dashboardMentorCancel
• Log multi-mentorat : si le mentor était en multi-mentorat, désactivation + entrée log-multibinome (origin dashboard)
• Mail jeune : template Brevo 4320 (binome-annule-jeune-dashboard-mentor), variables PRENOM_JEUNE, PRENOM_MENTOR

Constantes et utilitaires