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.

app/Exceptions/LogisticsApiException.php

@@ -0,0 +1,38 @@
+<?php
+
+namespace App\Exceptions;
+
+use RuntimeException;
+
+class LogisticsApiException extends RuntimeException
+{
+    public function __construct(
+        string $message,
+        public readonly string $endpoint = '',
+        public readonly array $params = [],
+        int $code = 0,
+        ?\Throwable $previous = null,
+    ) {
+        parent::__construct($message, $code, $previous);
+    }
+
+    public static function connectionTimeout(string $endpoint, array $params, \Throwable $previous): self
+    {
+        return new self(
+            message: "L'API Logistics est injoignable. Verifiez que le serveur est accessible et que votre connexion reseau fonctionne.",
+            endpoint: $endpoint,
+            params: $params,
+            previous: $previous,
+        );
+    }
+
+    public static function requestFailed(string $endpoint, array $params, \Throwable $previous): self
+    {
+        return new self(
+            message: "La requete vers l'API Logistics a echoue : {$previous->getMessage()}",
+            endpoint: $endpoint,
+            params: $params,
+            previous: $previous,
+        );
+    }
+}

app/Filament/Pages/Articles.php

@@ -2,6 +2,7 @@
 
 namespace App\Filament\Pages;
 
+use App\Exceptions\LogisticsApiException;
 use App\Services\LogisticsService;
 use Filament\Pages\Page;
 use Filament\Support\Icons\Heroicon;
@@ -50,9 +51,12 @@ class Articles extends Page
             $this->data = $response['data'] ?? [];
             $this->metadata = $response['metadata'] ?? null;
             $this->errorMessage = $response['error'] ?? null;
-        } catch (\Throwable $e) {
+        } catch (LogisticsApiException $e) {
             $this->errorMessage = $e->getMessage();
             $this->data = [];
+        } catch (\Throwable $e) {
+            $this->errorMessage = "Erreur inattendue : {$e->getMessage()}";
+            $this->data = [];
         }
     }
 
@@ -68,9 +72,12 @@ class Articles extends Page
 
             $this->stockData = $response['data'] ?? [];
             $this->errorMessage = $response['error'] ?? null;
-        } catch (\Throwable $e) {
+        } catch (LogisticsApiException $e) {
             $this->errorMessage = $e->getMessage();
             $this->stockData = [];
+        } catch (\Throwable $e) {
+            $this->errorMessage = "Erreur inattendue : {$e->getMessage()}";
+            $this->stockData = [];
         }
     }
 }

app/Filament/Pages/Documents.php

@@ -2,6 +2,7 @@
 
 namespace App\Filament\Pages;
 
+use App\Exceptions\LogisticsApiException;
 use App\Services\LogisticsService;
 use Filament\Pages\Page;
 use Filament\Support\Icons\Heroicon;
@@ -49,9 +50,12 @@ class Documents extends Page
             $this->data = $response['data'] ?? [];
             $this->metadata = $response['metadata'] ?? null;
             $this->errorMessage = $response['error'] ?? null;
-        } catch (\Throwable $e) {
+        } catch (LogisticsApiException $e) {
             $this->errorMessage = $e->getMessage();
             $this->data = [];
+        } catch (\Throwable $e) {
+            $this->errorMessage = "Erreur inattendue : {$e->getMessage()}";
+            $this->data = [];
         }
     }
 
@@ -67,9 +71,12 @@ class Documents extends Page
 
             $this->detailData = $response['data'] ?? [];
             $this->errorMessage = $response['error'] ?? null;
-        } catch (\Throwable $e) {
+        } catch (LogisticsApiException $e) {
             $this->errorMessage = $e->getMessage();
             $this->detailData = [];
+        } catch (\Throwable $e) {
+            $this->errorMessage = "Erreur inattendue : {$e->getMessage()}";
+            $this->detailData = [];
         }
     }
 }

app/Filament/Pages/Journaux.php

@@ -2,6 +2,7 @@
 
 namespace App\Filament\Pages;
 
+use App\Exceptions\LogisticsApiException;
 use App\Services\LogisticsService;
 use Filament\Pages\Page;
 use Filament\Support\Icons\Heroicon;
@@ -46,9 +47,12 @@ class Journaux extends Page
             $this->data = $response['data'] ?? [];
             $this->metadata = $response['metadata'] ?? null;
             $this->errorMessage = $response['error'] ?? null;
-        } catch (\Throwable $e) {
+        } catch (LogisticsApiException $e) {
             $this->errorMessage = $e->getMessage();
             $this->data = [];
+        } catch (\Throwable $e) {
+            $this->errorMessage = "Erreur inattendue : {$e->getMessage()}";
+            $this->data = [];
         }
     }
 }

app/Filament/Pages/TablesExplorer.php

@@ -2,6 +2,7 @@
 
 namespace App\Filament\Pages;
 
+use App\Exceptions\LogisticsApiException;
 use App\Services\LogisticsService;
 use Filament\Pages\Page;
 use Filament\Support\Icons\Heroicon;
@@ -41,8 +42,10 @@ class TablesExplorer extends Page
 
             $this->tables = $response['data'] ?? [];
             $this->errorMessage = $response['error'] ?? null;
-        } catch (\Throwable $e) {
+        } catch (LogisticsApiException $e) {
             $this->errorMessage = $e->getMessage();
+        } catch (\Throwable $e) {
+            $this->errorMessage = "Erreur inattendue : {$e->getMessage()}";
         }
     }
 
@@ -60,8 +63,10 @@ class TablesExplorer extends Page
 
             $this->columns = $response['data'] ?? [];
             $this->errorMessage = $response['error'] ?? null;
-        } catch (\Throwable $e) {
+        } catch (LogisticsApiException $e) {
             $this->errorMessage = $e->getMessage();
+        } catch (\Throwable $e) {
+            $this->errorMessage = "Erreur inattendue : {$e->getMessage()}";
         }
     }
 }

app/Filament/Pages/Tiers.php

@@ -2,6 +2,7 @@
 
 namespace App\Filament\Pages;
 
+use App\Exceptions\LogisticsApiException;
 use App\Services\LogisticsService;
 use Filament\Pages\Page;
 use Filament\Support\Icons\Heroicon;
@@ -50,9 +51,12 @@ class Tiers extends Page
             $this->data = $response['data'] ?? [];
             $this->metadata = $response['metadata'] ?? null;
             $this->errorMessage = $response['error'] ?? null;
-        } catch (\Throwable $e) {
+        } catch (LogisticsApiException $e) {
             $this->errorMessage = $e->getMessage();
             $this->data = [];
+        } catch (\Throwable $e) {
+            $this->errorMessage = "Erreur inattendue : {$e->getMessage()}";
+            $this->data = [];
         }
     }
 
@@ -68,9 +72,12 @@ class Tiers extends Page
 
             $this->historyData = $response['data'] ?? [];
             $this->errorMessage = $response['error'] ?? null;
-        } catch (\Throwable $e) {
+        } catch (LogisticsApiException $e) {
             $this->errorMessage = $e->getMessage();
             $this->historyData = [];
+        } catch (\Throwable $e) {
+            $this->errorMessage = "Erreur inattendue : {$e->getMessage()}";
+            $this->historyData = [];
         }
     }
 }

app/Services/LogisticsService.php

@@ -2,6 +2,8 @@
 
 namespace App\Services;
 
+use App\Exceptions\LogisticsApiException;
+use Illuminate\Http\Client\ConnectionException;
 use Illuminate\Http\Client\Response;
 use Illuminate\Support\Facades\DB;
 use Illuminate\Support\Facades\Http;
@@ -14,11 +16,23 @@ class LogisticsService
 
     private string $folder;
 
+    private int $timeout;
+
+    private int $connectTimeout;
+
+    private int $retryTimes;
+
+    private int $retrySleepMs;
+
     public function __construct()
     {
         $this->baseUrl = rtrim(config('logistics.base_url'), '/');
         $this->apiKey = config('logistics.api_key');
         $this->folder = config('logistics.folder');
+        $this->timeout = config('logistics.timeout', 30);
+        $this->connectTimeout = config('logistics.connect_timeout', 10);
+        $this->retryTimes = config('logistics.retry.times', 3);
+        $this->retrySleepMs = config('logistics.retry.sleep_ms', 500);
     }
 
     public function tablesList(): array
@@ -141,31 +155,62 @@ class LogisticsService
 
     /**
      * @return array{data: mixed, metadata: array, error: mixed}
+     *
+     * @throws LogisticsApiException
      */
     private function post(string $endpoint, array $params = []): array
     {
         $url = "{$this->baseUrl}/{$this->folder}/{$endpoint}";
 
-        $response = Http::withHeaders([
-            'X-API-KEY' => $this->apiKey,
-        ])->post($url, $params);
+        try {
+            $response = Http::withHeaders([
+                'X-API-KEY' => $this->apiKey,
+            ])
+                ->timeout($this->timeout)
+                ->connectTimeout($this->connectTimeout)
+                ->retry($this->retryTimes, $this->retrySleepMs, fn (\Exception $e) => $e instanceof ConnectionException)
+                ->post($url, $params);
 
-        $this->logRequest($endpoint, $params, $response);
+            $this->logRequest($endpoint, $params, $response);
 
-        return $response->json() ?? [
-            'data' => null,
-            'metadata' => ['rowcount' => 0, 'issuccess' => false],
-            'error' => 'Empty response from API',
-        ];
+            return $response->json() ?? [
+                'data' => null,
+                'metadata' => ['rowcount' => 0, 'issuccess' => false],
+                'error' => 'Empty response from API',
+            ];
+        } catch (ConnectionException $e) {
+            $this->logFailedRequest($endpoint, $params, $e);
+
+            throw LogisticsApiException::connectionTimeout($endpoint, $params, $e);
+        } catch (\Throwable $e) {
+            $this->logFailedRequest($endpoint, $params, $e);
+
+            throw LogisticsApiException::requestFailed($endpoint, $params, $e);
+        }
     }
 
     private function logRequest(string $endpoint, array $params, Response $response): void
     {
+        $body = $response->body();
+        $isValidJson = json_decode($body) !== null || $body === 'null';
+
         DB::table('api_request_logs')->insert([
             'endpoint' => $endpoint,
             'parameters' => json_encode($params),
             'response_status' => $response->status(),
-            'response_data' => $response->body(),
+            'response_data' => $isValidJson ? $body : json_encode(['raw' => $body]),
+            'created_at' => now(),
+            'updated_at' => now(),
+        ]);
+    }
+
+    private function logFailedRequest(string $endpoint, array $params, \Throwable $exception): void
+    {
+        DB::table('api_request_logs')->insert([
+            'endpoint' => $endpoint,
+            'parameters' => json_encode($params),
+            'response_status' => 0,
+            'response_data' => json_encode(['error' => $exception->getMessage()]),
             'created_at' => now(),
             'updated_at' => now(),
         ]);