रॉ प्रदाता डेटा के बजाय सिमेंटिक इवेंट (Semantic Events Over Raw Provider Payloads)

हमने पिछले अनुभाग में देखा कि ऑर्केस्ट्रेटर को पीएसपी एसडीके बिल्कुल नहीं देखना चाहिए। सिंक्रोनस कॉल से एक कदम आगे फिर से वही सीमा दिखाई देती है: प्रदाता से वेबहुक।

एक पीएसपी वेबहुक आमतौर पर अपना स्वयं का आंतरिक डेटा मॉडल रखता है: प्रदाता-विशिष्ट ईवेंट प्रकार का नाम, प्रदाता-विशिष्ट स्थिति कोड, प्रदाता-विशिष्ट ऑब्जेक्ट संरचना। इस पेलोड को संदेश कतार या ईवेंट स्ट्रीम में डालने का अर्थ है प्रदाता की स्कीमा को सभी डाउनस्ट्रीम उपभोक्ताओं तक लीक करना।```text PSP Webhook { type: 'charge.succeeded', data: { object: {...} } } ▼ Provider Gateway (çeviri) ▼ Semantik event PaymentCaptured { paymentId, amount, currency }

## पहले उल्लेख पर अवधारणाएँ```text
📦 Semantik Event
İş diliyle adlandırılmış, provider'a hiç referans vermeyen olay: PaymentCaptured, PaymentFailed.

📦 Ham Provider Payload
PSP'nin webhook body'sinde gönderdiği, kendi iç modelini taşıyan orijinal veri.

📦 Çeviri Katmanı (Translator)
Ham payload'ı okuyup semantik event'e dönüştüren, gateway içinde yaşayan bileşen.

📦 Event Sözleşmesi Sahipliği
Semantik event'in alanlarını ve anlamını kimin belirlediği; burada her zaman gateway.
````charge.succeeded` प्रदाता की आंतरिक शब्दावली है; `PaymentCaptured` आपके डोमेन की वास्तविकता है। दोनों एक ही समय में नहीं बदलते हैं: प्रदाता ईवेंट का नाम बदल सकता है, सिमेंटिक ईवेंट का नाम स्थिर रहता है।

## कच्चे पेलोड के परिवहन की लागत यथावत

एकीकृत करने का सबसे तेज़ तरीका वेबहुक बॉडी को पार्स किए बिना संदेश ब्रोकर को पुश करना है। यह अल्पावधि में काम करता है: उपभोक्ता भी उसी पेलोड को पार्स करता है। लेकिन यह प्रदाता के स्कीमा परिवर्तनों को सीधे प्रत्येक उपभोक्ता तक प्रचारित करता है। जब PSP किसी डोमेन का नाम बदलता है, तो आपके नियंत्रण से परे एक घटना आपके अधिकांश सिस्टम को एक साथ तोड़ देती है।```text
Ham payload yayılırsa
  PSP şema değişikliği → N tüketici aynı anda etkilenir

Semantik event yayılırsa
  PSP şema değişikliği → sadece gateway'in çeviri katmanı güncellenir
```## अनुवाद परत क्या करती है और क्या नहीं करती?

अनुवाद परत प्रदाता-विशिष्ट स्थिति कोड को सिमेंटिक एनम में मैप करती है, असंगत या गायब फ़ील्ड को सामान्य करती है, और यदि आवश्यक हो तो स्थानीय रिकॉर्ड से लापता डेटा (जैसे राशि, मुद्रा) को पूरा करती है। इसे जो नहीं करना चाहिए वह व्यावसायिक निर्णय लेना है: 'यह भुगतान विफल क्यों हुआ, क्या किया जाना चाहिए' प्रश्न का उत्तर ऑर्केस्ट्रेटर का काम है, न कि अनुवाद परत का।```text
Webhook geldi
  → provider event tipini oku
  → statü eşleme tablosuna bak
  → semantik event oluştur
  → local correlation id ile eşle
  → yayınla (Outbox üzerinden)
```## मैपिंग टेबल एक ठोस डिज़ाइन उपकरण है

प्रदाता के पास दर्जनों प्रकार के इवेंट हो सकते हैं; आपका सिमेंटिक इवेंट सेट बहुत छोटा और स्थिर होना चाहिए।

| प्रदाता घटना | अर्थपूर्ण घटना |
| --- | --- |
| चार्ज.सफल | भुगतान कैप्चर किया गया |
| आरोप.असफल | भुगतान विफल |
| आरोप.विवाद.बनाया गया | भुगतानविवादित |
| payment_intent.requires_action | भुगतानकार्रवाई आवश्यक |

यह तालिका कोड समीक्षा में पठनीय होनी चाहिए; जब कोई नया प्रदाता ईवेंट आता है, तो प्रश्न 'यह किस सिमेंटिक ईवेंट से मेल खाता है' एक-पंक्ति का निर्णय होना चाहिए, न कि पूरे कोड बेस में बिखरी हुई कोई और श्रृंखला।

## ऑर्डर और पुनर्वितरण गारंटी अभी भी वैध है

अनुवाद परत को उन परिदृश्यों को भी संभालना होगा जहां वेबहुक बार-बार आता है या क्रम से बाहर हो जाता है। नेटवर्क त्रुटि के कारण प्रदाता एक ही वेबहुक दो बार भेज सकता है; सिमेंटिक इवेंट उत्पन्न करते समय, इसके लिए आवश्यक है कि इवेंट जेनरेशन निष्क्रिय हो - जब वही वेबहुक आईडी दूसरी बार आती है तो उसी सिमेंटिक इवेंट को दोबारा उत्सर्जित नहीं किया जाना चाहिए (या डाउनस्ट्रीम निष्क्रिय होने के लिए डिज़ाइन नहीं किया जाना चाहिए)।

## अक्सर भ्रमित होने वाले भेद```text
❌ Webhook = Event
✓ Webhook bir bildirim tetikleyicisidir; semantik event iş dilindeki gerçektir

❌ Ham payload'ı saklamak gereksizdir
✓ Ham payload tanılama için saklanır, ama yalnızca gateway'in kendi arşivinde

❌ Eşleme tablosu bir kere yazılır, bitmiştir
✓ Provider yeni event tipleri ekledikçe tablo canlı bir sözleşmedir
```## कच्चे पास के साथ अर्थपूर्ण अनुवाद

| कसौटी | कच्चा पास | शब्दार्थ अनुवाद |
| --- | --- | --- |
| डाउनस्ट्रीम के प्रदाता की जानकारी | आवश्यक | अनावश्यक |
| स्कीमा परिवर्तन के प्रति भेद्यता | उच्च | निम्न |
| निदान के लिए कच्चा डेटा | खो सकता है | गेटवे में संग्रहित |
| नया पीएसपी जोड़ें | उपभोक्ताओं को प्रभावित करता है | केवल मैपिंग तालिका को प्रभावित करता है |

## अनुवाद परत को डिज़ाइन करते समय चेकलिस्ट

1. क्या कोई डाउनस्ट्रीम उपभोक्ता प्रदाता-विशिष्ट डोमेन या स्टेटस कोड पढ़ता है?
2. क्या मैपिंग तालिका एक ही स्थान पर परिभाषित है या पूरे कोड बेस में बिखरी हुई है?
3. क्या कच्चा वेबहुक पेलोड डायग्नोस्टिक्स के लिए गेटवे के अपने संग्रह में संग्रहीत है?
4. जब एक ही वेबहुक दो बार आता है, तो क्या एक ही अर्थपूर्ण घटना दो बार प्रसारित होती है?
5. जब एक नया प्रदाता ईवेंट प्रकार आता है तो क्या होता है यदि इसे अभी तक मैप नहीं किया गया है - क्या इसे चुपचाप निगल लिया जाता है, या यह एक दृश्य चेतावनी उत्पन्न करता है?

पाँचवाँ प्रश्न विशेष रूप से महत्वपूर्ण है: चुपचाप निगल ली गई अज्ञात घटनाएँ उत्पादन में डेटा हानि के सबसे घातक रूपों में से एक हैं।

## इस लेख से आपको क्या याद रखना चाहिए

1. डाउनस्ट्रीम को कभी भी प्रदाता का ईवेंट नाम या स्थिति कोड नहीं देखना चाहिए।
2. अनुवाद परत एक मैपिंग तालिका और सामान्यीकरण तर्क है, यह व्यावसायिक निर्णय नहीं लेती है।
3. कच्चे पेलोड को निदान के लिए संग्रहीत किया जाता है, लेकिन केवल गेटवे की अपनी सीमा के भीतर।
4. अज्ञात प्रदाता घटनाओं को चुपचाप नहीं निगलना चाहिए, बल्कि एक दृश्यमान संकेत उत्पन्न करना चाहिए।

> यह समझने का सबसे आसान तरीका है कि कोई घटना अर्थपूर्ण है या नहीं, इसका नाम अपने स्वयं के डोमेन शब्दकोश से पढ़ना है, न कि प्रदाता के दस्तावेज़ से।

अगले भाग में हम इन अर्थपूर्ण घटनाओं द्वारा दी गई विफलता की जानकारी को गहराई से देखेंगे: प्रत्येक `PaymentFailed` का एक ही अर्थ नहीं है, हमें एक विफलता वर्गीकरण की आवश्यकता है।