màj wiki avec retour MES lot-5 AD

2026-05-20 09:41:27 +02:00
commit 23eb3f3c84
4106 changed files with 469381 additions and 0 deletions
@@ -0,0 +1,466 @@
+---
+title: "Réception retour commandes clients"
+tags: [inbound, réception, retour, client, API, lot]
+status: draft
+standard_ref: concepts/reception.md
+jira_refs: [LIM-72, LIM-67, LIM-68, LIM-66, LIM-64, LIM-70, LIM-73]
+confluence_refs: []
+sources: [FR-SW-04-07_LIMAGRAIN_Functional_Analysis_V1.5.docx, "Réception - LIMAGRAIN - DEV - Confluence.md", "LIM-72 LOT1.3 [RETOUR] Flux complet PK.md", "LIM-73 - LOT1.3 [RECEPTION] Fermetures, REF et gestion retours.md", "recap_session_LIM-72_13-05-2026.md"]
+last_updated: 2026-05-13
+author: Arthur
+---
+
+# Réception retour commandes clients
+
+> **Résumé** : processus spécifique de réception des retours client, avec
+> interrogation API SAP pour validation lot, et déclaration enrichie sur
+> poste de travail.
+
+> **Standard EasyWMS** : → voir [Reception](../../concepts/reception.md)
+> Ce qui suit documente les **spécificités Limagrain** par rapport au standard.
+
+## Contexte projet
+
+Les retours client suivent un flux similaire aux réceptions extérieures
+(passage poste de travail obligatoire) mais avec des particularités :
+
+- `InboundType = 1` (Return) — vs 0 (Standard) pour les autres flux
+- Création de lignes autorisée (article non attendu possible)
+- Tolérance illimitée : profil de réception par défaut configuré en
+  « illimité » sur tous les articles
+- `ReceiveLessAllowed = true` — réception partielle toujours autorisée
+- Interrogation API SAP pour valider le lot officiel
+- `AccountCode` = code client SAP (le client doit exister dans EasyWMS)
+
+## Process complet de réception retour client
+
+| Étape | Description | Ticket |
+|-------|-------------|--------|
+| 1 | Déclaration sur l'image de quai | [LIM-64](https://easywmsfrance.atlassian.net/browse/LIM-64) |
+| 2 | Déplacement AGV → poste de travail | [LIM-70](https://easywmsfrance.atlassian.net/browse/LIM-70) |
+| 3 | **Traitement au poste de travail** | [LIM-72](https://easywmsfrance.atlassian.net/browse/LIM-72) |
+| 4 | Déplacement AGV → table d'entrée (+ filmage si demandé) | — |
+| 5 | Passage PIE | [LIM-66](https://easywmsfrance.atlassian.net/browse/LIM-66) |
+| 6 | Stockage ou rejet | — |
+| 7 | Clôture de la réception | — |
+| 8 | Libération quai / image de quai | — |
+
+Voir [Réception fournisseur](reception-fournisseur.md) pour le détail
+du déchargement camion et des déclarations initiales
+([LIM-67](https://easywmsfrance.atlassian.net/browse/LIM-67) pour le
+flux fournisseur au PK).
+
+## Notification ROR
+
+Message ROR de SAP (type ORDRSP) avec :
+
+- Numéro de réception
+- Articles / Lots / Quantités attendues
+- Codes articles **génériques** (codes uniques avec nomenclature
+  précise, pas réutilisables — assure la traçabilité)
+
+**Différence clé** : cette réception **autorise la création de lignes**.
+Limagrain peut recevoir un article non présent dans le ROR initial.
+Un article inconnu de la base EasyWMS = ROR refusé. Un article connu
+mais non prévu dans le retour = accepté (tolérance illimitée).
+
+## [CUSTOM] Identification lot — Interrogation API SAP
+
+Lors du scan du lot officiel sur le poste de travail, le WMS vérifie
+d'abord si le lot est connu localement. Si oui, pas d'appel API. Sinon :
+
+### Rappel : structure des articles chez Limagrain
+
+Chez Limagrain, le **code article WMS = lot SAP** (cf.
+[Données principales](../06-erp-interface/donnees-principales.md)).
+Chaque lot SAP est descendu via le fichier **ITM** (fiche article
+complète), et le code produit est un attribut stocké en CstAtt du stock.
+Le **lot officiel** est l'alias de l'article dans le WMS.
+
+Quand le lot est "inconnu du WMS", cela signifie qu'**aucun article
+(ITM) n'existe avec ce lot officiel comme alias**. Il faut demander à
+SAP d'envoyer la fiche article complète.
+
+### Logique de vérification
+
+```mermaid
+flowchart TD
+    A[Scan / saisie lot officiel] --> B{Lot officiel connu du WMS ?<br/>= alias article existant ?}
+    B -- Oui --> C{Vendu par Limagrain ?}
+    B -- Non --> D[Appel API SAP]
+    D --> E[Écran attente<br/>refresh 5s / timeout 1 min]
+    E --> F{ITM reçu via API WMS ?}
+    F -- Oui --> C
+    F -- Non / Timeout --> G{Tentative < 5 ?}
+    G -- Oui --> H[Bouton Réessayer]
+    H --> D
+    G -- Non --> I[Erreur finale :<br/>contacter responsable]
+    C -- Oui --> J{Plusieurs articles ?}
+    C -- Non --> K[Erreur : lot non vendu<br/>par Limagrain]
+    J -- Non --> L[Sélection automatique<br/>→ déclaration contenu]
+    J -- Oui --> M[Dialogue choix article<br/>par pays d'origine]
+    M --> L
+```
+
+### Appel API SAP — Vérification du lot officiel (ATH214)
+
+L'appel API REST est fait **directement depuis le workflow** (pas via
+GNA). Il sert à notifier SAP que le WMS a besoin de la fiche article.
+
+> **Architecture CPI** : tous les flux WMS → SAP passent par un
+> **endpoint unique** SAP CPI, différencié par le champ `MessageType`
+> dans l'enveloppe JSON. Le flux retour utilise `MessageType = "ATH214"`.
+> Voir [Intégration GNA → SAP-CPI](../06-erp-interface/gna-sap-cpi.md)
+> pour le détail de l'architecture et de l'authentification OAuth 2.0.
+
+**Séquence d'échange :**
+
+```mermaid
+sequenceDiagram
+    participant WF as WMS (workflow)
+    participant CPI as SAP CPI
+    participant SAP as SAP ECC
+
+    WF->>CPI: GET /http/ATHInboundMessage<br/>MessageType: ATH214
+    Note over WF,CPI: Auth: OAuth 2.0 Bearer token<br/>Body: { MessageType, data }
+    CPI->>SAP: Z_IATH214 (check batch)
+    SAP-->>CPI: Réponse (EV_RETURN, ET_BATCH)
+    CPI-->>WF: Réponse JSON
+    alt EV_RETURN = "X" (OK)
+        SAP->>CPI: ATH002 (push ITM automatique)
+        CPI->>WF: POST ApplicationService/ITM
+        Note over CPI,WF: Fiche article complète :<br/>lot SAP = code article,<br/>lot officiel = alias
+        WF->>WF: Poll alias en base (5s)
+        alt Alias trouvé
+            WF->>WF: Continuer
+        else Timeout 1 min
+            WF->>WF: Proposer réessayer
+        end
+    else EV_RETURN ≠ "X" (NOK)
+        WF->>WF: Erreur immédiate
+    end
+```
+
+**Authentification OAuth 2.0 :**
+
+- Grant type : `client_credentials`
+- Token endpoint TEST :
+  `https://vilm-cpi-test-73ltxp48.authentication.eu30.hana.ondemand.com/oauth/token`
+- Token endpoint PROD : à définir
+- Body : `x-www-form-urlencoded` avec `grant_type`, `client_id`,
+  `client_secret`
+- Le token est envoyé en header `Authorization: Bearer <token>`
+- Expiration gérée côté WMS (cache + renouvellement)
+
+**Payload de requête :**
+
+```json
+GET /http/ATHInboundMessage
+{
+  "MessageType": "ATH214",
+  "data": {
+    "IV_LGNUM": "WF02",
+    "IV_MATNR": "",
+    "IV_CHARG": "",
+    "IV_BATCH_OFF": "<lot officiel scanné>",
+    "IV_RETURN": "<code OE retour>"
+  }
+}
+```
+
+| Champ | Type | Description |
+|-------|------|-------------|
+| `IV_LGNUM` | CHAR 4 | Toujours `"WF02"` |
+| `IV_MATNR` | CHAR 40 | OPTIONNEL - code lot WMS (= product code SAP) |
+| `IV_CHARG` | CHAR 10 | OPTIONNEL - code article WMS (= lot SAP) |
+| `IV_BATCH_OFF` | CHAR 30 | Lot officiel scanné sur le sac |
+| `IV_RETURN` | CHAR 10 | Numéro du document de retour (code OE) |
+
+> ⚠️ **Méthode HTTP** : `GET` avec body JSON — spécifique SAP CPI.
+> Header `Connection: keep-alive` requis.
+
+**Payload de réponse :**
+
+```json
+{
+  "EV_RETURN": "X",
+  "ET_RETURN": [ { "TYPE": "...", "MESSAGE": "..." } ],
+  "ET_BATCH": [
+    {
+      "MATNR": "000000000000020955",
+      "CHARG": "2023293649",
+      "BATCH_OFF": "F0964D002488",
+      "EV_DEPLOY": "X"
+    }
+  ]
+}
+```
+
+| Champ | Type | Description |
+|-------|------|-------------|
+| `EV_RETURN` | CHAR 1 | `"X"` = aucune erreur, vide = erreur |
+| `ET_RETURN[]` | Table | Messages d'erreur ou de succès SAP |
+| `ET_BATCH[].MATNR` | CHAR 40 | Code lot WMS = product code SAP |
+| `ET_BATCH[].CHARG` | CHAR 10 | Code article WMS = lot SAP |
+| `ET_BATCH[].BATCH_OFF` | CHAR 30 | Lot officiel |
+| `ET_BATCH[].EV_DEPLOY` | CHAR 1 | `"X"` = déployé/vendu, `""` = non |
+
+> ⚠️ **Mapping inversé CHARG / MATNR** : contrairement à la
+> nomenclature SAP standard, `MATNR` (Material Number) porte ici le
+> **product code** (= code lot WMS), et `CHARG` (Charge/Batch) porte le
+> **code article WMS** (= lot SAP). Ce mapping est confirmé par Michael
+> Chaudier et Vincent Goyet (avril 2026).
+
+> ⚠️ **À confirmer** : le nom du champ de déploiement est ambigu dans
+> les échanges — `EV_DEPLOY` ou `ZDEPLOY` ? En attente de clarification
+> (question A2 dans
+> [Questions ouvertes](../08-transverse/questions-ouvertes.md)).
+
+Si `EV_RETURN = "X"`, on récupère dans `ET_BATCH` tous les
+`BATCH_OFF` dont `EV_DEPLOY = "X"` — ce sont les lots autorisés
+pour l'opérateur.
+
+### Écran d'attente pendant la réception de l'ITM
+
+Après l'appel API, SAP appelle directement l'API du WMS pour pousser
+l'ITM. Pendant cette attente :
+
+- **Message** : "Vérification du lot en cours..."
+- **Refresh automatique** toutes les 5 secondes : le WMS vérifie si
+  un **alias correspondant au lot officiel** existe en base
+- **Bouton "Réessayer"** visible (relance un nouvel appel API)
+- **Timeout** : 1 minute maximum par tentative
+- **Nombre maximum de tentatives** : 5
+
+| Tentative | Comportement en cas de timeout |
+|-----------|-------------------------------|
+| 1 à 4 | Message "Erreur de communication avec SAP. Réessayer ?" + bouton Réessayer |
+| 5 | Message final "Impossible de contacter SAP après 5 tentatives. Veuillez contacter votre responsable." + bouton Annuler → retour au scan lot |
+
+### Choix du code lot (multi-résultat)
+
+Si l'API a renvoyé **plusieurs résultats** dans `ET_BATCH` (plusieurs
+`BATCH_OFF` avec `EV_DEPLOY = "X"`), un dialogue de sélection est
+affiché avec la liste des codes lots disponibles. L'opérateur en choisit
+un (filtrage par pays d'origine).
+
+Si un **seul résultat** → sélection automatique, pas de dialogue.
+
+**Pourquoi le choix article ?** Un lot SAP peut être associé à plusieurs
+articles (dépend du pays d'origine). L'opérateur doit choisir l'article
+physiquement présent sur la palette.
+
+**Gestion dans le REF :** le code générique envoyé dans le ROR est
+remplacé par le vrai code lot dans le REF (custom).
+
+## Déclaration au poste de travail (LIM-72)
+
+Le traitement au PK reprend les mêmes étapes que le flux fournisseur
+([LIM-67](https://easywmsfrance.atlassian.net/browse/LIM-67)) avec des
+adaptations. Le tableau ci-dessous récapitule chaque étape et ses
+différences :
+
+| # | Étape | Différence vs fournisseur (LIM-67) |
+|---|-------|------------------------------------|
+| 1 | Sélection de la réception | Affichage "**Client: CODE - NOM**" (au lieu de "Fournisseur") sur tous les écrans |
+| 2 | Big bag (CstAtt02) | Identique — toggle ON/OFF |
+| 3 | Scan lot officiel + vérification | **+ Vérification API SAP** (voir section ci-dessus) |
+| 4 | Déclaration quantité | Identique — affichage qté attendue + UdM, prompt non pré-rempli |
+| 4bis | Flag big-bag (bouton custom) | Identique (CstAtt02) |
+| 5 | Statut de stock | **Modifiable** — boutons visibles (masqués dans LIM-67) |
+| 6 | Flag "À anoxier" | Identique (CstAtt03 = true) |
+| 7 | Programme de filmage | Identique (paramètre FILMAGES → CstAtt05) |
+| 8 | Impression étiquette RFID | Identique ([LIM-68](https://easywmsfrance.atlassian.net/browse/LIM-68)) |
+| 9 | Validation → évacuation AGV | Identique |
+
+### Statut de stock — Modifiable
+
+Contrairement au flux fournisseur (LIM-67) où le statut de stock est
+verrouillé (boutons masqués), dans le flux retour client :
+
+- Les **boutons de changement de statut sont visibles** et fonctionnels
+- L'opérateur peut modifier le statut (ex : Conforme, Sac sale,
+  Non conforme, etc.)
+- Les écrans de **date de fin de statut** et **commentaire** suivent
+  le comportement standard (non skippés contrairement au fournisseur)
+- [CUSTOM] Statuts spécifiques retour : **F9** (sacs sales), **B6**
+  (non conforme) — assignables uniquement dans ce processus
+
+### Tolérance illimitée
+
+- **Article non prévu** dans le retour → accepté (création de ligne
+  autorisée)
+- **Quantité supérieure** au prévu → acceptée
+- **Quantité inférieure** au prévu → acceptée (réception fermée
+  manuellement)
+
+> Le prompt type de poste (3 ou 6 TP) prévu initialement est
+> **abandonné** — remplacé par un message d'avertissement si le poste
+> adjacent est déjà ouvert (voir
+> [Stations picking](../03-picking/stations-picking.md)).
+
+## Constitution palettes mono référence
+
+Obligation de constituer des palettes **mono référence** avant stockage.
+Si la palette retour est multi-ref :
+
+- Opérateur appelle une palette vide sur une TP disponible
+- Tri de marchandise
+
+## Calcul poids et passage PIE
+
+Identique aux réceptions extérieures (mêmes formules de répartition
+prorata, mêmes contrôles). Voir
+[Contrôle qualité réception](controle-qualite-reception.md).
+
+**Différences pour les retours client :**
+
+- Verrou si écart poids : **« Écart inventaire »** (vs « Réception »
+  pour les autres flux) — verrou posé sur le **support** (pas sur
+  le stock)
+- Action requise en cas d'écart : **recomptage du nombre de sacs**
+- Rejet PIE : dirigé vers **poumon au sol** + notification SmartUI
+  (ancienne approche de renvoi au PK abandonnée)
+
+## Clôture — Spécificités retour client (LIM-73)
+
+Le mécanisme général de clôture (déclenchement auto-close, tolérance par
+ligne, CstAtt01 OE hors tolérance, clôture OE) est documenté dans
+[Réception fournisseur — Clôture](reception-fournisseur.md). Cette
+section décrit le **delta retour client** : le REF est conditionné au
+rangement ASRS complet.
+
+### Contexte métier
+
+Pour les retours clients, le REF influe sur la **facturation SAP**. Il
+ne doit être envoyé que lorsque **tous les supports** de la réception
+sont rangés dans l'ASRS (et ont passé l'ensemble des contrôles,
+notamment PIE).
+
+Pour les autres types de réception (fournisseur / intersite), le REF est
+émis à la clôture de la réception, quelle que soit la position des
+supports.
+
+### CstAtt11 — Marqueur de rangement ASRS
+
+À chaque fin de tâche de rangement dans l'ASRS :
+
+- Vérifier si le support provient d'une réception de type **retour**
+- Si oui → `CstAtt11 = true` sur le support
+- Sinon → aucune action
+
+Le CstAtt11 est posé une fois et n'est **jamais remis à false**, même si
+le support ressort ensuite de l'ASRS (picking). Cela garantit que la
+condition de clôture reste satisfaisable même si une palette a déjà été
+expédiée entre-temps.
+
+### Statut « Clôture en cours »
+
+Dans la vue des réceptions, le statut visuel est piloté par le
+`CstAtt01 de la réception` (posé par Reception_Close_PR_V2) :
+
+| CstAtt01 réception | État | Affichage |
+|---------------------|------|-----------|
+| null / vide | En attente | Standard |
+| true | Clôture en attente de rangement ASRS complet | **« Clôture en cours »**, ligne en **jaune** |
+
+Pour les réceptions non-retour, CstAtt01 de la réception n'est pas
+utilisé (affichage standard).
+
+### Adaptation Reception_Close_PR_V2 — Partie A (retours)
+
+- **Si non-retour** → clôture immédiate, génération REF (standard)
+- **Si retour** :
+  - Vérifier que **tous les supports** ont `CstAtt11 = true`
+  - **Oui** → `CstAtt01 réception = false`, fermer la réception,
+    générer REF
+  - **Non** → ne pas fermer, `CstAtt01 réception = true` (statut
+    « Clôture en cours »). Le WF est rejoué à chaque event
+    _task finished_ sur un support de la réception
+
+> Si une palette est refusée au PIE puis retirée du retour (ROR), le
+> client doit la **supprimer du WMS**, sinon la clôture ne sera jamais
+> effectuée.
+
+### Zone de stockage dans le REF
+
+Pour les retours, le REF n'est émis qu'une fois tous les supports rangés
+en ASRS → la valeur sera toujours une zone réelle (jamais "NON RANGEE").
+
+### Récapitulatif CstAtt clôture retour
+
+| CstAtt | Entité | Rôle |
+|--------|--------|------|
+| CstAtt08 | Palette fictive | Code réception — détecte l'absence de palettes fictives restantes (§ auto-close) |
+| CstAtt10 | Palette réelle au PK | `true` pendant traitement PK — détecte qu'aucune palette n'est en cours de traitement |
+| CstAtt11 | Palette réelle | `true` quand rangée en ASRS — condition de clôture retour |
+| CstAtt01 | Réception | `true` = clôture en attente de rangement ASRS (affichage jaune) |
+
+## État du développement LIM-72
+
+### Implémenté (commit 8401f5456d, 28/04/2026)
+
+- Entité `CST_StockStatus` : CstAtt 1 applicable en retour, CstAtt 2 =
+  ZLOG, CstAtt 3 = ZINCO
+- Query `CST_StockStatus_AllowedForReturn` : filtre statuts autorisés
+- Workflow `CST_Return_Stock_GetStatus_UI` : sélection statut simplifié
+- Workflow `Reception_FilterLinesByProductAndContainer_UI_V1` : retrait
+  filtre quantité (tolérance illimitée)
+- Dialog `CST_GetProductQuantity_Prompt` : option SelectStatus ajoutée
+
+### Reste à développer
+
+- Appel API SAP ATH214 + gestion token OAuth 2.0
+- Écran d'attente ITM (polling alias 5s, timeout 1 min, 5 tentatives)
+- Dialogue choix multi-lot (quand ET_BATCH contient plusieurs articles)
+- Impression étiquette stock retour client (rapport custom à créer)
+- Configuration flux de rejet PIE retours (verrou ECART RETOUR,
+  destination, notification)
+
+## Points d'attention
+
+⚠️ Le paramètre `SAP_LOT_VERIFY_URL` doit pointer vers l'endpoint CPI
+unique `/http/ATHInboundMessage`, pas vers `/api/v1/lot/verify`.
+
+⚠️ Le `MessageType` doit être `"ATH214"` dans l'enveloppe JSON.
+
+⚠️ Pour les lots **déjà connus** en base WMS, le flag "déployé" n'est
+pas vérifié dans le design actuel — trou fonctionnel identifié (question
+A4 dans [Questions ouvertes](../08-transverse/questions-ouvertes.md)).
+
+## Questions ouvertes
+
+- [ ] Champs manquants ET_BATCH : description article, pays destination,
+  propriétaire (@Vincent Goyet) — A1
+- [ ] Nom final champ déploiement : EV_DEPLOY ou ZDEPLOY ?
+  (@Vincent Goyet) — A2
+- [ ] Délai ATH214 → push ITM dimensionnement polling
+  (@Vincent Goyet) — A3
+- [ ] Vérification "déployé" pour lots déjà connus sans ATH214
+  (@Vincent Goyet) — A4
+- [ ] Étiquette stock retour : format, champs, imprimante
+  (@Leila / @Antoine) — B1
+- [ ] Flux rejet PIE retour : destination, notification, actions
+  (@Leila / @Antoine) — B2
+
+## Historique des modifications
+
+| Date | Auteur | Modification |
+|------|--------|-------------|
+| 2026-05-05 | Arthur | Création initiale depuis AF V1.5 |
+| 2026-05-05 | Arthur | Enrichissement depuis ateliers DEV réception |
+| 2026-05-12 | Arthur | Intégration LIM-72 (process complet 8 étapes, API SAP, CstAtt) |
+| 2026-05-12 | Arthur | Intégration LIM-73 (clôture retour, CstAtt11, REF conditionné) |
+| 2026-05-13 | Arthur | Correction API : endpoint CPI unique + ATH214, auth OAuth 2.0, mapping CHARG/MATNR, état dev, questions ouvertes |
+
+## Références
+
+| Source | Type | Date |
+|--------|------|------|
+| Jira LIM-72 | Ticket | 2025 |
+| Jira LIM-73 | Ticket | 2025 |
+| Jira LIM-14 | Ticket (CstAtt) | 2025 |
+| Athenzat SAP-CPI Webservices Documentation v1.0 | PDF | 2026-04-24 |
+| Mail Michael Chaudier ↔ Vincent Goyet | Échange | 2026-04-07/10 |
+| Mail Justine ↔ Leila ↔ Vincent Goyet ↔ Maxime Tourrette | Échange | 2026-04-24/29 |
+| recap_session_LIM-72_13-05-2026.md | Récap session | 2026-05-13 |