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

Урок 06 — Сглобяване на EDI

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

Какво ще постигнеш: да превърнеш поръчката в документа, който очаква търговският партньор — един X12 850, и да провериш с четец на испански, че е сглобен правилно. Днес средата не е нужна: само Docker.

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

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

API-то говори JSON, а ERP говори с таблици. Търговският партньор говори EDI: текстов формат, който фирмите използват още отпреди да съществува интернет, за да си пращат поръчки за покупка, фактури и известия за изпращане. Този, който използва нашият партньор, се казва X12, а поръчката за покупка е документът 850.

Така изглежда една поръчка 850:

ISA*00*          *00*          *ZZ*TIENDANORTE    *ZZ*SOCIO01        *261112*1015*U*00401*000001001*0*P*>~
GS*PO*TIENDANORTE*SOCIO01*20261112*1015*1001*X*004010~
ST*850*0001~
BEG*00*SA*1001**20261112~
N1*ST*Tienda T-014*92*T-014~
PO1*1*2*EA*89.50**VN*SKU-0001~
PID*F****Taza blanca~
PO1*2*1*EA*249.00**VN*SKU-0042~
PID*F****Mantel azul~
CTT*2~
SE*9*0001~
GE*1*1001~
IEA*1*000001001~

Няма имена на полета като в JSON: всяка стойност важи според позицията си. Изглежда нечетимо, но днес ще се научиш да го четеш.


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

cd lecciones/06-armar-el-edi
cp -R inicio mio

2. Предвиди

Погледни 850-ката по-горе. Без да търсиш нищо, отговори на лист хартия:

  1. На всеки ред има * и ~. Какво според теб разделя всеки от тях?
  2. На кой ред според теб е номерът на поръчката (1001)? А редовете ѝ?
  3. Думите TIENDANORTE и SOCIO01 се появяват по два пъти. На първия ред имат излишни интервали в края, а на втория — не. Защо според теб е така?

3. Прочети го с четеца

Курсът носи четец, който обяснява един X12 на испански. От папката на урока:

../../herramientas/leer-x12 ../../datos/edi/850-ejemplo.edi

Сравни с предвиждането си:

  • ~ затваря сегмент. Сегментът е като ред от документа, а името му са първите букви (ISA, BEG, PO1…).
  • * разделя елементите на един сегмент. Четецът ги номерира: в BEG*00*SA*1001**20261112 елемент 03 е 1001, номерът на поръчката. Две * едно след друго означават, че този елемент е празен.
  • Редовете от поръчката са двойките PO1 (количество, мерна единица, цена и продукт) и PID (описание).

Документът пътува в два плика, като писмо в колет:

Отваря Затваря Какво е
ISA IEA Външният плик: кой праща, на кого и един контролен номер
GS GE Група документи от един и същи тип (тук — поръчки за покупка)
ST SE Документът: поръчката 850

Всеки плик се затваря, като повтаря контролния си номер, а SE освен това брои колко сегмента има документът, от ST до SE. Така партньорът знае дали нещо се е загубило по пътя.

А интервалите от въпрос 3? ISA е с фиксирана ширина: винаги е 106 знака и всяка стойност заема точно определено място. TIENDANORTE има 11 букви, а мястото му е 15, така че се допълва с 4 интервала.

Накрая четецът прави шест проверки (ширината на ISA, контролните номера, броя в SE…). Ако някоя не мине, излиза в червено.

4. Мапингът изчислява, шаблонът подрежда

Маршрутът mio/orden-a-edi.camel.yaml сглобява 850-ката на две стъпки, всяка с една-единствена задача:

Част Нейната задача Къде живее
Мапингът (JSONata, както в урок 03) Изчислява всичко: допълването до 15, контролния номер от 9 цифри (1001 → 000001001), датите, цените с два знака след запетаята, броя за SE и изчистения текст mio/mappings/edi/850/v1/ · идва готов
Шаблонът (Mustache) Подрежда вече изчисленото на мястото му в документа. Не изчислява нищо mio/templates/edi/850/v1/850.mustache · твой ред е

Тествай го както в урок 03 и отвори mio/mappings/edi/850/v1/cases/dos-renglones/esperado.json, за да видиш какви данни стигат до шаблона:

../../herramientas/probar-mapeo mio/mappings/edi/850/v1

Защо да разделяме двете задачи? Защото всяка се тества отделно. Изчислението си има еталонни случаи; шаблонът трябва само да сложи всяка стойност на мястото ѝ. Ако смесиш изчисленията вътре в шаблона, няма да има начин да ги тестваш.

5. Довърши шаблона

Отвори mio/templates/edi/850/v1/850.mustache. Вече носи плика, началото на документа и за кого е:

ISA*00*          *00*          *ZZ*{{{body.isa.emisor}}}*ZZ*{{{body.isa.receptor}}}*…~
GS*PO*{{{body.gs.emisor}}}*…~
ST*850*{{{body.st.control}}}~
BEG*00*SA*{{{body.beg.orden}}}**{{{body.beg.fecha}}}~
N1*ST*{{{body.tienda.nombre}}}*92*{{{body.tienda.clave}}}~

Всяко {{{ … }}} е празно поле, което Mustache попълва със стойност от мапинга. Липсват ти две части. Пълните указания са в LEEME.md, до шаблона.

Редовете. Трябват ти по един PO1 и един PID за всеки ред, а редовете са в body.lineas. В Mustache една секция повтаря това, което е вътре в нея, по веднъж за всеки елемент от списък:

{{#body.lineas}}
… lo que va por cada renglón, usando {{{n}}}, {{{cantidad}}}, {{{precio}}}, {{{sku}}} y {{{descripcion}}} …
{{/body.lineas}}

Вътре в секцията вече си застанал върху един ред, също както вътре в renglones.{ … } в JSONata. Използвай примерната 850-ка и четеца, за да разбереш на коя позиция отива всяка стойност.

Затварянето. След редовете: CTT (колко реда), SE (броят на сегментите и контролният номер на ST), GE и IEA. Всички числа вече идват изчислени в body.ctt, body.se.segmentos и контролните номера.

Две правила:

  • Не пиши коментари вътре в шаблона: там, където е имало коментар, Mustache оставя празен ред, а празен ред е грешка в X12.
  • Използвай тройни скоби {{{ }}}. В стъпка 7 ще видиш защо.

6. Пусни го и го прочети

От mio/ сложи две поръчки в entrada/ и стартирай маршрута:

cd mio
mkdir -p entrada
cp ../../../datos/ordenes/orden-1001.json ../../../datos/ordenes/orden-1005-caracteres.json entrada/
../../../herramientas/camel run orden-a-edi.camel.yaml

Когато видиш Generé el 850 de la orden 1005, спри го с Ctrl+C и прочети какво е излязло:

../../../herramientas/leer-x12 salida/850-1001.edi
diff salida/850-1001.edi ../../../datos/edi/850-ejemplo.edi

Ако четецът даде шестте зелени отметки, а diff не отпечата нищо, твоята 850-ка за поръчка 1001 е идентична с примерната.

7. Знаците, които чупят един документ

Отвори datos/ordenes/orden-1005-caracteres.json в основната папка на курса. Двата ѝ продукта имат неудобни имена:

Продукт в поръчката Как излиза в 850-ката
Taza & plato Taza & plato
Juego 4*6 ~ cristal Juego 4 6 cristal

Предвиди: защо второто име се е променило? Помисли какво би направил партньорът, като прочете PID*F****Juego 4*6 ~ cristal~.

* и ~ са разделителите на документа, а също и >: ISA ги декларира (> е последният му елемент). Ако са вътре в стойност, партньорът би прочел един елемент в повече и един сегмент, отрязан наполовина. Затова мапингът ги заменя с интервали, преди да стигнат до шаблона, а еталонният случай caracteres-especiales проверява, че го прави.

Сега за &. Той не е разделител: X12 го приема вътре в стойност и партньорът би го прочел добре. Рискът при него е друг и идва от шаблона. Смени само {{{descripcion}}} с {{descripcion}}, с двойни скоби, и пусни отново маршрута. Виж PID на поръчка 1005:

PID*F****Taza & plato~

Mustache е създаден, за да прави уеб страници, и с двойни скоби „защитава“ текста, сякаш е HTML: & се превръща в &. В уеб страница това е правилното. В X12 партньорът би получил продукт, който се казва Taza & plato. Тройните скоби казват на Mustache: сложи стойността точно каквато е. Върни тройните скоби.

8. Провери

От папката на урока:

cd ..
./verifica

verifica изпразва mio/entrada/ и mio/salida/, генерира 850-ките за поръчки 1001 и 1005 и ги проверява с четеца. Урокът е завършен, когато видиш петте зелени отметки:

✅ El mapeo del 850 pasa sus casos dorados
✅ El 850 de la 1001 es un X12 bien armado (el lector no encontró fallas)
✅ El 850 de la 1005 es un X12 bien armado (el lector no encontró fallas)
✅ El 850 de la 1001 es idéntico al de ejemplo
✅ El 850 de la 1005 (con & y *) es el esperado

Не тръгва? ./verifica solucion тества нашето решение, а diff mio/templates/edi/850/v1/850.mustache solucion/templates/edi/850/v1/850.mustache ти казва по какво се различават.

Какво виждаш Какво правиш
trae &: usa llaves TRIPLES Някоя скоба е останала двойна: върни се на стъпка 7
no pasa la revisión del lector Пусни leer-x12 върху този файл: проверката в червено казва какво липсва (почти винаги затварянето)
no es idéntico al de ejemplo Сравни ги с diff: обикновено е елемент на друга позиция или едно * по-малко

Какво научихме, докато сглобявахме този урок

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

  • Функция, която „почиства“, може да счупи фиксираната ширина. JSONata има $trim, която маха интервали. Тя също така слива повтарящите се интервали в един, а това би изтрило допълването на ISA. Затова мапингът използва $pad, която допълва, и никога $trim върху поле с фиксирана ширина.
  • Броенето на ръка греши. При писането на примерната 850-ка SE казваше 10 сегмента там, където имаше 9. Четецът го отбеляза в червено. Затова броенето го прави мапингът, а го проверява инструмент, не човек.

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

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

  • EDI се сглобява с шаблон без логика

Преговор

  1. Какво разделя * и какво разделя ~ в един X12?
  2. Кои са трите плика на документа и кой сегмент отваря и затваря всеки?
  3. Защо ISA носи интервали за допълване?
  4. Какво прави мапингът и какво прави шаблонът? Защо е добре да не се смесват?
  5. Защо не може да има * в името на продукт и какво става с &, ако използваш двойни скоби?

Следва: в урок 07 850-ката вече не остава в salida/: пътува до SFTP пощенската кутия на партньора, като внимаваме той да не вземе файл наполовина.

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

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