mpa/logisticsAPI
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7df94b64faf9a1c0669169f99db9cb605345a9b2
logisticsAPI/memory-bank/systemPatterns.md
Marvin 7df94b64fa Implement toggle for read/write mode across entity pages and enhance Documents and Divers functionality 
- Added a toggle for switching between read and write modes on the Articles, Documents, Journaux, Tiers, and Divers pages, allowing users to access both data retrieval and data submission endpoints.
- Updated the Documents page to cover all 9 documented endpoints, including 7 for reading and 2 for writing, with appropriate error handling.
- Created a new Divers page to handle three endpoints: getserialnumber, codes_list, and custom_geninv_updatestock (the latter being non-functional).
- Introduced new methods in LogisticsService for handling PDF generation and stock updates, with corresponding updates in the API documentation.
- Improved form field components for better visual spacing in input fields.
2026-02-20 15:51:58 +01:00

10 KiB
Raw Blame History

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 (<x-logistics.empty-state>) 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
<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 + padding gauche) à 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.

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.