mpa/logisticsAPI
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
dfe20e79d720a852092ca56835508bc25cf4843e
logisticsAPI/memory-bank/systemPatterns.md
Marvin dfe20e79d7 Enhance Documents page functionality and update API documentation 
- Added a new `$results` property to the Documents page to allow users to specify the maximum number of results returned by the `document_list` endpoint, defaulting to ~108.
- Updated the `searchDocuments` method to include the `results` parameter in API requests, ensuring it is sent as a string.
- Modified the documents.blade.php view to include an input field for the `results` parameter, with appropriate placeholder text and guidance.
- Improved the documentation for the `document_list` endpoint to clarify the behavior of the `results` parameter and its interaction with `thirdid`.
- Updated the `Document_GetPDF` section to reflect its functionality and correct usage of the `LAYOUT` parameter.
- Added a new test to verify that the `results` parameter is correctly sent to the API.
- Overall, enhanced the user experience and API interaction for document management.
2026-02-23 11:24:57 +01:00

236 lines
13 KiB
Markdown
Raw Blame History

# System Patterns
Dernière mise à jour : 2026-02-23
## 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"]`.
### Traduction et normalisation des erreurs API
`App\Support\ApiErrorTranslator` centralise le traitement des erreurs retournées par l'API :
- **Normalisation** : Le champ `error` de l'API peut être `null`, une chaîne ou un tableau de chaînes. La méthode `normalize()` convertit tout en chaîne lisible.
- **Traduction** : La méthode `translate()` ajoute une explication en français aux messages d'erreur connus (ex: "Search terms are required" -> "Le champ de recherche est obligatoire.").
- **Format de sortie** : Quand une explication est trouvée, le message est formaté sur plusieurs lignes : `{message original}\n\nExplication : {explication}`.
### Validation et tracking des appels API
Chaque page Filament implémente :
- **Validation** : Les champs obligatoires sont vérifiés avant chaque appel API. Si un champ requis est vide, un message d'erreur en français est affiché via `$this->errorMessage` et la méthode retourne sans appeler l'API. Les règles de validation sont basées sur la documentation fournisseur (`documentation/WEB-A-1 (3).md`).
- **Tracking** : Des propriétés booléennes publiques (`$hasSearched`, `$hasCheckedStock`, etc.) sont mises à `true` après chaque appel API (succès ou erreur). Cela permet de distinguer "jamais recherché" de "recherché sans résultat" dans les vues Blade.
- **État vide** : Le composant `json-block` accepte une prop `$searched`. Quand `$searched` est `true` et `$data` est vide, un état vide est affiché. Pour les `data-table`, les vues vérifient `$hasSearched && count($data) === 0`.
- **Badge de comptage** : Les badges de résultats utilisent `count($data)` (comptage réel PHP) au lieu de `$metadata['rowcount']` (retourné par l'API, parfois incorrect).
### Endpoints partiellement fonctionnels
L'endpoint `Document_GetPDF` est fonctionnel : le paramètre `LAYOUT` doit être une valeur numérique sous forme de string (ex: `"1"`). Les valeurs textuelles provoquent une erreur. Le PDF est retourné encodé en base64 dans le champ `data.pdf`.
### Endpoints non fonctionnels
L'endpoint `custom_geninv_updatestock` est présent dans l'interface avec un bandeau d'avertissement ambre expliquant pourquoi il ne fonctionne pas. La méthode service existe 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)
Support/
ApiErrorTranslator.php # Normalisation et traduction des erreurs API
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/
ArticlesPageTest.php # 8 tests page Articles (toggle, validation, tracking, erreurs)
DocumentationTest.php # 5 tests page Documentation (Livewire + PDF)
DocumentsPageTest.php # 22 tests page Documents (toggle, 9 endpoints, validation, erreurs, results)
DiversPageTest.php # 8 tests page Divers (toggle, 3 endpoints, validation, erreurs)
JournauxPageTest.php # 6 tests page Journaux (toggle, validation, tracking, erreurs)
LogisticsServiceTest.php # 14 tests service API (mocks HTTP)
TablesExplorerTest.php # 6 tests page TablesExplorer (Livewire)
TiersPageTest.php # 8 tests page Tiers (toggle, validation, tracking, erreurs)
FilamentDashboardTest.php # Tests dashboard Filament (1 test en échec pré-existant)
DashboardTest.php # Tests dashboard
ExampleTest.php # Test d'exemple Laravel
tests/Unit/
ApiErrorTranslatorTest.php # 9 tests normalisation et traduction des erreurs API
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.
- L'endpoint non fonctionnel (custom_geninv_updatestock) est présent dans l'interface avec un bandeau d'avertissement.
Reference in New Issue View Git Blame Copy Permalink