Olay Sırası — sequence & sequenceScope ✓ Canlı

Nerede bulunur — üç yol

Aynı çift artık üç gövdede geliyor ve üçünde de aynı sözleşmedir:

// kapanış hook'u
{
  "type": "hook", "event": "table.close", "stage": "before",
  "target": { "type": "table", "id": "masa-12" },
  "sequence": 14,
  "sequenceScope": "sq_5776130612ab",
  …
}

İki garanti

Neden occurredAt yetmiyor

occurredAt iki teslimi ayırt etmeye yetmez: sunucular arası saat kayması ve aynı milisaniyede yapılan iki yazım mümkündür. Bir hesabın durum değişiklikleri ise satış düzeyinde numaralanır — bayat bir snapshot'ı bu numaradan tanırsın.

{
  "id": "evt_9f3a…",
  "type": "table.updated",
  "occurredAt": 1768818213617,
  "sequence": 7,                      // bu satışın kaçıncı durum değişikliği
  "sequenceScope": "sq_9f3ab27c…",    // sequence'in geçerli olduğu SATIŞ HATTI
  "data": { "tableId": "masa-5", "docNo": 12, "…": "…" }
}

Kullanım algoritması — beş kural, hepsi zorunlu

1. Defterini (tenantId, sequenceScope) ile anahtarla. Her scope için ayrı bir "son işlenen sequence" tut. Tek slotlu bir uygulama (yalnız son gördüğüm scope'u hatırla) yanlıştır: yeni satış başladıktan sonra gelen geç bir eski-satış olayı "scope farklı → karşılaştırma yok" diye kabul edilir ve bayat durumu yeninin üstüne yazar.
2. Aynı scope içinde sequence, o scope için en son işlediğinden küçükse yok say.
3. Eşit sequence sıra bilgisi taşımaz. Tekrar teslimi zarf id'si ile dedup et. Farklı içerikli eşit-numaralı iki olay, aralarında güvenilir bir sıra olmadığı anlamına gelir — son gelen kazanır.
4. Terminal olaylar eşit numarada bile terminaldir. *.closed, *.cancelled, *.deleted, *.closed_deleted satışı sonlandırır. Bunlardan birini işledikten sonra aynı scope'ta gelen bir *.updated'ı — numarası eşit ya da büyük olsa bile — satışı yeniden açmak için kullanma. Yalnız *.reopened satışı geri açar.
5. Defterini terminal olaydan hemen sonra silme. Scope kaydını en az yeniden-teslim penceresi kadar tut (öneri: 7 gün). Silersen, geç gelen bir ilk teslim (tekrar değil → id dedup'u çalışmaz) "bu scope defterde yok → kabul" yolundan geçip satışı diriltir.

import {
  isSaleSequenceEvent, sequenceKey, sequenceVerdict, advanceSequenceCursor,
} from '@restomenum/plugin-sdk';

if (isSaleSequenceEvent(envelope.type)) {
  const key = sequenceKey(envelope.tenantId, envelope);   // (tenantId, sequenceScope) — TEK SLOT YASAK
  const cursor = key ? await ledger.get(key) : null;      // { sequence, terminal? } | null

  switch (sequenceVerdict(envelope, cursor)) {
    case 'stale':    return ok();     // daha küçük numara → bayat, YOK SAY (yine de 2xx dön)
    case 'terminal': return ok();     // satış sonlanmış; *.updated onu DİRİLTMEZ
    default: break;                   // 'apply' | 'unsequenced' → işle
  }

  await handle(envelope);
  if (key) await ledger.set(key, advanceSequenceCursor(cursor, envelope));  // ≥ 7 gün sakla
}

// SDK kullanmıyorsan birebir aynı karar (kural 2–4):
const key = `${envelope.tenantId}:${envelope.sequenceScope}`;   // scope YOKSA karşılaştırma YAPMA
const cursor = await ledger.get(key);                            // { sequence, terminal }

if (envelope.sequence != null && envelope.sequenceScope && cursor) {
  if (envelope.sequence < cursor.sequence) return;               // 2) bayat
  const TERMINAL = /\.(closed|cancelled|deleted|closed_deleted)$/;
  const REOPEN   = /\.reopened$/;
  if (cursor.terminal && !TERMINAL.test(envelope.type) && !REOPEN.test(envelope.type)) return;  // 4)
}
// 3) eşit numara → sıra bilgisi yok: son gelen kazanır (tekrar teslimi zarf id'si ile dedup et)

// Defter satırı — anahtar (tenantId, sequenceScope), TTL ≥ 7 gün
{
  "tenantId": "tnt_123",
  "sequenceScope": "sq_9f3ab27c",
  "sequence": 12,        // bu hat için İŞLENMİŞ en büyük numara
  "terminal": true,      // *.closed / *.cancelled / *.deleted / *.closed_deleted işlendi
  "updatedAt": 1768820000000
}

Numara atlaması normaldir — ama kaybı DIŞLAMAZ

Hat (scope) ne zaman değişir

Kapanışta hesabın kimliği değişir (table.updated'daki tableId ile table.closed'daki farklıdır), geri açmada da yeni bir kimlik doğar (hesap yaşam döngüsü). Fazlar arasında kararlı kalan tek bağ sequenceScope'tur.

Alanların gelmediği durumlar

• Bu değişiklikten önce açılmış, hâlâ açık duran satışlar — ilk mutasyonlarında hat kazanırlar.
• Entegrasyon kanallarının (Getir / Yemeksepeti / Trendyol / Migros / Fuudy / WebStore) açtığı paketlerin packet.created'ı.
• Başka işletmeye taşınmış paketin hedefteki packet.created'ı — hat bilerek sökülür ki kaynak işletmenin satışıyla karışmasın.

Alan yoksa karşılaştırma yapılamaz; bugünkü davranışını sürdür (occurredAt karşılaştırması + id dedup'u).

En iyi pratikler

• Sıra kontrolü dedup'ın yerine geçmez. Önce imzayı ham gövde üzerinden doğrula (geçersizse 401), sonra zarf id'si ile dedup et, sonra sıra kararını ver.
• Terminal bayrağını defterde tut. Kural 4 için "bu satış sonlandı mı" bilgisi gerekir; numara karşılaştırması tek başına yetmez.
• Defteri işlemden SONRA ilerlet. Handler hata verirse kayıt ilerlemesin ki yeniden teslim işlensin.
• Echo koruması ayrı bir iştir: kendi yazdığın değişikliğin olayı da sana gelir → isOwnEcho ile ele.