Finance + Logistics + Travelium osszevasalasa — kozos state machine

A Netorigo legbonyolultabb interface-pontja a Finance, a Logistics es a Travelium kozos hatara. Egy rendeles letrejotte utan harom modulnak kell osszehangoltan dolgozni: ki kell szamlazni, le kell szallitani, es ha utazasi termek is van benne, akkor a foglalast is rogziteni. Az alabbiakban a kozos state machine-t mutatjuk be, amire 18 honapnyi production tapasztalat tett pontot.

A rendeles ot allapota

A sales_orders.status enum elobb 14 allapotot tartalmazott. Egy retrospektiv utan ezt visszafarafogtuk ot domain-allapotra, mert a tobbit modul-szinten lehet kezelni:

1. pending — a kosar checkout-on at, fizetes-igazolas vagyas.
2. confirmed — fizetes megerkezett, a rendeles "el".
3. fulfilling — legalabb egy modul aktívan dolgozik rajta (logistics pickelese, finance szamla, travelium foglalas).
4. completed — minden modul vegzett, az ugyfel megkapta a termeket / szolgaltatast.
5. cancelled — barmely modul vetozta (refund initialted, vagy soha sem fulfillte).

A pending → confirmed egy fizetes-callback. A confirmed → fulfilling automatikus, amint a Finance modul megerkezett szamlat allitott ki. A fulfilling → completed egy aggregalt: minden modul-specifikus sub-allapot done kell hogy legyen.

A modul-specifikus sub-allapotok

Minden modul a sajat tablajaban tarol egy order_module_state rekordot, ami a kozos order_id-ra hivatkozik. Igy:

• Finance: invoice_state = (pending | issued | paid | refunded)
• Logistics: shipment_state = (waiting | picked | packed | shipped | delivered | returned)
• Travelium: booking_state = (pending | reserved | confirmed | travelled | cancelled)

Egy rendeles akkor completed, ha minden hozzakapcsolt modul-state egy „terminal happy” allapotban van: invoice = paid, shipment = delivered (ha van fizikai termek), booking = travelled (ha van utazasi termek). Ha nincs modulhoz tartozo sor, az nem blokkol — egy tisztan digitalis termek-rendeles a Logistics tablajaban sehol sem szerepel.

Az event bus mint kommunikacio

A modulok kozotti kommunikacio NEM kozvetlen API-hivasok, hanem egy eseme-bus (order_events Postgres outbox + NATS terjesztes). Egy OrderConfirmedEvent peldaul minden modul listenere felveszi, mindenki eldonti, hogy reagal-e ra:

• Finance listener: szamlat allit ki, beirja a invoice_state = issued-t.
• Logistics listener: ha van fizikai SKU, letrehoz egy pick_list rekordot, shipment_state = waiting.
• Travelium listener: ha van utazasi SKU, allotment-foglalast tesz, booking_state = reserved.

A tobbi modul (Catalog, Inventory) is hallja az eventet, de nem reagal (vagy csak metriket frissit).

Mit kell tudni a fejlesztonek aki interface-pontot epit

Ha egy uj integraciot epitesz egy 7. modullal (peldaul „Subscription”), ezeket kell betartanod:

1. Te is feliratkozol az order_events bus-ra. Sosem hivod direktben a Sales modult.
2. Sajat order_module_state rekordot vezetsz. Ha a te modulod erinti a rendelest, irsz egy sort, allapot-valtaskor frissited.
3. A fulfilling → completed aggregatorba bejelentkezel. Egy konfiguracio-elem (modules_required_for_completion) hozzaadja a te modulodot — addig nem completed a rendeles, amig nem vegeztel.
4. Cancel-eseteket kezeled. Ha a Sales modul cancelled-re viszi a rendelest, neked kell olyan rollback-logikat hivnod, hogy a modulod is takarit (peldaul a subscription-t terminalni).
5. Idempotency-kulcsot hasznalsz minden mutatation. Az event-bus at-least-once, ezert ha ket azonos eventet kapsz, csak egyszer reagalsz. Az event id egy jo idempotency-kulcs.

Egy konkret problema, amit megoldottunk

Kezdetben az volt a baj, hogy ha a Finance szamlat issued, de a Logistics meg nem szallitott, az ugyfel ket emailt kapott: egy szamlat es egy "hamarosan szallitunk" emailt — ket idopontban. A jelenlegi megoldas: a notifikacio nem modul-szintu, hanem state-machine-szintu. Az OrderStateChangedEvent kuldi az emailt csak a confirmed-re („Koszi a rendelest, szamlat csatolva, szallitas hamarosan”) es a completed-re („Megerkezett, ertekeles?”). A modul-belso allapotvaltozasok nem zarolnak emailt.

Tanulsag

A harom modul (Finance + Logistics + Travelium) osszevasalasa nem egy „REST API a Finance-ben, REST API a Logistics-ben, az osszehivok integracioja a kozepen” problema. Hanem egy kozos state machine + egy event bus problema. A kozos state machine 5 allapotos, a sub-allapotok modul-szintuek, az event bus a kapcsolat. Aki ezt megerti, az 80%-at megertette a Netorigo backend-jenek.