# 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.