feat(25-6-b): le PDF d'une facture est figé — une pièce émise ne change plus (closes #387)

[guycorbaz]

Closes #387.

Ce qui change

Le PDF d'une facture ne change plus après son émission. Il était régénéré à chaque téléchargement, à partir des données du moment : modifier ses coordonnées, l'adresse du client ou la mise en page modifiait aussi les factures déjà envoyées, et deux téléchargements ne rendaient jamais le même fichier.

• Figé au premier rendu : le premier téléchargement ou envoi par e-mail qui suit la validation produit le PDF, dans la langue du client. Kesh l'écrit sous KESH_DOCUMENTS_DIR et en garde l'empreinte SHA-256. Ensuite, chaque téléchargement et chaque envoi rendent ce même fichier, octet pour octet. Le gel est audité (invoice.pdf_frozen) au nom de l'acteur : utilisateur, consultation comprise, ou clé d'API.
• Un seul chemin vers le PDF d'une facture : routes/issued_invoice_pdf.rs. L'ancienne fonction de rendu direct est retirée.
• Gardes contre les courses : la pose est un UPDATE conditionnel (pdf_storage_path IS NULL, status = 'validated', version lue au rendu), dans une transaction avec son audit. Une seule nouvelle tentative, puis 409 INVOICE_CHANGED.
• Intégrité : fichier absent → 410 INVOICE_PDF_GONE, dont le message nomme le fichier à restaurer. Fichier altéré → 500, rien n'est servi. Jamais de régénération silencieuse.
• Refiger (Admin, refusé aux clés d'API) : POST /api/v1/invoices/{id}/pdf/refreeze. Il produit un nouveau document quand le fichier a disparu ; l'audit invoice.pdf_refrozen garde les deux empreintes. Il est impossible pour une facture annulée.
• Cycle de vie : la dévalidation détache le document. Une facture annulée par un avoir garde son PDF figé, mais ne s'envoie plus.
• Export de souveraineté : invoices.csv gagne pdf_sha256, pdf_frozen_at et pdf_language, insérés avant version.
• Écran : bouton PDF aussi sur une facture annulée figée, mention « Document figé le », bouton « Refiger le document » pour un administrateur après un 410.
• Manuels FR (et PDF) : section « Le PDF émis est figé » ; côté admin, le répertoire des documents doit être sauvegardé et restauré avec la base, car le .keshbackup ne contient pas les fichiers ([CR] La sauvegarde .keshbackup doit emporter les fichiers — justificatifs et PDF figés #503).

Migration 20261003000001_invoices_frozen_pdf.sql : quatre colonnes nullables et une contrainte tout-ou-rien. Elle est non breaking (ADD COLUMN nullable), sans bump de min_required.

Corrigé en route (revue)

• Un import de l'inbox en échec supprimait un fichier archivé nommé par son contenu, qui pouvait être un PDF figé ou le justificatif d'une autre société.
• « Trop de lignes pour le PDF » affichait { $count } brut sur les fiches facture et avoir (défaut antérieur). Les deux fiches partagent désormais shared/utils/pdf-error.ts.
• Les messages d'erreur à argument ne portent plus les marques d'isolation invisibles de Fluent.

Revue et gates

• Validation de la spec en 4 passes. Revue de code en 4 passes : P1 3 MEDIUM → P2 5 MEDIUM → P3 0 au-dessus de LOW → P4 ciblée 0. Prompts versionnés 25-6-b-review-prompt-p1…p4.md.
• Mutations tuées sur toutes les gardes (base, service, écran). Les courses non reproductibles sont déclarées sans test dans la fiche.
• Sur l'état fusionné avec main (25-6-a) : backend 2602/2602, frontend 889/889, build OK, E2E complet 233 passés, 9 échecs attendus (KF-029 ×7, KF-051 ×2 avant 12:00 UTC).

Hors périmètre

• Figer les PDF d'avoir et de rappel : [CR] Figer aussi les PDF d'avoir et de rappel, comme la facture (suite de #387) #502.
• Emporter les fichiers dans .keshbackup : [CR] La sauvegarde .keshbackup doit emporter les fichiers — justificatifs et PDF figés #503.
• Défauts antérieurs relevés en revue : [bug] La communication de la QR-facture est toujours en français (« Facture {n} ») #504 (communication de la QR toujours en français) et [bug] La fiche facture perd « Déjà réglé / Reste dû » après un envoi par e-mail #505 (fiche non relue après un envoi par e-mail).

⚠️ Des conflits sont attendus avec la chaîne 25-4 (#493 et suivantes) : rounding_amount dans la liste unique des colonnes d'Invoice (invoice_columns!), et les compteurs de migrations (migrations_upgrade_path, audit d'idempotence).

🤖 Generated with Claude Code