ElementAPI mimarisi

1. Tarayıcı POST /api/v1/orders isteğini Idempotency-Key başlığıyla gönderir. Gateway oturumu doğrular ve isteği order'a iletir.
2. order fiyatı ve görünen stoğu catalog'dan, bakiyeyi wallet'tan sorar. Stok yetmiyorsa hemen 409, bakiye yetmiyorsa 402 döner. Bu ağ çağrıları transaction'dan önce yapılır; transaction açıkken başka bir servisi beklemek kilitleri uzatırdı.
3. order tek transaction'da siparişi Submitted olarak yazar, aynı transaction'da outbox tablosuna iki olay ekler: UpdateOrderStatusEvent ve OrderSubmittedEvent. Kullanıcı hemen 202 Accepted alır; gerisi arka planda yürür.
4. Outbox relay commit edilmiş satırları RabbitMQ'ya yayımlar ve broker onayını bekler.
5. inventory, Au stok satırını kilitler (FOR UPDATE), 10 g ayırır, mesaj kimliğini inbox'a ve StockReservedEvent'i outbox'a aynı transaction'da yazar.
6. order siparişi kilitler, StockReserved durumuna geçer ve PaymentRequestedEvent yazar.
7. wallet cüzdan satırını kilitler, bakiyeyi kontrol eder, KREDI'yi çeker, deftere kayıt atar, PaymentProcessedEvent yazar.
8. order Shipping durumuna geçer; shipment gönderim kaydını açıp TRK-… takip numarasıyla ShipmentDispatchedEvent gönderir.
9. order Completed olur. AssetsCreditedEvent ile wallet 10 g altını varlıklara ekler; OrderCompletedEvent ile inventory ayrılan stoğu kesin düşer, catalog altının fiyatını bir kez yukarı iter.
10. Her durum değişikliğinde notification kullanıcıya bildirim gönderir.

order, istek anında stoğu zaten kontrol eder. Bu senaryo kontrolle rezervasyon arasında başka bir siparişin stoğu almasıyla oluşur. Ön kontrol yalnızca bir kolaylıktır; asıl kararı stok satırını kilitleyen inventory verir.

1. inventory stok satırını kilitler ve stok − ayrılmış < istenen olduğunu görür.
2. Hiçbir şey ayırmadan StockReservationFailedEvent gönderir.
3. order siparişi Failed yapar ve telafi olaylarını yazar: stok bırakma ve iade.
4. İki telafi de bu durumda boşa çalışır: ayrılmış stok ve çekilmiş KREDI yoktur. Telafiler idempotent yazıldığı için "gerekmeyen telafi" zarar vermez. Order hangi adımın gerçekten yapıldığını takip etmek zorunda kalmaz.

Bu durum da ön kontrolden sonra bakiye değişirse oluşur (örneğin aynı anda verilen ikinci bir sipariş).

1. Stok ayrıldı, order PaymentRequestedEvent gönderdi.
2. wallet cüzdanı kilitler; bakiye yetmediği için Wallet aggregate'i tahsilatı reddeder ve INSUFFICIENT_ELX nedeniyle PaymentFailedEvent gönderir.
3. order Failed olur; OrderStockReleaseEvent ile inventory ayrılan 10 g'ı geri bırakır.
4. Kullanıcı "Ödeme başarısız" bildirimini alır. Bakiyesi ve stok, sipariş hiç verilmemiş gibi kalır.

Toplam 50.000 KREDI'yi aşarsa order isteği HTTP katmanında 400 ile reddeder; saga hiç başlamaz. Aynı kural Order aggregate'inde ve wallet'ta da var. Biri atlansa bile öteki yakalar.

1. İstemci aynı Idempotency-Key ile isteği tekrarlar.
2. order bu anahtarı sipariş kimliği olarak kullandığı için mevcut siparişi bulur ve onu 200 ile döner. İkinci sipariş oluşmaz, KREDI iki kez çekilmez.
3. Aynı anahtar farklı bir sipariş gövdesiyle gelirse yanıt 409 olur.

1. wallet KREDI'yi çekti, commit etti, ama RabbitMQ'ya onay (ack) göndermeden çöktü.
2. RabbitMQ PaymentRequestedEvent'i yeniden teslim eder.
3. wallet yeni transaction'da mesaj kimliğini processed_messages tablosuna yazmaya çalışır; kimlik zaten var, işlem orada durur. KREDI ikinci kez çekilmez.
4. catalog'da aynı koruma sipariş başına bir işaretle yapılır: fiyat bir sipariş için yalnızca bir kez hareket eder.

1. RabbitMQ yeniden başlıyor. order siparişi ve outbox satırlarını yine de commit eder; kullanıcı yanıtını alır.
2. Relay yayımlayamaz, satırlar pending kalır. Hiçbir olay kaybolmaz.
3. Broker döndüğünde relay satırları sırayla yayımlar ve her birini broker onayından sonra işaretler.
4. Outbox olmasaydı iki kötü sonuçtan biri olurdu: önce yayımla sonra commit et (commit başarısızsa var olmayan bir sipariş için olay gider) ya da önce commit et sonra yayımla (yayım başarısızsa sipariş sonsuza kadar Submitted kalır).

1. İki OrderSubmittedEvent aynı anda inventory'ye ulaşır.
2. İkisi de aynı stok satırını FOR UPDATE ile kilitlemeye çalışır; ikincisi birincinin commit'ini bekler.
3. Birinci 5 g'ı ayırır. İkinci, kilidi aldığında güncel değeri okur, stok kalmadığını görür ve StockReservationFailedEvent gönderir.
4. Kod bir gün yanlış yazılsa bile veritabanındaki stock_items_never_oversold CHECK kısıtı fazla satışı reddeder. Bu senaryo Testcontainers ile gerçek PostgreSQL üzerinde test ediliyor; kilit kaldırıldığında test kırılıyor.

1. shipment servisi kapalı; sipariş Shipping durumunda bekliyor. KREDI çekilmiş, stok ayrılmış.
2. order'daki süpürücü düzenli aralıklarla süresi geçmiş saga'ları arar. Varsayılan süreler: Submitted 120 sn, StockReserved 120 sn, Shipping 180 sn.
3. Süresi geçen siparişi kilitler, süreyi kilit altında yeniden kontrol eder (bu arada gerçek bir olay gelip siparişi ilerletmiş olabilir), sonra Failed yapar ve stok bırakma + iade gönderir.
4. shipment geri gelip geç bir ShipmentDispatchedEvent gönderirse order bunu yok sayar; Failed son durumdur. Düşen bir siparişe geç gelen ödeme onayı ise yalnızca kendi iadesini tetikler.

1. Kullanıcı POST /api/v1/desk/sell ile 3 g altın satar.
2. wallet tek transaction'da varlığı azaltır, alış fiyatı (bid) üzerinden KREDI ekler, deftere yazar ve outbox'a ElementSoldEvent koyar.
3. inventory 3 g'ı stoğa geri ekler; catalog altının fiyatını bir kez aşağı iter. İkisi de satışı bir kez işlemek için mesaj kimliğine bakar.

1. Docker bütün konteynerleri aynı anda başlatır; PostgreSQL birkaç saniye geç hazır olur.
2. Servisler ilk bağlantı hatasını "geçici" olarak tanır ve 2 saniye arayla 30 kez dener. Yanlış şifre ya da bozuk migration gibi beklemekle düzelmeyecek hatalarda hemen durur, hata loglarda açıkça görünür.
3. Bu sayede servisler restart döngüsüne girmez. Test: PostgreSQL 20 sn kapatıldığında order dışındaki servislerin restart sayısı 0 kaldı. order bilerek bir kez yeniden başlar; o sırada gelen mesajlar RabbitMQ'da bekler.