Съдържание на курса
Урок 06 — Сглобяване на EDI
От Dorian Chávez · съосновател и 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-ката по-горе. Без да търсиш нищо, отговори на лист хартия:
- На всеки ред има
*и~. Какво според теб разделя всеки от тях? - На кой ред според теб е номерът на поръчката (1001)? А редовете ѝ?
- Думите
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 се сглобява с шаблон без логика
Преговор
- Какво разделя
*и какво разделя~в един X12? - Кои са трите плика на документа и кой сегмент отваря и затваря всеки?
- Защо
ISAноси интервали за допълване? - Какво прави мапингът и какво прави шаблонът? Защо е добре да не се смесват?
- Защо не може да има
*в името на продукт и какво става с&, ако използваш двойни скоби?
Следва: в урок 07 850-ката вече не остава в salida/: пътува до SFTP пощенската кутия на партньора, като внимаваме
той да не вземе файл наполовина.
Предпочитате имейл? Пишете ни на hola@habil.mx