Implement robust error handling and configuration for Logistics API interactions
- Introduced `LogisticsApiException` to handle connection and request errors with user-friendly messages in French. - Updated `LogisticsService` to include configurable timeout, connection timeout, retry attempts, and sleep duration for retries. - Enhanced error handling in Filament pages to catch `LogisticsApiException` and provide clear feedback to users. - Updated `.env` and `config/logistics.php` to support new configuration options. - Added logging for failed API requests in `api_request_logs`. - Created comprehensive API documentation for Logistics endpoints.
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
# Memory Bank
|
||||
|
||||
Derniere mise a jour : 2026-02-19
|
||||
Derniere mise a jour : 2026-02-20
|
||||
|
||||
## Presentation
|
||||
|
||||
@@ -12,10 +12,10 @@ Ce dossier contient le Memory Bank du projet API Logistics. Il sert de source de
|
||||
|---------|-------------|
|
||||
| `projectbrief.md` | Vision, objectifs et perimetre du projet |
|
||||
| `productContext.md` | Contexte produit, problemes resolus, experience utilisateur |
|
||||
| `techContext.md` | Stack technique, API Logistics, dependances |
|
||||
| `systemPatterns.md` | Architecture, patterns, structure des repertoires |
|
||||
| `techContext.md` | Stack technique, API Logistics, dependances, configuration |
|
||||
| `systemPatterns.md` | Architecture, patterns, structure des repertoires, conventions |
|
||||
| `activeContext.md` | Travail en cours, decisions recentes, prochaines etapes |
|
||||
| `progress.md` | Avancement, ce qui fonctionne, ce qui reste a faire |
|
||||
| `progress.md` | Avancement, ce qui fonctionne, ce qui reste a faire, metriques |
|
||||
|
||||
## Utilisation
|
||||
|
||||
|
||||
@@ -1,10 +1,10 @@
|
||||
# Active Context
|
||||
|
||||
Derniere mise a jour : 2026-02-19
|
||||
Derniere mise a jour : 2026-02-20
|
||||
|
||||
## Travail en cours
|
||||
|
||||
Aucun travail en cours. Le setup initial du projet est termine.
|
||||
Aucun travail en cours. Les ameliorations de robustesse du service API sont terminees.
|
||||
|
||||
## Decisions recentes
|
||||
|
||||
@@ -14,20 +14,31 @@ Aucun travail en cours. Le setup initial du projet est termine.
|
||||
- **LogisticsService** : Toutes les interactions avec l'API sont centralisees dans un seul service pour faciliter la maintenance et le tracage.
|
||||
- **Heroicon enum** : Filament v5 impose l'utilisation de `BackedEnum` pour `$navigationIcon` au lieu de strings.
|
||||
- **$view non-static** : Filament v5 a change `$view` de static a instance property.
|
||||
- **Timeout et retry configurables** (2026-02-20) : Les parametres `timeout`, `connect_timeout`, `retry.times` et `retry.sleep_ms` sont desormais dans `config/logistics.php` et pilotes par des variables `.env`. Le retry ne se declenche que sur les `ConnectionException`.
|
||||
- **LogisticsApiException** (2026-02-20) : Exception dediee creee pour distinguer les erreurs de connexion (API injoignable) des erreurs de requete generiques. Messages en francais.
|
||||
- **Logging des echecs** (2026-02-20) : Les requetes echouees sont desormais aussi enregistrees dans `api_request_logs` avec `response_status = 0`.
|
||||
- **Contrainte reseau** (2026-02-20) : Le serveur API `tse-10-test.esiweb.pro` est sur un reseau prive, accessible uniquement via Bureau a distance (RDP). L'application locale ne peut pas joindre l'API sans tunnel ou deploiement sur le reseau distant.
|
||||
|
||||
## Changements importants
|
||||
## Changements importants (2026-02-20)
|
||||
|
||||
- `LogisticsService` mis a jour : timeout, connectTimeout, retry, gestion d'erreur avec `LogisticsApiException`.
|
||||
- `LogisticsApiException` creee dans `app/Exceptions/`.
|
||||
- `config/logistics.php` etendu avec timeout et retry.
|
||||
- `.env` et `.env.example` completes avec les nouvelles variables.
|
||||
- Les 5 pages Filament mises a jour pour attraper `LogisticsApiException`.
|
||||
- Tests passes de 8 a 12 (4 nouveaux tests pour timeout, exception, logging, contexte).
|
||||
|
||||
## Historique (2026-02-19)
|
||||
|
||||
- Installation de Filament v5.0.0 (31 packages ajoutes).
|
||||
- 5 pages Filament creees : TablesExplorer, Articles, Documents, Journaux, Tiers.
|
||||
- `LogisticsService` couvre 17 endpoints de l'API.
|
||||
- Migration `api_request_logs` creee pour le tracage des requetes.
|
||||
- 8 tests Pest ecrits et valides pour le service.
|
||||
- `LogisticsService` cree avec 17 endpoints.
|
||||
- Migration `api_request_logs` creee.
|
||||
- 8 tests Pest ecrits et valides.
|
||||
|
||||
## Prochaines etapes
|
||||
|
||||
- L'utilisateur doit creer la base de donnees MySQL `api_logistics`.
|
||||
- L'utilisateur doit executer `php artisan migrate`.
|
||||
- L'utilisateur doit renseigner sa cle API dans `.env` (`LOGISTICS_API_KEY`).
|
||||
- L'utilisateur doit executer `npm run build`.
|
||||
- Tester le dashboard avec de vraies donnees API.
|
||||
- Deployer l'application sur le reseau distant (serveur accessible via RDP) ou mettre en place un tunnel SSH/VPN pour que l'application puisse joindre l'API.
|
||||
- Tester le dashboard avec de vraies donnees API une fois la connectivite reseau resolue.
|
||||
- Eventuellement : ajouter des pages pour les endpoints d'ecriture (document_add, document_mod).
|
||||
- Eventuellement : ameliorer l'affichage des resultats (pagination, formatage).
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Product Context
|
||||
|
||||
Derniere mise a jour : 2026-02-19
|
||||
Derniere mise a jour : 2026-02-20
|
||||
|
||||
## Pourquoi ce projet existe
|
||||
|
||||
@@ -14,7 +14,8 @@ L'API Logistics (Flex/ESI Gescom) est un systeme de gestion commerciale accessib
|
||||
|
||||
- **Exploration de l'API** : Le dashboard permet de tester chaque endpoint avec des parametres personnalisables, sans avoir besoin de Postman.
|
||||
- **Comprehension de la structure** : La page "Tables" permet de decouvrir les tables et colonnes disponibles dans l'API.
|
||||
- **Tracabilite** : Chaque requete effectuee est enregistree dans `api_request_logs` pour pouvoir analyser les echanges.
|
||||
- **Tracabilite** : Chaque requete effectuee (reussie ou echouee) est enregistree dans `api_request_logs` pour pouvoir analyser les echanges.
|
||||
- **Resilience** : Les erreurs de connexion sont gerees avec retry automatique et messages explicites en francais.
|
||||
|
||||
## Experience utilisateur
|
||||
|
||||
@@ -26,4 +27,4 @@ L'utilisateur accede au dashboard Filament sur `http://api-logistics.test/admin`
|
||||
4. **Journaux** : Recherche par type de journal (TYPE).
|
||||
5. **Tiers** : Recherche de tiers (search obligatoire) + historique des articles d'un tiers.
|
||||
|
||||
Chaque page affiche les resultats sous forme de tableau dynamique et les metadonnees de la reponse (nombre de resultats, succes).
|
||||
Chaque page affiche les resultats sous forme de tableau dynamique et les metadonnees de la reponse (nombre de resultats, succes). En cas d'erreur de connexion a l'API, un message clair en francais est affiche a l'utilisateur.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Progress
|
||||
|
||||
Derniere mise a jour : 2026-02-19
|
||||
Derniere mise a jour : 2026-02-20
|
||||
|
||||
## Ce qui fonctionne
|
||||
|
||||
@@ -9,33 +9,35 @@ Derniere mise a jour : 2026-02-19
|
||||
- [x] Fortify installe (authentification existante, non utilisee par Filament)
|
||||
- [x] Documentation API redigee (`documentation/WEB-A-1 (3).md`, `documentation/result.pdf`)
|
||||
- [x] Memory bank cree et structure (`memory-bank/`, `.cursor/rules/memory-bank.mdc`)
|
||||
- [x] Configuration API Logistics (`.env`, `config/logistics.php`)
|
||||
- [x] `LogisticsService` cree (`app/Services/LogisticsService.php`) avec 17 methodes
|
||||
- [x] Configuration API Logistics (`.env`, `config/logistics.php`) avec timeout et retry
|
||||
- [x] `LogisticsService` cree (`app/Services/LogisticsService.php`) avec 17 methodes, timeout, retry, gestion d'erreur
|
||||
- [x] `LogisticsApiException` creee (`app/Exceptions/LogisticsApiException.php`) avec messages francais
|
||||
- [x] Migration `api_request_logs` creee
|
||||
- [x] Filament v5.0.0 installe et configure sans authentification
|
||||
- [x] 5 pages Filament creees : TablesExplorer, Articles, Documents, Journaux, Tiers
|
||||
- [x] 5 vues Blade associees dans `resources/views/filament/pages/`
|
||||
- [x] 8 tests Pest pour LogisticsService (tous passent)
|
||||
- [x] Gestion d'erreur dans toutes les pages Filament (LogisticsApiException + Throwable)
|
||||
- [x] Logging des requetes API reussies et echouees dans `api_request_logs`
|
||||
- [x] 12 tests Pest pour LogisticsService (tous passent)
|
||||
- [x] `README.md` cree
|
||||
- [x] Formatage Pint valide
|
||||
- [x] CI GitHub Actions (lint + tests)
|
||||
|
||||
## Ce qui reste a faire
|
||||
|
||||
- [ ] Creer la base de donnees MySQL `api_logistics` (a faire par l'utilisateur)
|
||||
- [ ] Executer `php artisan migrate` (a faire par l'utilisateur)
|
||||
- [ ] Renseigner la cle API dans `.env` (`LOGISTICS_API_KEY`)
|
||||
- [ ] Executer `npm run build`
|
||||
- [ ] Resoudre la connectivite reseau : deployer sur le reseau distant ou mettre en place un tunnel
|
||||
- [ ] Tester le dashboard avec de vraies donnees API
|
||||
- [ ] Eventuellement : pages d'ecriture (document_add, document_mod)
|
||||
- [ ] Eventuellement : ameliorer l'affichage des resultats (pagination, formatage)
|
||||
|
||||
## Problemes connus
|
||||
|
||||
- L'erreur `SQLSTATE[HY000] [1049] Unknown database 'api_logistics'` apparait lors de `composer update` car le script `boost:update` tente d'acceder a la base de donnees qui n'existe pas encore. Sans impact sur le fonctionnement une fois la base creee.
|
||||
- **API injoignable depuis la machine locale** : Le serveur `tse-10-test.esiweb.pro` est sur un reseau prive accessible uniquement via Bureau a distance (RDP). L'application locale recoit `cURL error 28: Connection timed out`. Solution : deployer sur le reseau distant ou creer un tunnel SSH/VPN.
|
||||
- L'erreur `SQLSTATE[HY000] [1049] Unknown database` peut apparaitre lors de `composer update` si la base n'est pas encore creee (script `boost:update`). Sans impact une fois la base creee.
|
||||
|
||||
## Metriques
|
||||
|
||||
- Tests : 8 (tous passent)
|
||||
- Tests : 12 (tous passent, 18 assertions)
|
||||
- Pages Filament : 5
|
||||
- Endpoints API couverts par LogisticsService : 17
|
||||
- Migrations : 5 (users, cache, jobs, two_factor, api_request_logs)
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Project Brief
|
||||
|
||||
Derniere mise a jour : 2026-02-19
|
||||
Derniere mise a jour : 2026-02-20
|
||||
|
||||
## Vision
|
||||
|
||||
@@ -19,11 +19,13 @@ Application Laravel de test dont l'objectif est de comprendre le fonctionnement
|
||||
- Formulaires de recherche parametrables pour chaque endpoint.
|
||||
- Affichage des resultats bruts retournes par l'API.
|
||||
- Tracage des requetes effectuees dans une table `api_request_logs`.
|
||||
- Gestion robuste des erreurs API (timeout, retry, messages utilisateur en francais).
|
||||
|
||||
## Contraintes
|
||||
|
||||
- Pas d'authentification sur le dashboard (projet de test interne).
|
||||
- L'API Logistics est hebergee sur le serveur TSE-10-TEST (`http://tse-10-test.esiweb.pro`).
|
||||
- Le serveur API est accessible uniquement via le reseau interne (connexion Bureau a distance / RDP requise). L'application doit etre deployee sur ce reseau ou un tunnel doit etre mis en place.
|
||||
- Toutes les requetes API sont en POST et necessitent un header `X-API-KEY`.
|
||||
- Le nom du dossier dans les URLs de l'API doit etre en minuscules.
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# System Patterns
|
||||
|
||||
Derniere mise a jour : 2026-02-19
|
||||
Derniere mise a jour : 2026-02-20
|
||||
|
||||
## Architecture applicative
|
||||
|
||||
@@ -14,8 +14,12 @@ Utilisateur --> Filament Dashboard (/admin)
|
||||
LogisticsService (app/Services/)
|
||||
|
|
||||
+---> API Logistics (HTTP POST + X-API-KEY)
|
||||
| (retry automatique sur ConnectionException)
|
||||
|
|
||||
+---> api_request_logs (MySQL)
|
||||
| (succes ET echecs)
|
||||
|
|
||||
+---> LogisticsApiException (en cas d'erreur)
|
||||
```
|
||||
|
||||
## Patterns utilises
|
||||
@@ -26,8 +30,19 @@ Utilisateur --> Filament Dashboard (/admin)
|
||||
|
||||
- Construit l'URL a partir de `config('logistics.base_url')`, `config('logistics.folder')` et le nom de l'endpoint.
|
||||
- Ajoute automatiquement le header `X-API-KEY`.
|
||||
- Enregistre chaque requete dans la table `api_request_logs`.
|
||||
- Configure `timeout()` et `connectTimeout()` depuis la config.
|
||||
- Effectue un retry automatique (nombre et delai configurables) uniquement sur les `ConnectionException`.
|
||||
- Enregistre chaque requete dans la table `api_request_logs` (succes et echecs).
|
||||
- Retourne un tableau PHP avec les cles `data`, `metadata`, `error`.
|
||||
- Lance une `LogisticsApiException` en cas d'erreur de connexion ou de requete.
|
||||
|
||||
### Exception dediee
|
||||
|
||||
`App\Exceptions\LogisticsApiException` (etend `RuntimeException`) fournit :
|
||||
|
||||
- Des messages d'erreur en francais lisibles par l'utilisateur.
|
||||
- Des proprietes `endpoint` et `params` pour le contexte de l'erreur.
|
||||
- Deux methodes statiques : `connectionTimeout()` (API injoignable) et `requestFailed()` (erreur de requete).
|
||||
|
||||
### Pages Filament personnalisees (pas de Resources)
|
||||
|
||||
@@ -36,33 +51,38 @@ L'application n'utilise pas de Resources Filament (pas de CRUD local). Chaque pa
|
||||
- Etend `Filament\Pages\Page`.
|
||||
- Utilise des proprietes Livewire publiques pour les champs de formulaire.
|
||||
- Appelle `LogisticsService` via `app(LogisticsService::class)` dans des methodes d'action (ex: `searchArticles()`).
|
||||
- Attrape `LogisticsApiException` pour afficher un message clair, et `\Throwable` en fallback.
|
||||
- Affiche les resultats dans des tableaux HTML dynamiques generes dans les vues Blade.
|
||||
|
||||
### Configuration externalisee
|
||||
|
||||
Les parametres de connexion a l'API sont dans `config/logistics.php` et lus depuis `.env`.
|
||||
Les parametres de connexion a l'API (URL, cle, dossier, timeout, retry) sont dans `config/logistics.php` et lus depuis `.env`.
|
||||
|
||||
## Structure des repertoires
|
||||
|
||||
```
|
||||
app/
|
||||
Exceptions/
|
||||
LogisticsApiException.php # Exception dediee API
|
||||
Filament/
|
||||
Pages/
|
||||
Articles.php # Recherche articles + stock
|
||||
Documents.php # Recherche documents + detail
|
||||
Journaux.php # Recherche journaux
|
||||
TablesExplorer.php # Exploration tables + colonnes
|
||||
Tiers.php # Recherche tiers + historique
|
||||
Articles.php # Recherche articles + stock
|
||||
Documents.php # Recherche documents + detail
|
||||
Journaux.php # Recherche journaux
|
||||
TablesExplorer.php # Exploration tables + colonnes
|
||||
Tiers.php # Recherche tiers + historique
|
||||
Models/
|
||||
User.php # Modele utilisateur (Fortify)
|
||||
User.php # Modele utilisateur (Fortify)
|
||||
Providers/
|
||||
Filament/
|
||||
AdminPanelProvider.php # Configuration du panel (sans auth)
|
||||
AdminPanelProvider.php # Configuration du panel (sans auth)
|
||||
FortifyServiceProvider.php # Authentification Fortify
|
||||
AppServiceProvider.php # Config globale (CarbonImmutable, DB safety)
|
||||
Services/
|
||||
LogisticsService.php # Service centralise API Logistics
|
||||
LogisticsService.php # Service centralise API Logistics
|
||||
|
||||
config/
|
||||
logistics.php # Configuration API Logistics
|
||||
logistics.php # Configuration API Logistics (URL, cle, timeout, retry)
|
||||
|
||||
database/
|
||||
migrations/
|
||||
@@ -81,7 +101,7 @@ resources/views/
|
||||
tiers.blade.php
|
||||
|
||||
tests/Feature/
|
||||
LogisticsServiceTest.php # 8 tests avec mocks HTTP
|
||||
LogisticsServiceTest.php # 12 tests avec mocks HTTP
|
||||
```
|
||||
|
||||
## Conventions
|
||||
@@ -90,3 +110,5 @@ tests/Feature/
|
||||
- Filament v5 : la propriete `$view` est non-static (`protected string $view`).
|
||||
- Les proprietes statiques (`$navigationIcon`, `$navigationLabel`, `$title`, `$navigationSort`) restent static.
|
||||
- Les appels API passent toujours par `LogisticsService`, jamais directement par `Http::`.
|
||||
- Les pages Filament attrapent `LogisticsApiException` en premier, puis `\Throwable` en fallback.
|
||||
- Les messages d'erreur affiches a l'utilisateur sont en francais.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Tech Context
|
||||
|
||||
Derniere mise a jour : 2026-02-19
|
||||
Derniere mise a jour : 2026-02-20
|
||||
|
||||
## Stack technique
|
||||
|
||||
@@ -33,21 +33,35 @@ Derniere mise a jour : 2026-02-19
|
||||
LOGISTICS_API_BASE_URL=http://tse-10-test.esiweb.pro
|
||||
LOGISTICS_API_KEY=<cle API>
|
||||
LOGISTICS_API_FOLDER=esigescom
|
||||
LOGISTICS_API_TIMEOUT=30
|
||||
LOGISTICS_API_CONNECT_TIMEOUT=10
|
||||
LOGISTICS_API_RETRY_TIMES=3
|
||||
LOGISTICS_API_RETRY_SLEEP_MS=500
|
||||
```
|
||||
|
||||
Fichier de config : `config/logistics.php`
|
||||
|
||||
| Cle de config | Variable .env | Defaut | Description |
|
||||
|---------------|---------------|--------|-------------|
|
||||
| `logistics.base_url` | `LOGISTICS_API_BASE_URL` | - | URL de base de l'API |
|
||||
| `logistics.api_key` | `LOGISTICS_API_KEY` | - | Cle d'authentification |
|
||||
| `logistics.folder` | `LOGISTICS_API_FOLDER` | - | Dossier dans l'URL |
|
||||
| `logistics.timeout` | `LOGISTICS_API_TIMEOUT` | 30 | Timeout total de la requete (secondes) |
|
||||
| `logistics.connect_timeout` | `LOGISTICS_API_CONNECT_TIMEOUT` | 10 | Timeout de connexion (secondes) |
|
||||
| `logistics.retry.times` | `LOGISTICS_API_RETRY_TIMES` | 3 | Nombre de tentatives en cas d'echec de connexion |
|
||||
| `logistics.retry.sleep_ms` | `LOGISTICS_API_RETRY_SLEEP_MS` | 500 | Delai entre les tentatives (ms) |
|
||||
|
||||
### Base de donnees
|
||||
|
||||
- Connexion : MySQL
|
||||
- Base : `api_logistics`
|
||||
- Base : `logistics`
|
||||
- Configuration dans `.env` : `DB_CONNECTION=mysql`
|
||||
|
||||
## API Logistics
|
||||
|
||||
### Connexion
|
||||
|
||||
- Serveur : TSE-10-TEST
|
||||
- Serveur : TSE-10-TEST (reseau prive, accessible uniquement via Bureau a distance / RDP)
|
||||
- Base URL : `http://tse-10-test.esiweb.pro`
|
||||
- Dossier : `esigescom` (minuscules obligatoires)
|
||||
- Authentification : Header `X-API-KEY`
|
||||
|
||||
Reference in New Issue
Block a user