Към съдържанието
Съдържание на курса

Урок 16 — Пристига доставката

От · съосновател и Chief Executive Officer на Hábil ·

Какво ще постигнеш: да получиш известието, което куриерската фирма праща, когато достави една пратка, така че поръчката да стане ENTREGADO в API-то и в ERP, а партньорът да получи своята 214. И да различаваш такова известие от заявка.

Преди да започнеш, ти трябват: завършен урок 15 и включена средата от урок 00.

Новото днес, в едно изречение

Вече имаш две събития от жизнения цикъл на поръчката: тя се създава (магазинът се обажда) и се изпраща (складът оставя файл). Днес идва третото: тя се доставя. И идва по трети начин: куриерската фирма ти се обажда сама, когато е доставила, на твой адрес. Това е webhook, а това, което носи, е събитие: не иска нищо от теб, а ти съобщава, че нещо вече се е случило.

Картината: съобщението от куриерската фирма на телефона ти: „Пратката ви е доставена“. Не иска да правиш нищо и не очаква да му отговориш какво ще направиш. Иска само да знае, че съобщението е стигнало до теб. Какво ще направиш после (да уведомиш този, който я е чакал, да провериш дали е твоята пратка) е твоя работа.


1. Подготви папката си

cd lecciones/16-llega-la-entrega
cp -R inicio mio

Отвори примерното известие, datos/webhooks/entrega-4001.json. Носи събитието (entregado), куриерската фирма, товарителницата, поръчката, кога е доставена и кой я е получил.

Цялата изходяща част вече е направена. Всеки канал има свой entrega.camel.yaml:

Канал Какво прави с доставката
int-rest Съобщава на API-то, че поръчката е доставена, като събитие със своя ключ
int-bd Регистрира доставката в ERP и прехвърля поръчката в ENTREGADO
int-edi Сглобява 214, статуса на пратката в X12, с товарителницата в сегмента B10, и го оставя на SFTP

Разпределянето от урок 15 вече умее да праща събитието entregada. Липсва вратата.

2. Предвиди

Отговори на лист хартия:

  1. Куриерската фирма съобщава, че е доставила 4001. Какво трябва да остане в базата на състоянието и какво — във всяка дестинация?
  2. Какво отговаря рутерът на куриерската фирма: това, което са казали API-то, ERP и партньорът, или само „получено“? Защо?
  3. Пристига известие за поръчка 9999, която магазинът никога не е създавал. Какво трябва да отговори рутерът?

Виж какво е положението днес:

./verifica inicio

Webhook-ът отговаря с 501, което в HTTP означава „това не умея да го правя“, и не записва нищо. 4001 остава в EMBARCADO завинаги, макар че клиентът вече има пратката си.

3. Отвори вратата

Отвори mio/orden-router/paqueteria.camel.yaml. Маршрутът webhook-paqueteria слуша на POST /webhooks/paqueteria и днес само отговаря с 501. Образецът ти е embarque-router от orden-router.camel.yaml: прави почти същото за пратката. Прочети го, преди да започнеш.

TODO Какво пишеш За какво
1 convertBodyTo към String Известието да се запише точно каквото е пристигнало
2 Две променливи: orden (от $.orden, с jsonpath) и momento (entregada). И извикай direct:hilo Да знаеш за коя поръчка е и кое събитие е, с нишката от урок 09
3 Извикай direct:cargar-orden. С choice: ако ${variable.tienda} == null, към direct:no-existe; ако не, към direct:canales, direct:guardar-momento и direct:contestar-y-repartir Поръчка, която не познаваме, се отхвърля; позната поръчка се записва, получава отговор и се разпределя

И изтрий двете стъпки, които днес отговарят с 501.

Забележи, че не пишеш нищо ново по същество: cargar-orden, canales, guardar-momento и contestar-y-repartir съществуват още от урок 15. Доставката влиза през различна врата, но вътре следва същия път като поръчката и пратката: запиши, отговори, разпредели.

4. Счупи едно нарочно

С твоя завършен webhook махни choice и остави само това от клона otherwise: сякаш всяка поръчка съществува. Вдигни услугите и прати известие за поръчка, която не съществува:

DONDE=mio docker compose -f compose.yaml up -d
curl -i -XPOST localhost:8080/webhooks/paqueteria -H 'Content-Type: application/json' \
  -d '{"evento":"entregado","paqueteria":"PAQX","guia":"PAQX770009999","orden":"9999"}'

Преди това предвиди: какво отговаря рутерът?

Вече не отговаря с 404, а със сървърна грешка. guardar-momento се опитва да създаде операциите на поръчка, която я няма в таблицата orden, базата не го позволява и транзакцията се отменя. Сега помисли за куриерската фирма: при сървърна грешка един изпращач на webhook-ове праща известието отново и ще продължи да го праща. 404 казва истината — „тази поръчка не я познавам“ — и изпращачът спира да настоява. Върни choice и изключи:

DONDE=mio docker compose -f compose.yaml down

5. Провери

./verifica

verifica създава 4001, изпраща я, влиза в ролята на куриерската фирма с entrega-4001.json и накрая праща известие за 9999. Урокът е завършен, когато видиш деветте зелени отметки:

✅ Arrancaron el router (con el webhook de la paquetería), los tres canales y el sondeo
✅ Antes de la entrega: la 4001 está EMBARCADO en la API y en el ERP
✅ La paquetería avisó la entrega de la 4001 y el router contestó 202 «recibida»
✅ Estado: tres operaciones de la 4001 con momento=entregada, aceptadas, y la orden va en «entregada»
✅ API: la 4001 está ENTREGADO, con la guía con la que salió
✅ ERP: la 4001 está ENTREGADO y su fila de entrega tiene la guía
✅ Socio: el 214 de la 4001 está en su SFTP y el lector X12 no le encontró fallas
✅ Socio: el 214 lleva la guía en el B10 y el número de control de la base (…)
✅ Un aviso de la orden 9999, que no existe: el router contestó 404 y no guardó nada

Отвори 214-ката, която стигна до партньора, mio/salida/214-4001.edi, и намери товарителницата в сегмента B10.

Не тръгва? ./verifica solucion тества нашето решение, а diff mio/orden-router/paqueteria.camel.yaml solucion/orden-router/paqueteria.camel.yaml ти казва по какво се различават.

Какво виждаш Какво правиш
Esperaba 202 del webhook y el router contestó … 501 Останали са двете стъпки от inicio/, които отговарят с 501: изтрий ги
Un aviso de una orden que no existe contestó «500» Липсва choice или условието не е ${variable.tienda} == null
las operaciones de la entrega quedaron «sin operaciones» Променливата momento не се казва така или не е entregada, или липсва direct:guardar-momento
4001 е записана, но никоя дестинация я няма Липсва direct:contestar-y-repartir накрая
El puerto 8080 está ocupado Услугите от стъпка 4 са останали вдигнати: DONDE=mio docker compose -f compose.yaml down

Какво учи това извън курса

На събитие и на заявка се отговаря различно. На заявка („създай тази поръчка“) се отговаря дали е станало. На събитие („вече доставих“) се отговаря само, че е пристигнало: случилото се вече се е случило и не зависи от теб. Затова рутерът отговаря с 202 и разпределя след това.

Който праща webhook, чака малко и опитва отново. Изпращачите броят за доставено само това, което е получило 2xx навреме, и пращат отново останалото. Да отговориш веднага щом си записал пази и двете: не кара никого да чака и не предизвиква излишни повторни опити.

Кодът на отговора е указание за този, който праща. 202 е „вече го имам“, 404 е „не настоявай, това не съществува“, а сървърна грешка е „опитай по-късно“. Грешно избраният код променя това, което прави другата система.

Упражнение: три врати, един път

С твоята завършена версия:

  1. Направи таблица с трите събития: създадена, изпратена и доставена. За всяко: кой го праща, откъде влиза (HTTP от магазина, файл от склада, webhook) и кой маршрут на рутера го получава. Какво е общото между трите маршрута след входа?
  2. В базата на състоянието провери операциите на 4001 за трите събития: SELECT momento, canal, estado FROM operacion WHERE orden = '4001' ORDER BY id. Колко реда са и защо?
  3. Какво би станало, ако куриерската фирма съобщи за доставката на 4002, преди да е пристигнала нейната пратка? Запиши отговора си: това е урок 17.

Защо е направено така

Какво решихме в този урок, заедно с това, което отхвърлихме, и какво би ни накарало да си променим мнението:

  • Webhook-ът на куриерската фирма отговаря с 202 веднага щом е записал

Преговор

  1. Какво е webhook и по какво се различава от начина, по който пристига поръчката, и от начина, по който пристига пратката?
  2. Какво е 214 и какво носи в сегмента си B10?
  3. Защо рутерът отговаря на куриерската фирма с 202, а не с това, което са казали API-то, ERP и партньорът?
  4. Защо на известие за поръчка, която не съществува, се отговаря с 404, а не със сървърна грешка?
  5. Заключителният въпрос: „доставих пратката“ е събитие; „създай тази поръчка“ е заявка. С по един пример от курса за всяко обясни по какво се различават и как се променя това, което отговаря рутерът.

Следва: в урок 17 светът се разбърква: доставката на 4002 пристига преди нейната товарителница. Рутерът не може да я разпредели още, но не може и да я изхвърли. Какво правиш с нея?

Да обсъдим вашия проект

Предпочитате имейл? Пишете ни на hola@habil.mx