Toplu Sipariş Pipeline: Kuyruk, Batch ve Kısmi Başarı

Toplu sipariş sistemi, yüzlerce müşteri talebini tek bir API çağrısına doldurmak değildir. Sağlam bir pipeline; siparişleri doğrular, en fazla 100 öğelik batch’lere ayırır, RoketBayim add_bulk yanıtındaki her satırı yerel kayıtla eşler ve kısmi başarıları güvenli biçimde yönetir. Bu rehber kuyruk, batch, retry ve hata kuyruğu tasarımını açıklar.

add_bulk davranışını doğru anlayın

RoketBayim API dokümantasyonuna göre add_bulk aynı istekte en fazla 100 sipariş kabul eder. İşlem atomik değildir: bazı siparişler order ID döndürürken bazıları servis veya miktar hatası alabilir. Tüm batch tek başarı veya hata olarak işlenmemelidir.

{
  "0": { "error": "Order 1: Service not found" },
  "1": { "order": 23502 },
  "2": { "error": "Order 3: Quantity must be at least 100" }
}

Yanıt anahtarı gönderim sırasını temsil eder. Her öğenin yerel referansı batch oluşturulurken sıra numarasıyla eşlenmelidir.

Önerilen pipeline aşamaları

Batch’e girmeden önce doğrulama

Geçersiz siparişi API’ye göndermek batch kapasitesini ve operasyon süresini boşa harcar. Güncel services yanıtından service, type, min, max ve kullanılabilirlik bilgilerini yerel katalogda tutun. Sipariş anında katalog yaşını kontrol edin.

• Servis ID güncel katalogda var mı?
• Link seçilen platform ve hedef türüyle uyumlu mu?
• Default serviste quantity min-max aralığında mı?
• Custom Comments serviste comments var mı ve satırlar temiz mi?
• Yerel sipariş daha önce gönderilmiş mi?
• Kampanya veya müşteri bütçe kuralı karşılanıyor mu?

Batch oluşturma stratejisi

Boyut

Üst sınır 100 olsa da her batch’in mutlaka 100 olması gerekmez. Trafik hacmi, bekleme toleransı ve worker kapasitesine göre daha küçük gruplar kullanılabilir. Düşük trafikte batch’in dolmasını uzun süre bekletmeyin; maksimum bekleme zamanı belirleyin.

Gruplama

Operasyonel görünürlük için batch’leri müşteri, para birimi veya servis sınıfına göre gruplayabilirsiniz. Ancak gereksiz parçalama çağrı sayısını artırır. En önemli gereksinim her öğenin yerel kimliğinin korunmasıdır.

Sıra kararlılığı

orders dizisi oluşturulduktan sonra yanıt işlenene kadar sıralama değişmemelidir. Her satır için batch_id ve batch_index saklayın. Yanıt index 3 döndürdüğünde hangi yerel siparişe ait olduğu kesin olmalıdır.

Örnek batch kaydı

{
  "batch_id": "B-20260813-0042",
  "status": "submitting",
  "items": [
    { "index": 0, "local_order_id": "L-101" },
    { "index": 1, "local_order_id": "L-102" },
    { "index": 2, "local_order_id": "L-103" }
  ]
}

Batch kaydı, API isteğinin özeti ve gönderim zamanıyla birlikte kalıcı yazılmalıdır. Yalnız bellekte tutulan index eşlemesi worker yeniden başladığında kaybolabilir.

Kısmi başarı işleme

Her yanıt öğesini bağımsız işleyin. order alanı varsa provider_order_id kaydedilir ve kayıt tracking kuyruğuna geçer. error varsa hata sınıflandırılır ve yerel durum failed veya review yapılır.

Yetersiz bakiye yönetimi

API, gerekli ve kullanılabilir tutarı içeren yetersiz bakiye hatası döndürebilir. Bu durumda batch’in hangi aşamada reddedildiğini ve satır bazında sonuç bulunup bulunmadığını kontrol edin. Yanıt açıkça hiçbir order üretmediyse kayıtlar bakiye bekleme durumuna alınabilir.

Bakiyeyi çok sık sorgulamak yerine büyük batch öncesi balance kontrolü ve yerel bütçe rezervasyonu kullanın. Eş zamanlı worker’ların aynı bakiyeyi harcamasını önlemek için yerel limit uygulayın. Balance yalnız anlık görüntüdür; gerçek sipariş yanıtı nihai karardır.

Kuyruk bölümlendirme

Tek bir kuyruk yerine en azından gönderim, takip ve inceleme işlerini ayırmak yararlıdır:

• order-submit: doğrulanmış yeni siparişler
• order-track: provider_order_id alınmış aktif siparişler
• order-review: belirsiz yanıt, eşleşme veya operasyon kararı gerektiren kayıtlar
• order-dead-letter: deneme sınırını aşan teknik işler

Bu ayrım, yeni sipariş trafiğinin uzun süren takip veya hata işlemleri tarafından bloke edilmesini önler.

Dead-letter queue kullanımı

Aynı teknik hata belirlenen deneme sayısını aştığında mesajı sonsuz döngüde tutmayın. Dead-letter kuyruğuna taşıyın ve hata nedeni, deneme sayısı, son zaman ve ilgili batch ID’yi saklayın.

İş kuralı hataları doğrudan kullanıcı düzeltmesi gerektirdiği için teknik retry kuyruğuna hiç girmemelidir. DLQ yalnız geçici olduğu düşünülen fakat çözülemeyen teknik işler için kullanılmalıdır.

Retry ve belirsiz batch sonucu

Bağlantı kurulmadan önce hata oluştuğu kesin ise kontrollü retry düşünülebilir. İstek gönderildikten sonra yanıt alınamadıysa batch’in uzak tarafta işlenmiş olma ihtimali vardır. Tüm batch’i tekrar göndermek yüksek mükerrer riskidir.

Belirsiz batch’i review durumuna alın; gönderim zamanı, istek özeti ve yerel öğeleri saklayın. Otomatik yeniden gönderim yerine operasyonel mutabakat uygulayın.

Durum takip batch’leri

Başarılı order ID değerleri, action=status ve orders parametresiyle çoklu sorgulanabilir. Takip batch’i oluştururken yalnız aktif siparişleri seçin. Completed, Partial veya Canceled kayıtları kuyruktan çıkarın.

Durum yanıtında bir order için error bulunması diğer geçerli siparişlerin işlenmesini engellememelidir. Her ID sonucunu bağımsız yazın.

Worker eş zamanlılığı

Bir batch yalnız tek worker tarafından submitting durumuna geçirilmelidir. Atomik durum geçişi veya kayıt kilidi kullanın. Worker kapanırsa lease süresi sonunda batch yeniden incelenebilir; fakat API’ye gönderilip gönderilmediği belirsizse doğrudan tekrar yapılmamalıdır.

Birden fazla worker aynı yerel siparişi farklı batch’lere alamamalıdır. Sipariş kaydında batch_id için tek aktif sahiplik ve idempotency kısıtı kullanın.

Gözlemlenmesi gereken metrikler

• Dakika başına ingest ve submit edilen sipariş sayısı
• Batch başına ortalama öğe sayısı
• Kuyruk bekleme süresi
• Başarılı order ve error oranı
• Service not found ve miktar hatası sayısı
• Belirsiz batch ve DLQ büyüklüğü
• Pending, Processing ve terminal sipariş sayıları
• Batch gönderim gecikmesi ve API yanıt süresi

Test planı

• 1, 99, 100 ve 101 siparişlik girişler
• Batch içinde tek ve birden fazla iş kuralı hatası
• Tüm satırların başarılı olması
• Yetersiz bakiye yanıtı
• Eksik veya beklenmeyen index
• Yanıt sonrası worker kapanması
• Aynı siparişin iki batch’e alınmaya çalışılması
• Belirsiz zaman aşımı
• DLQ’ya taşıma ve kontrollü geri alma

Canlıya geçiş kontrol listesi

1. Her sipariş için benzersiz yerel kimlik ve idempotency kısıtı oluşturun.
2. Batch ID ve index eşlemesini kalıcı saklayın.
3. Kısmi yanıtı satır bazında işleyin.
4. Başarılı satırların retry edilmesini engelleyin.
5. Belirsiz sonuç için review prosedürü hazırlayın.
6. Submit, track ve DLQ kuyruklarını izleyin.
7. Küçük hacimle başlayıp sonuç eşleşmesini doğrulayın.

Backpressure ve kapasite koruması

Gelen sipariş hızı worker kapasitesini aştığında kuyruk sürekli büyür. Sistem yeni sipariş kabul etmeye devam ederken teslimat gecikmesi görünmez hâle gelebilir. order_queue_age ve kuyruk uzunluğuna göre backpressure uygulayın.

Kritik eşiklerde kullanıcıya gecikme bilgisi göstermek, düşük öncelikli kampanyaları bekletmek veya belirli müşteri limitlerini geçici olarak azaltmak mümkündür. Siparişi kabul edip saatlerce gönderim kuyruğunda gizlemekten daha şeffaftır.

Önceliklendirme

Birden fazla öncelik kuyruğu kullanıyorsanız düşük öncelikli işlerin sonsuza kadar beklememesini sağlayın. Yüksek öncelik trafiğine maksimum pay ayırın veya yaşlandıkça önceliği artırın. Öncelik, aynı batch içindeki index eşlemesini ve idempotency kuralını değiştirmemelidir.

Batch boyutu için deneysel yaklaşım

10, 25, 50 ve 100 öğelik batch’lerde API yanıt süresi, error oranı, kuyruk yaşı ve worker bellek kullanımını ölçün. En büyük batch her zaman en yüksek verimi sağlamaz. Düşük trafikte küçük batch daha hızlı kullanıcı deneyimi sunabilir.

Batch oluşturucuda hem maksimum boyut hem maksimum bekleme süresi olmalıdır. Örneğin grup dolmasa bile yaş sınırına ulaşınca gönderilir. Değerleri gerçek trafik ve ölçümlere göre belirleyin.

Adil kullanım

Tek bir büyük müşterinin kuyruğu diğer müşterilerin siparişlerini geciktirebilir. Müşteri başına eş zamanlı gönderim sınırı veya round-robin seçim uygulanabilir. Ancak bir müşterinin aynı linkteki siparişlerini sıraya koymak çakışmayı önlemek açısından ayrıca değerlidir.

Şema ve veri kalitesi hataları

Batch worker, yerel kayıtta eksik service, link veya quantity gördüğünde bütün grubu durdurmamalıdır. Hatalı öğeyi validation error ile ayırıp diğer geçerli kayıtları batch’e alabilir. Buna karşılık index eşleme tablosu bozuksa tüm batch güvenli biçimde review durumuna alınmalıdır.

Yeniden oynatma aracı

Operasyon ekibine “batch’i tekrar gönder” düğmesi vermeyin. Yeniden oynatma aracı satır bazında çalışmalı, provider_order_id bulunmadığını ve hatanın düzeltildiğini doğrulamalıdır. İşlem önizlemesinde kaç satırın gönderileceği, kaçının zaten başarılı olduğu gösterilmelidir.

Maliyet ve bakiye rezervasyonu

Yerel sistem tahmini maliyeti servis rate ve miktardan hesaplayıp batch hazırlanırken rezervasyon yapabilir. Gerçek charge yanıtı geldiğinde rezervasyon nihai tutarla mutabık hâle getirilir. Rate veya currency değişimi ihtimaline karşı rezervasyon kesin muhasebe kaydı sayılmamalıdır.

Yetersiz bakiye durumunda tüm müşterilerin kayıtlarını sınırsız retry kuyruğuna atmak yerine bakiye bekleme havuzu oluşturun. Bakiye güncellendiğinde kontrollü ve yaş sıralı serbest bırakın.

Batch sürümleme

Batch payload oluşturulduktan sonra değişmez kabul edilmelidir. Bir satırın servis veya miktarı değişirse mevcut batch’ten çıkarılıp yeni sürümde yeniden doğrulanmalıdır. Gönderilen payload’ın hash’ini saklamak, yanıtın hangi veri setine ait olduğunu kanıtlar.

Operasyon raporu

Her batch için toplam satır, başarılı order, iş kuralı hatası, belirsiz sonuç ve işlem süresi raporlanmalıdır. Servis bazında hata dağılımı katalog senkronizasyonu veya doğrulama kuralı sorunlarını ortaya çıkarır.

Gün sonunda yerel başarılı satır sayısı ile kaydedilmiş provider order ID sayısı eşleşmelidir. Fark varsa yeni batch göndermeden önce mutabakat kuyruğu incelenir.

Şema uyumluluğu

Producer ve worker farklı sürümlerde çalışıyorsa kuyruk mesajına schema_version ekleyin. Worker desteklemediği yeni sürümü sessizce işlememeli; mesajı güvenli inceleme kuyruğuna almalıdır. Yeni alanlar mümkün olduğunca geriye uyumlu ve opsiyonel eklenmelidir.

Deploy sırasında eski mesajların hâlâ kuyrukta bulunabileceğini unutmayın. Entegrasyon testi yalnız yeni producer ile yeni worker’ı değil, eski-yeni sürüm kombinasyonlarını da kapsamalıdır.

Şema geçişi öncesinde kuyruk yaşı, aktif batch sayısı ve geri alma planı doğrulanmalıdır. Uyumsuz mesajlar silinmemeli; özgün payload ve hata nedeni korunarak inceleme kuyruğuna aktarılmalıdır.

Aktarım sonuçları zaman damgasıyla denetim geçmişine eksiksiz biçimde kaydedilmelidir.