بناء خدمة طلبات قائمة على مصادر الأحداث

الهدف

ابنِ خدمة طلبات كاملة قائمة على مصادر الأحداث تُظهر أنماط بنية البيانات الأساسية التي تمت تغطيتها في الدرس: مصادر الأحداث وCQRS ونمط Saga وتحسين اللقطات. هذا المعمل يعكس البنية المعمارية التي ستقترحها في مقابلة تصميم أنظمة لخدمة طلبات تجارة إلكترونية.

نظرة عامة على البنية المعمارية

Commands                    Event Store (ملحق فقط)
   |                              |
   v                              v
Command Handler -----> Events -> [E1, E2, E3, E4, ...]
                                  |              |
                                  v              v
                          Order Projection   Analytics Projection
                          (الحالة الحالية)   (الإيرادات، الأعداد)
                                  |
                                  v
                          Snapshot Manager
                          (لقطات دورية)

Saga Orchestrator
   |
   +---> Payment Step ----> (نجاح) ---> Inventory Step
   |                                        |
   |                                   (نجاح) ---> Shipping Step
   |                                                    |
   +--- تعويض <--- (فشل في أي خطوة) <-----------------+

المتطلبات

ستنفّذ 8 ملفات TypeScript تعمل معًا:

الملف 1: src/events/event-store.ts — مخزن الأحداث الملحق فقط

• نفّذ مخزن أحداث ملحق فقط في الذاكرة
• كل حدث يحتوي على aggregateId (مثلاً orderId) ورقم version تسلسلي
• ادعم التحكم في التزامن المتفائل: عند إلحاق أحداث، مرر الإصدار المتوقع؛ ارفض إذا كان هناك تعارض في الإصدار (كتابة أخرى حدثت بشكل متزامن)
• نفّذ append(aggregateId, events, expectedVersion): يرمي استثناء عند عدم تطابق الإصدار
• نفّذ getEvents(aggregateId): يُرجع جميع الأحداث لكيان مجمّع بالترتيب
• نفّذ getEventsAfterVersion(aggregateId, afterVersion): يُرجع الأحداث بعد إصدار معين (يُستخدم مع اللقطات)
• نفّذ getAllEvents(): يُرجع جميع الأحداث عبر جميع الكيانات المجمّعة (لإسقاط التحليلات)

الملف 2: src/events/event-types.ts — أحداث المجال

• عرّف واجهة DomainEvent أساسية تحتوي على: type وaggregateId وversion وtimestamp وmetadata (correlationId وcausationId)
• عرّف أحداث مجال الطلبات: OrderCreated وItemAdded وPaymentProcessed وOrderShipped وOrderCancelled
• كل حدث يحمل البيانات الخاصة بما حدث (مثلاً OrderCreated يتضمن customerId والعناصر)
• استخدم الاتحادات المميزة في TypeScript لأمان الأنواع

الملف 3: src/commands/command-handler.ts — معالج الأوامر

• تعامل مع الأوامر: PlaceOrder وAddItem وProcessPayment وShipOrder وCancelOrder
• كل معالج أوامر: يحمّل الحالة الحالية من مخزن الأحداث، يتحقق من قواعد العمل، ينتج أحداثًا جديدة
• قواعد العمل التي يجب فرضها:
  • لا يمكن إضافة عناصر لطلب ملغى أو مشحون
  • لا يمكن معالجة الدفع لطلب ملغى
  • لا يمكن شحن طلب لم يتم دفعه
  • لا يمكن إلغاء طلب تم شحنه بالفعل
• استخدم التحكم في التزامن المتفائل لمخزن الأحداث للكتابات الآمنة

الملف 4: src/projections/order-projection.ts — نموذج قراءة الطلب

• أنشئ حالة الطلب الحالية بإعادة تشغيل الأحداث
• نموذج القراءة يجب أن يتضمن: orderId وcustomerId وitems وstatus وtotalAmount وpaymentId وshippedAt وcancelledAt وversion
• الحالات: pending وpaid وshipped وcancelled
• نفّذ getOrder(orderId): يُرجع حالة الطلب الحالية
• نفّذ rebuildFromEvents(events): يعيد بناء الحالة من قائمة أحداث

الملف 5: src/projections/analytics-projection.ts — إسقاط التحليلات

• حافظ على مقاييس مجمّعة عبر جميع الطلبات:
  • totalRevenue: مجموع مبالغ جميع الطلبات المدفوعة
  • totalOrders: عدد جميع الطلبات المُنشأة
  • averageOrderValue: totalRevenue / عدد الطلبات المدفوعة
  • ordersByStatus: عدد الطلبات في كل حالة
  • cancelledRevenue: إجمالي مبالغ الطلبات الملغاة (الإيرادات المفقودة)
• عالج الأحداث بشكل تدريجي (لا تعد تشغيل جميع الأحداث في كل مرة)
• نفّذ processEvent(event) وgetAnalytics()

الملف 6: src/saga/order-saga.ts — منسق Saga

• نفّذ Saga قائمة على التنسيق لسير عمل الطلب من 3 خطوات:
  1. الدفع: خصم من العميل (محاكاة بدالة غير متزامنة)
  2. المخزون: حجز العناصر (محاكاة بدالة غير متزامنة)
  3. الشحن: جدولة الشحن (محاكاة بدالة غير متزامنة)
• كل خطوة يمكن أن تنجح أو تفشل (استخدم محاكاة فشل قابلة للتكوين)
• عند الفشل في أي خطوة، نفّذ التعويض لجميع الخطوات المكتملة سابقًا بترتيب عكسي:
  • فشل الشحن: حرر المخزون، استرد الدفع
  • فشل المخزون: استرد الدفع
• تتبع حالة Saga: pending وpayment_completed وinventory_reserved وcompleted وcompensating وcompensated وfailed
• سجّل كل خطوة للرؤية

الملف 7: src/snapshots/snapshot-manager.ts — مدير اللقطات

• خزّن لقطات دورية لحالة الكيان المجمّع لتجنب إعادة تشغيل جميع الأحداث
• نفّذ saveSnapshot(aggregateId, state, version): حفظ لقطة عند إصدار معين
• نفّذ getLatestSnapshot(aggregateId): إرجاع أحدث لقطة
• نفّذ shouldSnapshot(eventCount): إرجاع true إذا يجب أخذ لقطة (مثلاً كل 5 أحداث في هذا المعمل؛ في الإنتاج كل 100)
• نفّذ loadAggregateState(aggregateId, eventStore, projector):
  1. حمّل أحدث لقطة (إن وجدت)
  2. احصل على الأحداث بعد إصدار اللقطة
  3. طبّق تلك الأحداث على حالة اللقطة
  4. أرجع الحالة الحالية

الملف 8: src/index.ts — نقطة الدخول الرئيسية

• اربط كل شيء معًا
• شغّل سيناريو اختبار يُظهر:
  1. إنشاء طلب بعنصرين
  2. إضافة عنصر آخر للطلب
  3. معالجة الدفع
  4. شحن الطلب
  5. استعلام إسقاط الطلب للحالة الحالية
  6. استعلام التحليلات للمقاييس المجمّعة
  7. إظهار حفظ وتحميل اللقطات
  8. تشغيل منسق Saga (مرة بنجاح ومرة مع فشل محاكى يُظهر التعويض)
• اطبع النتائج في كل خطوة لإظهار سير العمل الكامل

تلميحات

• استخدم Map<string, DomainEvent[]> لمخزن الأحداث في الذاكرة، مفتاحه aggregateId
• للتحكم في التزامن المتفائل، قارن الإصدار المتوقع مع العدد الحالي للأحداث لذلك الكيان المجمّع
• منسق Saga يمكنه استخدام async/await بسيط مع try/catch لتنفيذ الخطوات والتعويض
• لإسقاط التحليلات، تتبع مجموعة processedEventIds لتجنب معالجة نفس الحدث مرتين
• مدير اللقطات هو أساسًا Map<string, { state: OrderState; version: number }>
• استخدم console.log مع تسميات واضحة (مثلاً [EventStore] و[Saga] و[Projection]) لإظهار ما يحدث

ما يجب تقديمه

يجب أن يحتوي تقديمك على 8 أقسام ملفات في المحرر أدناه، كل منها ينفّذ أحد الملفات المذكورة أعلاه.

---