Étape 22 : feuilles de poste (PDF), complément des badges

Une page par poste et par jour, listant les créneaux avec les bénévoles
affectés et leur téléphone — à imprimer et afficher sur place. Aucune
nouvelle entité : dérivé de Position/Shift/Assignment/Volunteer
existants (contrairement aux badges, pas de personnalisation à
configurer). Un créneau à besoin 0/0 sans affectation n'apparaît pas.

Backend : app/sheets/pdf.py (ReportLab, Platypus — SimpleDocTemplate/
Table plutôt que le canvas bas niveau des badges, plus adapté à un
rapport texte multi-pages), POST /editions/{id}/position-sheets/generate
(COORDINATION, {position_ids?} — absent = tous les postes).

Frontend : bouton « Feuilles de poste » dans la grille des besoins,
respecte le filtre de catégorie déjà actif à l'écran.

Vérifié : pytest (284 passés), ruff, alembic check, tsc --noEmit,
eslint, vite build, smoke (flux de bout en bout en mode démonstration)
— tous verts.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

backend/app/api/position_sheets.py

@@ -0,0 +1,115 @@
+"""Feuilles de poste (PDF) : une page par poste et par jour, listant les
+créneaux du jour avec les bénévoles affectés et leur téléphone — à imprimer
+et afficher sur place. Complément des badges (`app/api/badges.py`) : un
+badge identifie un bénévole, une feuille identifie un poste pour la
+journée. Voir `app/sheets/pdf.py` pour la composition du PDF.
+"""
+
+import datetime as dt
+import uuid
+from collections import defaultdict
+
+from fastapi import APIRouter, Depends, HTTPException, Response
+from sqlmodel import Session, select
+
+from app.api.deps import get_edition
+from app.api.schemas import PositionSheetsRequest
+from app.auth.deps import require_coordinator
+from app.db import get_session
+from app.models import Account, Assignment, Edition, Position, Shift, Volunteer
+from app.sheets.pdf import (
+    PositionDaySheet,
+    SheetShift,
+    SheetVolunteer,
+    generate_position_sheets_pdf,
+)
+
+router = APIRouter(
+    prefix="/editions/{edition_id}/position-sheets", tags=["position-sheets"]
+)
+
+
+@router.post("/generate")
+def generate_position_sheets(
+    payload: PositionSheetsRequest,
+    edition: Edition = Depends(get_edition),
+    _guard: Account = Depends(require_coordinator),
+    session: Session = Depends(get_session),
+) -> Response:
+    query = select(Position).where(Position.edition_id == edition.id)
+    if payload.position_ids is not None:
+        query = query.where(Position.id.in_(payload.position_ids))
+    positions = list(session.exec(query.order_by(Position.name)))
+    if not positions:
+        raise HTTPException(
+            status_code=422, detail={"code": "position_sheets.no_positions"}
+        )
+
+    position_ids = [p.id for p in positions]
+    shifts = list(
+        session.exec(
+            select(Shift)
+            .where(Shift.position_id.in_(position_ids))
+            .order_by(Shift.starts_at)
+        )
+    )
+    shift_ids = [s.id for s in shifts]
+
+    volunteers_by_shift: dict[uuid.UUID, list[Volunteer]] = defaultdict(list)
+    if shift_ids:
+        rows = session.exec(
+            select(Assignment.shift_id, Volunteer)
+            .join(Volunteer, Volunteer.id == Assignment.volunteer_id)
+            .where(Assignment.shift_id.in_(shift_ids))
+        ).all()
+        for shift_id, volunteer in rows:
+            volunteers_by_shift[shift_id].append(volunteer)
+        for vs in volunteers_by_shift.values():
+            vs.sort(key=lambda v: (v.last_name, v.first_name))
+
+    # Un jour sans aucun besoin réel (créneau 0/0 généré automatiquement,
+    # jamais rempli) n'apparaît pas — évite des pages « personne affecté »
+    # pour des créneaux qui ne représentent aucun besoin.
+    shifts_by_position_day: dict[tuple[uuid.UUID, dt.date], list[Shift]] = defaultdict(list)
+    for shift in shifts:
+        undefined_need = shift.min_staff == 0 and shift.ideal_staff == 0
+        if undefined_need and not volunteers_by_shift.get(shift.id):
+            continue
+        shifts_by_position_day[(shift.position_id, shift.starts_at.date())].append(shift)
+
+    positions_by_id = {p.id: p for p in positions}
+    sheets = [
+        PositionDaySheet(
+            position_name=positions_by_id[position_id].name,
+            position_location=positions_by_id[position_id].location,
+            date=date,
+            shifts=tuple(
+                SheetShift(
+                    starts_at=s.starts_at,
+                    ends_at=s.ends_at,
+                    min_staff=s.min_staff,
+                    ideal_staff=s.ideal_staff,
+                    volunteers=tuple(
+                        SheetVolunteer(name=f"{v.first_name} {v.last_name}", phone=v.phone)
+                        for v in volunteers_by_shift.get(s.id, [])
+                    ),
+                )
+                for s in sorted(day_shifts, key=lambda s: s.starts_at)
+            ),
+        )
+        for (position_id, date), day_shifts in sorted(
+            shifts_by_position_day.items(),
+            key=lambda item: (positions_by_id[item[0][0]].name, item[0][1]),
+        )
+    ]
+    if not sheets:
+        raise HTTPException(
+            status_code=422, detail={"code": "position_sheets.no_shifts"}
+        )
+
+    pdf_bytes = generate_position_sheets_pdf(sheets)
+    return Response(
+        content=pdf_bytes,
+        media_type="application/pdf",
+        headers={"Content-Disposition": 'attachment; filename="feuilles-de-poste.pdf"'},
+    )

backend/app/api/schemas.py

@@ -398,6 +398,14 @@ class BadgeGenerateRequest(ApiModel):
     volunteer_ids: list[uuid.UUID] | None = None
 
 
+# --------------------------------------------------------------------------- #
+# Feuilles de poste (PDF)                                                      #
+# --------------------------------------------------------------------------- #
+class PositionSheetsRequest(ApiModel):
+    # None/absent = tous les postes de l'édition.
+    position_ids: list[uuid.UUID] | None = None
+
+
 # --------------------------------------------------------------------------- #
 # Authentification et comptes                                                  #
 # --------------------------------------------------------------------------- #

backend/app/i18n/locales/fr.json

@@ -80,5 +80,7 @@
   "form.photo_type_not_supported": "La photo doit être au format PNG ou JPEG.",
   "form.photo_too_large": "La photo est trop volumineuse.",
   "form.too_many_position_wishes": "Deux vœux de poste au maximum.",
-  "form.too_many_artists_same_day": "Un seul artiste souhaité par soir de festival."
+  "form.too_many_artists_same_day": "Un seul artiste souhaité par soir de festival.",
+  "position_sheets.no_positions": "Aucun poste ne correspond à cette sélection.",
+  "position_sheets.no_shifts": "Aucun créneau à imprimer pour ces postes."
 }

backend/app/main.py

@@ -16,6 +16,7 @@ from app.api.health import router as health_router
 from app.api.imports import router as import_router
 from app.api.matrix import router as matrix_router
 from app.api.notifications import router as notification_router
+from app.api.position_sheets import router as position_sheets_router
 from app.api.positions import router as position_router
 from app.api.shifts import router as shift_router
 from app.api.solver import router as solver_router
@@ -74,3 +75,4 @@ app.include_router(matrix_router)
 app.include_router(notification_router)
 app.include_router(badge_router)
 app.include_router(form_router)
+app.include_router(position_sheets_router)

backend/app/sheets/__init__.py

@@ -0,0 +1,13 @@
+from app.sheets.pdf import (
+    PositionDaySheet,
+    SheetShift,
+    SheetVolunteer,
+    generate_position_sheets_pdf,
+)
+
+__all__ = [
+    "PositionDaySheet",
+    "SheetShift",
+    "SheetVolunteer",
+    "generate_position_sheets_pdf",
+]

backend/app/sheets/pdf.py

@@ -0,0 +1,148 @@
+"""Génération des feuilles de poste (PDF).
+
+Module isolé, fonction pure (`generate_position_sheets_pdf`) : aucun accès
+base ici — voir `app/api/position_sheets.py` pour l'assemblage des données.
+
+Une page par poste et par jour, listant les créneaux du jour avec les
+bénévoles affectés et leur téléphone — à imprimer et afficher sur place.
+Complément des badges (`app/badges/pdf.py`) : un badge identifie un
+bénévole, une feuille identifie un poste pour la journée.
+"""
+
+import datetime as dt
+import io
+from dataclasses import dataclass
+
+from reportlab.lib import colors
+from reportlab.lib.pagesizes import A4
+from reportlab.lib.styles import ParagraphStyle, getSampleStyleSheet
+from reportlab.lib.units import mm
+from reportlab.platypus import (
+    PageBreak,
+    Paragraph,
+    SimpleDocTemplate,
+    Spacer,
+    Table,
+    TableStyle,
+)
+
+_WEEKDAYS_FR = ["Lundi", "Mardi", "Mercredi", "Jeudi", "Vendredi", "Samedi", "Dimanche"]
+_MONTHS_FR = [
+    "janvier", "février", "mars", "avril", "mai", "juin",
+    "juillet", "août", "septembre", "octobre", "novembre", "décembre",
+]
+
+
+def _format_day_fr(date: dt.date) -> str:
+    return f"{_WEEKDAYS_FR[date.weekday()]} {date.day} {_MONTHS_FR[date.month - 1]} {date.year}"
+
+
+@dataclass(frozen=True)
+class SheetVolunteer:
+    name: str
+    phone: str | None
+
+
+@dataclass(frozen=True)
+class SheetShift:
+    starts_at: dt.datetime
+    ends_at: dt.datetime
+    min_staff: int
+    ideal_staff: int
+    volunteers: tuple[SheetVolunteer, ...]
+
+    @property
+    def understaffed(self) -> bool:
+        return len(self.volunteers) < self.min_staff
+
+
+@dataclass(frozen=True)
+class PositionDaySheet:
+    """Une page : un poste, un jour, ses créneaux triés chronologiquement."""
+
+    position_name: str
+    position_location: str | None
+    date: dt.date
+    shifts: tuple[SheetShift, ...]
+
+
+def _styles() -> dict[str, ParagraphStyle]:
+    base = getSampleStyleSheet()
+    return {
+        "title": ParagraphStyle(
+            "SheetTitle", parent=base["Title"], alignment=0, fontSize=22, spaceAfter=2
+        ),
+        "subtitle": ParagraphStyle(
+            "SheetSubtitle", parent=base["Normal"],
+            fontSize=12, textColor=colors.grey, spaceAfter=16,
+        ),
+        "shiftHeader": ParagraphStyle(
+            "ShiftHeader", parent=base["Heading3"], fontSize=13, spaceBefore=12, spaceAfter=4
+        ),
+        "shiftHeaderWarning": ParagraphStyle(
+            "ShiftHeaderWarning", parent=base["Heading3"],
+            fontSize=13, spaceBefore=12, spaceAfter=4, textColor=colors.HexColor("#b23a1f"),
+        ),
+        "normal": base["Normal"],
+    }
+
+
+def _shift_table(shift: SheetShift) -> Table:
+    rows = [["Bénévole", "Téléphone"]] + [
+        [v.name, v.phone or "—"] for v in shift.volunteers
+    ]
+    table = Table(rows, colWidths=[110 * mm, 55 * mm])
+    table.setStyle(
+        TableStyle(
+            [
+                ("FONTNAME", (0, 0), (-1, 0), "Helvetica-Bold"),
+                ("FONTSIZE", (0, 0), (-1, -1), 10.5),
+                ("TOPPADDING", (0, 0), (-1, -1), 5),
+                ("BOTTOMPADDING", (0, 0), (-1, -1), 5),
+                ("LINEBELOW", (0, 0), (-1, 0), 0.75, colors.black),
+                ("GRID", (0, 1), (-1, -1), 0.25, colors.lightgrey),
+            ]
+        )
+    )
+    return table
+
+
+def generate_position_sheets_pdf(sheets: list[PositionDaySheet]) -> bytes:
+    styles = _styles()
+    buffer = io.BytesIO()
+    doc = SimpleDocTemplate(
+        buffer, pagesize=A4,
+        leftMargin=18 * mm, rightMargin=18 * mm, topMargin=16 * mm, bottomMargin=16 * mm,
+    )
+
+    story = []
+    for i, sheet in enumerate(sheets):
+        if i > 0:
+            story.append(PageBreak())
+        story.append(Paragraph(sheet.position_name, styles["title"]))
+        subtitle = _format_day_fr(sheet.date)
+        if sheet.position_location:
+            subtitle += f" — {sheet.position_location}"
+        story.append(Paragraph(subtitle, styles["subtitle"]))
+
+        if not sheet.shifts:
+            story.append(Paragraph("Aucun créneau ce jour-là.", styles["normal"]))
+            continue
+
+        for shift in sheet.shifts:
+            header = (
+                f"{shift.starts_at:%H:%M} – {shift.ends_at:%H:%M}"
+                f"  ({len(shift.volunteers)}/{shift.ideal_staff})"
+            )
+            if shift.understaffed:
+                header += "  ⚠ sous l'effectif minimal"
+            style = styles["shiftHeaderWarning"] if shift.understaffed else styles["shiftHeader"]
+            story.append(Paragraph(header, style))
+            if shift.volunteers:
+                story.append(_shift_table(shift))
+            else:
+                story.append(Paragraph("Personne affecté pour l'instant.", styles["normal"]))
+        story.append(Spacer(1, 0))
+
+    doc.build(story)
+    return buffer.getvalue()

backend/tests/test_position_sheets_api.py

@@ -0,0 +1,69 @@
+"""Feuilles de poste (PDF) — API."""
+
+from app.models import Assignment, Role
+from tests.factories import dt_at, make_position, make_shift, make_volunteer
+
+
+def _url(edition):
+    return f"/editions/{edition.id}/position-sheets/generate"
+
+
+def test_is_coordinator_only(edition, make_account, as_account):
+    lead = make_account(Role.LEAD, email="lead@e.fr")
+    client = as_account(lead)
+    resp = client.post(_url(edition), json={})
+    assert resp.status_code == 403
+
+
+def test_rejects_when_no_position_matches(client, edition):
+    resp = client.post(
+        _url(edition),
+        json={"position_ids": ["00000000-0000-0000-0000-000000000000"]},
+    )
+    assert resp.status_code == 422
+    assert resp.json()["detail"]["code"] == "position_sheets.no_positions"
+
+
+def test_rejects_when_no_real_need_to_print(client, edition, session):
+    # Créneaux générés à 0/0, jamais remplis : rien à imprimer.
+    make_position(session, edition, name="Bar central")
+    resp = client.post(_url(edition), json={})
+    assert resp.status_code == 422
+    assert resp.json()["detail"]["code"] == "position_sheets.no_shifts"
+
+
+def test_generates_a_pdf_with_assigned_volunteers(client, edition, session):
+    position = make_position(session, edition, name="Bar central")
+    shift = make_shift(
+        session, edition, position, start=dt_at(9, 19), end=dt_at(9, 22),
+        min_staff=1, ideal_staff=2,
+    )
+    volunteer = make_volunteer(session, edition, first_name="Alex", last_name="Martin")
+    session.add(
+        Assignment(edition_id=edition.id, volunteer_id=volunteer.id, shift_id=shift.id)
+    )
+    session.commit()
+
+    resp = client.post(_url(edition), json={})
+    assert resp.status_code == 200
+    assert resp.headers["content-type"] == "application/pdf"
+    assert resp.content.startswith(b"%PDF")
+
+
+def test_position_ids_filter_scopes_the_sheets(client, edition, session):
+    bar = make_position(session, edition, name="Bar central")
+    welcome = make_position(session, edition, name="Accueil")
+    make_shift(
+        session, edition, bar, start=dt_at(9, 19), end=dt_at(9, 22),
+        min_staff=1, ideal_staff=2,
+    )
+    make_shift(
+        session, edition, welcome, start=dt_at(9, 9), end=dt_at(9, 13),
+        min_staff=1, ideal_staff=2,
+    )
+
+    resp = client.post(_url(edition), json={"position_ids": [str(bar.id)]})
+    assert resp.status_code == 200
+
+    resp = client.post(_url(edition), json={"position_ids": [str(welcome.id)]})
+    assert resp.status_code == 200

backend/tests/test_position_sheets_pdf.py

@@ -0,0 +1,70 @@
+"""Génération des feuilles de poste (module pur, sans base)."""
+
+import datetime as dt
+
+from app.sheets.pdf import (
+    PositionDaySheet,
+    SheetShift,
+    SheetVolunteer,
+    generate_position_sheets_pdf,
+)
+
+
+def _sheet(volunteers=(), min_staff=1, ideal_staff=2) -> PositionDaySheet:
+    return PositionDaySheet(
+        position_name="Bar central",
+        position_location="Chapiteau",
+        date=dt.date(2026, 7, 10),
+        shifts=(
+            SheetShift(
+                starts_at=dt.datetime(2026, 7, 10, 19, 0),
+                ends_at=dt.datetime(2026, 7, 10, 22, 0),
+                min_staff=min_staff,
+                ideal_staff=ideal_staff,
+                volunteers=volunteers,
+            ),
+        ),
+    )
+
+
+def test_shift_is_understaffed_when_below_min_staff():
+    fully_staffed = _sheet(
+        volunteers=(SheetVolunteer(name="Alex Martin", phone="0600000000"),),
+        min_staff=1,
+    )
+    assert fully_staffed.shifts[0].understaffed is False
+
+    understaffed = _sheet(volunteers=(), min_staff=1)
+    assert understaffed.shifts[0].understaffed is True
+
+
+def test_generates_a_valid_pdf_with_volunteers():
+    sheet = _sheet(
+        volunteers=(
+            SheetVolunteer(name="Alex Martin", phone="0600000000"),
+            SheetVolunteer(name="Sam Nuit", phone=None),
+        )
+    )
+    pdf = generate_position_sheets_pdf([sheet])
+    assert pdf.startswith(b"%PDF")
+    assert pdf.rstrip().endswith(b"%%EOF")
+
+
+def test_generates_a_valid_pdf_with_no_volunteers_assigned():
+    pdf = generate_position_sheets_pdf([_sheet(volunteers=())])
+    assert pdf.startswith(b"%PDF")
+
+
+def test_generates_a_valid_pdf_with_no_shifts_that_day():
+    sheet = PositionDaySheet(
+        position_name="Bar central", position_location=None,
+        date=dt.date(2026, 7, 10), shifts=(),
+    )
+    pdf = generate_position_sheets_pdf([sheet])
+    assert pdf.startswith(b"%PDF")
+
+
+def test_multiple_sheets_produce_a_larger_pdf():
+    one = generate_position_sheets_pdf([_sheet()])
+    two = generate_position_sheets_pdf([_sheet(), _sheet()])
+    assert len(two) > len(one)