Table des matières du cours
Leçon 23 — Retraiter ce qui a échoué
Par Dorian Chávez · cofondateur et Chief Executive Officer de Hábil ·
Ce que vous allez obtenir : une porte dans le routeur,
POST /rerun, pour qu'une personne renvoie seulement l'étape qui est restée bloquée, sans rien dupliquer dans les destinations et en laissant écrit qui l'a demandé, pourquoi et avec quelle version c'est parti.
Avant de commencer, il vous faut : les leçons 22 et 18 terminées, et l'environnement de la 00 allumé.
La nouveauté du jour, en une phrase
Dans la 20, vous avez laissé en conciliacion_pendiente ce dont on n'a pas pu connaître l'issue, et dans la 22, en
pendiente, ce que le coupe-circuit n'a pas envoyé. Les deux attendent la même chose : que quelqu'un corrige la cause et le renvoie. Jusqu'à aujourd'hui, ce
quelqu'un n'avait aucun moyen de le faire. Le rerun est cet outil : une tentative de plus de la même opération, demandée par une personne
et notée comme telle.
L'image : le comptoir des réclamations d'un transporteur. Vous apportez votre numéro de suivi et vous dites « ce colis est resté à l'entrepôt à cause de la tempête ». On ne vous renvoie pas tout ce que vous avez expédié ce jour-là : on cherche ce colis, on vérifie qu'il est vraiment bloqué et on le réexpédie. Dans le système, il reste noté que c'est le comptoir qui l'a renvoyé, à votre demande, à cause de la tempête. Si vous apportez le numéro de suivi d'un colis déjà livré, on vous dit non.
1. Préparez votre dossier
cd lecciones/23-reprocesar-lo-que-fallo
cp -R inicio mio
Le routeur a un nouveau fichier, orden-router/rerun.camel.yaml, avec une seule route : rerun, qui écoute sur
POST /rerun. Elle reçoit ceci :
{"orden": "4001", "momento": "creada", "canal": "edi",
"pedido_por": "ana.soporte", "motivo": "el SFTP del socio estuvo caído"}
Ouvrez-le et lisez le commentaire du haut. La version d'inicio/ fonctionne, mais ne suffit pas. Elle marque l'opération
comme pendiente et la remet dans la distribution. Cela pose trois problèmes :
| Problème | Pourquoi cela compte |
|---|---|
Elle part comme une tentative auto, sans nom ni motif |
Demain, personne ne sait qu'une personne l'a demandée, ni pourquoi |
| Elle rouvre ce qui s'était déjà bien passé, et le renvoie | Un rerun de quelque chose d'accepté rappelle la destination |
| Elle répond 202 « devuelta al reparto » | Celui qui l'a demandé ne sait pas comment cela s'est passé |
Et il y a quelque chose que vous n'avez pas à construire : la table intento a déjà les colonnes tipo, pedido_por et
motivo, et l'INSERT de la route intentar (dans reparto.camel.yaml) les remplit déjà avec trois variables. Si elles
n'existent pas, tipo reste à auto.
2. Prédisez
Répondez sur papier :
- Le SFTP du partenaire revient. Si vous retraitez la commande complète (les trois canaux) de la 4001, qu'arrive-t-il à l'API et à l'ERP, qui l'avaient déjà ?
- L'API a tardé et le canal a coupé : la 4005 est restée sans que l'on sache comment cela s'est passé. Vous faites le rerun. Une autre commande est-elle créée dans l'API ? (Indice : la 02 et la 18.)
- Quelqu'un demande un rerun d'une opération qui est déjà
aceptada. Que devrait répondre le routeur ?
Regardez l'état actuel :
./verifica inicio
Les retraitements partent, et c'est pour cela que plusieurs coches passent. Mais ils partent comme des tentatives auto, le rerun de ce qui était déjà
accepté rappelle la destination au lieu de refuser, et un rerun sans motif est accepté quand même.
3. Une tentative manuelle, avec un nom et un motif
Ouvrez mio/orden-router/rerun.camel.yaml. Après les cinq variables extraites du corps, il y a quatre TODO, et
les quatre remplacent ce qui se trouve en dessous : l'UPDATE vers pendiente, l'envoi à seda:repartir et la réponse 202.
TODO 1 : sans nom ou sans motif, non
D'abord deux en-têtes, pour que la réponse sorte propre : removeHeaders avec pattern: "*" et un setHeader de
Content-Type à application/json. Puis un filter qui ne laisse passer que ce qui est faux : s'il manque orden,
momento, canal, pedido_por ou motivo, il répond 400 et s'arrête.
- filter:
expression:
simple:
expression: >-
${variable.orden} == null || ${variable.orden} == '' || …
${variable.pedido_por} == null || ${variable.pedido_por} == '' ||
${variable.motivo} == null || ${variable.motivo} == ''
steps:
- setHeader:
name: CamelHttpResponseCode
expression:
constant:
expression: "400"
resultType: java.lang.Integer
- setBody:
expression:
constant:
expression: '{"resultado":"no reprocesado","motivo":"faltan datos: orden, momento, canal, pedido_por y motivo"}'
- stop: {}
Le stop termine la route à cet endroit : ce qui vient en dessous ne s'exécute pas.
TODO 2 : seulement ce qui a échoué
Lisez l'opération dans la base, pas dans le corps. Copiez la requête de la route repartir de reparto.camel.yaml et
changez-y deux choses : qu'elle filtre aussi sur p.canal = :#${variable.canal} au lieu de p.estado = 'pendiente',
et qu'elle renvoie aussi p.estado. Elle va avec outputType: SelectOne : le corps est donc une ligne (ou
null).
Ensuite, un choice à deux branches qui répondent et s'arrêtent, comme le filter du TODO 1 :
| Si | Répond | Pourquoi |
|---|---|---|
${body} == null |
404 | Cette opération n'existe pas |
${body[estado]} in 'aceptada,confirmada,estacionada' |
409 | Ce qui est accepté et ce qui est confirmé s'est bien passé ; ce qui est garé est libéré par le balayage (la 17) |
Tout le reste (pendiente, no_se_sabe, conciliacion_pendiente, rechazada) continue vers le TODO 3. Avant de continuer,
conservez l'état dans une variable antes : vous le renverrez dans la réponse à la fin.
TODO 3 : une tentative, ici même
C'est la difficulté d'aujourd'hui. Le retraitement n'est pas mis en file : on fait une tentative à cet instant, avec les mêmes routes que celles qu'utilise la distribution.
- Un
setVariabletipoavecconstantmanual. Avec cela, l'INSERTd'intentarnote qui et pourquoi (les variablespedido_poretmotivoexistent déjà). - Un
toversdirect:preparar, avec la ligne dans le corps. Il construit l'enveloppe, l'empreinte et le numéro de contrôle comme le fait la distribution. - Un
doTryavec untoversdirect:intentar. Dans sondoCatchdejava.io.IOException(le « on n'a pas pu savoir » de la 20), unUPDATE operacion SET estado = 'conciliacion_pendiente' WHERE id = :#${variable.operacion}: une tentative manuelle ne se retente pas toute seule, elle revient sous les yeux de celui qui l'a demandée. - Un
filter: si${variable.desenlace} == 'aceptada', untoversdirect:barrido, comme le fait la distribution. Quelque chose de garé pouvait attendre cette étape (la 17).
TODO 4 : dites-lui comment cela s'est passé
Répondez 200 avec ce qui est resté dans les variables :
- setBody:
expression:
simple:
expression: '{"resultado":"reprocesado","operacion":${variable.operacion},"intento":${variable.intento},"antes":"${variable.antes}","desenlace":"${variable.desenlace}","codigo":${variable.codigo},"version":"${variable.version}"}'
Regardez le dernier champ. La tentative part avec ce qui est déployé aujourd'hui : le mapping et le gabarit en vigueur, pas
ceux du jour où elle a échoué. Si, entre la panne et le rerun, quelqu'un a corrigé le mapping, le rerun part corrigé, et la
version avec laquelle il est parti reste notée dans la tentative (version_mapeo) et dans la réponse.
4. Cassez-en une exprès
Une fois tout terminé, retirez la seconde branche du choice du TODO 2, celle du 409. Lancez ./verifica.
Avant cela, prédisez : le verifica demande un rerun de la 4001, qui est déjà aceptada chez le partenaire. Que se passe-t-il dans la destination ?
Le routeur fait la tentative manuelle : il rappelle le canal du partenaire, et l'opération a une tentative de plus. La coche du rerun de ce qui est accepté sort en rouge. La piste d'audit contient désormais un retraitement dont personne n'avait besoin, et dans une destination qui ne reconnaîtrait pas les doublons il y aurait un doublon. Le routeur ne demande pas à la destination si elle l'a déjà : il le demande à sa propre base. Remettez la branche.
5. Vérifiez
./verifica
verifica éteint le SFTP et envoie quatre commandes ; il met l'API en mode lent et envoie la 4005 ; puis il remet tout en place et
fait cinq reruns, un pour chaque étape bloquée. À la fin, il en demande un pour quelque chose d'accepté et un sans motif. Elle est terminée
quand vous voyez les onze coches vertes :
✅ Arrancaron el router (con su POST /rerun), los tres canales y el sondeo
✅ Con el SFTP caído, el canal del socio de la 4001 a la 4004 quedó pendiente (lo que se reprocesa)
✅ Con la API lenta, el canal rest de la 4005 no supo cómo le fue y quedó (…)
✅ Rerun: el canal del socio de la 4001 a la 4004 y el rest de la 4005 quedaron aceptados
✅ Cada rerun quedó como intento «manual», con quién lo pidió, por qué y la versión del mapeo con que salió
✅ Sin duplicados: un 850 por orden en el socio, y la API creó la 4005 una vez y al rerun contestó 200 «reenvío»
✅ Solo el paso que falló: la API y el ERP de la 4001 a la 4004 no recibieron intentos nuevos
✅ Rerun de lo que ya está aceptado: 409, sin intento nuevo y la operación sigue (…)
✅ Rerun sin motivo: 400 (sin quién y por qué, el rastro quedaría mudo)
✅ El ERP reconoce un pedido que ya tiene: 200 «ya registrado», sin renglones nuevos
✅ El 997 del socio confirmó los cuatro 850 reprocesados
Regardez la sixième. L'API avait déjà la 4005 : l'appel lent l'a enregistrée après que le canal a coupé, comme dans la 20. Le rerun l'a renvoyée avec la même clé, et l'API a répondu 200 « reenvío », pas 201. C'est ce qui rend sûr le rerun d'un « on ne sait pas ».
Faites vous-même un rerun à la main et regardez la réponse :
curl -s -XPOST localhost:8080/rerun -H 'Content-Type: application/json' \
-d '{"orden":"4001","momento":"creada","canal":"edi","pedido_por":"yo","motivo":"probar"}'
Ça ne tourne pas ? ./verifica solucion teste la nôtre, et
diff mio/orden-router/rerun.camel.yaml solucion/orden-router/rerun.camel.yaml vous dit en quoi elles diffèrent.
| Ce que vous voyez | Ce que vous faites |
|---|---|
Esperaba 5 intentos manuales et il y en a 0 |
Il manque le setVariable tipo à manual, ou vous avez mis la tentative en file au lieu d'appeler direct:intentar |
Se reprocesó de más: la API y el ERP … pasaron de … a … intentos |
Votre requête ne filtre pas par canal : elle prend les trois opérations de l'événement |
Rerun de la 4001 ya aceptada: contestó … |
Il manque la branche du 409, ou elle ne porte pas de stop |
Rerun sin motivo: esperaba 400 |
Il manque motivo au filter du TODO 1, ou il lui manque le stop |
de las 5 operaciones reprocesadas, … quedaron aceptadas |
Il manque direct:preparar avant direct:intentar : sans lui, il n'y a ni enveloppe ni numéro de contrôle |
No pude poner la API en modo lento |
Votre API date d'avant : recréez-la comme dans la 20 |
El puerto 8080 está ocupado |
Les services d'une autre exécution sont restés en marche : DONDE=mio docker compose -f compose.yaml down |
Ce que cela enseigne au-delà du cours
Un retraitement est une tentative de plus, pas une nouvelle opération. Si elle était nouvelle, chaque destination la verrait comme une autre commande. Comme c'est la même opération, elle part avec la même clé et le même numéro de contrôle, et chaque destination peut la reconnaître.
On retraite l'étape, pas la commande. Tout renvoyer « au cas où » remplit la piste d'audit de bruit et parie que toutes les destinations supportent un doublon. On envoie ce qui a échoué et on refuse pour ce qui s'est bien passé.
Qui et pourquoi, ce n'est pas de la bureaucratie. Dans un mois, quelqu'un demandera pourquoi la 4005 a deux tentatives.
Sans pedido_por ni motivo, la réponse est « je ne sais pas » ; avec eux, « le support l'a demandé parce que l'API était lente ».
Il part avec ce qui vaut aujourd'hui, et on le note. Un rerun ne ressuscite pas le passé : il utilise le mapping en vigueur. C'est pour cela que chaque tentative conserve sa version, et que l'on peut savoir ce qu'a reçu la destination à chaque fois.
Exercice : le comptoir des réclamations
Avec votre version terminée, lancez ./verifica, puis :
- Consultez les tentatives du canal du partenaire pour la 4001 :
SELECT n, tipo, pedido_por, motivo, desenlace, version_mapeo FROM intento i JOIN operacion p ON p.id = i.operacion WHERE p.orden = '4001' AND p.canal = 'edi' ORDER BY n;Racontez l'histoire de cette opération en trois phrases, avec ce que dit chaque ligne. - Demandez trois reruns à la main : un pour une commande qui n'existe pas (
9999), un pour la 4001 dans le canalrestet un sanspedido_por. Notez ce que répond chacun et pourquoi. - Imaginez que demain vous corrigiez le mapping du partenaire en version 2 et que vous fassiez un rerun d'un 850 qui avait échoué hier. Avec quelle version part-il ? Où pouvez-vous le vérifier ? Pourquoi ne serait-il pas préférable qu'il parte avec la version d'hier ?
Pourquoi on a fait ainsi
Ce que nous avons décidé dans cette leçon, avec ce que nous avons écarté et ce qui nous ferait changer d'avis :
- Le retraitement à la main est une tentative de plus, avec un nom et un motif
Révision
- Quels états d'une opération peuvent être retraités, et lesquels non ? Pourquoi pas non plus ce qui est garé ?
- Pourquoi le rerun lit-il l'opération dans la base au lieu de se fier à ce que dit le corps ?
- Qu'est-ce qui évite qu'un rerun de la 4005 crée une autre commande dans l'API ?
- Pourquoi répond-on 400 sans
pedido_porou sansmotivo? - La question de clôture : le rerun part avec la configuration en vigueur et laisse sa version notée. Pourquoi avec celle d'aujourd'hui, et à quoi sert de la noter ?
Suite : dans la leçon 24, le problème n'est pas que la destination soit en panne, mais que ce soit vous qui la fassiez tomber. Avec trois répliques d'int-bd, combien d'appels simultanés l'ERP reçoit-il ?
Vous préférez l'e-mail ? Écrivez-nous à hola@habil.mx