mpa/logisticsAPI
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0ab94fdb9105ad60d09402b366f0c076ae254f3e
logisticsAPI/memory-bank/productContext.md
Marvin bb1bbc2904 Refactor error handling and enhance API interactions across Filament pages 
- Introduced `ApiErrorTranslator` to normalize and translate API error messages, providing clearer feedback in French.
- Updated all Filament pages (Articles, Documents, Divers, Journaux, Tiers, TablesExplorer) to utilize the new error translation mechanism, improving user experience during API interactions.
- Added validation for required fields before API calls, ensuring users receive immediate feedback when mandatory inputs are missing.
- Implemented tracking properties to distinguish between "never searched" and "searched without results," enhancing the user interface.
- Removed the obsolete `$results` property from the Articles page and added a new `$barcode` property to align with API requirements.
- Updated documentation to reflect changes in API behavior and error handling, including new metadata returned by the `art_list` endpoint.
- Added new tests to verify the functionality of the barcode handling and validation logic.
2026-02-23 10:15:17 +01:00

3.9 KiB
Raw Blame History

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é (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, y compris les 2 non fonctionnels (avec avertissement).

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) + vérification du stock d'un article par son ARTID. 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 (document_list, document_detail, Document_GetStatusList, Document_GetUnitPriceAndVat, Document_GetDueDate, Document_GetAttachListThumbnail, Document_GetPDF). En écriture : 2 formulaires (document_add, document_mod). Le formulaire Document_GetPDF affiche un bandeau d'avertissement (endpoint non fonctionnel).
  5. Journaux : Toggle Lecture/Ecriture. En lecture : recherche par type de journal (TYPE). En écriture : état vide.
  6. Tiers : Toggle Lecture/Ecriture. En lecture : recherche de tiers (search obligatoire) + historique des articles d'un tiers. En écriture : état vide.
  7. Divers : Toggle Lecture/Ecriture. En lecture : getserialnumber (numéro de série), codes_list (données par code interne). En écriture : custom_geninv_updatestock (avec bandeau d'avertissement, endpoint non fonctionnel).

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.