logisticsAPI/memory-bank/systemPatterns.md

System Patterns

Dernière mise à 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)
                    |     (succès ET échecs)
                    |
                    +---> LogisticsApiException (en cas d'erreur)

Patterns utilisés

Service centralisé

App\Services\LogisticsService encapsule tous les appels HTTP vers l'API Logistics. Chaque méthode publique correspond à un endpoint. Le service :

• Construit l'URL à 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 délai configurables) uniquement sur les ConnectionException.
• Enregistre chaque requête dans la table api_request_logs (succès et échecs).
• Retourne un tableau PHP avec les clés data, metadata, error.
• Lance une LogisticsApiException en cas d'erreur de connexion ou de requête.

Exception dédiée

App\Exceptions\LogisticsApiException (étend RuntimeException) fournit :

• Des messages d'erreur en français lisibles par l'utilisateur.
• Des propriétés endpoint et params pour le contexte de l'erreur.
• Deux méthodes statiques : connectionTimeout() (API injoignable) et requestFailed() (erreur de requête).

Pages Filament personnalisées (pas de Resources)

L'application n'utilise pas de Resources Filament (pas de CRUD local). Chaque page Filament :

• Étend Filament\Pages\Page.
• Utilise des propriétés Livewire publiques pour les champs de formulaire.
• Appelle LogisticsService via app(LogisticsService::class) dans des méthodes d'action (ex: searchArticles()).
• Attrape LogisticsApiException en premier, puis \Throwable en fallback.
• Affiche les résultats via les composants du système de design x-logistics.*.

Page Documentation

App\Filament\Pages\Documentation est une page spéciale qui :

• Lit le fichier documentation/documentation_api_logistics.md au montage.
• Convertit le markdown en HTML via Str::markdown().
• Affiche le contenu dans une vue avec la classe CSS .documentation-prose pour un rendu stylisé.
• Propose deux actions d'en-tête : télécharger en PDF (via barryvdh/laravel-dompdf) et ouvrir dans un nouvel onglet.

Système de design (composants Blade)

Convention documentée dans .cursor/rules/design-system.mdc. Tous les composants visuels réutilisables sont dans resources/views/components/logistics/ :

Composant	Rôle
<x-logistics.card>	Conteneur blanc arrondi avec ombre et anneau
<x-logistics.section-header>	En-tête de section (titre, description, slot actions)
<x-logistics.error-banner>	Bandeau d'erreur API conditionnel
<x-logistics.stat-bar>	Barre horizontale de métadonnées
<x-logistics.stat-item>	Élément individuel (icône + label + valeur)
<x-logistics.data-table>	Tableau dynamique avec en-têtes auto-détectés et état vide
<x-logistics.empty-state>	État vide centré (icône + titre + description)
<x-logistics.search-input>	Champ de recherche avec icône loupe intégrée
<x-logistics.form-field>	Champ de formulaire (label + input) à espacement homogène
<x-logistics.json-block>	Bloc JSON formaté avec bordure et fond adapté

Règles :

• Toujours utiliser les composants x-logistics.* au lieu de dupliquer les classes CSS.
• Un <x-logistics.card> n'a pas de padding interne. Le padding est géré par les enfants (<div class="p-6">).
• Le <x-logistics.section-header> est le premier enfant d'une carte et crée une bordure de séparation.
• Toutes les actions réseau doivent avoir un indicateur de chargement (wire:loading).

Thème Filament personnalisé

Le panel Filament utilise un thème CSS personnalisé (resources/css/filament/admin/theme.css) enregistré via ->viteTheme() dans AdminPanelProvider. Ce thème :

• Importe le CSS de base Filament.
• Active le plugin @tailwindcss/typography pour les classes prose.
• Scanne les fichiers app/Filament/**/*, resources/views/filament/**/*, et resources/views/components/logistics/**/* pour inclure les classes Tailwind utilisées dans les composants.
• Contient des styles CSS personnalisés pour la classe .documentation-prose : hiérarchie de titres (h1-h4 avec bordures), tableaux avec bordures et en-têtes stylisés, blocs de code avec fond sombre, code inline avec fond distinct, liens colorés, listes avec marqueurs, séparateurs horizontaux visibles.

Après tout ajout de nouvelles classes Tailwind dans ces fichiers, il faut exécuter npm run build.

Configuration externalisée

Les paramètres de connexion à l'API (URL, clé, dossier, timeout, retry) sont dans config/logistics.php et lus depuis .env.

Structure des répertoires

app/
  Exceptions/
    LogisticsApiException.php  # Exception dédiée API
  Filament/
    Pages/
      Articles.php             # Recherche articles + stock
      Dashboard.php            # Page d'accueil
      Documentation.php        # Documentation API (markdown -> HTML)
      Documents.php            # Recherche documents + détail
      Journaux.php             # Recherche journaux
      TablesExplorer.php       # Exploration tables + colonnes (filtre, déduplication, types)
      Tiers.php                # Recherche tiers + historique
  Models/
    User.php                   # Modèle utilisateur (Fortify)
  Providers/
    Filament/
      AdminPanelProvider.php   # Configuration du panel (sans auth, viteTheme)
    FortifyServiceProvider.php # Authentification Fortify
    AppServiceProvider.php     # Config globale (CarbonImmutable, DB safety)
  Services/
    LogisticsService.php       # Service centralisé API Logistics

config/
  logistics.php                # Configuration API Logistics (URL, clé, timeout, retry)

documentation/
  documentation_api_logistics.md  # Documentation complète de l'API (avec accents)

resources/
  css/
    app.css                    # CSS principal (Tailwind 4, Flux UI)
    filament/admin/
      theme.css                # Thème Filament personnalisé (Tailwind 4 + Typography + prose)
  views/
    components/logistics/      # 10 composants du système de design
    filament/pages/            # 6 vues de pages Filament
    pdf/
      documentation.blade.php  # Template PDF pour la documentation

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

tests/Feature/
  DocumentationTest.php        # 5 tests page Documentation (Livewire + PDF)
  LogisticsServiceTest.php     # 12 tests service API (mocks HTTP)
  TablesExplorerTest.php       # 6 tests page TablesExplorer (Livewire)
  FilamentDashboardTest.php    # Tests dashboard Filament
  DashboardTest.php            # Tests dashboard
  ExampleTest.php              # Test d'exemple Laravel

routes/
  web.php                      # Routes web (home, dashboard, documentation PDF)

.cursor/rules/
  design-system.mdc            # Convention de design (composants, CSS, structure)
  memory-bank.mdc              # Gestion du memory bank
  update-documentation.mdc     # Procédure de mise à jour de la documentation
  laravel-boost.mdc            # Règles Laravel Boost

Conventions

• Filament v5 : les icônes de navigation utilisent l'enum Filament\Support\Icons\Heroicon (pas de strings).
• Filament v5 : la propriété $view est non-static (protected string $view).
• Les propriétés 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 affichés à l'utilisateur sont en français.
• Toutes les vues Filament utilisent les composants x-logistics.* du système de design.
• Après modification des vues ou composants, exécuter npm run build pour recompiler le thème.
• Tous les contenus rédigés en français doivent utiliser les accents appropriés.