نمط Outbox — التسليم الموثوق للأحداث

// ❌ خطر — عمليتان منفصلتان بلا ضمان اتساق
async function createOrder(data) {
  const order = await db.orders.save(data);       // نجحت
  await messageBroker.publish('order.created', order); // ← ماذا لو فشل هنا أو تعطّل الخادم؟
  return order;
}

-- جدول outbox بجانب جداول البيانات، بنفس قاعدة البيانات
CREATE TABLE outbox (
  id            UUID PRIMARY KEY,
  aggregate_type VARCHAR(50)  NOT NULL,   -- مثال: 'Order'
  aggregate_id   VARCHAR(50)  NOT NULL,
  event_type     VARCHAR(100) NOT NULL,   -- مثال: 'order.created'
  payload        JSONB        NOT NULL,
  created_at     TIMESTAMP    NOT NULL DEFAULT now(),
  published_at   TIMESTAMP                -- NULL = لم يُنشر بعد
);

// ✅ تحديث البيانات وتسجيل الحدث في نفس المعاملة المحلية
async function createOrder(data) {
  return db.transaction(async (tx) => {
    const order = await tx.orders.save(data);

    await tx.outbox.insert({
      id: crypto.randomUUID(),
      aggregateType: 'Order',
      aggregateId: order.id,
      eventType: 'order.created',
      payload: order,
      createdAt: new Date(),
    });

    return order; // commit واحد — الاثنان ينجحان أو يفشلان معاً
  });
}

طرق نشر أحداث الـ Outbox:
  Polling Publisher:
    الفكرة: عملية مستقلة تستعلم دورياً عن الصفوف غير المنشورة وتنشرها
    الميزة: بسيط التنفيذ، لا يحتاج بنية تحتية إضافية
    العيب: تأخير بحجم فترة الاستعلام، وحمل إضافي على قاعدة البيانات

  Transaction Log Tailing (CDC):
    الفكرة: أداة (مثل Debezium) تقرأ سجل معاملات قاعدة البيانات مباشرة وتنشر كل إدراج جديد فوراً
    الميزة: زمن استجابة شبه فوري، بلا استعلام متكرر
    العيب: يحتاج بنية تحتية إضافية (Kafka Connect + Debezium أو ما يعادلها)

// مثال مبسّط لـ Polling Publisher — عملية خلفية منفصلة
async function pollAndPublishOutbox() {
  const pending = await db.outbox.findUnpublished({ limit: 50 });

  for (const event of pending) {
    await messageBroker.publish(event.eventType, event.payload);
    await db.outbox.markPublished(event.id); // يُحدَّث بعد تأكيد النشر
  }
}

setInterval(pollAndPublishOutbox, 2000);

// المستهلك يتحقق من معرّف الحدث قبل معالجته
async function handleOrderCreated(event) {
  const alreadyProcessed = await db.processedEvents.exists(event.id);
  if (alreadyProcessed) return; // تجاهل التكرار بأمان

  await sendInvoice(event.payload);
  await db.processedEvents.markProcessed(event.id);
}