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

frontend/src/api/mock/dataset.ts

@@ -233,6 +233,10 @@ export function buildMockState(): MockState {
     const artist_ids = artists.filter(() => rnd() < 0.25).map((a) => a.id);
     const wished_position_ids =
       rnd() < 0.4 ? [positions[Math.floor(rnd() * positions.length)].id] : [];
+    // Vœu de compagnon (couple, amis) : un autre bénévole de la liste, jamais
+    // soi-même (décalage d'au moins un cran).
+    const wished_companion_ids =
+      rnd() < 0.2 ? [`v${(i + 1 + Math.floor(rnd() * 5)) % 64}`] : [];
     volunteers.push({
       id,
       edition_id,
@@ -243,6 +247,7 @@ export function buildMockState(): MockState {
       comment: null,
       artist_ids,
       wished_position_ids,
+      wished_companion_ids,
       created_at: NOW,
       updated_at: NOW,
     });

frontend/src/api/mock/mock-client.ts

@@ -120,6 +120,15 @@ function resolveWishes<T extends { id: string }>(
   return wanted;
 }
 
+/** Vœux de compagnon : comme `resolveWishes`, plus le rejet de soi-même. */
+function resolveCompanionWishes(ids: string[], selfId?: string): string[] {
+  const resolved = resolveWishes(state.volunteers, ids, 'volunteer.unknown');
+  if (selfId != null && resolved.includes(selfId)) {
+    throw new ApiError(422, 'volunteer.cannot_wish_self');
+  }
+  return resolved;
+}
+
 function shiftWindow(day: string, dp: DayPartRead): [string, string] {
   const endDay = dp.end_time <= dp.start_time ? addDays(day, 1) : day;
   return [`${day}T${dp.start_time}`, `${endDay}T${dp.end_time}`];
@@ -392,9 +401,12 @@ const SOLVER_AVAIL_PENALTY_PER_HALF_HOUR = 5;
 const SOLVER_REST_PENALTY = 60;
 const SOLVER_ARTIST_CONFLICT_PENALTY = 80;
 const SOLVER_FAIRNESS_PENALTY_PER_HOUR = 2;
-// Le bénévole a déjà tenu le créneau précédent de ce même poste (même jour) :
-// favorise la rotation plutôt que d'enchaîner toujours la même personne.
+// Le bénévole a déjà tenu le créneau immédiatement précédent (même jour,
+// n'importe quel poste) : limite les enchaînements de shifts plutôt que de
+// faire tourner un poste en particulier.
 const SOLVER_CHAIN_PENALTY = 40;
+// Par compagnon souhaité déjà affecté au créneau (0 à N vœux par bénévole).
+const SOLVER_COMPANION_BONUS_PER_MATCH = 25;
 
 type TimeWindow = { starts_at: string; ends_at: string };
 
@@ -408,6 +420,14 @@ function volunteerExistingShifts(volunteerId: string): ShiftRead[] {
     .map((a) => shiftById(a.shift_id));
 }
 
+/** Bénévoles déjà affectés (décisions déjà prises) à un créneau — sert au
+ * bonus de compagnon de route (voir `solverScore`). */
+function assignedVolunteerIds(shiftId: string): Set<string> {
+  return new Set(
+    state.assignments.filter((a) => a.shift_id === shiftId).map((a) => a.volunteer_id),
+  );
+}
+
 /** Créneau(x) — n'importe quel poste — dont la fin coïncide avec le début de
  * chaque créneau, le même jour (indexé par id de créneau) — sert au malus de
  * chaînage (voir `solverScore`), pour limiter les enchaînements de shifts
@@ -459,6 +479,7 @@ function solverScore(
   existing: ShiftRead[],
   wishedArtists: TimeWindow[],
   chainedFromPredecessor: boolean,
+  alreadyAssignedIds: Set<string>,
 ): number {
   let score = assignedCount < shift.min_staff ? SOLVER_URGENT_BASE : SOLVER_NORMAL_BASE;
   if (volunteer.wished_position_ids.includes(shift.position_id)) score += SOLVER_WISH_BONUS;
@@ -466,6 +487,10 @@ function solverScore(
     score -= SOLVER_ARTIST_CONFLICT_PENALTY;
   }
   if (chainedFromPredecessor) score -= SOLVER_CHAIN_PENALTY;
+  const companionsPresent = volunteer.wished_companion_ids.filter((id) =>
+    alreadyAssignedIds.has(id),
+  ).length;
+  score += SOLVER_COMPANION_BONUS_PER_MATCH * companionsPresent;
 
   const windows = state.availability.get(volunteer.id) ?? [];
   const missed = uncoveredMinutes(windows, shift.starts_at, shift.ends_at);
@@ -523,6 +548,7 @@ function runSolver(): SolverRunResult {
   for (const shift of ordered) {
     const gap = shift.ideal_staff - (assignedCount.get(shift.id) ?? 0);
     if (gap <= 0) continue;
+    const alreadyAssignedIds = assignedVolunteerIds(shift.id);
     const picked = state.volunteers
       .filter((v) => {
         const busy = [
@@ -544,6 +570,7 @@ function runSolver(): SolverRunResult {
             existing,
             artistWindowsByVolunteer.get(v.id) ?? [],
             chained,
+            alreadyAssignedIds,
           ),
         };
       })
@@ -729,6 +756,7 @@ export function createMockApi(): PlanningApi {
             body.wished_position_ids ?? [],
             'position.unknown',
           ),
+          wished_companion_ids: resolveCompanionWishes(body.wished_companion_ids ?? []),
           created_at: now,
           updated_at: now,
         };
@@ -756,6 +784,9 @@ export function createMockApi(): PlanningApi {
                 ),
               }
             : {}),
+          ...(body.wished_companion_ids != null
+            ? { wished_companion_ids: resolveCompanionWishes(body.wished_companion_ids, v.id) }
+            : {}),
           updated_at: touch(),
         });
         return delay(v);
@@ -764,8 +795,12 @@ export function createMockApi(): PlanningApi {
         state.volunteers = state.volunteers.filter((x) => x.id !== id);
         state.assignments = state.assignments.filter((a) => a.volunteer_id !== id);
         state.availability.delete(id);
-        // RGPD : effacement complet, y compris le compte de connexion éventuel.
+        // RGPD : effacement complet, y compris le compte de connexion éventuel
+        // et les vœux de compagnon dont il était la cible.
         state.accounts = state.accounts.filter((a) => a.volunteer_id !== id);
+        state.volunteers.forEach((v) => {
+          v.wished_companion_ids = v.wished_companion_ids.filter((cid) => cid !== id);
+        });
         return delay(undefined);
       },
     },
@@ -998,6 +1033,7 @@ export function createMockApi(): PlanningApi {
               comment: null,
               artist_ids: [],
               wished_position_ids: [],
+              wished_companion_ids: [],
               created_at: now,
               updated_at: now,
             };

frontend/src/api/schema.ts

@@ -106,6 +106,8 @@ export interface VolunteerRead {
   artist_ids: string[];
   /** Vœux : postes que le bénévole voudrait tenir. */
   wished_position_ids: string[];
+  /** Vœux : bénévoles avec qui il voudrait être affecté (0 à N, à sens unique). */
+  wished_companion_ids: string[];
   created_at: string;
   updated_at: string;
 }
@@ -118,6 +120,7 @@ export interface VolunteerCreate {
   comment?: string | null;
   artist_ids?: string[];
   wished_position_ids?: string[];
+  wished_companion_ids?: string[];
 }
 
 export interface VolunteerUpdate {
@@ -129,6 +132,7 @@ export interface VolunteerUpdate {
   /** null / absent = inchangé ; [] = vider. */
   artist_ids?: string[] | null;
   wished_position_ids?: string[] | null;
+  wished_companion_ids?: string[] | null;
 }
 
 // --------------------------------------------------------------------------- //