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/tests/test_api_solver.py

@@ -71,6 +71,37 @@ def test_avoids_volunteer_whose_wished_artist_would_be_missed(client, edition, s
     assert suggestion["volunteer_ids"] == [str(indiff.id)]
 
 
+def test_prefers_volunteer_whose_wished_companion_is_already_on_the_shift(
+    client, edition, session
+):
+    from app.models import Assignment
+
+    position = make_position(session, edition)
+    shift = make_shift(
+        session, edition, position,
+        start=dt_at(10, 14), end=dt_at(10, 18), min_staff=1, ideal_staff=2,
+    )
+    copain = make_volunteer(session, edition, email="copain@ex.fr")
+    session.add(
+        Assignment(edition_id=edition.id, volunteer_id=copain.id, shift_id=shift.id)
+    )
+    session.commit()
+
+    buddy = make_volunteer(session, edition, email="buddy@ex.fr")
+    assert client.patch(
+        f"/editions/{edition.id}/volunteers/{buddy.id}",
+        json={"wished_companion_ids": [str(copain.id)]},
+    ).status_code == 200
+    stranger = make_volunteer(session, edition, email="stranger@ex.fr")
+
+    resp = client.post(_url(edition, "/suggestions"))
+    suggestion = next(
+        s for s in resp.json()["suggestions"] if s["shift_id"] == str(shift.id)
+    )
+    assert suggestion["volunteer_ids"] == [str(buddy.id)]
+    assert str(stranger.id) not in suggestion["volunteer_ids"]
+
+
 def test_chain_penalty_applies_across_different_positions(client, edition, session):
     from app.models import Assignment, PositionCategory
 

backend/tests/test_api_volunteers.py

@@ -110,6 +110,61 @@ def test_unknown_artist_wish_is_422(client, edition):
     assert resp.json()["detail"]["code"] == "artist.unknown"
 
 
+def test_create_with_companion_wish(client, edition, session):
+    friend = make_volunteer(session, edition, email="friend@ex.fr")
+    resp = client.post(
+        _url(edition),
+        json={
+            "first_name": "Alex",
+            "last_name": "Martin",
+            "wished_companion_ids": [str(friend.id)],
+        },
+    )
+    assert resp.status_code == 201
+    assert resp.json()["wished_companion_ids"] == [str(friend.id)]
+
+
+def test_unknown_companion_wish_is_422(client, edition):
+    resp = client.post(
+        _url(edition),
+        json={
+            "first_name": "A",
+            "last_name": "B",
+            "wished_companion_ids": [str(uuid.uuid4())],
+        },
+    )
+    assert resp.status_code == 422
+    assert resp.json()["detail"]["code"] == "volunteer.unknown"
+
+
+def test_cannot_wish_oneself_as_companion(client, edition, session):
+    volunteer = make_volunteer(session, edition, email="solo@ex.fr")
+    resp = client.patch(
+        _url(edition, f"/{volunteer.id}"),
+        json={"wished_companion_ids": [str(volunteer.id)]},
+    )
+    assert resp.status_code == 422
+    assert resp.json()["detail"]["code"] == "volunteer.cannot_wish_self"
+
+
+def test_companion_wish_is_one_directional(client, edition, session):
+    # A souhaite B ne veut pas dire que B souhaite A.
+    a = make_volunteer(session, edition, email="a@ex.fr")
+    b = make_volunteer(session, edition, email="b@ex.fr")
+    client.patch(_url(edition, f"/{a.id}"), json={"wished_companion_ids": [str(b.id)]})
+    assert client.get(_url(edition, f"/{a.id}")).json()["wished_companion_ids"] == [str(b.id)]
+    assert client.get(_url(edition, f"/{b.id}")).json()["wished_companion_ids"] == []
+
+
+def test_deleting_a_wished_companion_clears_the_wish(client, edition, session):
+    # RGPD : effacement complet, y compris les vœux dont on est la cible.
+    a = make_volunteer(session, edition, email="a@ex.fr")
+    b = make_volunteer(session, edition, email="b@ex.fr")
+    client.patch(_url(edition, f"/{a.id}"), json={"wished_companion_ids": [str(b.id)]})
+    assert client.delete(_url(edition, f"/{b.id}")).status_code == 204
+    assert client.get(_url(edition, f"/{a.id}")).json()["wished_companion_ids"] == []
+
+
 def test_patch_replaces_and_clears_wishes(client, edition, session):
     a1 = make_artist(session, edition, name="A1")
     a2 = make_artist(session, edition, name="A2")

backend/tests/test_models.py

@@ -20,6 +20,7 @@ EXPECTED_TABLES = {
     "volunteer",
     "volunteer_artist",
     "volunteer_position_wish",
+    "volunteer_companion_wish",
     "account",
     "magic_link_token",
     "position",

backend/tests/test_seed.py

@@ -20,6 +20,7 @@ def test_build_creates_a_realistic_dataset(session):
     assert summary.artists > 0
     assert summary.position_wishes > 0
     assert summary.artist_wishes > 0
+    assert summary.companion_wishes > 0
 
     edition = session.exec(
         select(Edition).where(Edition.name == DEMO_EDITION_NAME)
@@ -45,6 +46,7 @@ def test_build_is_deterministic_and_idempotent(session):
     assert second.artists == first.artists
     assert second.position_wishes == first.position_wishes
     assert second.artist_wishes == first.artist_wishes
+    assert second.companion_wishes == first.companion_wishes
 
     editions = session.exec(
         select(Edition).where(Edition.name == DEMO_EDITION_NAME)

backend/tests/test_solver_engine.py

@@ -21,6 +21,7 @@ def _shift(
     ideal_staff=1,
     already_assigned=0,
     predecessor_shift_ids=frozenset(),
+    assigned_volunteer_ids=frozenset(),
 ) -> SolverShift:
     return SolverShift(
         id=sid,
@@ -31,6 +32,7 @@ def _shift(
         ideal_staff=ideal_staff,
         already_assigned=already_assigned,
         predecessor_shift_ids=frozenset(predecessor_shift_ids),
+        assigned_volunteer_ids=frozenset(assigned_volunteer_ids),
     )
 
 
@@ -39,6 +41,7 @@ def _volunteer(
     *,
     availability=(),
     wished_position_ids=frozenset(),
+    wished_companion_ids=frozenset(),
     wished_artist_windows=(),
     existing_shifts=(),
     existing_minutes=0,
@@ -47,6 +50,7 @@ def _volunteer(
         id=vid,
         availability=tuple(availability),
         wished_position_ids=frozenset(wished_position_ids),
+        wished_companion_ids=frozenset(wished_companion_ids),
         wished_artist_windows=tuple(wished_artist_windows),
         existing_shifts=tuple(existing_shifts),
         existing_minutes=existing_minutes,
@@ -266,3 +270,39 @@ def test_artist_conflict_outside_shift_hours_has_no_effect():
     )
     solution = solve(SolverInput(shifts=(shift,), volunteers=(fan,)))
     assert _by_shift(solution, "s1") == ("fan",)
+
+
+def test_prefers_volunteer_whose_wished_companion_is_already_on_the_shift():
+    # « buddy » a souhaité être avec « copain », déjà affecté au créneau :
+    # préféré à « stranger », qui n'a pas ce lien.
+    shift = _shift(ideal_staff=2, already_assigned=1, assigned_volunteer_ids={"copain"})
+    buddy = _volunteer(
+        "buddy", availability=[_full_day(10)], wished_companion_ids={"copain"}
+    )
+    stranger = _volunteer("stranger", availability=[_full_day(10)])
+    solution = solve(SolverInput(shifts=(shift,), volunteers=(buddy, stranger)))
+    assert _by_shift(solution, "s1") == ("buddy",)
+
+
+def test_companion_bonus_scales_with_number_of_matches():
+    # Deux compagnons souhaités déjà présents valent mieux qu'un seul.
+    shift = _shift(
+        ideal_staff=4, already_assigned=2, assigned_volunteer_ids={"a", "b"}
+    )
+    two_friends = _volunteer(
+        "two_friends", availability=[_full_day(10)], wished_companion_ids={"a", "b"}
+    )
+    one_friend = _volunteer(
+        "one_friend", availability=[_full_day(10)], wished_companion_ids={"a"}
+    )
+    solution = solve(SolverInput(shifts=(shift,), volunteers=(two_friends, one_friend)))
+    assert _by_shift(solution, "s1") == ("two_friends", "one_friend")
+
+
+def test_wished_companion_absent_from_the_shift_has_no_effect():
+    shift = _shift()
+    volunteer = _volunteer(
+        "v", availability=[_full_day(10)], wished_companion_ids={"not-here"}
+    )
+    solution = solve(SolverInput(shifts=(shift,), volunteers=(volunteer,)))
+    assert _by_shift(solution, "s1") == ("v",)