Съдържание на курса
Урок 16 — Пристига доставката
От Dorian Chávez · съосновател и 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. Предвиди
Отговори на лист хартия:
- Куриерската фирма съобщава, че е доставила 4001. Какво трябва да остане в базата на състоянието и какво — във всяка дестинация?
- Какво отговаря рутерът на куриерската фирма: това, което са казали API-то, ERP и партньорът, или само „получено“? Защо?
- Пристига известие за поръчка 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 е „не настоявай, това не съществува“, а сървърна грешка е „опитай по-късно“. Грешно избраният код променя това, което прави другата система.
Упражнение: три врати, един път
С твоята завършена версия:
- Направи таблица с трите събития: създадена, изпратена и доставена. За всяко: кой го праща, откъде влиза (HTTP от магазина, файл от склада, webhook) и кой маршрут на рутера го получава. Какво е общото между трите маршрута след входа?
- В базата на състоянието провери операциите на 4001 за трите събития:
SELECT momento, canal, estado FROM operacion WHERE orden = '4001' ORDER BY id. Колко реда са и защо? - Какво би станало, ако куриерската фирма съобщи за доставката на 4002, преди да е пристигнала нейната пратка? Запиши отговора си: това е урок 17.
Защо е направено така
Какво решихме в този урок, заедно с това, което отхвърлихме, и какво би ни накарало да си променим мнението:
- Webhook-ът на куриерската фирма отговаря с 202 веднага щом е записал
Преговор
- Какво е webhook и по какво се различава от начина, по който пристига поръчката, и от начина, по който пристига пратката?
- Какво е 214 и какво носи в сегмента си
B10? - Защо рутерът отговаря на куриерската фирма с 202, а не с това, което са казали API-то, ERP и партньорът?
- Защо на известие за поръчка, която не съществува, се отговаря с 404, а не със сървърна грешка?
- Заключителният въпрос: „доставих пратката“ е събитие; „създай тази поръчка“ е заявка. С по един пример от курса за всяко обясни по какво се различават и как се променя това, което отговаря рутерът.
Следва: в урок 17 светът се разбърква: доставката на 4002 пристига преди нейната товарителница. Рутерът не може да я разпредели още, но не може и да я изхвърли. Какво правиш с нея?
Предпочитате имейл? Пишете ни на hola@habil.mx