mpa/logisticsAPI
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Enhance documentation and improve API configuration

Browse Source 
- Added VPN connection requirement to README.md for local access to the Logistics API.
- Updated documentation_api_logistics.md to clarify usage environments and provide detailed connection instructions.
- Modified update-documentation.mdc to include guidelines on handling sensitive information in examples.
- Implemented automatic heading ID generation in Documentation.php for better navigation in the documentation.
- Updated logistics.php configuration to include default values for base URL, API key, and folder.
- Added support contact information in the dashboard view for API-related issues.
This commit is contained in:
Marvin
2026-02-20 14:56:38 +01:00
parent 657c5ad5e3
commit 4b2f172e2a
7 changed files with 155 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
.cursor/rules/update-documentation.mdc
View File

@@ -62,8 +62,9 @@ Derniere mise a jour : <date du jour>
## Regles
- Ne jamais supprimer d'information existante sans raison (endpoint supprime du service).
- Ne jamais divulguer ou ecrire des informations sensibles (cles d'API, mots de passe, identifiants de connexion, tokens, secrets ou toute autre donnee confidentielle). Utiliser des valeurs fictives ou des placeholders (ex. `votre-cle-api`, `********`, `{API_KEY}`) dans les exemples.
- Ton factuel et concis, sans emojis.
- Toujours inclure les chemins de fichiers exacts dans les references.
- Les exemples de requete doivent utiliser des valeurs realistes.
- Les exemples de requete doivent utiliser des valeurs realistes mais ne contenant aucune donnee sensible.
- La table des matieres doit refleter les sections du document.
- Les endpoints non fonctionnels restent documentes avec le statut "Non fonctionnel" et la description du probleme.

1
README.md
View File

@@ -8,6 +8,7 @@ Application Laravel 12 de test pour comprendre et documenter l'API Logistics (Fl
- Composer
- Node.js et npm
- MySQL
- Connexion VPN vers ESI Cloud (obligatoire pour communiquer avec le serveur Logistics depuis un poste local)
## Installation

24
app/Filament/Pages/Documentation.php
View File

@@ -25,7 +25,29 @@ class Documentation extends Page
{
$markdownPath = base_path('documentation/documentation_api_logistics.md');
$markdown = file_get_contents($markdownPath);
$this->htmlContent = Str::markdown($markdown);
$html = (string) Str::markdown($markdown);
$this->htmlContent = preg_replace_callback(
'/<(h[1-6])>(.*?)<\/\1>/i',
function (array $matches): string {
$tag = $matches[1];
$content = $matches[2];
$slug = self::slugify(strip_tags($content));
return "<{$tag} id=\"{$slug}\">{$content}</{$tag}>";
},
$html,
) ?? $html;
}
private static function slugify(string $text): string
{
$slug = mb_strtolower($text, 'UTF-8');
$slug = preg_replace('/[.\s]+/', '-', $slug);
$slug = preg_replace('/[^\w\x{00C0}-\x{024F}-]/u', '', $slug);
$slug = preg_replace('/-+/', '-', $slug);
return trim($slug, '-');
}
public function getHeaderActions(): array

6
config/logistics.php
View File

@@ -2,11 +2,11 @@
return [
'base_url' => env('LOGISTICS_API_BASE_URL'),
'base_url' => env('LOGISTICS_API_BASE_URL', 'http://tse-10-test.esi.local'),
'api_key' => env('LOGISTICS_API_KEY'),
'api_key' => env('LOGISTICS_API_KEY', 'YOUR_API_KEY'),
'folder' => env('LOGISTICS_API_FOLDER'),
'folder' => env('LOGISTICS_API_FOLDER', 'esigescom'),
'timeout' => (int) env('LOGISTICS_API_TIMEOUT', 30),

115
documentation/documentation_api_logistics.md
View File

@@ -7,20 +7,25 @@ Dernière mise à jour : 2026-02-20
## Table des matières
1. [Pré-requis](#1-pré-requis)
2. [Comment effectuer des requêtes](#2-comment-effectuer-des-requêtes)
3. [Structure de réponse](#3-structure-de-réponse)
4. [Tables et colonnes disponibles](#4-tables-et-colonnes-disponibles)
5. [Récupération de données](#5-récupération-de-données)
6. [Envoi de données](#6-envoi-de-données)
7. [Endpoints non fonctionnels](#7-endpoints-non-fonctionnels)
8. [Relations entre entités](#8-relations-entre-entités)
9. [Remarques et points d'attention](#9-remarques-et-points-dattention)
10. [Ressources externes](#10-ressources-externes)
2. [Environnements d'utilisation](#2-environnements-dutilisation)
3. [Comment effectuer des requêtes](#3-comment-effectuer-des-requêtes)
4. [Structure de réponse](#4-structure-de-réponse)
5. [Tables et colonnes disponibles](#5-tables-et-colonnes-disponibles)
6. [Récupération de données](#6-récupération-de-données)
7. [Envoi de données](#7-envoi-de-données)
8. [Endpoints non fonctionnels](#8-endpoints-non-fonctionnels)
9. [Relations entre entités](#9-relations-entre-entités)
10. [Remarques et points d'attention](#10-remarques-et-points-dattention)
11. [Ressources externes](#11-ressources-externes)
---
## 1. Pré-requis
### Connexion VPN
L'API Logistics est hébergée sur l'infrastructure ESI Cloud. Pour y accéder depuis un poste de travail local (hors du réseau ESI), une connexion VPN vers ESI Cloud est obligatoire. Sans cette connexion VPN, le serveur n'est pas joignable. Contactez votre administrateur réseau pour obtenir les identifiants et la configuration du VPN.
### Accès au serveur
L'API Logistics est hébergée sur un serveur privé. Les informations de connexion sont les suivantes :
@@ -32,7 +37,7 @@ L'API Logistics est hébergée sur un serveur privé. Les informations de connex
| Port HTTP | 5186 |
| Port HTTPS | 7126 |
L'accès au serveur nécessite soit une connexion au réseau privé, soit l'utilisation de l'hôte public avec le port adéquat.
L'accès au serveur nécessite soit une connexion au réseau privé (via VPN), soit l'utilisation de l'hôte public avec le port adéquat.
### Clé API
@@ -49,7 +54,7 @@ L'application Laravel utilise les variables d'environnement suivantes pour se co
| Variable | Description | Exemple |
|----------|-------------|---------|
| `LOGISTICS_API_BASE_URL` | URL de base du serveur API | `http://tse-10-test.esi.local` |
| `LOGISTICS_API_KEY` | Clé d'authentification API | `ztpyQX1ajtzb10ypdPs3C8N2w3XY1A` |
| `LOGISTICS_API_KEY` | Clé d'authentification API | `YOUR_API_KEY` |
| `LOGISTICS_API_FOLDER` | Nom du dossier comptable (minuscules) | `esigescom` |
| `LOGISTICS_API_TIMEOUT` | Timeout total de la requête en secondes | `300` |
| `LOGISTICS_API_CONNECT_TIMEOUT` | Timeout de connexion en secondes | `10` |
@@ -74,7 +79,59 @@ Le service `App\Services\LogisticsService` utilise ces valeurs pour configurer a
---
## 2. Comment effectuer des requêtes
## 2. Environnements d'utilisation
L'API Logistics peut etre interrogee depuis deux environnements distincts. Selon l'environnement utilise, les parametres de connexion (URL de base, hote, ports) different.
### 2.1 Projet local avec VPN
Dans ce scenario, le developpeur travaille sur son poste local (par exemple avec Laravel Herd) et communique avec le serveur Logistics a distance via le VPN ESI Cloud.
| Element | Valeur |
|---------|--------|
| Connexion VPN | Obligatoire (VPN vers ESI Cloud) |
| Hote | `tse-10-test.esiweb.pro` (public) ou `tse-10-test.esi.local` (reseau prive via VPN) |
| Port HTTP | 5186 |
| Port HTTPS | 7126 |
| URL de base typique | `http://tse-10-test.esi.local:5186` ou `http://tse-10-test.esiweb.pro:5186` |
Exemple de configuration `.env` pour un projet local :
```
LOGISTICS_API_BASE_URL=http://tse-10-test.esi.local:5186
LOGISTICS_API_KEY=votre-cle-api
LOGISTICS_API_FOLDER=esigescom
```
Le port doit etre inclus dans l'URL de base car le serveur n'ecoute pas sur les ports standard (80/443).
### 2.2 Bureau a distance (Postman)
Dans ce scenario, l'utilisateur se connecte au serveur via une connexion de bureau a distance (Remote Desktop) et utilise Postman directement depuis cette session. Etant deja sur le reseau interne, aucun VPN n'est necessaire et le serveur est accessible directement.
| Element | Valeur |
|---------|--------|
| Connexion VPN | Non requise (connexion directe via bureau a distance) |
| Hote | `tse-10-test.esi.local` ou `localhost` (si Postman tourne sur le serveur lui-meme) |
| Port HTTP | 5186 |
| Port HTTPS | 7126 |
| URL de base typique | `http://tse-10-test.esi.local:5186` ou `http://localhost:5186` |
Pour obtenir un acces au bureau a distance et a l'application Logistics, contactez **Claudi Dewandre**.
### 2.3 Recapitulatif des differences
| Critere | Projet local (VPN) | Bureau a distance (Postman) |
|---------|--------------------|-----------------------------|
| VPN ESI Cloud | Obligatoire | Non requis |
| Outil | Application Laravel, cURL, Postman local | Postman sur le serveur distant |
| Hote | `tse-10-test.esiweb.pro` ou `tse-10-test.esi.local` | `tse-10-test.esi.local` ou `localhost` |
| Port dans l'URL | Oui (5186 ou 7126) | Oui (5186 ou 7126) |
| Acces requis | Identifiants VPN + cle API | Acces bureau a distance + acces Logistics (contacter Claudi Dewandre) + cle API |
---
## 3. Comment effectuer des requêtes
### Méthode HTTP
@@ -138,7 +195,7 @@ Le service `LogisticsService` de l'application gère automatiquement :
---
## 3. Structure de réponse
## 4. Structure de réponse
### Format standard
@@ -205,7 +262,7 @@ Certains endpoints retournent des clés supplémentaires dans `metadata` :
---
## 4. Tables et colonnes disponibles
## 5. Tables et colonnes disponibles
### Liste des tables
@@ -245,17 +302,17 @@ Chaque colonne d'une table possède un type de données identifié par un code
### Exploration des colonnes
Pour connaître les colonnes disponibles dans une table, utiliser les endpoints `tables_list` et `column_list/{tablename}` décrits dans la section 5.
Pour connaître les colonnes disponibles dans une table, utiliser les endpoints `tables_list` et `column_list/{tablename}` décrits dans la section 6.
**Remarque importante** : l'API retourne les colonnes en double dans la réponse de `column_list`. L'application effectue une déduplication automatique côté client.
---
## 5. Récupération de données
## 6. Récupération de données
Tous les endpoints de cette section servent à lire des données depuis l'API. Ils utilisent la méthode POST et retournent des données dans la clé `data` de la réponse.
### 5.1 Structure de la base de données
### 6.1 Structure de la base de données
#### `tables_list` -- Liste des tables
@@ -342,7 +399,7 @@ POST /esigescom/column_list/stk
---
### 5.2 Articles
### 6.2 Articles
Les articles sont les références produits du catalogue. Ils sont stockés dans la table `art`.
@@ -401,7 +458,7 @@ Retourne les informations de stock pour un article donné. Permet de vérifier l
---
### 5.3 Journaux
### 6.3 Journaux
Les journaux regroupent les documents commerciaux par type (ventes, achats, retours, etc.). Ils sont stockés dans la table `jnl`.
@@ -434,7 +491,7 @@ Retourne la liste des journaux correspondant au type demandé. Un journal contie
---
### 5.4 Documents
### 6.4 Documents
Les documents commerciaux (devis, commandes, factures, avoirs, etc.) constituent le coeur du système. Chaque document possède un en-tête (`dochead`) et une ou plusieurs lignes de détail (`docdet`). Un document appartient à un journal et est associé à un tiers.
@@ -604,7 +661,7 @@ Retourne les miniatures des fichiers images attachés à un document. Seuls les
---
### 5.5 Tiers
### 6.5 Tiers
Les tiers (clients, fournisseurs) sont les entités commerciales avec lesquelles l'entreprise interagit. Ils sont stockés dans la table `cust`.
@@ -662,7 +719,7 @@ Retourne l'historique complet des articles présents dans les documents associé
---
### 5.6 Divers
### 6.6 Divers
#### `getserialnumber` -- Numéro de série du dossier
@@ -710,11 +767,11 @@ Retourne les données associées à un code interne. Les codes proviennent de la
---
## 6. Envoi de données
## 7. Envoi de données
Les endpoints de cette section permettent de créer ou modifier des données dans le système de gestion via l'API.
### 6.1 Ajout d'un document
### 7.1 Ajout d'un document
#### `document_add` -- Création d'un document
@@ -775,7 +832,7 @@ Crée un nouveau document commercial (devis, commande, facture, etc.) dans un jo
---
### 6.2 Modification d'un document
### 7.2 Modification d'un document
#### `document_mod` -- Modification d'un document existant
@@ -812,7 +869,7 @@ Modifie un document existant identifié par son numéro et son journal. Permet d
---
## 7. Endpoints non fonctionnels
## 8. Endpoints non fonctionnels
Les endpoints suivants ont été identifiés mais ne fonctionnent pas dans l'état actuel ou nécessitent des paramètres dont les valeurs attendues sont inconnues.
@@ -857,7 +914,7 @@ Les endpoints suivants ont été identifiés mais ne fonctionnent pas dans l'ét
---
## 8. Relations entre entités
## 9. Relations entre entités
Les entités du système de gestion sont liées entre elles selon le schéma suivant :
@@ -888,7 +945,7 @@ Tiers (cust)
---
## 9. Remarques et points d'attention
## 10. Remarques et points d'attention
1. **Dossier en minuscules** : le nom du dossier dans les URLs doit toujours être en minuscules. Exemple : `esigescom`, pas `EsiGescom`. Le non-respect de cette règle provoque une erreur.
@@ -914,6 +971,6 @@ Tiers (cust)
---
## 10. Ressources externes
## 11. Ressources externes
- [Documentation Postman](https://documenter.getpostman.com/view/40440561/2sB2qaj2Pz)

17
resources/views/filament/pages/dashboard.blade.php
View File

@@ -167,4 +167,21 @@
</div>
</x-logistics.card>
{{-- Contacts en cas de problème --}}
<x-logistics.card>
<x-logistics.section-header
title="Contacts en cas de problème"
description="Contacts en cas de problème avec l'API Logistics."
/>
<div class="p-6">
<p class="text-gray-500 dark:text-gray-400">
En cas de problème avec l'API Logistics, veuillez contacter le support technique à l'adresse suivante :
</p>
<ul class="list-disc list-inside">
<li>Nom : Marvin</li>
<li>Email : <a href="mailto:mpa@esi-informatique.com" class="text-primary-600 dark:text-primary-400">mpa@esi-informatique.com</a></li>
</ul>
</div>
</x-logistics.card>
</x-filament-panels::page>

24
tests/Feature/DocumentationTest.php
View File

@@ -20,10 +20,32 @@ it('converts markdown to HTML content', function () {
expect($component->get('htmlContent'))
->toBeString()
->not->toBeEmpty()
->toContain('<h1>')
->toContain('<h1 id="')
->toContain('<table>');
});
it('generates heading IDs matching the table of contents anchors', function () {
$html = Livewire::test(Documentation::class)->get('htmlContent');
$anchors = [
'1-pré-requis',
'2-environnements-dutilisation',
'3-comment-effectuer-des-requêtes',
'4-structure-de-réponse',
'5-tables-et-colonnes-disponibles',
'6-récupération-de-données',
'7-envoi-de-données',
'8-endpoints-non-fonctionnels',
'9-relations-entre-entités',
'10-remarques-et-points-dattention',
'11-ressources-externes',
];
foreach ($anchors as $anchor) {
expect($html)->toContain("id=\"{$anchor}\"");
}
});
it('displays the main documentation sections', function () {
Livewire::test(Documentation::class)
->assertSee('Pré-requis')