Vœu de compagnon : être affecté avec 0 à N autres bénévoles

Nouveau vœu sur la fiche du bénévole — « je voudrais être affecté avec tel(s)
bénévole(s) » — pris en compte à la fois pour le rendre visible et par le
solveur.

Backend :
- `VolunteerCompanionWish` (`volunteer_id`, `companion_id`, à sens unique,
  `CHECK (volunteer_id <> companion_id)`) — migration 0010.
- API : `wished_companion_ids` sur `VolunteerCreate`/`Update`/`Read`, mêmes
  règles que les autres vœux (ids inconnus → 422 `volunteer.unknown` ; se
  souhaiter soi-même → 422 `volunteer.cannot_wish_self`).
- Solveur (`engine.py`) : bonus (+25 par correspondance) si un des compagnons
  souhaités du candidat est déjà affecté (décision déjà prise) au créneau —
  cumulable si plusieurs compagnons sont présents. Comme les autres termes de
  l'objectif, un bonus/malus, jamais une contrainte.
- Seed de démo : ~20 % des bénévoles ont un vœu de compagnon (couple, amis).

Frontend :
- Fiche bénévole (`ConfigVolunteers.tsx`) : sélecteur de compagnons (ajout et
  édition), avec une bulle d'aide expliquant le sens unique et l'effet sur le
  solveur — c'est ce qui « fait apparaître » le lien entre bénévoles.
- Panneau d'affectation : badge « avec N compagnon(s) souhaité(s) » sur un
  candidat, et bonus correspondant dans le classement par défaut
  (`candidateChanceScore`).
- Mock (`runSolver`) : même bonus, pour que la démonstration se comporte
  pareil que le vrai solveur.

CLAUDE.md à jour (modèle de domaine, section 4, journal).

Vérifié : 194 tests backend (dont 13 nouveaux), ruff, alembic check ;
typecheck/lint/build/smoke frontend ; solveur testé en direct sur le jeu de
démo reseedé (0,25 s, 47 suggestions).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017uUsRg7XzopkCPWimwg9ZM

backend/app/solver/engine.py

@@ -7,10 +7,10 @@ contente de faire remonter ces candidats en tête de liste).
 
 Contrainte dure : aucun chevauchement de créneaux pour un même bénévole (règle
 `SHIFT_OVERLAP`, cf. `app.validation`). Tout le reste (disponibilité, repos,
-chaînage entre créneaux consécutifs, vœu de poste, vœu d'artiste, équité de
-charge) est un terme de l'objectif, pas une contrainte — comme le moteur de
-validation, qui reste seul juge au moment où la coordination confirme une
-affectation.
+chaînage entre créneaux consécutifs, vœu de poste, vœu de compagnon, vœu
+d'artiste, équité de charge) est un terme de l'objectif, pas une contrainte —
+comme le moteur de validation, qui reste seul juge au moment où la
+coordination confirme une affectation.
 Pas de plafond de cumul journalier côté solveur : `DAILY_HOURS_EXCEEDED`
 reste vérifiée par la validation, à la confirmation.
 """
@@ -49,6 +49,8 @@ _ARTIST_CONFLICT_PENALTY = 80
 # n'importe quel poste) : limite les enchaînements de shifts plutôt que de
 # faire tourner un poste en particulier.
 _CHAIN_PENALTY = 40
+# Par compagnon souhaité déjà affecté au créneau (0 à N vœux par bénévole).
+_COMPANION_BONUS_PER_MATCH = 25
 
 
 def _overlaps(a: ShiftInfo, b: ShiftInfo) -> bool:
@@ -85,10 +87,12 @@ def _score(volunteer: SolverVolunteer, shift: SolverShift) -> int:
     """Score d'affinité (bénévole, créneau) : plus haut = meilleur candidat.
 
     Purement additif (aucune interaction entre deux affectations proposées),
-    ce qui garde le modèle CP-SAT linéaire simple. Repos et chaînage ne sont
-    vérifiés que contre les affectations déjà décidées, pas entre deux
-    suggestions du même calcul : la validation finale (à la confirmation)
-    reste seule juge en cas de cas limite entre deux suggestions.
+    ce qui garde le modèle CP-SAT linéaire simple. Repos, chaînage et
+    compagnons ne sont vérifiés que contre les affectations déjà décidées,
+    pas entre deux suggestions du même calcul : la validation finale (à la
+    confirmation) reste seule juge en cas de cas limite entre deux
+    suggestions (et deux compagnons suggérés ensemble dans le même calcul ne
+    se renforcent pas mutuellement, faute d'interaction entre variables).
     """
     score = _URGENT_BASE if shift.already_assigned < shift.min_staff else _NORMAL_BASE
     if shift.position_id in volunteer.wished_position_ids:
@@ -99,6 +103,8 @@ def _score(volunteer: SolverVolunteer, shift: SolverShift) -> int:
         score -= _REST_PENALTY
     if _chained_from_predecessor(volunteer, shift):
         score -= _CHAIN_PENALTY
+    companions_present = len(volunteer.wished_companion_ids & shift.assigned_volunteer_ids)
+    score += _COMPANION_BONUS_PER_MATCH * companions_present
     if any(
         _overlaps(shift.shift_info, passage) for passage in volunteer.wished_artist_windows
     ):

backend/app/solver/loader.py

@@ -14,6 +14,7 @@ from app.models import (
     Shift,
     Volunteer,
     VolunteerArtist,
+    VolunteerCompanionWish,
     VolunteerPositionWish,
 )
 from app.solver.models import SolverInput, SolverShift, SolverVolunteer
@@ -61,8 +62,10 @@ def build_solver_input(*, session: Session, edition: Edition) -> SolverInput:
 
     assigned_count: dict = defaultdict(int)
     shifts_by_volunteer: dict = defaultdict(list)
+    assigned_volunteers_by_shift: dict = defaultdict(set)
     for a in assignments:
         assigned_count[a.shift_id] += 1
+        assigned_volunteers_by_shift[a.shift_id].add(str(a.volunteer_id))
         shift = shifts_by_id.get(a.shift_id)
         if shift is not None:
             shifts_by_volunteer[a.volunteer_id].append(shift)
@@ -77,6 +80,7 @@ def build_solver_input(*, session: Session, edition: Edition) -> SolverInput:
             ideal_staff=s.ideal_staff,
             already_assigned=assigned_count.get(s.id, 0),
             predecessor_shift_ids=predecessor_ids.get(s.id, frozenset()),
+            assigned_volunteer_ids=frozenset(assigned_volunteers_by_shift.get(s.id, ())),
         )
         for s in shifts
         if assigned_count.get(s.id, 0) < s.ideal_staff
@@ -98,6 +102,14 @@ def build_solver_input(*, session: Session, edition: Edition) -> SolverInput:
     ):
         wishes[w.volunteer_id].add(str(w.position_id))
 
+    companion_wishes: dict = defaultdict(set)
+    for w in session.exec(
+        select(VolunteerCompanionWish).join(
+            Volunteer, Volunteer.id == VolunteerCompanionWish.volunteer_id
+        ).where(Volunteer.edition_id == edition.id)
+    ):
+        companion_wishes[w.volunteer_id].add(str(w.companion_id))
+
     artists_by_id = {
         a.id: a
         for a in session.exec(select(Artist).where(Artist.edition_id == edition.id))
@@ -120,6 +132,7 @@ def build_solver_input(*, session: Session, edition: Edition) -> SolverInput:
             id=str(v.id),
             availability=tuple(availabilities.get(v.id, ())),
             wished_position_ids=frozenset(wishes.get(v.id, ())),
+            wished_companion_ids=frozenset(companion_wishes.get(v.id, ())),
             wished_artist_windows=tuple(artist_wishes.get(v.id, ())),
             existing_shifts=tuple(
                 ShiftInfo(id=str(s.id), starts_at=s.starts_at, ends_at=s.ends_at)

backend/app/solver/models.py

@@ -27,6 +27,9 @@ class SolverShift:
     # chaînage (voir `engine._score`), pour limiter les enchaînements de
     # shifts plutôt que cibler la rotation d'un poste en particulier.
     predecessor_shift_ids: frozenset[str] = frozenset()
+    # Bénévoles déjà affectés à ce créneau (décisions déjà prises) : sert au
+    # bonus de compagnon de route (voir `engine._score`).
+    assigned_volunteer_ids: frozenset[str] = frozenset()
 
     @property
     def shift_info(self) -> ShiftInfo:
@@ -38,6 +41,8 @@ class SolverVolunteer:
     id: str
     availability: tuple[AvailabilityWindow, ...] = ()
     wished_position_ids: frozenset[str] = frozenset()
+    # Bénévoles (0 à N) avec qui il voudrait être affecté — à sens unique.
+    wished_companion_ids: frozenset[str] = frozenset()
     # Passages des artistes que le bénévole veut voir (heure de passage),
     # sous forme de fenêtres datées : un créneau qui chevauche l'une d'elles
     # lui ferait manquer le passage.