Documentation : structure README / CLAUDE / DECISIONS / MONITORING
Nouveaux documents :
- README.md : porte d'entrée humaine, absente jusqu'ici. Objet du projet,
installation, npm test, branchement Claude Desktop, ajout d'un profil WMS,
compilation de l'exécutable.
- DECISIONS.md : 20 décisions et pièges vérifiés sur un WMS réel (D1..D20),
chacun avec son pourquoi. Extrait ce qui était noyé dans CLAUDE.md :
100 % API, tenant_code OAuth, réponses {entities}, casse des propriétés,
dotenv sur stderr, dates relatives LINQ non traduisibles, absence de
CommandParameterData, etc.
- MONITORING.md : supervision du serveur MCP. Préfixes de logs, séquence
d'un démarrage sain, cycle de vie du token OAuth et ses trois filets,
état des caches, table symptôme -> cause. Une section dit explicitement
ce qui n'est pas instrumenté (ni healthcheck, ni métriques, ni alerte).
- docs/logs.md : accès aux logs du WMS. Chemins, placeholder {host},
blocage volontaire sur les profils SaaS, les trois outils, format des
lignes, limites connues.
Mises à jour :
- CLAUDE.md réécrit et aligné sur le code. Correction de l'écart le plus
gênant : le code utilise QueryType 0 (Reading), la doc annonçait 1, soit
l'inverse de ce qui fonctionne pour les comparaisons de statut par
chaîne. Corrigés également : 6 resources et non 7 (workflows://categories
n'existe pas), section .env mono-profil obsolète, références à des
fichiers de test absents, README annoncé mais inexistant. Le suivi de
projet et les checklists de phases sont retirés.
- docs/README.md : index réel du dossier. L'ancien promettait une resource
docs:// qui n'a jamais existé.
- docs/getting_started.md : avertissement en tête, c'est une capture
partielle du portail Mecalux dont les liens internes ne résolvent pas.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Arthur Ria
+36
-32
@@ -1,41 +1,45 @@
|
||||
# Documentation WMS
|
||||
# Documentation de référence
|
||||
|
||||
Bienvenue dans la documentation du WMS !
|
||||
Documents de référence sur EasyWMS et ses API, conservés dans le dépôt pour
|
||||
être consultables hors ligne et par un agent qui lit le code.
|
||||
|
||||
## Comment utiliser cette documentation
|
||||
> ⚠️ **Ce dossier n'est pas exposé comme resource MCP.** Une resource `docs://`
|
||||
> a existé sans jamais être branchée ; elle a été supprimée. Ces fichiers se
|
||||
> lisent directement depuis le dépôt. Voir D19 dans
|
||||
> [DECISIONS.md](../DECISIONS.md).
|
||||
|
||||
Cette documentation est automatiquement accessible via le serveur MCP. Claude peut lire tous les fichiers `.md` présents dans ce dossier et ses sous-dossiers.
|
||||
## Contenu
|
||||
|
||||
## Organisation
|
||||
| Fichier | Nature |
|
||||
|---|---|
|
||||
| [logs.md](logs.md) | **Rédigé pour ce projet** — accès aux logs WMS, outils, limites |
|
||||
| [ad-api-validation.md](ad-api-validation.md) | **Rédigé pour ce projet** — campagne de validation curl des 19 types AD testés (17 valides) |
|
||||
| [api/Application Service API Reference.md](api/Application%20Service%20API%20Reference.md) | Référence de l'API ApplicationService |
|
||||
| [api/POST apiQueryExecute.md](api/POST%20apiQueryExecute.md) | Détail de l'endpoint `QueryExecute` |
|
||||
| [entities/easywms_reading_entites.md](entities/easywms_reading_entites.md) | Catalogue des entités du modèle **Reading** |
|
||||
| [entities/easywms_reading_entites_outboundorder.md](entities/easywms_reading_entites_outboundorder.md) | Détail de l'entité `OutboundOrder` |
|
||||
| [entities/easywms_reading_entites_outboundorder_OutboundOrderStatus.md](entities/easywms_reading_entites_outboundorder_OutboundOrderStatus.md) | Valeurs de `OutboundOrderStatus` |
|
||||
| `getting_started.md`, `docs_downloads/` | Extractions du portail documentaire Mecalux |
|
||||
| `reference-queries-api.php` | Client PHP d'origine, source des patterns d'API. ⚠️ utilise `QueryType: 1` — ne pas recopier, voir D3 |
|
||||
|
||||
Organisez vos fichiers de documentation comme vous le souhaitez :
|
||||
**Sur les extractions du portail** : ce sont des captures partielles. Leurs
|
||||
liens internes pointent vers des pages non téléchargées (`ReleaseNotes.md`,
|
||||
`video_tutorials/`, …) et ne fonctionnent pas. Le seul document réellement
|
||||
exploitable de cet ensemble est
|
||||
`docs_downloads/communications/EasyWMS_WebApi_en.html.md` (référence complète de
|
||||
la Web API, ~320 Ko).
|
||||
|
||||
```
|
||||
docs/
|
||||
├── README.md (ce fichier)
|
||||
├── getting-started.md (guide de démarrage)
|
||||
├── api/
|
||||
│ ├── overview.md
|
||||
│ └── endpoints.md
|
||||
├── workflows/
|
||||
│ ├── reception.md
|
||||
│ └── expedition.md
|
||||
└── troubleshooting/
|
||||
└── common-errors.md
|
||||
```
|
||||
## Où trouver le reste
|
||||
|
||||
## Comment ajouter de la documentation
|
||||
| Question | Document |
|
||||
|---|---|
|
||||
| À quoi sert ce projet, comment l'installer | [../README.md](../README.md) |
|
||||
| Architecture, outils, resources, conventions de code | [../CLAUDE.md](../CLAUDE.md) |
|
||||
| Pourquoi le code est écrit ainsi, pièges vérifiés | [../DECISIONS.md](../DECISIONS.md) |
|
||||
| Le serveur ne répond pas / comment le superviser | [../MONITORING.md](../MONITORING.md) |
|
||||
|
||||
1. Créez vos fichiers `.md` dans ce dossier ou dans des sous-dossiers
|
||||
2. Redémarrez Claude Desktop
|
||||
3. Claude pourra automatiquement lire tous vos fichiers de documentation
|
||||
## Ajouter un document
|
||||
|
||||
## Accéder à la documentation depuis Claude
|
||||
|
||||
Dans Claude Desktop, vous pouvez demander :
|
||||
|
||||
- "Montre-moi le sommaire de la documentation"
|
||||
- "Lis la documentation sur les workflows"
|
||||
- "Affiche-moi la documentation de l'API"
|
||||
|
||||
Claude aura accès à tous les fichiers `.md` présents ici !
|
||||
Déposez le `.md` dans le sous-dossier qui convient et **ajoutez sa ligne au
|
||||
tableau ci-dessus**. Un document non listé ici est un document que personne ne
|
||||
retrouvera.
|
||||
|
||||
@@ -1,3 +1,9 @@
|
||||
> ⚠️ **Capture partielle du portail documentaire Mecalux.** Ce sommaire est
|
||||
> conservé pour mémoire : la quasi-totalité de ses liens pointe vers des pages
|
||||
> qui n'ont pas été téléchargées et ne résolvent pas. Seul
|
||||
> [docs_downloads/communications/EasyWMS_WebApi_en.html.md](docs_downloads/communications/EasyWMS_WebApi_en.html.md)
|
||||
> est exploitable hors ligne. Voir [README.md](README.md).
|
||||
|
||||
# MAP - Documentation Portal
|
||||
|
||||
## Table des matières
|
||||
|
||||
+165
@@ -0,0 +1,165 @@
|
||||
# Logs du WMS
|
||||
|
||||
Comment le serveur MCP accède aux fichiers de logs du WMS, ce qu'il sait faire
|
||||
et ce qu'il ne peut pas faire.
|
||||
|
||||
Pour superviser **le serveur MCP lui-même**, voir
|
||||
[MONITORING.md](../MONITORING.md).
|
||||
|
||||
---
|
||||
|
||||
## 1. Où sont les logs
|
||||
|
||||
Les logs sont lus **directement sur le système de fichiers** du serveur WMS,
|
||||
via des partages réseau Windows — jamais par API.
|
||||
|
||||
| Emplacement | Contenu |
|
||||
|---|---|
|
||||
| `\\<host>\inetpub\logs\LogFiles\Mecalux` | logs applicatifs IIS, organisés en sous-dossiers par composant |
|
||||
| `\\<host>\ProgramData\Mecalux\ETLLogs` | logs du middleware ETL |
|
||||
|
||||
Configuration dans `.env`, plusieurs chemins séparés par des `;` :
|
||||
|
||||
```env
|
||||
LOGS_PATH=\\{host}\inetpub\logs\LogFiles\Mecalux;\\{host}\ProgramData\Mecalux\ETLLogs
|
||||
```
|
||||
|
||||
**Le placeholder `{host}` est remplacé à chaque appel** par le host du profil
|
||||
actif. Il n'y a donc pas de chemin de logs à redéfinir par profil : un seul
|
||||
gabarit suffit, et il suit automatiquement `switch_wms_profile`.
|
||||
|
||||
Le scan est **récursif** et ne retient que les fichiers dont le nom se termine
|
||||
par `.log`. Un dossier absent ou inaccessible n'interrompt pas le scan : il est
|
||||
journalisé (`[Logs] Cannot scan directory …`) et ignoré.
|
||||
|
||||
---
|
||||
|
||||
## 2. Prérequis d'accès
|
||||
|
||||
Les partages `\\<host>\...` doivent être joignables **depuis la machine qui
|
||||
exécute le serveur MCP**, avec les droits de lecture du compte Windows courant.
|
||||
Le serveur ne présente aucun credential propre pour SMB — il hérite de la
|
||||
session Windows.
|
||||
|
||||
Vérification rapide, hors serveur MCP :
|
||||
|
||||
```bash
|
||||
Test-Path "\\10.255.255.2\inetpub\logs\LogFiles\Mecalux"
|
||||
```
|
||||
|
||||
Si cette commande renvoie `False`, aucun outil de log ne fonctionnera : le
|
||||
problème est réseau ou droits, pas applicatif.
|
||||
|
||||
---
|
||||
|
||||
## 3. Profils SaaS : les logs ne sont pas accessibles
|
||||
|
||||
Quand le profil actif est déclaré `<PROFIL>_SAAS=true`, les trois outils de log
|
||||
**échouent volontairement** avec :
|
||||
|
||||
> Log access is disabled for SaaS profile "X". The WMS is cloud-hosted — local
|
||||
> log files are not reachable. Use the WMS API (query/command/workflow tools)
|
||||
> instead.
|
||||
|
||||
C'est un choix explicite, pas une régression : le WMS est hébergé dans le cloud
|
||||
Mecalux, son système de fichiers n'est pas exposé. Retourner « 0 fichier »
|
||||
laisserait croire à une absence d'erreurs — un faux négatif dangereux en
|
||||
diagnostic. Voir D9 dans [DECISIONS.md](../DECISIONS.md).
|
||||
|
||||
**Sur un profil SaaS, le diagnostic passe donc uniquement par les API** :
|
||||
`query_wms_entities`, `count_wms_entities`, `search_wms_data`, les outils AD et
|
||||
`get_system_parameters`.
|
||||
|
||||
---
|
||||
|
||||
## 4. Les trois outils
|
||||
|
||||
### `list_log_files`
|
||||
|
||||
Liste tous les `.log` trouvés sous `LOGS_PATH`, **triés du plus récent au plus
|
||||
ancien**, avec taille, date de modification et dossier d'origine. Point de
|
||||
départ naturel : il montre quels composants ont écrit récemment.
|
||||
|
||||
Si aucun fichier n'est trouvé, l'erreur **énumère les chemins scannés** — c'est
|
||||
généralement suffisant pour diagnostiquer un `{host}` mal résolu.
|
||||
|
||||
### `read_recent_logs(count, log_file)`
|
||||
|
||||
Renvoie les `count` dernières lignes (100 par défaut). Sans `log_file`, prend
|
||||
**le fichier le plus récemment modifié, tous dossiers confondus** — ce qui n'est
|
||||
pas forcément celui que l'on croit sur un serveur multi-composants ; préférez
|
||||
nommer le fichier.
|
||||
|
||||
La résolution de `log_file` se fait en trois passes, de la plus stricte à la
|
||||
plus permissive :
|
||||
|
||||
1. chemin direct sous le premier `LOGS_PATH`
|
||||
(ex. `ApplicationDictionary\ApplicationDictionary.log`) ;
|
||||
2. nom exact recherché dans chaque sous-dossier immédiat ;
|
||||
3. correspondance partielle, insensible à la casse.
|
||||
|
||||
En cas d'échec, l'erreur liste les fichiers disponibles.
|
||||
|
||||
### `search_logs(keyword, max_results, context_lines)`
|
||||
|
||||
Recherche insensible à la casse dans **tous** les fichiers, du plus récent au
|
||||
plus ancien, en s'arrêtant à `max_results` (50 par défaut). Chaque résultat
|
||||
porte son fichier, son numéro de ligne et `context_lines` lignes avant/après (2
|
||||
par défaut), la ligne trouvée étant marquée `isMatch`.
|
||||
|
||||
C'est l'outil à privilégier pour tracer un identifiant métier (numéro de
|
||||
commande, code produit, id de tâche) à travers les composants.
|
||||
|
||||
---
|
||||
|
||||
## 5. Format des lignes
|
||||
|
||||
`ApplicationService.log` suit ce format :
|
||||
|
||||
```
|
||||
YYYY-MM-DD HH:MM:SS.ffff [thread] [Level] [Component] [message]
|
||||
```
|
||||
|
||||
Exemple :
|
||||
|
||||
```
|
||||
2026-08-24 09:14:22.1873 [42] [ERROR] [OutboundOrderService] [Order 4711 not found]
|
||||
```
|
||||
|
||||
Conséquence pratique : une recherche par **date préfixe** (`2026-08-24 09:`)
|
||||
fonctionne bien, et le niveau se filtre par `[ERROR]` — crochets inclus, pour
|
||||
éviter les faux positifs sur le mot « error » dans un message.
|
||||
|
||||
Les logs ETL n'ont pas le même format ; ne présumez pas d'une structure commune
|
||||
entre les deux emplacements.
|
||||
|
||||
---
|
||||
|
||||
## 6. Limites à connaître
|
||||
|
||||
- **Lecture intégrale en mémoire.** `read_recent_logs` et `search_logs`
|
||||
chargent chaque fichier entier avant de le découper. Sur un log de plusieurs
|
||||
centaines de Mo, c'est lent et coûteux en RAM. Vérifiez les tailles avec
|
||||
`list_log_files` avant de lancer une recherche large.
|
||||
- **Recherche par sous-chaîne uniquement**, pas d'expression régulière.
|
||||
- **Pas de filtre temporel** : `search_logs` ne sait pas restreindre à une
|
||||
plage horaire. Le contournement est d'inclure le préfixe de date dans le
|
||||
mot-clé.
|
||||
- **Aucun filtre de nom de fichier configurable.** Le scan retient tous les
|
||||
`.log`. (Une variable `LOG_FILE_PATTERN` a existé dans `.env` sans jamais
|
||||
être appliquée ; elle a été supprimée — voir D20.)
|
||||
- **Pas de rotation ni de purge** : le serveur MCP lit, il n'écrit ni ne
|
||||
supprime rien.
|
||||
|
||||
---
|
||||
|
||||
## 7. Hors périmètre : l'historique des shipment templates
|
||||
|
||||
Les logs `ApplyShipmentTemplates` **ne sont pas présents** sur l'hôte joignable
|
||||
(`10.255.255.2`) : ils résident sur les serveurs de production / ETL des
|
||||
clients. Aucun outil ne les analyse, car il n'y aurait rien à lire.
|
||||
|
||||
Ce que l'on peut obtenir par API se limite à la **dernière** exécution, via
|
||||
l'entité Reading `ShipmentTemplate` (`LastExecuteDate`, `Status`,
|
||||
`IsEnabled`). Voir D16 dans [DECISIONS.md](../DECISIONS.md) et les recettes de
|
||||
la resource `wms://query-examples`.
|
||||
Reference in New Issue
Block a user