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

Урок 17 — Доставката пристигна преди товарителницата

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

Какво ще постигнеш: доставка, която пристига преди своята пратка, нито да се губи, нито да се праща не навреме: остава паркирана в базата и излиза сама, само веднъж, веднага щом пристигне пратката.

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

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

В урок 16 всичко пристигна поред: поръчката беше създадена, после изпратена и накрая доставена. Но складът и куриерската фирма не си говорят и понякога известието за доставка пристига преди файла за пратката. Ако рутерът го разпредели така, API-то и ERP го отхвърлят: не може да се достави нещо, което за тях никога не е излизало. А ако го изхвърли, клиентът никога няма да се появи като обслужен. Днес го паркираш и го освобождаваш, когато вече може да излезе.

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


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

cd lecciones/17-la-entrega-llego-antes-que-la-guia
cp -R inicio mio

Днес рутерът носи нови части. Почти всички вече са направени: твоята работа е последната.

Част Къде Пишеш ли я?
Машината на състоянията: кое събитие от жизнения цикъл от кое има нужда, във всеки канал mio/orden-router/reglas/maquina-de-estados.yaml Не, прочети я
Решението: с машината и записаното казва procesa, estaciona или invalido direct:decidir, със своя мапинг в mappings/estado/decision/v1/ и своите еталонни тестови случаи Не, прочети го
Паркирането: при записване на едно събитие всяка операция се ражда pendiente или estacionada guardar-momento, в estado.camel.yaml Не, вече е готово
Обхождането: освобождава паркираното, което вече може да излезе barrido.camel.yaml Да

Отвори машината на състоянията. Чете се така: в канала rest събитието entregada има нужда embarcada вече да е приета в същия този канал. Правилото е по канал, защото всяка дестинация си има собствена последователност: това, че API-то вече има пратката, не казва нищо за ERP.

Отвори и един еталонен случай на решението, cases/entrega-sin-embarque/: неговия entrada.json и неговия esperado.json. Същата идея като в урок 03: правилото се тества с примери, а не с вяра.

2. Предвиди

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

  1. Пристига доставката на 4002, а пратката ѝ още не. Какво трябва да остане в базата? Какво трябва да получи всяка дестинация?
  2. После пристига пратката. Кой разбира, че доставката вече може да излезе? Кога?
  3. Ако обхождането мине два пъти, може ли доставката да излезе два пъти? Какво би го предотвратило?

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

./verifica inicio

Доставката се паркира правилно, но обхождането не освобождава нищо: макар пратката да пристига, доставката остава паркирана завинаги. 4002 никога не се появява като ENTREGADO.

3. Напиши обхождането

Отвори mio/orden-router/barrido.camel.yaml. Отгоре е barrido-http, вратата, през която се иска обхождане на ръка с POST /barrido; тя вече е готова. Твоята работа е маршрутът barrido, с четири TODO:

TODO Какво пишеш За какво
1 Един to със sql:SELECT id, orden, momento, canal FROM operacion WHERE estado = 'estacionada' ORDER BY id Да донесеш паркираното, в реда, в който е пристигнало
2 Един split върху ${body}; вътре — четири променливи (operacion, orden, momento, canal, от ${body[id]}, ${body[orden]}…) и извикване на direct:decidir Да решиш отново за всяка с това, което днес има в базата
3 Ако ${variable.decision} == 'procesa': UPDATE operacion SET estado = 'pendiente' WHERE id = … AND estado = 'estacionada' Да я прехвърлиш в чакаща, само ако още е паркирана
4 Ако ${header.CamelSqlUpdateCount} == 1: към seda:repartir с pattern: InOnly Да сложиш разпределянето на опашка, само ако ти си този, който я е променил

За „ако…“ използвай filter: пропуска съобщението само когато условието е изпълнено. TODO 4 е вътре във filter-а от TODO 3.

Това AND estado = 'estacionada' от TODO 3 е сърцето на урока. Представи си две обхождания по едно и също време: и двете четат паркираната доставка и двете решават procesa. Първото я променя: базата отговаря „промених 1 ред“. Второто закъснява и тъй като тя вече не е паркирана, базата отговаря „промених 0“. Само този, който е променил 1, я слага на опашката. Базата решава кой печели, а не късметът.

А кой вика обхождането? Отвори reparto.camel.yaml и намери direct:barrido, почти в края: вика се всеки път, когато един канал приеме едно събитие, защото това е единственото, което може да отключи друго. Няма часовник, който да го пуска от време на време.

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

С твоето завършено обхождане коментирай в reparto.camel.yaml стъпката, която вика direct:barrido. Вдигни услугите, създай 4002, прати доставката ѝ и после остави партидата от склада, която носи нейната пратка:

DONDE=mio docker compose -f compose.yaml up -d
curl -s -XPOST localhost:8080/ordenes -H 'Content-Type: application/json' -d @../../datos/ordenes/tramo-2/orden-4002.json
curl -s -XPOST localhost:8080/webhooks/paqueteria -H 'Content-Type: application/json' -d @../../datos/webhooks/entrega-4002.json
cp ../../datos/embarques/lote-bodega-0001.json buzon/

Партидата носи пратки за други поръчки, които днес не си създал; рутерът ги отхвърля с 404 и това е в реда на нещата. Изчакай няколко секунди и попитай базата:

docker compose -f ../../infra/compose.yaml exec estado psql -U router -d estado \
  -c "SELECT momento, canal, estado FROM operacion WHERE orden = '4002' ORDER BY id"

Преди това предвиди: в какво състояние е доставката?

Пратката вече е aceptada в трите канала, но доставката остава estacionada. Никой не е съобщил, че нещо се е променило. Сега поискай обхождането на ръка и попитай отново:

curl -s -XPOST localhost:8080/barrido

Сега вече излиза. Точно това прави събитието: съобщава в точния миг. Без него някой би трябвало да го поиска или един часовник би трябвало да проверява базата от време на време, дори нищо да не се е случило. Върни извикването и изключи:

DONDE=mio docker compose -f compose.yaml down

5. Провери

./verifica

verifica създава 4002, праща доставката ѝ преди пратката ѝ, проверява, че се е паркирала, оставя пратката в пощенската кутия и накрая иска обхождане на ръка, за да провери, че нищо не излиза два пъти. Урокът е завършен, когато видиш десетте зелени отметки:

✅ Arrancaron el router (con su máquina de estados y el barrido), los tres canales y el sondeo
✅ La 4002 está creada: CREADO en la API y REGISTRADO en el ERP
✅ La entrega de la 4002 llegó antes que su embarque y el router contestó 202 «recibida»
✅ Estado: las tres operaciones de la entrega quedaron estacionadas, sin ningún intento
✅ Destinos: a nadie le llegó la entrega a destiempo (la API sigue en CREADO, el ERP sin entrega, sin 214)
✅ Estado: llegó el embarque, el barrido soltó la entrega y los seis quedaron aceptados; la orden va en «entregada»
✅ API: la 4002 está ENTREGADO, con su guía
✅ ERP: la 4002 está ENTREGADO y su fila de entrega tiene la guía
✅ Socio: el 214 de la 4002 está en su SFTP y el lector X12 no le encontró fallas
✅ Una sola vez: un intento por canal para la entrega y un solo 201 en la API, aunque el barrido corrió otra vez a mano

Четвъртата и последната са най-важните. Паркираното няма опити: не е излязло никъде. А допълнителното обхождане не повтори нищо.

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

Какво виждаш Какво правиш
después del embarque, embarque y entrega quedaron … с доставката в estacionada Липсва TODO 3 или 4, или filter сравнява decision с друга дума: тя е 'procesa'
${body[id]} излиза празно SELECT не носи колоната id или променливите са останали извън split
Esperaba el barrido a mano en 200, 3 intentos de la entrega y un 201, а има повече UPDATE не носи AND estado = 'estacionada' или не си филтрирал по CamelSqlUpdateCount
Нищо не влиза в опашката, макар UPDATE да е променил реда to към seda:repartir е останал извън втория filter или липсва pattern: InOnly
El puerto 8080 está ocupado Услугите от стъпка 4 са останали вдигнати: DONDE=mio docker compose -f compose.yaml down

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

Последователността, в която нещата пристигат, не е последователността, в която са се случили. Между системи, които не се координират, едно известие може да изпревари друго. Шаблонът, който решава това, се нарича Resequencer: да запазиш това, което е пристигнало извън реда си, и да го освободиш в правилния ред.

Правилото кой е преди кого живее на едно-единствено място. То е в YAML, който се чете като данни. Да добавиш ново събитие, например връщане, означава да добавиш един ред, а не още един маршрут.

Когато два процеса се състезават за едно и също, нека реши базата. UPDATE … WHERE … AND estado = … е вид ключалка: само един може да прехвърли реда от едно състояние в друго. Ще срещнеш тази идея в почти всяка система, която разпределя работа.

Упражнение: правилото като данни

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

  1. Какво би трябвало да добавиш в машината на състоянията за ново събитие, devuelta, което има нужда от доставката? Напиши го. Би ли трябвало да пипнеш някой маршрут?
  2. Отвори петте еталонни случая на решението. За entrega-con-embarque-pendiente защо решението е паркиране, щом пратката вече е пристигнала?
  3. В базата, след verifica, преброй опитите за доставката на 4002: SELECT o.canal, COUNT(i.id) FROM operacion o LEFT JOIN intento i ON i.operacion = o.id WHERE o.orden = '4002' AND o.momento = 'entregada' GROUP BY o.canal. Колко очакваш на канал и защо не са два, макар обхождането да мина два пъти?

Какво вече работи

С този урок затваряш част 2. Освен това от част 1, една поръчка вече прави следното:

  • изпраща се от файл на склада, със или без партида, без той да се взема наполовина или два пъти;
  • записва се, преди да се отговори, с един ред на канал и запис за всеки опит;
  • доставя се от известието на куриерската фирма, която получава 202 веднага щом то е записано;
  • и ако доставката пристигне преди пратката, чака паркирана и излиза само веднъж, веднага щом може.

Какво още не прави: да разпознава съобщение, което пристига повторно с друго съдържание, нито да опитва отново това, което е останало в no_se_sabe. Това е част 3.

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

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

  • Това, което пристига преди времето си, се паркира, не се отхвърля

Преговор

  1. Какво означава една операция да е estacionada и по какво се различава от pendiente?
  2. Какво казва машината на състоянията за доставката и защо е по канал?
  3. За какво служи AND estado = 'estacionada' в UPDATE-а на обхождането?
  4. Защо обхождането проверява CamelSqlUpdateCount, преди да сложи на опашката?
  5. Заключителният въпрос: обхождането го пуска събитие — това, че един канал е приел едно събитие от жизнения цикъл, — а не таймер, който проверява базата всяка минута. Какво печелиш със събитието? Какво би загубил с таймера и в кой случай все пак би ти потрябвал такъв?

Следва: в урок 18 започва част 3, „да не се проваля“. Първо — един въпрос, който изглежда лесен: кога две съобщения са едно и също?

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

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