@movalib/movalib-commons 1.68.32 → 1.68.34

package/.claude/FEATURE_minimize-rdv-dialog.md

@@ -0,0 +1,74 @@
+# Feature : Minimiser la dialog de création de RDV (MyCalendarEventDialog)
+
+## Contexte
+
+L'application movalib-pro (React/TypeScript + MUI) possède une grosse dialog de création/édition de rendez-vous : `MyCalendarEventDialog`. Actuellement, si l'utilisateur ferme la dialog en cours de saisie, tout est perdu.
+
+## Objectif
+
+Permettre de **minimiser** la dialog de création de RDV (façon Gmail compose / fenêtres Windows) pour la reprendre plus tard, sans perdre la saisie en cours. Les dialogs minimisées apparaissent sous forme de chips/onglets dans une barre fixée en bas à droite de l'écran.
+
+## Règles métier
+
+1. **Uniquement en mode CRÉATION.** `MyCalendarEventDialog` peut aussi s'ouvrir en mode édition : dans ce cas, PAS de bouton minimiser, comportement actuel inchangé.
+2. **Maximum 3 brouillons minimisés simultanément.** Si l'utilisateur tente d'ouvrir une 4e création alors que 3 brouillons existent déjà : bloquer l'ouverture et afficher un snackbar d'information (ex: "Vous avez atteint la limite de 3 brouillons de rendez-vous. Fermez ou finalisez un brouillon existant."). Utiliser le système de snackbar existant du projet.
+3. **Une seule dialog visible à la fois.** Restaurer un brouillon alors qu'une dialog est ouverte → minimiser automatiquement la dialog courante (si en mode création) avant de restaurer l'autre. Si la dialog courante est en mode édition, bloquer avec snackbar.
+4. **Label du chip minimisé** : nom du client si saisi, sinon plaque d'immatriculation si saisie, sinon "Brouillon RDV". Mettre à jour le label au moment de la minimisation (pas besoin de temps réel).
+5. **Persistance au refresh (F5)** : les brouillons doivent survivre à un rechargement de page via `localStorage` (voir section Persistance).
+6. La **fermeture définitive** (croix / annuler / création réussie du RDV) supprime le brouillon (state + localStorage).
+
+## Architecture attendue
+
+### Stratégie : composant gardé monté + snapshot localStorage
+
+- **En session** : quand une dialog est minimisée, NE PAS démonter le composant. Le cacher visuellement (wrapper avec `display: none`, ou garder la Dialog MUI avec `open=false` selon ce qui préserve le mieux le state — vérifier que MUI ne démonte pas le contenu : utiliser `keepMounted` sur la Dialog si nécessaire). Le state interne (Formik, refs, etc.) est ainsi préservé sans sérialisation.
+- **Pour le refresh** : en complément, sauvegarder un snapshot sérialisable des valeurs du formulaire dans `localStorage` à chaque minimisation (et idéalement de façon debounced pendant la saisie si simple à faire, sinon uniquement à la minimisation).
+
+### Composants / fichiers à créer
+
+1. **`MinimizedEventDialogsContext`** (Context + Provider + hook `useMinimizedEventDialogs`)
+   - State : liste des brouillons `{ id: string, label: string, createdAt: number }`, `activeDraftId: string | null`
+   - Actions : `openNewDraft()` (retourne null + snackbar si limite atteinte), `minimizeDraft(id, label, formSnapshot)`, `restoreDraft(id)`, `closeDraft(id)`
+   - Gère la synchronisation avec localStorage.
+
+2. **`MinimizedDialogsBar`** — barre fixe en bas à droite (`position: fixed; bottom; right; zIndex` au-dessus du contenu mais sous les dialogs/snackbars MUI). Affiche un chip MUI par brouillon :
+   - Clic sur le chip → restaure le brouillon
+   - Petite croix sur le chip (`onDelete` du Chip MUI) → fermeture définitive du brouillon, avec dialog de confirmation ("Supprimer ce brouillon ?") via le système de confirmation existant du projet
+   - La barre n'est pas rendue si aucun brouillon.
+
+3. **Intégration dans `MyCalendarEventDialog`** :
+   - Ajouter un **IconButton "Réduire"** (icône `Minimize` ou `Remove` de @mui/icons-material) dans la **toolbar existante de la dialog, juste à côté du bouton close**, uniquement en mode création. Respecter le style existant de la toolbar (taille, couleur des icons).
+   - Au clic : calculer le label (client > plaque > "Brouillon RDV"), snapshot des valeurs du formulaire, appeler `minimizeDraft`.
+   - Chaque instance de dialog en création reçoit un `draftId` (uuid généré à l'ouverture).
+
+4. **Rendu des instances** : le composant parent qui monte `MyCalendarEventDialog` (probablement le composant calendrier) doit pouvoir rendre jusqu'à 3 instances simultanées (une par brouillon), chacune cachée ou visible selon `activeDraftId`. Adapter le point de montage actuel en conséquence (ex: mapper sur la liste des brouillons du context). Analyser d'abord comment la dialog est actuellement ouverte (state local ? context existant type DocumentEditorContext ?) et s'intégrer proprement dans le pattern existant — modification chirurgicale, pas de refactoring massif.
+
+### Persistance localStorage
+
+- Clé : `movalib.rdvDrafts` (ou préfixe cohérent avec les conventions existantes du projet — vérifier s'il y a déjà des clés localStorage et suivre le même pattern).
+- Contenu : `[{ id, label, createdAt, formValues }]` où `formValues` est un snapshot JSON-sérialisable des champs du formulaire.
+- **Attention aux types non sérialisables** : dates (stocker en ISO string, reconvertir au restore), fichiers/pièces jointes (NE PAS persister — accepter la perte au refresh, éventuellement le signaler), instances de classes (class-transformer : utiliser `instanceToPlain`/`plainToInstance` si le form utilise des modèles de classe).
+- Au chargement de l'app : lire localStorage, recréer les entrées de brouillons dans le context (dialogs montées cachées, formulaire réhydraté avec les snapshots).
+- Prévoir une expiration simple : purger les brouillons de plus de 7 jours au chargement.
+- Versionner le schéma (`{ version: 1, drafts: [...] }`) : si le schéma ne matche pas, purger silencieusement (pas de crash).
+
+## Étapes suggérées
+
+1. **Explorer** : localiser `MyCalendarEventDialog`, comprendre comment elle est ouverte (props, state parent, mode création vs édition), identifier le système de formulaire (Formik ?), le système snackbar et le système de dialog de confirmation existants.
+2. Créer le context + provider, brancher au niveau racine approprié (au même niveau que les providers existants).
+3. Créer `MinimizedDialogsBar`.
+4. Adapter le montage de `MyCalendarEventDialog` pour supporter les instances multiples cachées + le bouton Réduire.
+5. Ajouter la persistance localStorage (snapshot + réhydratation).
+6. Vérifier : build TypeScript OK, pas de régression sur le mode édition, la limite de 3 fonctionne, le F5 restaure bien.
+
+## Contraintes
+
+- Respecter les conventions existantes du projet (MUI theming, structure des dossiers, i18n si les libellés passent par un système de traduction — vérifier).
+- Modifications minimales et chirurgicales sur `MyCalendarEventDialog` : la logique de minimisation doit vivre au maximum dans le context et le wrapper, pas dans le corps de la dialog.
+- Aucun changement de comportement pour le mode édition.
+- Tous les libellés en français.
+
+## Questions à poser si ambigu
+
+- Si le formulaire n'utilise pas Formik ou si le state est éclaté dans plusieurs sous-composants, proposer la stratégie de snapshot avant d'implémenter.
+- Si `MyCalendarEventDialog` est montée via un portal/context existant, montrer le plan d'intégration avant de modifier.

package/.claude/MOVA-393-export-fec.md

@@ -0,0 +1,392 @@
+# MOVA-393 — Export FEC incrémentiel (écritures comptables)
+
+## But de la tâche
+
+Implémenter, dans **movalib-pro**, un écran de **gestion des exports comptables (FEC)**
+accessible depuis le module **Facturation**. L'utilisateur doit pouvoir :
+
+- voir le **nombre d'écritures en attente d'export** (WIP) ;
+- **générer un export incrémentiel** à tout moment (seules les écritures non encore consommées) ;
+- **suivre l'avancement** de la génération (et voir un échec) ;
+- **télécharger** les exports disponibles ;
+- **identifier** les exports déjà téléchargés ;
+- **annuler** le dernier export généré s'il n'a pas encore été téléchargé ;
+- **consulter tout l'historique**, avec pagination (potentiellement volumineux).
+
+> ⚠️ **La maquette HTML fournie n'est pas à reprendre telle quelle.** Elle sert
+> **uniquement de référence pour l'ordre et la présence des blocs**. Le rendu doit
+> respecter la **DA (design system) réelle de movalib-pro** : MUI v6, thème existant
+> (`src/theme`), composants et patterns déjà en place. Aucune couleur / police / valeur
+> en dur issue de la maquette. Voir la section « Correspondance maquette → DA ».
+
+---
+
+## Emplacements des fichiers à créer
+
+```
+src/pages/billing/AccountingExports.tsx        # page principale (l'écran)
+src/pages/billing/components/                   # sous-composants de l'écran (voir plus bas)
+src/models/Billing/AccountingExport.ts          # modèles class-transformer
+src/services/Billing/AccountingExportService.ts # service + hooks React Query
+```
+
+Créer les dossiers `src/models/Billing` et `src/services/Billing` s'ils n'existent pas.
+Router : ajouter la route de la page dans `src/App.tsx` (suivre exactement le pattern des
+autres pages `billing/*` déjà importées là — ex. `BankTransactions`, `Stocks`).
+
+---
+
+## Contraintes projet (rappel — ne pas dévier)
+
+- **Composants fonctionnels uniquement**, hooks. Pas de class component React.
+- **Data fetching = React Query v5** (`useQuery` / `useInfiniteQuery` / `useMutation`).
+  Jamais `useEffect` + fetch manuel.
+- **Modèles = class-transformer** (`@Expose()`, `@Type()`, `plainToInstance(..., { excludeExtraneousValues: true })`),
+  méthodes statiques `JsonToObject` / `JsonToObjects`. Reproduire à l'identique le pattern
+  de `src/models/SupplierOrder.ts`.
+- **Appels API via `request`** importé de `@movalib/movalib-commons` (avec `APIMethod`,
+  `APIResponse`), `API_BASE_URL` depuis `src/helpers/Constants`. Suivre `SupplierOrderService`
+  / `DataBoxService` comme référence.
+- **Styles = MUI `sx` prop ou `styled()`**. Aucun CSS inline, aucun fichier `.css`, aucune
+  variable CSS de la maquette.
+- **Dates = date-fns v2** (`format`, locale `fr`). Pas de moment (sauf code existant).
+- **Feedback utilisateur = `useSnackbar` / `showSnackbar(message, severity)`** (pattern existant).
+- **Chips de statut** : suivre le pattern `QuoteStatusChip` (variantes palette `light` / `dark`).
+- Pas de `any` non justifié, pas de `console.log`, pas de props drilling > 2 niveaux.
+- Ne pas réécrire de fichiers hors périmètre ; proposer les diffs pour `App.tsx`.
+
+---
+
+## API backend
+
+Base : `${API_BASE_URL}/accounting/garage/{garageId}/...`
+`garageId` provient du garage courant (même mécanisme que les autres pages du module —
+récupérer via le contexte / `useFetchAdministratedGarages` comme ailleurs, ne pas hardcoder `20`).
+
+| Action | Méthode & URL |
+|---|---|
+| Liste paginée des exports | `GET  /exports?page={p}&size={s}` |
+| Écritures en attente (WIP) | `GET  /exports/pending`  *(à créer côté API — voir note)* |
+| Générer un export | `POST /exports?until={yyyy-MM-dd}` |
+| État d'un export | `GET  /exports/{exportId}` |
+| Annuler le dernier export non téléchargé | `DELETE /exports/{exportId}` |
+| Déclencher un téléchargement | `POST /exports/{exportId}/download` |
+| État d'un téléchargement | `GET  /sinao-downloads/{downloadId}` |
+
+> **Note pagination / pending :** aujourd'hui `GET /exports` **et** `GET /exports/pending`
+> ne sont pas encore livrés côté back sous cette forme. Deux formes de réponse ont été
+> observées dans les échantillons (voir plus bas) :
+> 1. une réponse `Page<Export>` Spring « nue » (`{ content, pageable, totalPages, ... }`) ;
+> 2. une réponse enveloppée `{ exports: Page<Export>, pendingEntriesCount: number }`.
+>
+> **Implémenter le service de façon défensive** : parser `pendingEntriesCount` depuis la
+> réponse liste **si présente**, sinon consommer `GET /exports/pending`. Isoler ce choix
+> dans le service pour qu'un seul endroit change quand l'API sera figée. Documenter par un
+> commentaire l'hypothèse retenue.
+
+### Formes de réponse (échantillons réels)
+
+**Génération — `POST /exports?until=...`** (statut initial `generating`) :
+```json
+{ "exportId": 250, "periodStart": "2026-05-01", "periodEnd": "2026-05-16", "status": "generating" }
+```
+
+**État d'un export — `GET /exports/{id}`** :
+```json
+{
+  "id": 250,
+  "periodStart": "2026-05-01",
+  "periodEnd": "2026-05-16",
+  "status": "generated",
+  "sinaoEntriesCount": 23,
+  "sinaoZipUrl": null,
+  "downloadedAt": null,
+  "transmissions": [],
+  "canTransmit": ["pennylane"],
+  "createdAt": "2026-09-02T16:20:30.741872Z"
+}
+```
+
+**Liste — `GET /exports` (forme 1, Page nue)** :
+```json
+{
+  "content": [ { "id": 250, "periodStart": "...", "periodEnd": "...", "status": "generated",
+    "sinaoEntriesCount": 23, "sinaoZipUrl": "https://...", "downloadedAt": "2026-09-02T16:21:54Z",
+    "transmissions": [], "canTransmit": ["pennylane"], "createdAt": "..." } ],
+  "totalElements": 1, "totalPages": 1, "number": 0, "size": 12, "first": true, "last": true, "empty": false
+}
+```
+
+**Liste — `GET /exports` (forme 2, enveloppée + WIP)** :
+```json
+{ "exports": { "content": [ ...Export ], "totalPages": 1, "totalElements": 2, "number": 0, "size": 12, ... },
+  "pendingEntriesCount": 20 }
+```
+
+**État d'un téléchargement — `GET /sinao-downloads/{id}`** (⚠️ snake_case ici) :
+```json
+{
+  "id": 80,
+  "status": "finished",
+  "entries_count": 9,
+  "file_url": "https://sinao-prod-storage.s3.eu-west-3.amazonaws.com/.../80.zip?...",
+  "period_start": "2026-05-14T22:00:00.000000Z",
+  "period_end": "2026-05-26T22:00:00.000000Z",
+  "error_message": null,
+  "info_message": null
+}
+```
+
+> ⚠️ Incohérence de casing entre endpoints : `/exports/*` renvoie du **camelCase**,
+> `/sinao-downloads/*` du **snake_case**. Gérer via les `@Expose({ name: ... })` dans deux
+> classes distinctes.
+
+### Statuts (`Export.status`)
+
+Valeurs observées : `generating`, `generated`. Prévoir aussi un statut d'échec
+(`failed` / `error` — à confirmer côté back ; mapper de façon tolérante et logguer un warn
+si valeur inconnue plutôt que crash). Modéliser en `enum` :
+
+```ts
+export enum AccountingExportStatus {
+  GENERATING = "generating",
+  GENERATED = "generated",
+  FAILED = "failed", // à confirmer avec le back
+}
+```
+
+État de téléchargement (`SinaoDownload.status`) : `pending` / `processing` / `finished` /
+`failed` (observé : `finished`). Même prudence.
+
+---
+
+## Modèles à créer — `src/models/Billing/AccountingExport.ts`
+
+Suivre **exactement** le pattern class-transformer de `SupplierOrder`.
+
+- `AccountingExport`
+  - `@Expose() id!: number`
+  - `@Expose() periodStart!: string` / `@Expose() periodEnd!: string`
+  - `@Expose() status!: AccountingExportStatus`
+  - `@Expose() sinaoEntriesCount?: number | null`
+  - `@Expose() sinaoZipUrl?: string | null`
+  - `@Expose() downloadedAt?: string | null`
+  - `@Expose() createdAt?: string`
+  - `@Expose() transmissions?: unknown[]` (typer plus finement si le back documente)
+  - `@Expose() canTransmit?: string[]`
+  - statiques `JsonToObject` / `JsonToObjects`
+  - helpers dérivés (getters ou fonctions pures exportées), utilisés par l'UI :
+    - `isDownloaded` = `downloadedAt != null`
+    - `isGenerating` = `status === GENERATING`
+    - `isFailed` = `status === FAILED`
+    - `isAvailable` = `status === GENERATED && downloadedAt == null`
+
+- `SinaoDownload` (mapping snake_case)
+  - `@Expose() id!: number`
+  - `@Expose() status!: SinaoDownloadStatus`
+  - `@Expose({ name: "entries_count" }) entriesCount?: number`
+  - `@Expose({ name: "file_url" }) fileUrl?: string | null`
+  - `@Expose({ name: "period_start" }) periodStart?: string`
+  - `@Expose({ name: "period_end" }) periodEnd?: string`
+  - `@Expose({ name: "error_message" }) errorMessage?: string | null`
+  - `@Expose({ name: "info_message" }) infoMessage?: string | null`
+  - statiques `JsonToObject`
+
+- `PendingEntries` (si `GET /exports/pending` renvoie un objet) : `@Expose() count!: number`
+  (adapter au vrai payload ; à défaut typer `{ count: number }`).
+
+- Type d'aide pour la liste paginée (générique Spring) — soit réutiliser un type `Page<T>`
+  déjà présent dans le projet **s'il existe**, sinon en définir un local :
+  ```ts
+  export type Page<T> = {
+    content: T[];
+    totalPages: number;
+    totalElements: number;
+    number: number; // index de page courant
+    size: number;
+    first: boolean;
+    last: boolean;
+    empty: boolean;
+  };
+  ```
+
+---
+
+## Service à créer — `src/services/Billing/AccountingExportService.ts`
+
+Clé de cache : `export const ACCOUNTING_EXPORT = "ACCOUNTING_EXPORT";`
+
+Hooks / fonctions à exposer (adapter la signature au pattern maison `useFetch...`) :
+
+1. **`useFetchPendingEntriesCount(garageId)`** → `useQuery`
+   - `GET /exports/pending` (ou lire `pendingEntriesCount` de la liste selon la note API).
+   - Renvoie un `number`. `queryKey: [ACCOUNTING_EXPORT, "pending", garageId]`.
+
+2. **`useFetchExports(garageId, { page, size })`** → `useQuery`
+   - `GET /exports?page=&size=`. `size` par défaut = **12** (cf. échantillons).
+   - Renvoie un `Page<AccountingExport>`. Gérer les deux formes de payload (nue / enveloppée).
+   - `queryKey: [ACCOUNTING_EXPORT, "list", garageId, page, size]`.
+
+3. **`useFetchExportsInfinite(garageId, { size })`** → `useInfiniteQuery`
+   - Pour l'historique « Voir tout ». `getNextPageParam` basé sur `totalPages` (cf. pattern
+     `useFetchQuoteByState` déjà utilisé dans le projet). Aplatir via `data.pages.flatMap`.
+   - À utiliser pour la liste « Déjà téléchargés » quand on déplie l'historique complet.
+
+4. **`useFetchExport(garageId, exportId, options?)`** → `useQuery`
+   - `GET /exports/{id}`. Sert au **polling** : activer `refetchInterval` tant que
+     `status === generating` (ex. 2000 ms), le couper sinon. `enabled` sur `!!exportId`.
+
+5. **`useGenerateExport(garageId)`** → `useMutation`
+   - `POST /exports?until={yyyy-MM-dd}`. Par défaut `until = today` (format date-fns
+     `yyyy-MM-dd`). Sur succès : invalider `pending` + `list`, retourner l'`AccountingExport`
+     initial (`generating`) pour amorcer le polling.
+
+6. **`useCancelExport(garageId)`** → `useMutation`
+   - `DELETE /exports/{id}`. Sur succès : invalider `pending` + `list`.
+   - Rappel métier : seul le **dernier** export **non téléchargé** est annulable — l'UI ne
+     doit proposer « Annuler » que dans ce cas, mais gérer aussi un refus back (409/403) via snackbar.
+
+7. **`useDownloadExport(garageId)`** → `useMutation`
+   - `POST /exports/{id}/download` → renvoie (ou permet de récupérer) un `downloadId`
+     (`sinao-download`). Puis suivre l'état.
+
+8. **`useFetchSinaoDownload(garageId, downloadId, options?)`** → `useQuery`
+   - `GET /sinao-downloads/{id}`, polling tant que `status` ∈ {pending, processing}.
+   - Quand `finished` + `file_url` : déclencher le téléchargement effectif du fichier
+     (réutiliser le helper de download authentifié déjà présent dans le projet — même
+     mécanisme que le download PDF factures : `readCookie("movalibProToken")`, blob, `<a>`
+     programmatique. **Ne pas réinventer** : chercher le helper existant et le réutiliser).
+
+9. **`invalidateAccountingExports(queryClient)`** → `invalidateQueries({ queryKey: [ACCOUNTING_EXPORT], exact: false })`.
+
+Toutes les fonctions passent par `request({ url, method, body? })`, puis
+`AccountingExport.JsonToObject(res)` / `.JsonToObjects(res.content)` selon le cas.
+Gérer les erreurs avec `.catch` → `throw new Error(...)` remonté aux mutations pour le snackbar.
+
+---
+
+## Écran — `src/pages/billing/AccountingExports.tsx`
+
+**Ordre des blocs à respecter (issu de la maquette) — du haut vers le bas :**
+
+1. **En-tête** : titre « Écritures comptables » + nom du garage (dans le style d'en-tête
+   des autres pages du module, pas la mise en forme de la maquette).
+
+2. **Bloc générateur** (carte MUI, style thème) :
+   - Grand **compteur** = nombre d'écritures en attente (`pending`) + libellé
+     « pièces prêtes à exporter » (accord singulier/pluriel).
+   - Ligne d'info secondaire : « Saisies depuis votre dernière génération, le {date du dernier export} »
+     (formatée date-fns/fr). Si aucun export précédent, adapter le texte.
+   - **Bouton principal « Générer l'export FEC »** (couleur primaire du thème) :
+     - actif si `pending > 0` et pas de génération en cours ;
+     - **désactivé** avec libellé « Aucune écriture à exporter » si `pending === 0` ;
+     - **désactivé** avec libellé « Génération en cours… » pendant un `generating`.
+   - **Zone de progression** (visible seulement pendant `generating`) : un indicateur de
+     progression MUI (`LinearProgress` — indéterminé, car l'API n'expose pas de %) + texte
+     d'état. À la fin : message « Export prêt — à télécharger ci-dessous » (style thème,
+     pas la pastille jaune de la maquette).
+   - **État « génération déjà lancée au chargement »** : si, au montage, un export est déjà
+     `generating` (présent en tête de liste), afficher directement l'état en cours + bouton
+     désactivé, et démarrer le polling.
+
+3. **Bloc « À télécharger »** (exports `isAvailable` = generated & non téléchargés) :
+   - En-tête de section « {n} fichier(s) à télécharger ».
+   - Une ligne par export : date (`createdAt`), détail « {sinaoEntriesCount} écritures »,
+     bouton **Télécharger**.
+   - Sur **le tout premier** (le plus récent) et **seulement s'il est le dernier généré non
+     téléchargé** : bouton **Annuler** (avec confirmation — voir plus bas).
+   - Ligne nouvellement générée : léger highlight transitoire (via `sx`/thème), optionnel.
+   - **État « échec »** : si un export est `failed`, l'afficher en ligne d'erreur (couleur
+     d'erreur du thème) avec message « La génération a échoué. Aucune écriture n'a été
+     consommée, vous pouvez relancer. » + bouton **Relancer** (= re-générer).
+
+4. **État « Tout récupéré »** : si aucun export « à télécharger » → petit bloc centré
+   « Tous vos fichiers ont été récupérés. » (icône check du thème).
+
+5. **Section « Déjà téléchargés »** (exports `isDownloaded`) :
+   - Liste : icône check, résumé « {date} · {n} écritures », mention « récupéré le {downloadedAt} »,
+     bouton discret **Télécharger** (re-download).
+   - **Pagination** : afficher d'abord la première page (size 12), puis bouton
+     **« Voir tout l'historique »** qui bascule sur `useFetchExportsInfinite` (ou incrémente
+     la page) — l'historique peut être volumineux, ne jamais tout charger d'un coup.
+
+**Cas limites à couvrir explicitement (critères d'acceptation) :**
+- `pending === 0` → compteur 0 + bouton désactivé « Aucune écriture à exporter ».
+- Génération en cours → progression + bouton désactivé + polling.
+- Échec de génération → ligne d'erreur + relance possible.
+- Annulation impossible (un export plus récent existe) → **ne pas** afficher « Annuler » sur
+  les exports concernés ; si le back refuse une annulation, snackbar explicite.
+- Historique volumineux → pagination / infinite scroll.
+- Aucun doublon entre exports successifs : garanti côté back (incrémental) ; l'UI se contente
+  de ne jamais relancer deux générations en parallèle (désactiver le bouton pendant le WIP).
+
+---
+
+## Sous-composants suggérés (`src/pages/billing/components/`)
+
+Découper pour rester lisible (chaque fichier ≈ une responsabilité) :
+
+- `ExportGenerator.tsx` — carte compteur + bouton générer + progression.
+- `ExportAvailableList.tsx` — liste « à télécharger » (+ gestion Annuler/Relancer).
+- `ExportDownloadedList.tsx` — liste « déjà téléchargés » + pagination / voir tout.
+- `ExportRow.tsx` — ligne d'export réutilisable (variantes : available / downloaded / error).
+- `CancelExportConfirm.tsx` — confirmation d'annulation (dialog MUI ou confirm inline selon
+  le pattern de confirmation déjà utilisé dans movalib-pro — réutiliser l'existant).
+- `AccountingExportStatusChip.tsx` — chip de statut façon `QuoteStatusChip`.
+
+Le téléchargement effectif du ZIP réutilise le helper de download authentifié existant
+(cf. download PDF factures). Chercher et réutiliser, ne pas dupliquer.
+
+---
+
+## Confirmation d'annulation
+
+Au clic sur « Annuler » : demander confirmation avec un message du type
+« Annuler l'export du {date} ? Ses {n} écritures repartiront dans le prochain export. »
+→ boutons « Conserver » / « Annuler l'export ». Sur confirmation : `useCancelExport`,
+puis invalider `pending` + `list` (le compteur WIP doit augmenter du nombre d'écritures
+restituées). Utiliser le composant/dialog de confirmation déjà en place dans le projet.
+
+---
+
+## Correspondance maquette → DA movalib-pro
+
+| Élément maquette | À remplacer par |
+|---|---|
+| Police Outfit, variables `--vert/--jaune/--rose/--noir` | Thème MUI (`theme.palette.*`), typo du thème |
+| `.bouton--principal` vert | `Button variant="contained"` couleur primaire du thème |
+| `.bouton--telecharger` noir | `Button variant="contained"` selon thème (secondaire/neutre) |
+| `.bouton--annuler` / `--discret` | `Button variant="outlined"` / `variant="text"` |
+| Bande jaune « à télécharger » | En-tête de section MUI (couleur d'accent du thème) |
+| Pastille jaune « Export prêt » | `Alert`/texte info du thème |
+| `.piste` + `.jauge` custom | `LinearProgress` MUI (indéterminé) |
+| Puce rose d'erreur / `.ligne--erreur` | Couleur `error` du thème + chip/texte d'erreur |
+| Icônes SVG inline | Icônes MUI (`@mui/icons-material`) équivalentes |
+| Highlights `--neuve` / `--recuperee` | `sx` avec transition légère du thème (optionnel) |
+
+Le **JS de la maquette est illustratif** (état simulé) : ne pas le porter. La logique réelle
+vient des hooks React Query ci-dessus.
+
+---
+
+## Definition of Done
+
+- [ ] Route ajoutée dans `App.tsx` (pattern des pages `billing/*`), accès depuis Facturation.
+- [ ] Modèles `AccountingExport` / `SinaoDownload` en class-transformer, casing géré.
+- [ ] Service complet (pending, liste paginée + infinite, état export, générer, annuler,
+      download + suivi sinao-download, invalidation).
+- [ ] Écran conforme à l'ordre des blocs, tous les états couverts (pending 0, generating,
+      failed, available, downloaded, annulation impossible, historique paginé).
+- [ ] DA respectée (MUI + thème, aucune valeur en dur de la maquette).
+- [ ] Polling génération + polling download, coupés dès l'état terminal.
+- [ ] Aucune génération en double possible (bouton verrouillé pendant le WIP).
+- [ ] `tsc` sans erreur, pas de `any` non justifié, pas de `console.log`.
+- [ ] `garageId` dynamique (pas de `20` en dur).
+
+## Questions ouvertes à confirmer côté back (à signaler, ne pas bloquer)
+
+- Forme définitive de `GET /exports` (nue vs enveloppée + `pendingEntriesCount`).
+- Payload exact de `GET /exports/pending`.
+- Valeur exacte du statut d'échec (`failed` ? `error` ?).
+- Réponse de `POST /exports/{id}/download` : renvoie-t-elle directement le `downloadId` /
+  l'URL, ou faut-il enchaîner sur `GET /sinao-downloads/{id}` avec un id connu autrement ?

package/.claude/POSTAL_CODE_AUTOCOMPLETE.md

@@ -0,0 +1,78 @@
+  Tous préfixés /api/billing/{garageId}/packages                                                                                                                                                         
+
+  ┌─────────┬──────────────────────────────────────────────┬─────────────────────────────────────┐                                                                                                       
+  │ Méthode │                     URL                      │             Description             │                                                                                                       
+  ├─────────┼──────────────────────────────────────────────┼─────────────────────────────────────┤                                                                                                       
+  │ GET     │ /{garageId}/packages?search=&page=0&limit=20 │ Liste paginée des forfaits          │                                                                                                     
+  ├─────────┼──────────────────────────────────────────────┼─────────────────────────────────────┤                                                                                                       
+  │ GET     │ /{garageId}/packages/{packageId}             │ Détail d'un forfait avec composants │                                                                                                       
+  ├─────────┼──────────────────────────────────────────────┼─────────────────────────────────────┤                                                                                                       
+  │ POST    │ /{garageId}/packages                         │ Création d'un forfait               │                                                                                                       
+  ├─────────┼──────────────────────────────────────────────┼─────────────────────────────────────┤                                                                                                       
+  │ PATCH   │ /{garageId}/packages/{packageId}             │ Modification d'un forfait           │                                                                                                     
+  ├─────────┼──────────────────────────────────────────────┼─────────────────────────────────────┤                                                                                                       
+  │ DELETE  │ /{garageId}/packages/{packageId}             │ Suppression d'un forfait            │                                                                                                     
+  └─────────┴──────────────────────────────────────────────┴─────────────────────────────────────┘                                                                                                       
+
+  Exemple body POST/PATCH :                                                                                                                                                                              
+  {                                                                                                                                                                                                    
+    "reference": "FORFAIT-VIDANGE-01",                                                                                                                                                                   
+    "label": "Forfait vidange complète",                                                                                                                                                               
+    "amountCents": 8000,                                                                                                                                                                                 
+    "amountInclVatCents": 9600,                                                                                                                                                                          
+    "vatRate": 20.00,                                                                                                                                                                                    
+    "accountId": 42,                                                                                                                                                                                     
+    "components": [                                                                                                                                                                                      
+      {                                                                                                                                                                                                  
+        "catalogId": 101,                                                                                                                                                                                
+        "reference": "HUI-MOT-5W30",                                                                                                                                                                     
+        "label": "Huile moteur 5W30 - 5L",                                                                                                                                                               
+        "quantity": 1,                                                                                                                                                                                   
+        "amountCents": 3500,                                                                                                                                                                             
+        "amountInclVatCents": 4200,                                                                                                                                                                      
+        "vatRate": 20.00,                                                                                                                                                                                
+        "index": 0                                                                                                                                                                                       
+      },                                                                                                                                                                                                 
+      {                                                                                                                                                                                                  
+        "catalogId": 102,                                                                                                                                                                                
+        "reference": "FIL-HUI-01",                                                                                                                                                                       
+        "label": "Filtre à huile",                                                                                                                                                                       
+        "quantity": 1,                                                                                                                                                                                   
+        "amountCents": 1000,                                                                                                                                                                             
+        "amountInclVatCents": 1200,                                                                                                                                                                      
+        "vatRate": 20.00,                                                                                                                                                                                
+        "index": 1                                                                                                                                                                                       
+      }                                                                                                                                                                                                  
+    ],                                                                                                                                                                                                   
+    "labor": {                                                                                                                                                                                           
+      "serviceId": 55,                                                                                                                                                                                   
+      "reference": "MO-VIDANGE",                                                                                                                                                                         
+      "label": "Main d'œuvre vidange",                                                                                                                                                                   
+      "quantity": 1,                                                                                                                                                                                     
+      "amountCents": 3500,                                                                                                                                                                               
+      "amountInclVatCents": 4200,                                                                                                                                                                        
+      "vatRate": 20.00                                                                                                                                                                                   
+    }                                                                                                                                                                                                    
+  }                                                                                                                                                                                                      
+
+  Tous les montants sont en centimes (8000 = 80,00 €). La somme Σ composants TTC + labor TTC doit être égale à amountInclVatCents — le back valide cette cohérence.                                      
+
+  Modifications sur les appels existants updateInvoice / updateQuote                                                                                                                                     
+
+  Quand un forfait est ajouté sur un devis ou une facture, il faut passer les IDs des forfaits concernés en query params sur les endpoints POST /{garageId}/invoices/{invoiceId} et POST
+  /{garageId}/quotes/{quoteId} :                                                                                                                                                                         
+
+  POST /api/billing/12/invoices/456?packageIds[0]=7&packageIds[1]=12                                                                                                                                     
+
+  Ces IDs servent à alimenter la table analytique document_packages. À chaque appel, le back repart de zéro et recrée les associations — pas d'état à maintenir côté front, envoyer simplement la liste  
+  complète des forfaits présents sur le document à ce moment-là. Si le document n'a plus de forfait, ne pas envoyer le paramètre (ou envoyer une liste vide).                                            
+
+  Nouvelles propriétés sur les lignes du document
+
+  Quand le front crée une ligne de type commentaire correspondant à un composant de forfait, il doit stocker et renvoyer l'UUID du PackageComponent associé. Ce champ est retourné dans la réponse GET du
+   forfait (components[].id).                                                                                                                                                                            
+
+  Ce packageComponentId est ce qui permet au back de déclencher la sortie de stock correcte au moment de la finalisation de la facture, en ignorant la quantité Sinao et en utilisant celle définie dans
+  le forfait.                                                                                                                                                                                          
+
+  ⚠️ Si l'utilisateur supprime une ligne COMPONENT du document avant de finaliser, ne pas envoyer le packageComponentId → pas de sortie de stock pour ce composant (comportement attendu).