planning-cardiomaine

Imported from zid-web/planning-cardiomaine (AGENTS.md). Install upstream with npx skills add zid-web/planning-cardiomaine. Copyright stays with the author.

AGENTS.md

Cursor Cloud specific instructions

Next.js 16 (App Router, React 19) + Supabase app ("Cardiomaine Planning", a French medical shift-scheduling tool). Package manager is bun (bun.lock). The single required service is the Next.js dev server; the backend is Supabase.

Backend Render (IMPORTANT — ne pas confondre)

• Le vrai solveur / API est le dépôt séparé github.com/zid-web/guard-api-cardiomaine (Render guard-api-cardiomaine.onrender.com).
• Le dossier guard-api/ dans ce repo (planning-cardiomaine) est un résidu : uniquement un README.md de redirection. Ne pas y remettre un miroir solver.py / patches / rules_config.json — source de confusion. Toute évolution backend = PR / push sur guard-api-cardiomaine uniquement.
• Correctifs RYTHMO (créneaux précis + vendredi P/U selon week_type) + allowlist historical_patterns + half_days_off : déjà fusionnés dans guard-api-cardiomaine (Claude + Cursor). Ne pas les retravailler ici.

Garde Nuit proposals / preferences

• generateNightGuardProposals (lib/guard-scheduler.ts) : Mar–Dim (+ Lun si FV vacances). Préférences : Lun→U, Mar→M/W, Mer→S/U/P, Jeu→O/G, Ven→rotation B/G/A/P/Z/H/S (O/W/M exclus). Pas de garde la veille d’un NCT pour le médecin NCT (W/M, calendrier NCT_DATES_2026). Miroir soft/hard dans guard-api-cardiomaine (NIGHT_GARDE_* / règles JSON).

Fixed clinical assignments & remplacant

• Règles fixes centralisées dans lib/fixed-assignments.ts (applyFixedClinicalAssignments) : IRM = S (Lundi matin + Vendredi après-midi), FV Garde Nuit Lundi + Coro Jeudi apm, DAAS = Apm - EE2 Lundi, Rythmo selon parité ISO (rythmoFixedSlotsForWeek) : impaire A Lun+Jeu apm, P Mar matin+apm, U Mer apm + Ven apm ; paire A Lun+Jeu apm, P Mar matin+apm, U Mer matin+apm, Ven matin alternance U/P. Visite = rotation U → A → B. DOC022 (ETT ped S mercredi Apm - ETT salle 1, etc.). Cases vides seulement : une saisie manuelle différente du titulaire n’est jamais réécrasée (ex. remplacer S en ETT ped). Si le titulaire est en congés, la contrainte saute (case libre). Case vidée → le défaut peut revenir. getAllVacations doit échouer proprement (pas [] silencieux) pour ne pas écraser Congés/Rythmo.
• Remplaçant texte libre : dans la modale d’affectation admin, champ « Remplaçant » → ajoute un libellé dans cell.value (badge ambre). Utiliser isListedDoctor / normalizeRemplacantLabel (lib/doctor-code.ts) — hors équité / hors contrôle vacances.
• Étiquettes variantes (lib/special-activity-labels.ts) : affichage seulement (pas de nouvelle activité solveur). S mercredi Apm - ETT salle 1 → badge S (ped) / « ETT pédiatrique » ; A mardi et P lundi Apm - Cs PSS → A (PM) / P (PM) / « Contrôle PM ». Compose avec doublon ² via formatDoctorWithDoublon. S mercredi : ETT ped compatible avec Garde Midi / ATL Midi (areCompatibleSamePeriod).
• Stress + D (lib/stress-rules.ts) : jamais Apm - Stress mercredi ni vendredi (cases grisées via isCellBlocked / refus canAssignDoctorToSlot). D (externe echo PSS) : tous les jeudis Stress matin ; 1er jeudi du mois aussi Stress apm ; autres jeudis EE1 + EE2 apm. Soft si D en congés.

Choix de Gardes (WE & fériés)

• Un seul mécanisme : remplir des initiales, exactement comme le calendrier NCT — plus de demandes / validation / refus (ancienne table guard_picks et ses server actions supprimées du code ; la table et les scripts SQL scripts/003/004 restent en base, inutilisés).
• components/guard-calendar-dialog.tsx : vue Mois (grille lundi→dimanche ; seuls samedis, dimanches et jours fériés sont cliquables ; chaque case montre ☀ Matin et ☾ Nuit avec les initiales colorées DOCTOR_COLORS) ⇄ vue Année (12 tuiles « n/N jours complets ») via le titre ; flèches ‹ › qui franchissent les années, ← → au clavier, « Aujourd'hui ». Férié = rose (prime sur le week-end), samedi bleu, dimanche gris, vacances scolaires zone B = ambre. Un jour sélectionné affiche les initiales des médecins pour Matin et Nuit ; un appui pose / retire l'initiale (bascule, toggleGuardDoctor), enregistrement immédiat.
• Les initiales sont écrites directement dans les lignes Garde Matin / Garde Nuit du planning de la bonne semaine (setGuardAssignment dans ScheduleApp) : saisie admin protégée (manualAssignment, ou manuallyCleared si vidée), ½ off de récupération après Garde Nuit recalculé comme dans la grille. Seuls les médecins que canAssignDoctor autorise sont proposés (congés, repos après garde, CH exclu…) + ceux déjà posés ; infirmières exclues ; valeurs non listées (remplaçant texte libre) affichées sans être modifiables ici.
• Admin uniquement pour modifier ; les autres rôles consultent (initiales en lecture seule). Logique pure testée : lib/guard-calendar.ts (guardDayKind, guardDatesInMonth, toggleGuardDoctor, guardFill).

Vues Aujourd’hui / Semaine

• UI moderne dans components/today-view.tsx et components/week-view.tsx (montées par ScheduleApp).
• Notes du jour (onglet Aujourd’hui) : carte cliquable → modale texte → saveScheduleToDb via updateSchedule sur la ligne Notes du jour.
• Toolbar admin : Journal = audit schedule_history (qui a changé quoi). Boutons outline : forcer !text-slate-900 + fond blanc (sinon icônes transparentes).
• Pages admin (/protected/admin/users|requests|feedback) : le layout racine est overflow-hidden — chaque page doit scroller avec h-full overflow-y-auto (sinon liste tronquée / emails invisibles).
• Couleurs / modales : dans app/globals.css, les tokens doivent être des couleurs CSS complètes (hsl(...)), pas des triplets HSL nus — sinon bg-card / bg-background → transparent (Notes du jour, Cards). Dialogs/Cards/Textarea : préférer bg-white text-slate-900 en secours.

Congés (ligne unique absences)

• Une seule ligne UI Congés (plus de ligne « Vacances »). normalizeLeaveSchedule (lib/vacation-congés-mapper.ts) : fusion legacy Vacances→Congés, remplissage depuis doctor_vacations, puis retrait des absents de toutes les autres lignes (y compris 1/2 journée off Matin/Après-midi).
• resolveRowKey mappe VACANCES et CONGE → Congés. detectConflict / canAssignDoctor n’appliquent pas le rouge conflit sur la ligne Congés — badges = DOCTOR_COLORS.
• Solveur Render : n’émettre que CONGE (dans guard-api-cardiomaine, pas le dossier local).
• Header admin Congé → VacationsModal : liste complète doctor_vacations (filtre médecin) + ajout / modification / suppression (vacation-actions.ts). Refresh via onVacationsUpdated → loadVacations dans ScheduleApp.
• populateCongesRowFromVacations reconstruit la ligne Congés depuis doctor_vacations (ajout et retrait). Modifier/supprimer des dates se répercute immédiatement sur le planning affiché ; persistance source: "constraints" sur les semaines déjà en mémoire (~150 ms).
• Écriture congés : addVacation / updateVacation n’écrivent que doctor_id + dates ; le motif reason est patché en best-effort (projets Supabase sans colonne → erreur PostgREST « schema cache »). Migration 20250726000000_doctor_vacations_reason_column.sql pour l’ajouter côté SQL.

1/2 journée off après Garde Nuit

• Règle (lib/half-day-off.ts) : après Garde Nuit → apm du lendemain (sauf vendredi et week-end). Si off habituel apm → matin. Vendredi nuit → pas de ½ off samedi (Sam Garde Matin = Ven Nuit). Dimanche → lundi semaine suivante.
• ½ off habituels (alignés rules_config.json de guard-api-cardiomaine) : Lundi matin R,K + am K ; Mardi am S ; Mercredi am M,W,G,Z,H,B ; Jeudi am U,P ; Vendredi matin K + am O,A,K,R,T.

Contraintes structurelles vs « Générer »

• Rotation LFB jeudi : H → S → G (modulo 3 sur le n° ISO), source unique LFB_POOL / lfbDoctorForWeekNum (lib/week-generation-params.ts), importée par apply-structural-constraints et schedule-utils. L'ordre était auparavant dupliqué dans trois fichiers avec deux valeurs différentes (G,S,H vs H,S,G) : le lfb_doctor envoyé au solveur ne désignait pas le médecin réellement posé, deux semaines sur trois.
• Consignes groupe DOC022 (PDF fonctionnement / répartition) : extraites dans docs/CONSIGNES-GROUPE-DOC022.md + lib/group-clinical-rules.ts. Noms médecins dans DOCTOR_METADATA, créneaux fixes ETT/EE/Scinti via applyFixedClinicalAssignments (dont T toujours sur EE1 le mercredi après-midi, consigne 26/08/2026), éligibilités envoyées en rules_override à /generate-week. Addon JSON : patches/rules_config-doc022-addon.json (à merger dans guard-api-cardiomaine si besoin de persistance serveur). Durées cs 20/30 min = hors grille planning.
• Toujours injectées (sans Générer) via applyStructuralConstraints (lib/apply-structural-constraints.ts) : IRM/FV/DAAS/Rythmo/Visite, ½-off habituelles, récupération garde nuit, Congés + strip absents, NCT calendrier, LFB, CH, ATL↔Coro, couplages weekend Garde/ATL. Appliqué à l’affichage + persisté (source: "constraints", debounce).
• Typecheck : npm run typecheck (tsc --noEmit). tsconfig.json fixe une liste explicite de types (node, react, react-dom) — sans elle TS inclut tous les @types/* du projet, dont le stub vide @types/minimatch tiré transitivement, échoue sur TS2688 et abandonne avant de vérifier le moindre fichier : la commande ne rapportait alors plus aucune erreur, y compris sur du code manifestement invalide. Le dépôt est à zéro erreur : le typecheck peut être branché en CI.
• Blocages assignation (lib/slot-blocking.ts) : jamais de médecin en congés hors ligne Congés ; ½-off Matin ⇒ pas d’activité matin ; ½-off Apm ⇒ pas d’activité apm ; 1 tâche / créneau matin|apm (sauf ATL+Coro, ETT salle1+salle2, EE1+EE2, et Garde Matin + I → Cs/ETT/EE matin autorisés, pas Coro/Rythmo/Rééducation) ; pas de cumul Cs PSS+Tessée ; LFB/CDL vs garde : le blocage du même jour ne porte plus que sur le créneau qui se chevauche (offSiteBlocksGardeSameDay) — hors site le matin ⇒ Garde Midi et Garde Nuit restent possibles ; hors site en journée entière ⇒ toutes les gardes bloquées, comme avant. Le lendemain d'une garde reste interdit quel que soit le créneau (repos post-garde) ; CDL mardi = matin seulement (O / V) → l’après-midi reste assignable (Astreinte ATL Midi + Coro apm), comme l’IRM lundi matin / vendredi apm. Doublon : Cs = 2× dans la même case → B² ; ETT et EE = les deux salles du créneau → S² / G². Interne I : Garde Matin uniquement ; S+I peut aussi rester sur IRM. CH : astreintes ATL uniquement — jamais Garde Matin/Midi/Nuit. Garde week-end + remplaçant : toujours autoriser l’association avec un médecin listé (merge solveur préserve le remplacant). Val en ETT : toujours ETT salle 2, jamais salle 1 (canNurseTakeRow, NURSE_FORBIDDEN_ROWS) — ETT Tessé reste ouvert. IRM strictement réservée à S (IRM_DOCTOR) : refusée à tout autre médecin, et case grisée quand S est en congés (isIrmSlotClosed, la case n'a alors aucun candidat). Vacations non bloquantes (NON_BLOCKING_ROWS) : Entrées PSS, Pré-op et Matin - Visite (B/U/A — pas de Apm - Visite dans la grille) n'occupent pas le créneau — le médecin qui y figure reste assignable à une autre tâche la même demi-journée ; congés et ½-off continuent de s'appliquer. Garde Nuit Lun-Ven : jamais deux nuits consécutives (adjacentWeekdayNightGuard) — le week-end est exempt (Ven Nuit → Sam Matin est un enchaînement voulu). UI : canAssignDoctor(..., { schedule, day }) + applySlotBlockingStrips.
• Infirmières (Val / Véro / Laura) (lib/nurse-rules.ts, liste NURSES dans lib/constants.ts) : jamais préfixées « Dr. » à l’affichage — tout rendu d’un intervenant passe par formatPersonLabel (lib/doctor-code.ts), qui renvoie Dr. X pour un médecin et le nom seul pour une infirmière ou pour CH (structure externe, pas une personne). plannings fixes par parité de semaine, binôme médecin obligatoire sur Stress/EE (STRESS_PARTNER_POOL / EE_PARTNER_POOL), Val seule autorisée sur ETT2 / ETT Tessé. Véro est au Stress tous les mardis et mercredis matin (les deux parités — elle n’est plus sur EE1 le mardi matin en semaine impaire) ; Val est à l’ETT Tessé les mardis et mercredis matin dans les deux parités (elle n’a plus le tour de Stress du mardi impair ni EE1 le mercredi matin) et garde EE1 jeudi matin (seul EE1 matin ouvert). Laura en congés → repli systématique sur Val (NURSE_ABSENCE_FALLBACK, appliqué dans applyNurseFixedAssignments) : Val est libérée de ses autres vacations fixes de la même demi-journée.
• Cases fermées (lib/closed-slots.ts, point d’entrée unique isSlotClosed) : Stress mercredi / vendredi apm (historique) et EE1 matin fermée lundi, mardi, mercredi, vendredi — seul le jeudi matin reste ouvert (consigne 26/08/2026 ; le matin, tout passe par EE2). Utilisé par canAssignDoctorToSlot (refus + message), isCellBlocked (case grisée UI) et applyClosedSlotsClear (vidage structurel).
• Visite hebdomadaire (lib/visite-rotation.ts) : la ligne Matin - Visite est une vacation de semaine (rotation U/A/B). Un changement manuel d'initiales sur une case se reporte du lundi au vendredi (spreadVisiteAcrossWeek, branché dans patchSelectedCell). Le report est désactivable case par case : un interrupteur « Reporter sur toute la semaine » dans la modale (actif par défaut) permet à l'admin de ne modifier que le jour en cours — l'exception ainsi posée survit aux contraintes structurelles (la rotation Visite ne remplit que les cases vides). Deux garde-fous : un jour où le médecin a une contrainte le matin (congés, ½-off matin) est laissé vide au lieu de recevoir une affectation impossible, et une case manuallyCleared n'est jamais re-remplie. La visite ne concerne que le matin et reste non bloquante : le médecin est assignable l'après-midi comme sur une autre tâche du matin.
• Créneau des vacations hors site (lib/off-site-slots.ts) : chaque case « Hors site - … » porte son créneau réel dans CellData.offSiteSlot (matin / apm / journée), modifiable case par case depuis la modale (sélecteur) et signalé dans la grille par un badge M / AM / J. periodOfRow(row, day, schedule) le lit pour décider de la disponibilité : hors site le matin ⇒ l’après-midi reste assignable, et inversement. Le sélecteur est actif : changer le créneau applique la conséquence immédiatement via applyOffSiteSlotRestriction — passer à « Journée » retire les vacations de la demi-journée nouvellement couverte, passer à « Matin » / « Après-midi » libère l’autre. Gardes et astreintes ne sont jamais retirées en silence : elles sont remontées dans conflicts et signalées à l’admin. Sans choix explicite, DEFAULT_OFF_SITE_SLOTS s’applique — IRM S lundi matin + vendredi apm, CDL mardi matin, Scinti lundi/mardi/mercredi matin, LFB / PSSL / NCT journée entière (indisponible ce jour-là). Les plannings déjà enregistrés gardent donc leur comportement à l’identique.
• Préférences de vacation souples (lib/vacation-preferences.ts) — « souvent » / « rarement », distinctes des créneaux fixes et des blocages durs. Consignes 26/08/2026 : K souvent au Stress mardi matin (binôme Véro), K rarement au Stress mercredi matin, S souvent au Stress vendredi matin sauf lendemain de garde de nuit ou congés, H souvent en EE2 lundi matin sauf congés (remplace le créneau fixe DOC022 « EE2 matin réservé Dr Lefebvre », retiré), R souvent en EE2 mercredi matin sauf congés (sa Scinti du mardi matin est inchangée), O souvent en EE2 vendredi matin sauf congés. EE2 matin n’a plus aucun créneau fixe : les réservations DOC022 « Dr Lefebvre » (lundi) et « Dr Bros » (vendredi) sont devenues des préférences souples. Deux points d’application : applyPreferenceBias biaise historical_patterns avant /generate-week (souvent → fréquence au-dessus du meilleur autre candidat ; rarement → retiré des eligible_doctors sauf s’il est le seul candidat), et preferredPartnerForNurseSlot oriente le médecin proposé en binôme dans ensureNurseDoctorBinomeProposals.
• Astreintes ATL :
  • Gardes Lun-Ven : Garde Matin / Midi / Nuit reviennent au même médecin (applyWeekdayGardeCoupling, ancré sur la Garde Nuit). Couplage souple : seules les cases vides sont remplies, toute exception saisie à la main est conservée. FV est exclu du couplage (GARDE_COUPLING_EXCLUDED) — externe, il ne fait que Garde Nuit lundi + Coro jeudi apm ; propager sa nuit occuperait la Garde Matin/Midi du lundi.
  • Pool général : M, O, W, CH. FV : uniquement ATL Midi jeudi (= miroir Apm Coro jeudi) — jamais Matin, Nuit, ni les autres AM. Front : isAtlEligibleForCell + sync Coro↔ATL. Payload solveur astreinte_allowed = M/O/W/CH (FV ATL jeudi via contraintes structurelles, pas de vars ASTREINTE globales FV).
  • rules_config.json Render : ne jamais mettre FV dans astreinte_allowed (ça recrée le bug « Aucune solution »). Canonical : patches/rules_config-cardiomaine-canonical.json + patch patches/guard-api-rules-astreinte-without-fv.patch. Coro garde ["W","M","O","FV"].
  • « Aucune solution trouvée » : souvent astreinte_allowed avec FV global + couplage ATL=Coro comptant CORO+ASTREINTE ×2. Warning LFB indépendant. Patch exclusivité : patches/guard-api-atl-coro-slot-exclusivity.patch.
• ATL Matin/Midi Lun–Ven = Coro pour M/O/W ; pour FV seulement jeudi Apm. applyAtlFollowsCoroConstraints unifie. Cumul autorisé dans slot-blocking.
  • Nuits + weekend (cycle 2 sem., source unique lib/astreinte-cycle.ts — isWomAstreinteWeek / isChAstreinteWeek / chNightWeekdaysForWeek) : semaine CH = CH Lun/Mar/Ven nuit + weekend ATL entier ; W/O/M = Mer/Jeu nuit. semaine WOM = W/O/M Lun/Mar/Ven nuit + weekend ATL (mono/combo habituels) ; CH = Mer/Jeu nuit. Jusqu'à 2026 : semaine CH = n° ISO impair. À partir de 2027-W01 : roulement inversé (S1 2027 = semaine WOM, alternance comptée depuis la S1 2027 — pas par parité, pour survivre aux années à 53 semaines). Ne pas utiliser isOddIsoWeek pour ce roulement (il reste pour Rythmo / infirmières / Coro vendredi, inchangés). Le solveur reçoit astreinte_week_type (1 = CH, 2 = WOM) en plus de week_type ; patch backend à appliquer sur guard-api-cardiomaine : patches/guard-api-astreinte-cycle-2027.patch (sans lui, « Générer » propose l'ancien roulement en 2027 — les contraintes structurelles corrigent CH mais les nuits W/O/M Lun/Mar/Ven restent à saisir). Weekend ASTREINTE mappe vers Astreintes ATL Matin (pas Garde).
  • Roulement CH modifiable : applyChAstreinteConstraints ne réécrit jamais une case ATL Nuit / ATL week-end saisie par l'admin (CellData.manualAssignment, posé par patchSelectedCell) ni vidée (manuallyCleared) — échange ponctuel CH ↔ W/O/M possible (ex. W fait le mercredi de CH). Sans saisie admin : CH ajouté sur ses nuits, retiré des autres. CH reste toujours retiré des Gardes et des ATL Matin/Midi en semaine.
  • Ven ATL Nuit = Sam ATL Nuit (même médecin, soft) — applyFriSatAtlNightCoupling.
  • Weekend ATL WOM (lib/weekend-wom-rules.ts, semaines paires) :
    • Combo (exactement 5 / semestre, calendrier WOM_COMBO_WEEK_KEYS_OVERRIDE / indices) : rôle A = Ven ATL Nuit + Sat ATL + Garde Dim ; rôle B = Garde Sam + Sun ATL (A/B = rôles, pas le code médecin « A »). Presets : lib/weekend-wom-presets.ts (ex. W40/48 mono ; W42 O+M ; W44 W+O ; W52 special M Jeudi nuit + Ven matin/midi/nuit — force M même si CH structurel). Remplissage week-end : jamais un médecin en vacances ; saisie manuelle (médecin disponible) non écrasée ; cases vides seulement pour la consigne. Après strip congés (étape 10bis), pas de réinjection de l’absent (ex. W32 8–9/08/2026) — sinon M réapparaît et bloque l’édition manuelle.
    • Solveur « Générer » : sur semaines combo uniquement, generateGuardsViaAPI envoie weekend_astreinte_combo + ancres (lib/weekend-combo-solver.ts / buildWeekendComboSolverFields). last_combo_garde_doctor/date lus/écrits dans settings (après Générer + validation Garde Sam) pour l’espacement 15 j. — lire le résultat réel, pas seulement l’ancre.
    • Mono (autres week-ends WOM) : Sat+Sun ATL Matin/Midi/Nuit = un seul M/O/W (équité 6 mois), vacances respectées.
    • Soft fill only (cases vides / absents retirés) — override admin disponible conservé.
  • Weekend ATL jour : couplage souple Matin/Midi/Nuit — applyWeekendGardeAtlCoupling.
  • Pas de nuits ATL consécutives Lun–Ven pour W/O/M (weekend et CH exempts) — solveur §5quinquies ; dérogation = saisie admin / existing_schedule.
  • generateGuardsViaAPI dérive week_type du n° de semaine ISO (ne plus laisser le défaut 1).
• Weekend Garde (applyWeekendGardeAtlCoupling + WOM rules) — saisie manuelle possible ; soft suggestions :
  • Sam : un médecin Matin → Midi → Nuit si cases vides (priorité Matin).
  • Dim Matin = Midi = Nuit (soft).
  • Sam Matin dérivé de Ven Garde Nuit + Sam Midi si Matin vide.
  • Combo WOM : Garde Sam/Dim complémentaires à l’ATL (voir ci-dessus).
  • Ne jamais réécraser une case déjà pourvue.
  • Patch solveur historique : patches/guard-api-weekend-garde-atl-rythmo.patch ; notes combo WOM : patches/guard-api-weekend-wom-combo.md
• « Générer » = propositions pending (gardes/astreintes WOM/Coro/…) à valider admin. Lignes : GENERATOR_PROPOSAL_ROW_KEYS. UI : cases violet + badge Prop. (isSolverProposalCell) — distinct des fixes/validated et des demandes de changement (orange). mergeSolverWeekIntoExisting : une case validated avec médecin listé n’est pas écrasée (saisie manuelle prime) ; remplaçant seul peut encore recevoir une proposition.
• Temps réel sur l'app installée (Android / iOS PWA) : ScheduleApp s'abonne à schedules pour tous les rôles (médecins compris ; toast réservé aux admins), plus doctor_vacations et settings (clé nct_calendar) — ces deux tables sont ajoutées à supabase_realtime par la migration 20261003000000_enable_realtime_vacations_settings.sql (à appliquer en prod ; sans elle ces deux abonnements restent muets). Les websockets sont coupés quand l'app passe en arrière-plan (surtout iOS) : au retour (visibilitychange ≥ 5 s caché, pageshow bfcache, online) une resynchronisation complète recharge planning, congés, calendrier NCT et demandes (au plus 1 fois / 20 s). Nouvelle version : AppUpdateWatcher vérifie /api/version chaque minute, à l'ouverture (3 s), au focus / pageshow / retour visible, et force reg.update() du service worker ; il propose « Recharger » (jamais de rechargement forcé : une modale peut contenir une saisie). Pas de notification push app fermée (Web Push non implémenté).
• Calendrier NCT modifiable (lib/nct-calendar.ts, app/actions/nct-calendar-actions.ts, components/nct-calendar-modal.tsx) : le calendrier par défaut (2025-12 + 2026, ex-NCT_DATES_* de guard-scheduler, ré-exportés) est surchargé par settings.nct_calendar (JSON, admin uniquement, pas de migration). Tous les consommateurs lisent getNctCalendar() / nctDoctorForDate (structurel, seed generateWeekSchedule, garde nuit « veille de NCT », guard-generation) ; ScheduleApp charge la liste au montage (loadNctCalendar) et bloque la persistance structurelle tant qu'elle n'est pas prête (nctReady), sinon une date supprimée serait réinjectée. Trois entrées : bouton NCT (modale : ajouter / supprimer / changer date ou W↔M, « Par défaut »), modification directe de la case Hors site - NCT (le calendrier suit via withNctEntry — sans cela la contrainte structurelle remettrait l'ancien médecin), dictée/saisie de liste de dates. Une date supprimée vide la case dans les semaines déjà enregistrées (commitNctCalendar) ; ajout / réaffectation sont appliqués par applyNctCalendarConstraints. generateGuardsViaAPI recharge le calendrier côté serveur (setNctCalendar). Médecins proposés dans la modale : W / M. Le sélecteur d'affectation de la case Hors site - NCT n'accepte aussi que W / M (canAssignDoctorToSlot : les autres médecins sont grisés avec le motif « Le NCT est réservé à W ou M » ; remplaçant texte libre toujours possible ; les valeurs déjà présentes ne sont pas retirées d'office). Pour ouvrir le NCT à d'autres médecins : élargir NCT_DOCTORS (lib/nct-calendar.ts), la modale et la règle suivent. Modale : vue Mois (grille lundi→dimanche, clic sur un jour = W → M → supprimer ; flèches ‹ › qui passent d'une année à l'autre) ⇄ vue Année (12 tuiles avec les dates, clic = ouvre le mois) via le titre ; ← → au clavier, bouton « Aujourd'hui », ouverture sur le mois de la semaine affichée (buildMonthGrid / shiftMonth / cycleNctUser). Jours fériés (rose, calculés dont Pâques/Ascension/Pentecôte) et vacances scolaires zone B (ambre) dans lib/french-calendar.ts — affichage seulement, mêmes codes couleur dans le planning global (en-tête de colonne + cases : férié = rose + bordures latérales, vacances zone B = ambre, légende en haut de la grille ; cases bloquées inchangées) ; données zone B 2025-26 et 2026-27 complètes, 2027-28 partiel (Toussaint + Noël) : compléter SCHOOL_HOLIDAYS_ZONE_B pour hiver/printemps 2028 et les années suivantes.
• Effacer les propositions (lib/clear-solver-proposals.ts, bouton « Effacer propositions (n) » à côté de Générer/Retour dans « Outils », toujours présent pour l'admin — grisé avec le message « Aucune proposition à effacer » quand il n'y a aucune case violette, pour ne pas donner l'impression qu'il a disparu) : retire toutes les cases isSolverProposalCell de la semaine, sans toucher aux cases validées, aux demandes de changement (request), aux manualAssignment, ni aux remplaçants/infirmières d'une case proposée. Les cases vidées ne sont pas manuallyCleared : applyStructuralConstraints les repeuple (LFB, CH, couplages…). Différent de Retour (restaure l'instantané d'avant Générer, donc perd aussi les saisies faites depuis) ; efface l'instantané Retour de la semaine. Sauvegarde source: "revert". Mobile : en vue Globale la barre d'outils est repliée derrière « Outils » ; le bouton (clearProposalsButton) est aussi rendu à côté d'« Outils » quand la barre est repliée et qu'il y a au moins une proposition, avec libellé court « Effacer (n) » sous md. Le solveur n'a pas de graine aléatoire : un nouveau Générer peut redonner les mêmes propositions.
• Paramètres semaine avant Générer (icône engrenage à côté du bouton) : visite_doctor (U/A/B), lfb_doctor (H/S/G), pssl_b_active (B jeudi), pssl_z_active (Z mardi). Défauts = rotation weekNum % 3 / parité ; l’admin peut corriger. Envoyés dans /generate-week (optionnels, rétrocompatibles). Helpers : lib/week-generation-params.ts. LFB structurel aligné H/S/G (plus B/Z/A). PSSL éditable Mardi + Jeudi.
• Congés CRUD : ne pas revalidatePath('/protected/planning') pendant la modale (course / faux positif « message channel closed »). Refresh via onVacationsUpdated + getAllVacations (noStore).
• Do not reintroduce generateWeekWithSolver / second bouton solveur.
• Equity / CellData: { value: string[], status, type? } + row key. Use lib/equity-tracking.ts. Fenêtre glissante 6 mois pour toutes les catégories : astreinte/garde/nct/weekend (getCumulativeEquityFromTable + repli JSON), CORO (getCoroEquity / points_coro), et Groupe 1 Cs/ETT/Stress (getGroupe1Equity → points_cs / points_ett / points_stress). Pas « depuis toujours », pas « mois calendaire ». Recalculée à chaque Générer ; pas de colonnes DB pour CORO/Cs/ETT/Stress (scan schedules). Lignes Cs = PSS+Tessée ; ETT = salles 1+2 ; Stress = Matin+Apm. Le solveur n’utilise Cs/ETT/Stress que pour B/Z/H/G/S.

Run / build / lint

• Dev server: bun run dev → http://localhost:3000 (this is the app; use dev, not build/start).
• Un seul next dev : si .next/dev/lock est pris (ou port 3000 déjà occupé), tuer l’ancien processus puis relancer — un second bun run dev échoue ou bascule sur 3001.
• Unit tests : bunx tsx lib/__tests__/<name>.test.ts (pas de script test npm ; pas de Jest).
• Build: bun run build (note: next.config.js sets typescript.ignoreBuildErrors: true, so TS errors do not fail the build).
• Lint: bun run lint works (flat config in eslint.config.mjs). It is configured to exit 0 with warnings only; several noisy/pre-existing rules (incl. React Compiler rules from react-hooks v6) are set to warn on purpose.
• Standard commands are also in README.md and QUICK_REFERENCE.md.
• E2E UI sans TEST_LOGIN_* : se connecter via le Desktop pane (session cookie) ; SUPABASE_SERVICE_ROLE_KEY suffit pour scripts admin.
• Roadmap options G1–G7: see docs/PLAN-OPTIONS-G1-G7.md. Prefer implementing through ScheduleApp + schedule-actions.ts; do not rebuild planning in page.tsx.
• Production go-live checklist (Vercel env vars, migrations, smoke tests): docs/PRODUCTION_CHECKLIST.md. Prefer console.error/warn only — avoid reintroducing [v0] debug console.logs.
• Performance / monitoring: docs/PERFORMANCE.md (Render keep-alive cron /api/ping-solver, SWR on planning, solver cache, Speed Insights). User testing: docs/USER_TESTING_PLAN.md + in-app Feedback → app_feedback / /protected/admin/feedback.
• Vercel / v0 URLs: Stable Production alias for keep-alive: https://v0-recreate-attached-ui-zids-projects-22b662f4.vercel.app/api/ping-solver (public JSON). Do not use old hashed deploy URLs like …-p2ci9kbnq-… — they are immutable snapshots and may still redirect to /auth/login. Hobby-safe daily cron only in vercel.json; use external 5–10 min ping for Render warmth.
• G1–G3 shipped pattern: PDF export is client-side (downloadPlanningPdf / lib/planning-pdf.ts) to avoid Vercel 413 on GET /api/export-planning-pdf (oversized Supabase auth cookies). The API route remains as fallback. PDF import via /api/upload-pdf is capped ~4 Mo (Vercel body limit). All week writes go through saveScheduleToDb (increments version, writes schedule_history, syncs full_schedule blob). Realtime: schedules is in supabase_realtime — ScheduleApp subscribes for admins and ignores own updated_by + the full_schedule blob key. After supabase db reset, recreate local test users (admin/doctor).
• G4: CSV/XLSX import in VoiceAndUploadPanel (local parse via lib/planning-import.ts → mapped_existing_schedule). Sample: fixtures/sample-planning-import.csv.
• G5: /protected/admin/users uses Server Actions + SUPABASE_SERVICE_ROLE_KEY (lib/supabase/admin.ts). Set that env var on Vercel; never expose it to the client.

Roles & API gotchas

• /protected/planning is a thin loader that renders ScheduleApp (components/schedule-app.tsx). Do not reintroduce a full planning implementation in app/protected/planning/page.tsx. Change requests, voice/PDF panel, solver persistence, and grid editing live in ScheduleApp. Guard generation sends previous_sunday_guard_doctor via getLastSundayGuardDoctor in app/actions/guard-api-actions.ts.
• profiles.role defaults to 'admin' (init migration), so brand-new users are admins. The planning page treats role === 'admin' as admin (direct grid editing + change-request approval panel); any other role is a "doctor" who can only submit change requests. To test the doctor flow, set a user's role to something else (e.g. UPDATE profiles SET role='doctor' WHERE ...).
• Admin hors planning (Lucie = L) : luciecardiomaine@gmail.com → profiles.role=admin + doctor_code=L. Pas dans DOCTORS (aucune tâche médicale). Édition grille des autres médecins OK. Saisies auto-validated via adminEditsAreValidated (lib/staff-admin.ts). Créer/maj : bun scripts/ensure-staff-admins.ts (service role) ou /protected/admin/users.
• Admin change-requests UI lives at /protected/admin/requests (app/protected/admin/requests/page.tsx): filters (status / date range / requester / requested doctor), pagination (20/page, count: 'exact' + range), full history (all statuses), detail modal with reject comment, and Supabase Realtime (INSERT on change_requests → toast + badge + list refresh). Migration 20250204000000_enable_realtime_change_requests.sql adds the table to supabase_realtime (do not drop that publication). Approve/reject stays in app/actions/change-request-actions.ts. The old path /protected/change-requests is a thin redirect() only — do not reintroduce a full page there. Emails demandeurs : chargés via requête profiles séparée (pas d’embed profiles(email) — 400 PostgREST si FK absente en prod).
• Route protection lives in root proxy.ts (Next.js 16; replaces middleware.ts). It uses Supabase SSR getUser() (not a raw cookie name check). Public: /, /auth/login, /auth/sign-up, /auth/forgot-password. Unauthenticated /api/* redirects to login — use a session for voice/PDF proxies.
• /api/voice-command and /api/upload-pdf are proxies to the Render guard API (GUARD_API_BASE_URL or fallback GUARD_API_URL, default https://guard-api-cardiomaine.onrender.com), optionally with GUARD_API_KEY (x-api-key header + x_api_key query). PDF upload goes direct browser → Render (lib/pdf-upload-client.ts) to avoid Vercel 504 on multi-page Claude Vision (1–3 min); /api/upload-pdf is fallback only (maxDuration = 60). Voice still uses the Next proxy. Prefer the stable Production alias, not preview …-dpl_… / hashed URLs.
• Voice payload expected by Render (built in VoiceAndUploadPanel / lib/guard-api-mapping.ts): { text, reference_date, known_doctors, current_week_request } where current_week_request matches /generate-week (week_start_date, week_type, medecins, …). Response is applied via parsed_command (surgical cell update), not the old local { operations: [...] } shape. PDF response uses raw_extraction.rows / mapped_existing_schedule (keys like Garde Nuit||LUNDI). Set GUARD_API_BASE_URL + GUARD_API_KEY on Vercel when needed.
• Voice doctor_in=null / weekend/ASTREINTE : Claude renvoyait parfois doctor_in: null → ValidationError Pydantic, ou slot=weekend + ASTREINTE → 422 « Combinaison créneau/activité non reconnue ». Correctif backend à porter sur guard-api-cardiomaine (patches/guard-api-voice-weekend-astreinte.md + patch doctor_in Optional). Repli front : shouldUseLocalVoiceFallback + parseVoiceCommandLocally dans VoiceAndUploadPanel (weekend → Astreintes ATL Matin via resolveRowKey).
• Voice mic (Web Speech) : helpers in lib/speech-recognition.ts. Requires Chrome/Edge + HTTPS (or localhost) + micro autorisé. Le panneau demande getUserMedia avant SpeechRecognition.start(), affiche les erreurs (not-allowed, etc.), écoute en continuous, et garde le textarea visible pendant la dictée. no-speech / aborted : non bloquants — auto-restart tant que l’utilisateur n’a pas arrêté le micro (wantListeningRef). Saisie manuelle + Appliquer reste le fallback. Après apply : si parsed_command ne modifie rien, fallback mergeAssignmentsIntoSchedule(..., { proposalRowsOnly: false }) ; date hors semaine affichée → écriture sur la bonne week_key.
• NCT dictée / saisie : resolveRowKey mappe toute combinaison */NCT → Hors site - NCT (Claude renvoie souvent matin/NCT). Une liste multi-dates (2026-09-10 → M) est détectée localement (lib/nct-command.ts) et appliquée sur les semaines concernées sans passer par Render. Évolutions prompt voice = guard-api-cardiomaine uniquement.
• Import historique multi-semaines : PDF avec weeks[] → HistoryImportDialog (review admin) → commitHistoryImport (lib/history-import.ts + app/actions/import-history-actions.ts). Ne remplit que cellules vides, ignore OCR confidence: low.
• « Générer » (une seule passe) : generateGuardsViaAPI calcule historical_patterns via buildHistoricalPatternsPayload (lib/pattern-analysis.ts, allowlist Cs/ETT/EE/Stress — isSolverHistoricalRowKey). Le solveur guard-api-cardiomaine applique la même allowlist + Rythmo précis (rythmo_slots, vendredi P/U) et émet aussi les hors site via HORSSITE::*. Côté front, resolveRowKey mappe les activités HIST/HORSSITE (suffixes Cs PSS, CDL, …) vers les row keys ; GENERATOR_PROPOSAL_ROW_KEYS inclut Cs/ETT/EE/Stress + hors site (sauf NCT calendrier) → cellules pending / violet « Prop. » à valider. NCT / Rythmo fixe / ½-off restent structurels validated.
• Suspensions d’activité (activity_maintenance) : même principe que room_maintenance (Coro) — période + liste d’activités bloquées pour tout le monde. Front : lib/activity-maintenance.ts (calendrier 2026 : PSSL/LFB/CDL S28–S36, NCT S31–S36) → payload /generate-week + clear structurel (applyActivityMaintenanceClear / LFB & NCT skip). Pas de formulaire UI pour l’instant (calendrier codé) ; vocal activity_maintenance = optionnel côté backend si besoin.
• Doublon Cs solveur : le backend peut émettre 2 Assignment identiques (ex. Apm Cs PSS Lun Z / Mar H, 2ᵉ note "… (doublon)"). mergeAssignmentsIntoSchedule + mergeCellDoctorsPreservingRemplacants ne dédupliquent pas les lignes isDoublonEligibleRow (lib/slot-blocking.ts) pour garder ["Z","Z"] → affichage Z². Les autres lignes restent dédupliquées.
• PDF « JSON malformé » : root cause dans guard-api-cardiomaine (pdf_upload.py / llm_json.py), pas le proxy Next. Corriger uniquement dans ce dépôt.

Configuration Supabase (code, pas Vercel)

• Source unique : lib/supabase/config.ts (getSupabaseConfig). Le projet de production (rmrxsaiianffhpxpntws, clé anon publique) est fixé dans le code pour le navigateur (client.ts), le serveur (server.ts), le proxy (proxy.ts, lib/supabase/proxy.ts) et l'admin (admin.ts, URL). Les variables Vercel NEXT_PUBLIC_SUPABASE_URL / NEXT_PUBLIC_SUPABASE_ANON_KEY sont ignorées (un avertissement console le signale) — l'intégration Supabase de Vercel (17/07) injecte celles d'un autre projet (cdvz…) et cassait la connexion dès qu'elles atteignaient le build.
• Exception : Supabase local (NEXT_PUBLIC_SUPABASE_URL en localhost / 127.0.0.1 et clé fournie) → l'environnement est respecté, pour les tests de bout en bout ci-dessous.
• Changer de projet = modifier SUPABASE_PROJECT_URL / SUPABASE_PROJECT_ANON_KEY dans config.ts. SUPABASE_SERVICE_ROLE_KEY (Vercel, Secret) doit appartenir au même projet que l'URL.
• Diagnostic : /api/debug-env (connecté) affiche effective (URL réellement utilisée, source, adresse d'environnement ignorée).

Supabase backend (important auth caveat)

• Committed .env points at a hosted Supabase project. The client (lib/supabase/client.ts) hardcodes the same values as a fallback.
• The hosted project has email confirmation ON (mailer_autoconfirm=false) and no seeded/test accounts, so you cannot self-signup and log in without access to the confirmation email. The documented sample accounts (e.g. marie@cardiomaine.fr) do not exist in that project.
• All protected pages require login (proxy.ts gates everything except /, /auth/login, /auth/sign-up, /auth/forgot-password).

Running a local Supabase for end-to-end testing (no real account needed)

Requires Docker + the Supabase CLI installed in the VM (not part of the update script). To exercise login + the protected planning grid autonomously:

1. supabase start (a committed supabase/config.toml already exists). Migrations in supabase/migrations/ are now aligned with the app code — 20240101000000_init_schema.sql creates the profiles (with role + must_change_password), week_key-based schedules, doctor_vacations, planning_notes, doctors, settings, congres, and equity tables, with permissive RLS and the required role GRANTs. Use supabase db reset to re-apply from scratch.
2. Create a confirmed user via the admin API (service_role key from supabase start output): POST http://127.0.0.1:54321/auth/v1/admin/users with {"email":"admin@cardiomaine.fr","password":"Admin123!","email_confirm":true,"user_metadata":{"first_name":"Marie","last_name":"Martin"}}. The on_auth_user_created trigger auto-creates a profiles row (default role='admin'). Note: supabase db reset wipes auth users, so recreate this user afterwards.
3. Point .env NEXT_PUBLIC_SUPABASE_URL/NEXT_PUBLIC_SUPABASE_ANON_KEY at the local stack (http://127.0.0.1:54321 + the printed anon key) and restart bun run dev. Restore .env to the hosted values when done.

• Non-obvious gotcha: Supabase REST needs table-level GRANTs to anon/authenticated in addition to RLS; without them PostgREST returns 401 permission denied for table .... The init migration already includes these grants.
• Note: the hosted Supabase project (the default .env target) may still have the older/inconsistent schema; these migrations describe the schema the code expects.

Supabase service role key (local vs hébergé)

• En local, utilisez la clé service_role générée par supabase status (copiez la clé dans .env.local).
• En hébergé (Supabase en production), utilisez la clé service_role du projet hébergé (disponible dans Settings → API).
• Ne pas confondre les deux clés : elles ne sont pas interchangeables.