mister-doc — Planning de gardes (PWA)

Application web progressive (PWA) permettant à une équipe de médecins d'un hôpital de synchroniser leur planning de gardes en dehors de l'outil métier, à partir d'un modèle simple de créneaux mensuels.

Reprend les bonnes pratiques de la famille d'applications miss-*/mister-* (React 19 + Vite + TypeScript strict, Tailwind 4, vite-plugin-pwa, CSP en défense en profondeur, Supabase avec RLS). Les briques partagées viennent du paquet @mister-guiiug/dev-pwa-config, publié sur GitHub Packages.

Fonctionnalités

Planning

• Vue mensuelle groupée par numéro de semaine ISO, avec liste (mobile) ou grille 7 colonnes (desktop, bascule mémorisée).

• Créneaux cliniques configurables à occupant unique : les types de garde ne sont plus codés en dur, un admin les crée, édite, réordonne et désactive (libellé, heures, « clinique », « requis le week-end », « nuit », horaires du flux .ics, couleur) — voir docs/spec-creneaux-configurables.md. Configuration par défaut :

  Créneau	Libellé	Heures	Week-end	Nuit
  S1J	S1 Jour	10 h	oui	non
  S1N	S1 Nuit	15 h	oui	oui
  S2J	S2 Jour	8 h	non	non

  1 médecin par créneau et par jour ; les créneaux non pourvus sont signalés « à couvrir ». Exception week-end / jours fériés (fériés FR calculés) : seuls les créneaux marqués « requis le week-end » le sont.

• Heures Non Cliniques (HNC, ex-« S3 ») : plusieurs médecins par jour, chacun saisit son propre nombre d'heures, n'importe quel jour, hors couverture « à couvrir ». Comptées dans le temps total et dans un compteur HNC dédié.

• Congés annuels et formations (heures/jour pour les formations), notes de jour, vœux / indisponibilités (dispo / indispo par jour).

• Édition partagée temps réel (Supabase Realtime) : tout médecin approuvé affecte n'importe qui, avec alertes (repos de sécurité après une nuit, conflit garde/absence, cumul). Confirmation avant chaque suppression.

• Affectation sur plusieurs semaines : depuis le dialogue d'affectation, répéter le même médecin sur le même créneau 1 à 4 semaines consécutives (mêmes jours de semaine).

• Copier le mois précédent : reprend ses gardes dans le mois affiché, alignées sur le jour de semaine ; récapitulatif (gardes à créer, ignorées et pourquoi) avant toute écriture, et aucun créneau déjà attribué n'est écrasé.

• Bourse aux gardes : proposer une de ses gardes (ciblée ou ouverte à tous) depuis la bourse (« Proposer une garde ») ou le planning ; accepter réaffecte la garde ; tri par date, « dans N j » et historique — page Échanges.

• Mon planning (/mon-planning) : agenda personnel du mois (mes gardes, absences, HNC) en liste, avec compteurs perso et abonnement calendrier.

• Compteurs du médecin connecté (bascule mois / quadrimestre) : vendredis / samedis / dimanches, heures de week-end, HNC, heures totales, congés, formation. Deux vues en carrousel : pastilles ou mini-calendrier du mois.

• Verrouillage de mois (admin) pour figer un planning validé.

Comptes, rôles, admin

• Authentification Supabase + barrière d'approbation (voir Sécurité).
• Profil dédié (/profil) : nom, couleur, thème clair/sombre, langue (français / anglais), abonnement calendrier, partage du lien de l'app, notifications push (opt-in), version + « forcer la mise à jour », déconnexion.
• Un compte en attente peut supprimer lui-même sa demande ; un admin peut l'approuver ou la rejeter.
• Vue admin /compteurs : compteurs de toute l'équipe (bascule Tableau / Équité) par mois / quadrimestre (4 mois) / année, colonnes triables dans la vue Tableau, export CSV, Excel (.xlsx) et PDF.
• Types de créneaux (carte d'admin) : créer, éditer, réordonner et (dés)activer les créneaux ; la suppression n'est possible que si aucune garde ni proposition d'échange ne les utilise.
• Aperçu « médecin » : un admin peut, via le bouclier de l'en-tête, masquer temporairement ses fonctions admin pour voir l'app comme un non-admin.

Notifications & sauvegardes

• Notifications in-app (cloche, temps réel) : garde attribuée/retirée, absence (posée/supprimée, groupée par plage), HNC, échange proposé/accepté/décliné, mois verrouillé/déverrouillé, demande de compte (aux admins), approbation, rappel de garde et récapitulatif hebdomadaire. Clic = raccourci vers le bon menu ; glissement latéral = marquer lu ; toast à l'arrivée d'une notif app ouverte. Une affectation en lot (copie de mois) ne donne qu'une seule notification par médecin.
• Rappels de garde (pg_cron, quotidien) : « garde demain » et « nuit ce soir » ; récapitulatif hebdomadaire (pg_cron, dimanche) listant les gardes des 7 jours à venir. Les deux sont aussi déclenchables à la main depuis les réglages admin.
• Notifications push (optionnel) : reçues même app fermée, via service worker + VAPID. Opt-in depuis le profil. Configuration : docs/notifications-push.md.
• Sauvegarde/restauration (admin) + sauvegarde auto hebdomadaire (pg_cron).

Technique

• PWA installable (invite d'installation), shell applicatif en cache ; nouvelle version téléchargée en fond puis proposée par un bandeau (vérifiée toutes les heures, appliquée quand l'utilisateur l'accepte), et bouton de mise à jour forcée.
• Écriture hors ligne : sans réseau, une affectation, une absence ou des heures non cliniques sont mises en file (persistée dans le navigateur, elle survit à un rechargement) et repartent seules au retour du réseau. Un badge d'en-tête compte ce qui attend. Au rejeu, les créneaux passent par une écriture conditionnelle (assign_shift_if_unchanged, clear_shift_if_unchanged) : si un collègue a pris le créneau entre-temps, c'est la base qui tranche, l'écriture est refusée, nommément notifiée et conservée dans le panneau (« Réessayer » / « Abandonner »). Rien n'est écrasé, rien n'est perdu en silence. La file appartient à l'appareil : la déconnexion la jette, après confirmation.
• Accessibilité (modales Échap + piège de focus), thème clair/sombre, optimisations mobile (safe-area, barre d'onglets basse).

Sécurité (important)

Le dépôt est public et la clé anon Supabase est présente dans le bundle (c'est prévu : elle est publique). Toute la sécurité repose donc sur les policies RLS côté serveur et sur une barrière d'approbation :

• un nouvel inscrit est « en attente » (approved = false) et ne voit rien du planning tant qu'un administrateur ne l'a pas approuvé ; il peut supprimer lui-même sa demande, et un admin peut l'approuver ou la rejeter (suppression de la fiche + du compte auth) ;
• le premier administrateur se débloque via un code de bootstrap secret (stocké dans app_config, jamais exposé au client) : écran « Compte en attente » → « J'ai un code d'administrateur ». Le code ne fonctionne que tant qu'aucun admin n'existe ;
• toutes les écritures sensibles (approbation, rôles, roster) passent par des fonctions Postgres SECURITY DEFINER.

Connexion : mot de passe (principal), avec deux options opt-in par médecin depuis le profil — double authentification TOTP (code à 6 chiffres + codes de secours) et connexion par empreinte / Face ID / Windows Hello (passkeys WebAuthn natives de Supabase Auth, beta). La double authentification est vérifiée par l'application à la connexion ; la base de données ne l'exige pas encore. Les passkeys exigent une activation côté dashboard Supabase (RP ID + origine) : voir docs/deploiement.md.

Ne committez jamais la clé service_role ni un token sbp_… (Management API). Le fichier .env est ignoré par git.

Confidentialité (RGPD) : une politique de confidentialité est accessible avant connexion (page de login) et depuis le profil — c'est un modèle dont les mentions légales [À compléter] (responsable du traitement, base légale, durées, contact) doivent être renseignées avant mise en service. Chaque médecin peut exporter ses données (droit d'accès / portabilité, art. 15/20) en JSON depuis son profil. Effacement (droit à l'oubli, art. 17) : un compte en attente se supprime lui-même ; un compte approuvé peut s'anonymiser depuis son profil (ou via un admin) — l'identité (nom, e-mail, connexion) est effacée tandis que les gardes passées restent au planning sous une identité anonyme (intégrité préservée).

Développement local

export NODE_AUTH_TOKEN=<jeton>  # jeton GitHub (droit read:packages), exigé par .npmrc
npm install
cp .env.example .env      # puis renseignez URL + clé anon (Supabase → Settings → API)
npm run dev               # http://localhost:5173

Les icônes PWA sont versionnées dans public/icons/. Pour les régénérer (optionnel), installez sharp puis lancez le script : npm i -D sharp && npm run icons.

Scripts utiles : npm run build, npm run preview, npm run test, npm run lint, npm run type-check.

Base de données Supabase

Le schéma versionné est découpé en migrations dans supabase/migrations/, appliquées dans l'ordre (0001 → 0029). Pour une instance existante, le déploiement (Edge Functions + migrations ≥ 0014) est automatisé par la CI — workflow .github/workflows/supabase.yml, déclenché par tout changement de supabase/migrations/, supabase/functions/ ou supabase/config.toml sur main. Détails, secrets requis et procédure manuelle de repli : docs/deploiement.md.

⚠️ Les migrations 0001→0013 ne sont jamais appliquées à la base hébergée par la CI (l'une d'elles supprime des données) : sur une base neuve, il faut les passer à la main dans l'éditeur SQL, sans supabase db push. La CI en vérifie ensuite la présence et refuse de continuer s'il en manque une. Le workflow « Supabase tests » les rejoue toutes, mais sur une pile jetable.

Migration	Contenu
0001_init	tables doctors / shifts / app_config, RLS, barrière d'approbation, RPC de base
0002_admin_update_doctor	édition profil (soi / admin)
0003_leaves	congés annuels & formations
0004_calendar_feed · 0005_improvements	flux .ics (token), tokens par médecin, notes de jour, verrou de mois, réglages
0006_notifications_backups	notifications (triggers) + sauvegarde/restauration + pg_cron
0007_swaps_wishes	échanges de gardes + vœux
0008_self_service	suppression de sa demande en attente
0009_hnc	Heures Non Cliniques (table hnc_hours, migration des ex-S3)
0010_admin_reject	rejet admin d'une demande en attente
0011_shift_history	historique des changements par créneau
0012_notif_improvements	améliorations des notifications
0013_push_subscriptions	abonnements Web Push
0014_calendar_rate_limit	rate-limit de l'Edge Function calendrier (table edge_rate_limit + RPC edge_rate_limit_hit)
0015_calendar_token_privacy	confidentialité du token calendrier (privilège colonne : calendar_token illisible par les autres médecins)
0016_extend_month_lock	verrou de mois étendu aux HNC / notes / vœux (triggers assert_month_unlocked)
0017_audit_log	journal d'audit admin (table audit_log + triggers sur doctors / locked_months)
0018_calendar_token_hash	tokens calendrier hashés au repos (SHA-256 ; plus de token en clair en base ; lien montré une seule fois)

Après 0001, renseignez le code de bootstrap :

update public.app_config set bootstrap_code = 'VOTRE-CODE-SECRET' where id = 1;

Calendrier (flux .ics)

Un flux iCalendar récapitule tout le planning (gardes + congés + formations), servi par l'Edge Function Supabase supabase/functions/calendar :

https://<ref>.supabase.co/functions/v1/calendar?token=SECRET          # toute l'équipe
https://<ref>.supabase.co/functions/v1/calendar?token=TOKEN&scope=me   # ses propres gardes

L'accès est protégé par un token secret propre à chaque médecin (stocké haché, cf. migration 0018) ; la fonction lit les données via la clé service_role et est déployée avec verify_jwt = false (les agendas ne peuvent pas envoyer de JWT). Dans l'app, la carte Calendrier du profil (et le bouton de « Mon planning ») affiche l'URL d'abonnement (équipe ou personnelle) avec liens webcal / Google Agenda / téléchargement, et permet de révoquer le token en le régénérant (rotate_calendar_token()).

Déploiement de la fonction : automatisé par la CI (workflow supabase.yml, verify_jwt déclaré dans supabase/config.toml) ; en manuel : supabase functions deploy calendar --no-verify-jwt.

Lien d'équipe partagé (facultatif et hérité : le lien de chaque médecin donne déjà le flux de l'équipe) : n'en stocker que l'empreinte.

update public.app_config
  set calendar_token_hash = encode(extensions.digest('SECRET', 'sha256'), 'hex')
  where id = 1;

La fonction accepte encore un calendar_token en clair, mais il resterait lisible dans une copie de la base.

Tokens hashés au repos (migration 0018) : la base ne stocke plus que le SHA-256 des tokens (calendar_token_hash) — un dump ne révèle aucun lien utilisable. La fonction hache le token reçu et compare au hash (repli sur le clair le temps de la transition). Conséquence : un lien n'est montré qu'une fois, à la génération/régénération (il n'est plus ré-affichable). ⚠️ Déployer la fonction avant d'appliquer 0018 (qui efface le clair).

Rate-limiting (défense en profondeur — le flux est public et lit via service_role) : la fonction borne le débit par IP avant toute requête en base (migration 0014, RPC atomique edge_rate_limit_hit). Défauts : 60 requêtes par 60 s, largement au-dessus du rafraîchissement des agendas ; réglables via les variables d'environnement de la fonction CALENDAR_RATE_MAX / CALENDAR_RATE_WINDOW. Au-delà : réponse 429 avec Retry-After. En cas d'échec de la RPC, on laisse passer (fail-open) pour ne jamais casser un abonnement légitime.

Pourquoi l'écriture du .ics n'est pas celle du socle. Le module ./ical de @mister-guiiug/dev-pwa-config (3.24.0) est promu de quatre réécritures RFC 5545, dont celle-ci, et corrige deux défauts de la nôtre : DTSTAMP recalculé à chaque événement (au lieu d'un seul par fichier, qui est la date de FABRICATION) et lignes non pliées à 75 octets. Il n'est pourtant pas importé, pour des raisons d'empaquetage et non de couverture :

• le .ics est engendré uniquement par cette Edge Function (Deno). Côté navigateur, src/backend/calendar.ts ne construit que l'URL d'abonnement, et le bouton « Télécharger le .ics » pointe sur ce même flux : il n'y a rien à migrer là ;
• le paquet n'est publié que sur GitHub Packages, qui exige un jeton même en lecture (401 sans en-tête ; absent de npmjs). La CI déploie avec --use-api : c'est l'infrastructure Supabase qui résout les spécifieurs npm:, sans nos identifiants. Le .npmrc par fonction que Supabase prévoit pour un registre privé demanderait le jeton en clair dans un dépôt public — celui de la racine s'appuie sur ${NODE_AUTH_TOKEN}, qui n'existe pas sur le constructeur distant ;
• toute modification sous supabase/functions/** poussée sur main déclenche supabase.yml, donc un redéploiement et les migrations : le coût d'un simple changement d'import n'est pas local.

Une échappatoire existe — le dépôt du socle est public, donc ical.js et son vcard.js sont servis en application/javascript par un CDN GitHub, importables tels quels par Deno —, mais elle troque le registre contre un tiers dans la chaîne d'approvisionnement d'un point d'entrée public qui lit via service_role, pour deux corrections de forme. Elle n'est pas prise.

La couverture, elle, est vérifiée propriété par propriété — METHOD, X-WR-CALNAME, X-WR-TIMEZONE, REFRESH-INTERVAL + X-PUBLISHED-TTL, CATEGORIES, TRANSP, journées entières à DTEND exclusif et créneaux de nuit franchissant minuit —, dans le même ordre de lignes. Le jour où le paquet est joignable depuis le constructeur Supabase, la bascule est mécanique.

Déploiement (GitHub Pages)

Le workflow .github/workflows/deploy.yml construit et publie sur GitHub Pages avec base = /mister-doc/. Renseignez au préalable, dans Settings → Secrets and variables → Actions → Variables :

• VITE_SUPABASE_URL
• VITE_SUPABASE_ANON_KEY
• VITE_VAPID_PUBLIC_KEY

puis activez Settings → Pages → Source : GitHub Actions. Les trois variables sont exigées : le déploiement s'arrête si l'une manque. VITE_SENTRY_DSN et VITE_POSTHOG_KEY sont facultatives : absentes, rien n'est chargé ni envoyé. VITE_POSTHOG_KEY ne doit pas être posée tant que la politique de confidentialité porte [À compléter] (cf. src/App.tsx).

Architecture

src/
  lib/        env (validation JS) · client Supabase · dates (semaine ISO) ·
              créneaux + compteurs · congés · HNC · validation/alertes · équité ·
              répétition + copie de mois · tons de chips · couleurs
  backend/    types · doctors · planning (shifts) · leaves · hnc · notes · wishes ·
              swaps · shiftTypes · notifications · push · reminders · history ·
              audit · gdpr · mfa · passkey · backup · locks · settings · calendar ·
              syncQueue + planningSync (file d'écritures hors ligne)
  auth/       contexte + porte d'authentification + page de connexion
  i18n/       catalogue FR/EN typé + fournisseur de traduction
  features/   planning/ (liste + grille, compteurs, dialogues affect./congé/note/HNC) ·
              swaps/ · admin/ (panel, compteurs équipe, créneaux, sauvegarde) ·
              profile/ · pending/ · sync/ (état de la file hors ligne) ·
              legal/ (politique de confidentialité)
  components/ en-tête · barre d'onglets basse · cloche notifications ·
              calendrier · profil · spinner

Les exports PDF et Excel passent par les modules pdf et xlsx du socle, et l'invite d'installation est son composant PwaInstallPrompt, posé sur le planning.

Tests : Vitest dans src/ (compteurs, semaine ISO, créneaux actifs, congés, alertes de validation, répétition hebdomadaire, copie de mois, file hors ligne, MFA, exports, mentions légales), Playwright dans e2e/tests/ (connexion, MFA, planning, verrou de mois, admin, file hors ligne, accessibilité) et pgTAP pour la barrière d'approbation, les droits des fonctions security definer et deux invariants de structure : aucune table sans RLS, et la liste relue des fonctions qu'anon peut exécuter (supabase/tests/, workflow « Supabase tests »).

Ce qui vient du socle, et ce qui reste local

Les briques d'interface partagées viennent de @mister-guiiug/dev-pwa-config (Button, TextField, EmptyState, Skeleton, ConfirmDialog, Toast, BottomNav, Sheet, useTheme/ThemeProvider), habillées par components.css et les quinze jetons --dwc-* câblés dans src/index.css. Le thème est écrit une seule fois, par le ThemeProvider de main.tsx.

Pourquoi Badge reste local. Les deux composants n'ont pas le même axe, et ce n'est pas une question de nommage :

• celui du socle est sémantique et volontairement fermé — brand, success, warning, danger, info, muted : ce que la pastille veut dire ;
• celui d'ici est chromatique et métier — teal / indigo distinguent une garde de jour d'une garde de nuit, violet / amber un congé d'une formation, sky les HNC. Cinq catégories de même niveau, dont aucune n'est une réussite, un avertissement ou un danger.

Les replier sur six intentions sémantiques ferait perdre la distinction (tout deviendrait muted) ou mentirait sur le sens (un congé n'est pas un danger). S'ajoutait que size="xs", utilisé par les pastilles de la carte des créneaux, n'avait pas d'équivalent. Le socle a ouvert depuis (02/09/2026) un axe de taille (xs, sm, md) : cet argument est tombé, seul celui des tons demeure. La carte des tons (src/lib/tones.ts) sert d'ailleurs aussi à Counters et SwapStatusBadge, qui ne sont pas des Badge.

Décision réexaminée contre le socle 3.24.0 (2026-08-30) : inchangée. La taille existe désormais au socle ; la décision redeviendra discutable le jour où il ouvrira son axe de tons, pas avant.