# 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 | |-----------|------| | `` | Conteneur blanc arrondi avec ombre et anneau | | `` | En-tête de section (titre, description, slot `actions`) | | `` | Bandeau d'erreur API conditionnel | | `` | Barre horizontale de métadonnées | | `` | Élément individuel (icône + label + valeur) | | `` | Tableau dynamique avec en-têtes auto-détectés et état vide | | `` | État vide centré (icône + titre + description) | | `` | Champ de recherche avec icône loupe intégrée | | `` | Champ de formulaire (label + input) à espacement homogène | | `` | Bloc JSON formaté avec bordure et fond adapté | Règles : - Toujours utiliser les composants `x-logistics.*` au lieu de dupliquer les classes CSS. - Un `` n'a pas de padding interne. Le padding est géré par les enfants (`
`). - Le `` 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.