doc: document models and business rules

Co-authored-by: OpenAI/GPT-5.6-Terra <vibecoder@antoineve.me>
Co-authored-by: Google/Gemini-3.5-Flash <vibecoder@antoineve.me>
Co-authored-by: DeepSeek/DeepSeek-v4-Pro <vibecoder@antoineve.me>
Co-authored-by: DeepSeek/DeepSeek-v4-Flash <vibecoder@antoineve.me>

app/business/time_calc.py

@@ -1,4 +1,13 @@
 def minutes_to_str(minutes: int) -> str:
+    """
+    Convertit une durée en minutes en une chaîne formatée lisible (ex: "7h45" ou "-1h15").
+
+    Paramètres :
+        minutes (int) : Le nombre de minutes à convertir (peut être négatif).
+
+    Retour :
+        str : La chaîne formatée au format "[signe]HhMM".
+    """
     sign = "-" if minutes < 0 else ""
     minutes = abs(minutes)
     return f"{sign}{minutes // 60}h{minutes % 60:02d}"
@@ -18,10 +27,34 @@ _REFERENCE_MINUTES = {
 
 
 def work_minutes_reference(day_type: str) -> int:
+    """
+    Retourne la durée de travail de référence en minutes pour un type de journée donné.
+
+    Les durées de référence sont :
+        - WORK, TT, FORMATION : 7h45 (465 minutes)
+        - GARDE : 10h00 (600 minutes)
+        - ASTREINTE, RTT, CONGE, MALADE, FERIE : 0 minute
+
+    Paramètres :
+        day_type (str) : Le type de journée (ex: "WORK", "TT", "CONGE").
+
+    Retour :
+        int : La durée de référence en minutes. Par défaut 465 minutes si le type est inconnu.
+    """
     return _REFERENCE_MINUTES.get(day_type, 465)
 
 
 def week_balance_minutes(actual_minutes: int, reference_minutes: int) -> int:
+    """
+    Calcule l'écart (solde) entre les minutes réellement travaillées et les minutes de référence.
+
+    Paramètres :
+        actual_minutes (int) : Le total des minutes travaillées.
+        reference_minutes (int) : Le total des minutes de référence.
+
+    Retour :
+        int : L'écart en minutes (positif si heures supplémentaires, négatif si déficit).
+    """
     return actual_minutes - reference_minutes
 
 
@@ -30,8 +63,18 @@ import statistics as _stats
 
 def monthly_stats(entries: list) -> dict:
     """
-    Calcule médiane journalière et médiane hebdomadaire (semaines ISO)
-    pour un groupe d'entrées. Les absences (total_minutes=0) sont incluses.
+    Calcule la médiane journalière et la médiane hebdomadaire (semaines ISO) pour un groupe d'entrées.
+
+    Les absences (durée de travail de 0 minute) sont incluses dans les calculs.
+    Les semaines sont regroupées selon le calendrier ISO (année, numéro de semaine).
+
+    Paramètres :
+        entries (list) : Une liste d'objets `WorkEntry`.
+
+    Retour :
+        dict : Un dictionnaire contenant :
+            - "median_daily_min" (int) : La médiane des minutes travaillées par jour.
+            - "median_weekly_min" (int) : La médiane des minutes travaillées par semaine ISO.
     """
     if not entries:
         return {"median_daily_min": 0, "median_weekly_min": 0}
@@ -50,7 +93,16 @@ def monthly_stats(entries: list) -> dict:
 
 
 def count_day_types(entries: list) -> dict[str, int]:
-    """Retourne un dict {day_type: count} pour une liste d'entrées, sans les zéros."""
+    """
+    Comptabilise le nombre d'occurrences de chaque type de journée dans une liste d'entrées.
+
+    Paramètres :
+        entries (list) : Une liste d'objets `WorkEntry`.
+
+    Retour :
+        dict[str, int] : Un dictionnaire associant chaque type de journée présent à son nombre d'occurrences.
+                         Les types de journées non représentés ne figurent pas dans le dictionnaire.
+    """
     counts: dict[str, int] = {}
     for entry in entries:
         counts[entry.day_type] = counts.get(entry.day_type, 0) + 1