Ajout des commentaires dans le code

app/Services/AgentHoursContractPdfService.php

@@ -10,13 +10,36 @@ use DateTimeZone;
 /**
  * Génère le document annuel de validation du quota horaire d'un agent.
  * Le PDF est autonome et ne nécessite aucune dépendance Composer.
+ *
+ * Document CONTRACTUEL, destiné à être signé : il n'affiche que le volume
+ * annualisé dû sur la période et la clause de validation, jamais le détail des
+ * créneaux planifiés.
+ *
+ * Seul PDF de l'application en A4 PORTRAIT (les plannings sont en paysage) :
+ * c'est le format attendu d'une pièce à signer et à classer.
+ *
+ * Contrairement aux PDF de planning, les libellés portent ici leurs ACCENTS :
+ * la valeur juridique du document prime, et iconv est présent dans le conteneur
+ * fourni. À vérifier si l'application est déployée sur un PHP sans iconv.
  */
 final class AgentHoursContractPdfService
 {
+    /** A4 PORTRAIT en points PDF, contrairement aux plannings en paysage. */
     private const PAGE_WIDTH = 595.28;
     private const PAGE_HEIGHT = 841.89;
     private const MARGIN = 42.0;
 
+    /**
+     * Assemble le contrat horaire annuel.
+     *
+     * La période affichée est celle du quota (année civile) et non l'année de
+     * contrat ; le libellé est repris tel quel de QuotaModel.
+     *
+     * @param array<string, mixed> $agent
+     * @param array<string, mixed> $quota Quota enrichi (forDateForApi).
+     *
+     * @return string Octets du PDF.
+     */
     public function annualContract(array $agent, array $quota): string
     {
         $pdf = new SimplePdf(self::PAGE_WIDTH, self::PAGE_HEIGHT);
@@ -39,6 +62,7 @@ final class AgentHoursContractPdfService
         return $pdf->output();
     }
 
+    /** Titre, période de référence, date d'édition et identité de l'agent. */
     private function drawHeader(SimplePdf $pdf, array $agent, string $periodLabel, DateTimeImmutable $generatedAt): void
     {
         $pdf->text(self::MARGIN, 48, 'CONTRAT HORAIRE ANNUEL', 18, true);
@@ -56,6 +80,7 @@ final class AgentHoursContractPdfService
         );
     }
 
+    /** Bloc d'identité : matricule, poste, contrat, lieu, quotité. */
     private function drawAgentIdentity(SimplePdf $pdf, array $agent): void
     {
         $x = self::MARGIN;
@@ -90,6 +115,7 @@ final class AgentHoursContractPdfService
         $pdf->text($rightX, $row4, 'Type du lieu : ' . $this->typeLabel((string) ($agent['structure_principale_type_affectation'] ?? '')), 8.5);
     }
 
+    /** Volume annualisé dû : référence, quotité appliquée, quota cible. */
     private function drawQuotaSummary(SimplePdf $pdf, array $quota): void
     {
         $x = self::MARGIN;
@@ -127,6 +153,11 @@ final class AgentHoursContractPdfService
         }
     }
 
+    /**
+     * Clause de validation : le texte que les parties reconnaissent en signant.
+     * Toute modification a une portée juridique — à ne pas retoucher pour des
+     * raisons de mise en page.
+     */
     private function drawValidationClause(SimplePdf $pdf, string $periodLabel, DateTimeImmutable $generatedAt): void
     {
         $x = self::MARGIN;
@@ -157,6 +188,7 @@ final class AgentHoursContractPdfService
         $pdf->text($x, 658, 'Document établi le ' . $generatedAt->format('d/m/Y') . '.', 8);
     }
 
+    /** Cartouches de signature, laissés vides pour un remplissage manuscrit. */
     private function drawSignatures(SimplePdf $pdf): void
     {
         $x = self::MARGIN;
@@ -184,6 +216,7 @@ final class AgentHoursContractPdfService
         $pdf->text($rightX, $y + 101, 'Signature et cachet :', 8.5);
     }
 
+    /** Libellé du type de lieu d'affectation. */
     private function typeLabel(string $type): string
     {
         return match (strtoupper($type)) {
@@ -193,12 +226,14 @@ final class AgentHoursContractPdfService
         };
     }
 
+    /** Quotité en pourcentage, telle qu'elle figure au contrat. */
     private function percentLabel(float $rate): string
     {
         $formatted = rtrim(rtrim(number_format($rate, 2, ',', ' '), '0'), ',');
         return $formatted . ' %';
     }
 
+    /** 450 → « 7 h 30 ». Gère les valeurs négatives. */
     private function minutesLabel(int $minutes): string
     {
         $sign = $minutes < 0 ? '-' : '';