# System Patterns Dernière mise à jour : 2026-02-21 ## Architecture applicative ``` Utilisateur --> Filament Dashboard (/admin) | v Pages Filament (Livewire) | +---> Toggle Lecture / Ecriture (propriété $mode) | 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 (19 méthodes). 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. - Possède une propriété `$mode` (string : `'read'` ou `'write'`) pour le toggle Lecture/Ecriture (sauf Dashboard, Documentation, TablesExplorer). - Appelle `LogisticsService` via `app(LogisticsService::class)` dans des méthodes d'action. - Attrape `LogisticsApiException` en premier, puis `\Throwable` en fallback. - Affiche les résultats via les composants du système de design `x-logistics.*`. ### Toggle Lecture / Ecriture Les pages entité (Articles, Documents, Journaux, Tiers, Divers) intègrent un toggle permettant de basculer entre : - **Lecture** (`$mode = 'read'`) : formulaires pour les endpoints de récupération de données. - **Ecriture** (`$mode = 'write'`) : formulaires pour les endpoints d'envoi de données. Le toggle est implémenté avec deux boutons et un `wire:click="$set('mode', 'read')"` / `wire:click="$set('mode', 'write')"`. Le rendu conditionnel utilise `@if ($mode === 'read')` / `@else`. Les pages sans endpoint d'écriture affichent un état vide (``) en mode écriture. ### Conversion CSV vers tableaux (splitCsv) La page Documents utilise une méthode privée `splitCsv(string $value): array` qui convertit les champs de formulaire (texte séparé par virgules) en tableaux PHP pour les paramètres d'API qui attendent des arrays (Artid, Qty, Saleprice, Discount, Vatid, Vatpc). Exemple : `"ART001,ART002"` devient `["ART001", "ART002"]`. ### Endpoints non fonctionnels Certains endpoints (Document_GetPDF, custom_geninv_updatestock) sont présents dans l'interface avec un bandeau d'avertissement ambre expliquant pourquoi ils ne fonctionnent pas. Les méthodes service existent dans LogisticsService pour permettre le test. ### 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 + padding gauche) à 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`. 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 (toggle lecture/écriture) Dashboard.php # Page d'accueil Divers.php # Endpoints divers : getserialnumber, codes_list, custom_geninv_updatestock (toggle) Documentation.php # Documentation API (markdown -> HTML) Documents.php # 9 endpoints documents (toggle lecture/écriture, splitCsv) Journaux.php # Recherche journaux (toggle lecture/écriture) TablesExplorer.php # Exploration tables + colonnes (filtre, déduplication, types) Tiers.php # Recherche tiers + historique (toggle lecture/écriture) 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 (19 méthodes) config/ logistics.php # Configuration API Logistics (URL, clé, timeout, retry) documentation/ documentation_api_logistics.md # Documentation complète de l'API (avec accents) WEB-A-1 (3).md # Documentation originale du fournisseur 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/ # 7 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) DocumentsPageTest.php # 13 tests page Documents (toggle, 9 endpoints, erreurs) DiversPageTest.php # 8 tests page Divers (toggle, 3 endpoints, erreurs) LogisticsServiceTest.php # 14 tests service API (mocks HTTP) TablesExplorerTest.php # 6 tests page TablesExplorer (Livewire) FilamentDashboardTest.php # Tests dashboard Filament (1 test en échec pré-existant) 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. - Les endpoints non fonctionnels sont présents dans l'interface avec un bandeau d'avertissement.