logisticsAPI/memory-bank/techContext.md

# 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.0`
- `laravel/framework: ^12.0`
- `livewire/livewire: ^4.0`
- `livewire/flux: ^2.9.0`
- `laravel/fortify: ^1.30`
- `barryvdh/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` (recompile `app.css` et `theme.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

```json
{
    "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 (19 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, ... |
| `custom_geninv_updatestock` | `customGeninvUpdatestock(array)` | Écriture | Mise à jour stock (Restock/Inventaire) | ARTID, STKID, QTY, TOCHECK, TOCHECKDETAIL, MODE, THIRDID |

**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.

**`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 dans `custid`).
- Colonnes valides pour `select` : `custid`, `name`, `name2`, `vat`, `email`, `groupid`, `website`, `memo`, `paydelay`, `paymode`, `bankname`, `iban`, `bic`, `custtype`, `discount`.
- La colonne `custname` n'existe PAS. Le nom est dans `name`.
- Colonnes par défaut (sans select) : `custid`, `name`.

**Particularités `third_GetArtHistory`** :
- Paramètre `thirdid` en 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 |