Съдържание на курса
Урок 17 — Доставката пристигна преди товарителницата
От Dorian Chávez · съосновател и 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. Предвиди
Отговори на лист хартия:
- Пристига доставката на 4002, а пратката ѝ още не. Какво трябва да остане в базата? Какво трябва да получи всяка дестинация?
- После пристига пратката. Кой разбира, че доставката вече може да излезе? Кога?
- Ако обхождането мине два пъти, може ли доставката да излезе два пъти? Какво би го предотвратило?
Виж какво е положението днес:
./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 = … е вид
ключалка: само един може да прехвърли реда от едно състояние в друго. Ще срещнеш тази идея в почти всяка система,
която разпределя работа.
Упражнение: правилото като данни
С твоята завършена версия:
- Какво би трябвало да добавиш в машината на състоянията за ново събитие,
devuelta, което има нужда от доставката? Напиши го. Би ли трябвало да пипнеш някой маршрут? - Отвори петте еталонни случая на решението. За
entrega-con-embarque-pendienteзащо решението е паркиране, щом пратката вече е пристигнала? - В базата, след
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.
Защо е направено така
Какво решихме в този урок, заедно с това, което отхвърлихме, и какво би ни накарало да си променим мнението:
- Това, което пристига преди времето си, се паркира, не се отхвърля
Преговор
- Какво означава една операция да е
estacionadaи по какво се различава отpendiente? - Какво казва машината на състоянията за доставката и защо е по канал?
- За какво служи
AND estado = 'estacionada'в UPDATE-а на обхождането? - Защо обхождането проверява
CamelSqlUpdateCount, преди да сложи на опашката? - Заключителният въпрос: обхождането го пуска събитие — това, че един канал е приел едно събитие от жизнения цикъл, — а не таймер, който проверява базата всяка минута. Какво печелиш със събитието? Какво би загубил с таймера и в кой случай все пак би ти потрябвал такъв?
Следва: в урок 18 започва част 3, „да не се проваля“. Първо — един въпрос, който изглежда лесен: кога две съобщения са едно и също?
Предпочитате имейл? Пишете ни на hola@habil.mx