Egress Servisi

Egress Servisi, kurumsal müşterilerin talebiyle Qapu'da oluşan veriyi dış sistemlere (CRM, ERP, SCADA vb.) kontrollü ve izlenebilir şekilde aktarır.

Bu servis, "veriyi bizim sisteme de gönderin" ihtiyacı için tasarlanmıştır. Hedef sistem ve payload yapısı müşteriye göre değişebildiği için policy tabanlı, dönüşüm yapabilen ve güvenlik katmanlarıyla çalışan bir entegrasyon katmanı olarak konumlanır.

Sorumluluk

• API ile tanımlanan entegrasyon policy'lerine göre hangi verinin nereye gideceğini belirlemek
• Telemetri ve otomasyon kaynaklı eventleri seçip dış sistem formatına dönüştürmek
• Hedef sisteme güvenli outbound gönderim yapmak (auth/sign/allowlist)
• Retry ve DLQ sürecini yönetmek
• Kalıcı hata durumunda ilgili birime bildirim aksiyonunu tetiklemek
• Tüm outbound denemeleri denetim izi ile kaydetmek

Girdiler

• window.ready.v1 (telemetri zinciri tamamlandığında)
• automation.command.requested.v1 (otomasyon kaynaklı komut akışlarında)
• automation.job.completed.v1 (komut başarı sonucu)
• automation.job.failed.v1 (komut hata sonucu)

Not: Metrik/genişletme ihtiyacına göre ileride synth.ready.v1 veya skor eventleri de policy bazlı dahil edilebilir.

Çıktılar

• egress.sent.v1
• egress.failed.v1
• (opsiyonel) action.execute.requested.v1 (kalıcı hata bildirim aksiyonu)

Akis Diyagrami

Detaylı adımlar için Egress Servisi Akış Diyagramı sayfasına bakınız.

Veri Katmanlari Yazim Sirasi

Policy okuma, outbound yazım ve hata kaydı sırasını sequence diyagramında görmek için Veri Katmanları Arası Yazım Sırası sayfasına bakınız.

Egress Event Envelopeları

window.ready.v1 ve otomasyon event girdileri ile egress.sent.v1 / egress.failed.v1 event payload sözleşmeleri merkezi standart belgesinde tanımlanmıştır. Detaylar için Egress Event Envelopeları sayfasına bakınız.

SSS

Müşteri bazlı payload farklılıkları, güvenlik ve retry davranışı için Egress Servisi SSS sayfasına bakınız.

Entegrasyon Politikası

Entegrasyon kayıtları büyük olasılıkla API üzerinden açılır ve güncellenir. Tipik policy kararları:

• Hangi kaynak event(ler)i dışarıya açık?
• Hangi müşteri hedefi (CRM/ERP/SCADA) bu veriyi alacak?
• Hangi dönüşüm profili kullanılacak?
• Hangi güvenlik profili (API key, mTLS, imza) zorunlu?

Ilgili Data-Model Tablolari

• egress_policies
• egress_deliveries

Topic ve Event Standardı

• Topic:
  • qapu.egress.events (ana Egress event topic'i)
  • qapu.dlq.egress (yalnız DLQ)
• Event:
  • egress.sent.v1
  • egress.failed.v1

Bu modelde event turu payload icindeki event alaniyla ayrisir; topic sayisi sade tutulur.

Retry / DLQ Politikası

• Backoff: 1s, 5s, 15s
• Max retry: 3
• Non-retryable hatalar doğrudan DLQ
• Kalıcı hata durumunda ilgili birime bildirim aksiyonu tetiklenebilir
• DLQ replay yalnız admin onayı ile

Retryable Karar Matrisi

Durum	retryable	Davranış
Geçici ağ hatası / timeout	true	Backoff ile yeniden dene
Partner tarafı 5xx	true	retry_max sınırına kadar yeniden dene
Partner tarafı 429	true	Backoff ile yeniden dene
Partner tarafı 4xx (validasyon/format)	false	Doğrudan egress.failed.v1 + DLQ
Güvenlik doğrulama hatası (imza/auth)	false	Doğrudan egress.failed.v1 + DLQ

Güvenlik

• Outbound allowlist zorunlu
• mTLS / API key / OAuth2 gibi profil bazlı auth desteklenir
• Payload signing (opsiyonel ama kurumsal hedeflerde önerilir)
• Hassas alanlar outbound öncesi maskeleme politikasıyla yönetilir
• Partner bazlı rate-limit ve anti-replay kontrolleri uygulanır

SLO (Öneri)

SLO (Service Level Objective), Egress Servisinin dış sistem entegrasyonunda beklenen operasyonel performans hedeflerini tanımlar. Aşağıdaki metrikler müşteriye veri iletim kalitesini izlemek, gecikme kaynaklarını tespit etmek ve hata durumda hızlı aksiyon almak için kullanılır.

Metrik	Hedef
p95 egress latency	< 800ms
delivery success rate	> 99%
dlq_rate	< 0.5%
policy transform fail rate	< 0.2%

SLO ölçüm kaynağı olarak egress_deliveries tablosu esas alınmalıdır. Ölçüm penceresi varsayılan olarak son 24 saat olup, dashboard katmanında 5 dakika tümeciklerle hesaplanır. Uyarı eşikleri aşıldığında alarm oluşturulur ve önceliklendirme sırası şu şekildedir: delivery success rate, dlq_rate, p95 egress latency, policy transform fail rate.

İzlenebilirlik

• Hangi müşteriye hangi servisten hangi zamanda ne gönderildiği izlenmelidir.
• Her delivery denemesi trace_id, policy_id, target_system, attempt_no, status alanlariyla kaydedilmelidir.
• Başarılı ve başarısız denemeler dashboard ve alarm katmanında ayrı izlenmelidir.

Veri Kapsamı

Egress ile dışarıya açılabilecek veri kapsamı policy bazlı seçilir:

• Baz telemetri verileri
• Sentez verileri
• Window verileri
• İleride eklenecek skor verileri (karar destek skorları)

Çıktı

• Dış sistem entegrasyon katmanı