Marvin
657c5ad5e3
- Added `barryvdh/laravel-dompdf` to `composer.json` for PDF generation capabilities. - Updated `boost.json` to include `tailwindcss-development` in skills. - Modified `package.json` and `package-lock.json` to upgrade Tailwind CSS and related packages. - Improved README.md for clarity and corrected French language errors. - Created design system documentation for Filament components. - Added new Filament pages for Dashboard and Documentation with dynamic content loading. - Enhanced TablesExplorer functionality with improved table and column management.
183 lines
8.6 KiB
Markdown
183 lines
8.6 KiB
Markdown
# 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.
|