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/leave_calc.py

@@ -7,6 +7,24 @@ from app.models import LeaveBalance, WorkEntry
 
 
 def compute_leave_used(year: int) -> dict[str, int]:
+    """
+    Calcule le nombre de jours de congés et de RTT consommés pour une année donnée.
+
+    Cette fonction interroge la base de données pour compter le nombre d'entrées
+    de journal (`WorkEntry`) de type 'CONGE' et 'RTT' comprises entre le 1er janvier
+    et le 31 décembre de l'année spécifiée.
+
+    Accès DB :
+        - Lecture seule sur la table `work_entries`.
+
+    Paramètres :
+        year (int) : L'année pour laquelle calculer les jours consommés.
+
+    Retour :
+        dict[str, int] : Un dictionnaire contenant :
+            - "conges" (int) : Le nombre de jours de congés consommés.
+            - "rtt" (int) : Le nombre de jours de RTT consommés.
+    """
     start = date(year, 1, 1)
     end = date(year, 12, 31)
 
@@ -34,6 +52,23 @@ def compute_leave_used(year: int) -> dict[str, int]:
 
 
 def get_or_create_balance(year: int) -> LeaveBalance:
+    """
+    Récupère le solde annuel des congés et RTT pour une année donnée, ou le crée s'il n'existe pas.
+
+    Si aucun solde n'existe pour l'année spécifiée, un nouvel enregistrement `LeaveBalance`
+    est créé avec les valeurs par défaut (28 jours de congés, 19 jours de RTT) et enregistré
+    en base de données.
+
+    Accès DB :
+        - Lecture sur la table `leave_balance`.
+        - Écriture (insertion et commit) si l'enregistrement n'existe pas.
+
+    Paramètres :
+        year (int) : L'année concernée.
+
+    Retour :
+        LeaveBalance : L'objet représentant le solde annuel pour l'année spécifiée.
+    """
     balance = db.session.scalar(sa.select(LeaveBalance).where(LeaveBalance.year == year))
     if balance is None:
         balance = LeaveBalance(year=year)