# Product Context

Dernière mise à jour : 2026-02-23

## Pourquoi ce projet existe

L'API Logistics (Flex/ESI Gescom) est un système de gestion commerciale accessible via une API REST. La documentation officielle est limitée. Ce projet a été créé pour :

- Explorer les endpoints disponibles de manière interactive.
- Comprendre les paramètres attendus et les formats de réponse.
- Servir de base pour une documentation plus complète.

## Problèmes résolus

- **Exploration de l'API** : Le dashboard permet de tester chaque endpoint (lecture et écriture) avec des paramètres personnalisables, sans avoir besoin de Postman.
- **Compréhension de la structure** : La page "Tables" permet de découvrir les tables et colonnes disponibles dans l'API, avec déduplication automatique des colonnes retournées en double par l'API.
- **Documentation intégrée** : La page "Documentation" affiche le markdown de la documentation API avec un rendu stylisé (typographie, tableaux, blocs de code) et propose un export PDF.
- **Traçabilité** : Chaque requête effectuée (réussie ou échouée) est enregistrée dans `api_request_logs` pour pouvoir analyser les échanges.
- **Résilience** : Les erreurs de connexion sont gérées avec retry automatique et messages explicites en français. Les erreurs API sont traduites et enrichies d'explications via `ApiErrorTranslator`.
- **Validation** : Les champs obligatoires sont validés avant chaque appel API avec des messages en français. Les pages distinguent "jamais recherché" de "recherché sans résultat" grace aux propriétés de tracking.
- **Cohérence visuelle** : Un système de design unifié (11 composants `x-logistics.*`) garantit une présentation homogène sur toutes les pages.
- **Couverture complète des endpoints** : Les 19 endpoints disponibles dans le service sont tous accessibles depuis l'interface et tous fonctionnels. L'endpoint Document_GetPDF, initialement considéré non fonctionnel, a été corrigé (LAYOUT doit être une valeur numérique). L'endpoint custom_geninv_updatestock, initialement considéré non fonctionnel, est fonctionnel en MODE=1 (Restock) avec THIRDID obligatoire.
- **Investigation des paramètres** : Chaque endpoint a été testé systématiquement pour documenter les paramètres réels (obligatoires ou non, types, formats, colonnes valides, comportement des paramètres ignorés). Les résultats sont documentés dans `documentation/documentation_api_logistics.md`.
- **Référence rapide des paramètres** : Chaque endpoint dispose d'un tableau de référence des paramètres directement sous le formulaire, permettant à l'utilisateur de comprendre les paramètres attendus sans consulter la documentation.

## Expérience utilisateur

L'utilisateur accède au dashboard Filament sur `http://api-logistics.test/admin`. La navigation latérale propose 7 pages :

1. **Documentation** : Affichage stylisé de la documentation API complète (markdown converti en HTML). Actions : télécharger en PDF, ouvrir dans un nouvel onglet.
2. **Tables** : Barre de statistiques (endpoint, type base, nombre de tables). Liste filtrable des tables avec compteur de colonnes. Clic sur une table pour voir ses colonnes avec badges de type colorés.
3. **Articles** : Toggle Lecture/Ecriture. En lecture : formulaire de recherche (search, select, barcode) avec tableau de paramètres + vérification du stock d'un article par son ARTID avec tableau de paramètres. L'API retourne un maximum fixe de 5 résultats (non configurable). Le paramètre `barcode` est présent dans le formulaire mais son effet côté API n'est pas observable. En écriture : état vide (aucun endpoint d'écriture disponible).
4. **Documents** : Toggle Lecture/Ecriture. En lecture : 7 formulaires avec tableaux de paramètres (document_list avec results, document_detail, Document_GetStatusList, Document_GetUnitPriceAndVat, Document_GetDueDate, Document_GetAttachListThumbnail, Document_GetPDF). En écriture : 2 formulaires avec tableaux de paramètres (document_add, document_mod). Le formulaire Document_GetPDF est fonctionnel (LAYOUT numérique obligatoire, ex: "1").
5. **Journaux** : Toggle Lecture/Ecriture. En lecture : recherche par type de journal (TYPE) avec tableau de paramètres. En écriture : état vide.
6. **Tiers** : Toggle Lecture/Ecriture. En lecture : recherche de tiers (search obligatoire, recherche dans name/groupid/vat, colonnes par défaut custid/name, max 10 résultats) avec tableau de paramètres + historique des articles d'un tiers (thirdid en minuscules, retourne tout l'historique sans limite) avec tableau de paramètres. En écriture : état vide.
7. **Divers** : Toggle Lecture/Ecriture. En lecture : getserialnumber (numéro de série, retourne un objet `{ "getserialnumber": "..." }`), codes_list (données par code interne, correspondance exacte sensible à la casse, chaîne vide = liste maître des 42 groupes) avec tableau de paramètres. En écriture : custom_geninv_updatestock (fonctionnel en MODE=1 Restock avec THIRDID obligatoire, bandeau d'information sur les modes) avec tableau de paramètres.

### Toggle Lecture / Ecriture

Toutes les pages entité disposent d'un sélecteur en haut de page avec deux boutons : "Lecture" et "Ecriture". Le bouton actif est mis en surbrillance. Le changement de mode affiche instantanément les formulaires correspondants sans rechargement de page.

### Tableaux de référence des paramètres

Sous chaque formulaire d'endpoint, un tableau de référence affiche les colonnes PARAMETRE, TYPE, OBLIGATOIRE et DESCRIPTION. Ce tableau fournit un aide-mémoire des paramètres attendus par l'API, avec les informations critiques (format obligatoire, limites connues, sensibilité à la casse). Les endpoints sans paramètres (comme `getserialnumber`) n'affichent pas de tableau.