Marvin
714bdc3dd7
- Introduced new endpoints for creating and modifying articles (`art_add`, `art_mod`) and tiers (`third_add`, `third_mod`), allowing users to manage these entities effectively. - Updated the Articles and Tiers pages to include forms for adding and modifying records, complete with parameter tables for clear guidance on required inputs. - Enhanced the API documentation to include detailed descriptions, examples, and metadata for the new endpoints, improving usability and understanding for developers. - Created a new rule for writing conventions with French accents to ensure consistency across the project. - Updated existing documentation to reflect structural changes and added a summary table for CRUD operations. - Added tests to verify the functionality of the new features and ensure robust error handling.
9.4 KiB
Tech Context
Dernière mise à jour : 2026-02-23
Stack technique
| Composant | Version | Rôle |
|---|---|---|
| PHP | 8.4 | Langage serveur |
| Laravel | 12 | Framework applicatif |
| Filament | 5.0 | Panel admin / dashboard |
| Livewire | 4 | Composants réactifs |
| Flux UI Free | 2.9+ | Composants UI Livewire |
| Fortify | 1.30+ | Authentification (existant, non utilisé par Filament) |
| Pest | 4.4+ | Framework de tests |
| MySQL | - | Base de données |
| Vite | 7.3 | Bundler frontend |
| Tailwind CSS | 4 | Framework CSS (via @tailwindcss/vite) |
| @tailwindcss/typography | 0.5.19 | Plugin prose pour le rendu markdown |
| barryvdh/laravel-dompdf | - | Génération PDF |
Dépendances principales (composer.json)
filament/filament: ^5.0laravel/framework: ^12.0livewire/livewire: ^4.0livewire/flux: ^2.9.0laravel/fortify: ^1.30barryvdh/laravel-dompdf(export PDF de la documentation)
Frontend
- Tailwind CSS 4 avec le plugin Vite
@tailwindcss/vite - Plugin
@tailwindcss/typography(v0.5.19) pour le rendu prose du markdown - Thème Filament personnalisé :
resources/css/filament/admin/theme.css - Le thème Filament scanne les sources :
app/Filament/**/*,resources/views/filament/**/*,resources/views/components/logistics/**/* - Le thème inclut des styles CSS personnalisés pour la classe
.documentation-prose(titres, tableaux, blocs de code, liens, listes) optimisés pour le dark mode Filament - Build :
npm run build(recompileapp.cssettheme.css)
Configuration
Variables d'environnement spécifiques
LOGISTICS_API_BASE_URL=http://tse-10-test.esi.local
LOGISTICS_API_KEY=<clé API>
LOGISTICS_API_FOLDER=esigescom
LOGISTICS_API_TIMEOUT=300
LOGISTICS_API_CONNECT_TIMEOUT=10
LOGISTICS_API_RETRY_TIMES=3
LOGISTICS_API_RETRY_SLEEP_MS=500
Fichier de config : config/logistics.php
| Clé de config | Variable .env | Défaut | Description |
|---|---|---|---|
logistics.base_url |
LOGISTICS_API_BASE_URL |
- | URL de base de l'API |
logistics.api_key |
LOGISTICS_API_KEY |
- | Clé d'authentification |
logistics.folder |
LOGISTICS_API_FOLDER |
- | Dossier dans l'URL |
logistics.timeout |
LOGISTICS_API_TIMEOUT |
30 | Timeout total de la requête (secondes) |
logistics.connect_timeout |
LOGISTICS_API_CONNECT_TIMEOUT |
10 | Timeout de connexion (secondes) |
logistics.retry.times |
LOGISTICS_API_RETRY_TIMES |
3 | Nombre de tentatives en cas d'échec de connexion |
logistics.retry.sleep_ms |
LOGISTICS_API_RETRY_SLEEP_MS |
500 | Délai entre les tentatives (ms) |
Base de données
- Connexion : MySQL
- Base :
logistics - Configuration dans
.env:DB_CONNECTION=mysql
API Logistics
Connexion
- Serveur : TSE-10-TEST (réseau privé)
- Base URL :
http://tse-10-test.esi.local - Dossier :
esigescom(minuscules obligatoires) - Authentification : Header
X-API-KEY - Méthode : POST pour tous les endpoints
Structure de réponse
{
"data": "<résultat>",
"metadata": { "rowcount": 0, "issuccess": true },
"error": "<message d'erreur ou null>"
}
Réponse tables_list : chaque table a name et columnCount.
Réponse column_list : chaque colonne a name, dataType (C/N/T/D/L/M), length, precision. Les colonnes sont retournées en double par l'API (dédupliquées côté client).
Endpoints (23 méthodes dans LogisticsService)
| Endpoint | Méthode service | Type | Description | Paramètres principaux |
|---|---|---|---|---|
tables_list |
tablesList() |
Lecture | Liste des tables | - |
column_list/{table} |
columnList(string) |
Lecture | Colonnes d'une table | table (URL) |
art_list |
artList(array) |
Lecture | Liste d'articles (max 5 résultats, limite fixe serveur) | select, search, barcode (results sans effet) |
art_getstk |
artGetStock(string) |
Lecture | Stock d'un article | ARTID |
jnl_list |
jnlList(array) |
Lecture | Liste des journaux | select, results, TYPE |
document_list |
documentList(array) |
Lecture | Liste des documents | select, thirdid, results (fonctionne, défaut ~108) |
document_detail |
documentDetail(string, string) |
Lecture | Détail d'un document | jnl, number |
Document_GetStatusList |
documentGetStatusList(string) |
Lecture | Statuts d'un journal | jnl |
Document_GetUnitPriceAndVat |
documentGetUnitPriceAndVat(array) |
Lecture | Prix et TVA | ARTID, QTY, JNL, THIRDID, DATE |
Document_GetDueDate |
documentGetDueDate(string, string) |
Lecture | Échéance | paydelay, date |
Document_GetAttachListThumbnail |
documentGetAttachListThumbnail(string, string) |
Lecture | Miniatures annexes | JNL, NUMBER |
Document_GetPDF |
documentGetPdf(string, string, string) |
Lecture | Génération PDF | JNL, NUMBER, LAYOUT |
third_list |
thirdList(array) |
Lecture | Liste des tiers (max 10 résultats, limite fixe serveur) | select, search (results sans effet) |
third_GetArtHistory |
thirdGetArtHistory(string) |
Lecture | Historique articles tiers | thirdid (minuscules obligatoires) |
getserialnumber |
getSerialNumber() |
Lecture | Numéro de série | - |
codes_list |
codesList(array) |
Lecture | Données par code | code |
document_add |
documentAdd(array) |
Écriture | Ajout d'un document | ThirdId, Date, Artid[], Qty[], Saleprice[], JNL, ... |
document_mod |
documentMod(array) |
Écriture | Modification d'un document | number, Thirdid, Artid[], Qty[], Saleprice[], JNL, ... |
art_add |
artAdd(array) |
Écriture | Création d'un article | ARTID (obligatoire), NAME1, SALEPRICE, ... |
art_mod |
artMod(array) |
Écriture | Modification d'un article | ARTID (obligatoire, existant), NAME1, SALEPRICE, ... |
third_add |
thirdAdd(array) |
Écriture | Création d'un tiers | NAME, VAT, EMAIL (aucun obligatoire, ID auto-généré) |
third_mod |
thirdMod(array) |
Écriture | Modification d'un tiers | CUSTID (obligatoire, existant), NAME, VAT, EMAIL, ... |
custom_geninv_updatestock |
customGeninvUpdatestock(array) |
Écriture | Mise à jour stock (Restock/Inventaire) | ARTID, STKID, QTY, TOCHECK, TOCHECKDETAIL, MODE, THIRDID |
Endpoints inexistants (HTTP 404) : art_del, third_del, jnl_add, jnl_mod, jnl_del, document_del. Aucune opération de suppression n'est disponible via l'API.
Endpoints partiellement fonctionnels : Document_GetPDF (LAYOUT doit être une valeur numérique en string, ex: "1". Les valeurs textuelles provoquent une erreur. Retourne le PDF en base64). custom_geninv_updatestock MODE=0 (Inventaire) dépend de la configuration des journaux KI du dossier.
art_add / art_mod : Paramètres en MAJUSCULES (ARTID, NAME1, SALEPRICE). art_add requiert un ARTID unique (erreur si doublon). art_mod requiert un ARTID existant. Autres colonnes de la table art acceptées.
third_add / third_mod : third_add est très permissif (aucun paramètre obligatoire, ID auto-généré _@NNNNNNNN). third_mod requiert CUSTID existant (MAJUSCULES). Paramètres : NAME, VAT, EMAIL et autres colonnes cust.
custom_geninv_updatestock (fonctionnel en MODE=1 Restock) : STKID = code de dépôt (obtenu via codes_list STOCK, ex: "SG", "A"). MODE=1 (Restock) nécessite THIRDID (fournisseur). TOCHECK = prix de contrôle. TOCHECKDETAIL = remarques. QTY peut être négatif. Les 6 paramètres ARTID, STKID, QTY, TOCHECK, TOCHECKDETAIL, MODE sont tous obligatoires.
codes_list (correspondance exacte) : le paramètre code fonctionne par correspondance exacte (pas par préfixe), sensible à la casse (MAJUSCULES). Chaîne vide = liste maître des 42 groupes (structure name/prompt1). Nom exact = valeurs du groupe (structure vala1-vala6, valn1, valn2).
Format de date : Tous les endpoints acceptant une date (DATE, date) exigent le format YYYY-MM-DD. Tout autre format retourne HTTP 400.
Codes de délai de paiement : Les valeurs valides pour paydelay (Document_GetDueDate) proviennent de codes_list avec code=PAYDELAY. Codes courants : 30, 30F, 45F, 50, 60, 60F, 75F, 90, 90F, 0F. Le suffixe F = fin de mois.
Particularités third_list :
- Recherche dans
name,groupid,vat(pas danscustid). - Colonnes valides pour
select:custid,name,name2,vat,email,groupid,website,memo,paydelay,paymode,bankname,iban,bic,custtype,discount. - La colonne
custnamen'existe PAS. Le nom est dansname. - Colonnes par défaut (sans select) :
custid,name.
Particularités third_GetArtHistory :
- Paramètre
thirdiden minuscules obligatoire (THIRDID= erreur). - Retourne l'intégralité de l'historique sans limite (potentiellement des milliers d'éléments).
- Structure :
artid,artname,jnl,unitprice,qty,vatid,vatpc,s_credate. - ID inexistant = tableau vide sans erreur.
Tables accessibles
art (160 col.), attach (13), barcode (12), category (10), codes (50), cust (216), docdet (82), dochead (212), docpay (22), file (17), hist (50), incodes (24), jnl (155), pers (78), price (28), stk (20)
Types de colonnes (dataType)
| Code | Label | Couleur badge |
|---|---|---|
| C | Caractère | Bleu |
| N | Numérique | Vert (emerald) |
| T | Date/Heure | Violet |
| D | Date | Violet |
| L | Logique | Ambre |
| M | Mémo | Gris |