Marvin
4aef33f270
- 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.
115 lines
4.3 KiB
Markdown
115 lines
4.3 KiB
Markdown
# System Patterns
|
|
|
|
Derniere mise a jour : 2026-02-20
|
|
|
|
## Architecture applicative
|
|
|
|
```
|
|
Utilisateur --> Filament Dashboard (/admin)
|
|
|
|
|
v
|
|
Pages Filament (Livewire)
|
|
|
|
|
v
|
|
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
|
|
|
|
### Service centralise
|
|
|
|
`App\Services\LogisticsService` encapsule tous les appels HTTP vers l'API Logistics. Chaque methode publique correspond a un endpoint. Le service :
|
|
|
|
- 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`.
|
|
- 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)
|
|
|
|
L'application n'utilise pas de Resources Filament (pas de CRUD local). Chaque page Filament :
|
|
|
|
- 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 (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
|
|
Models/
|
|
User.php # Modele utilisateur (Fortify)
|
|
Providers/
|
|
Filament/
|
|
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
|
|
|
|
config/
|
|
logistics.php # Configuration API Logistics (URL, cle, timeout, retry)
|
|
|
|
database/
|
|
migrations/
|
|
...create_users_table.php
|
|
...create_cache_table.php
|
|
...create_jobs_table.php
|
|
...add_two_factor_columns_to_users_table.php
|
|
...create_api_request_logs_table.php
|
|
|
|
resources/views/
|
|
filament/pages/
|
|
articles.blade.php
|
|
documents.blade.php
|
|
journaux.blade.php
|
|
tables-explorer.blade.php
|
|
tiers.blade.php
|
|
|
|
tests/Feature/
|
|
LogisticsServiceTest.php # 12 tests avec mocks HTTP
|
|
```
|
|
|
|
## Conventions
|
|
|
|
- Filament v5 : les icones de navigation utilisent l'enum `Filament\Support\Icons\Heroicon` (pas de strings).
|
|
- 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.
|