كيف تعمل المزامنة

SyncEngine

SyncEngine -- هو المكون المركزي لبنية العمل دون اتصال في tikento. وهو مسؤول عن:

• حفظ التغييرات في قاعدة البيانات المحلية (IndexedDB عبر Dexie.js)
• تتبع التغييرات المعلقة للمزامنة (pendingSync=true)
• إرسال التغييرات إلى الخادم عند استعادة الاتصال
• استلام التحديثات من الخادم (delta sync)
• إزالة التكرار لمنع الازدواجية

دورة حياة التغيير

1. إنشاء التغيير

عند تنفيذ إجراء (مثل تسجيل حضور مشارك)، يقوم SyncEngine بـ:

1. كتابة التغيير في IndexedDB مع علامة pendingSync=true
2. تعيين طابع وقت clientTs (الوقت الحالي على الجهاز)
3. زيادة عدّاد التغييرات المعلقة في المؤشر
4. عرض التغيير فوراً في الواجهة (تحديث متفائل)

2. الإرسال إلى الخادم

عند توفر الاتصال يقوم SyncEngine بـ:

1. استخراج جميع السجلات ذات pendingSync=true
2. ترتيبها حسب clientTs (من الأقدم إلى الأحدث)
3. إرسالها كحزمة إلى الخادم
4. انتظار التأكيد من الخادم

3. التأكيد

بعد استجابة الخادم الناجحة:

1. تُزال علامة pendingSync (false) لكل سجل مُرسل
2. ينخفض عدّاد التغييرات المعلقة
3. إذا أُرسلت جميع التغييرات، ينتقل المؤشر إلى الأخضر

4. معالجة الأخطاء

عند حدوث خطأ في الإرسال:

1. تبقى التغييرات مع pendingSync=true
2. تتم إعادة المحاولة بعد 30 ثانية
3. بحد أقصى 5 محاولات، بعدها يتم إشعار المستخدم

المزامنة التفاضلية (Delta sync)

تسمح المزامنة التفاضلية بالحصول من الخادم على البيانات التي تغيرت بعد آخر مزامنة فقط، بدلاً من تحميل مجموعة البيانات بالكامل.

كيف تعمل

1. يحتفظ SyncEngine بطابع وقت آخر مزامنة ناجحة في جدول meta.
2. عند المزامنة يُرسل طلب مع معامل since:

GET /sync/delta?since=2026-07-15T10:30:00Z&entities=registrations,payments

3. يُرجع الخادم السجلات التي تغيرت بعد الوقت المحدد فقط.
4. يُحدّث SyncEngine قاعدة البيانات المحلية ويحفظ طابع الوقت الجديد.

معاملات الطلب

المزايا

• توفير حركة البيانات. يتم نقل التغييرات فقط وليس جميع البيانات
• السرعة. تستغرق المزامنة ثوانٍ وليس دقائق
• الموثوقية. إذا انقطعت المزامنة، تبدأ المحاولة التالية من نفس since

المزامنة التلقائية

يتتبع SyncEngine حالة الشبكة ويشغّل المزامنة تلقائياً في الحالات التالية:

عند استعادة الاتصال

عندما ينتقل الجهاز من غير متصل إلى متصل:

1. يُكتشف حدث online (Network Information API)
2. يتحقق SyncEngine من توفر الخادم (ping)
3. تُرسل التغييرات المعلقة (upload)
4. تُطلب التحديثات من الخادم (download عبر delta sync)

المزامنة الدورية

في وضع الاتصال يتحقق SyncEngine دورياً من وجود تحديثات على الخادم، لتبقى البيانات محدّثة (مثلاً إذا سجّل عضو آخر في الفريق حضوراً من جهاز آخر).

إزالة التكرار

لمنع تكرار التغييرات يُستخدم مفتاح مركب:

clientTs + userId

يتم تعريف كل تغيير بشكل فريد من خلال مزيج طابع وقت الإنشاء على العميل ومعرّف المستخدم. إذا أُعيد إرسال نفس التغيير (مثلاً بسبب انتهاء مهلة الشبكة)، يتعرف الخادم على النسخة المكررة بهذا المفتاح ويُرجع تأكيداً دون تطبيقه مرة أخرى.

هذا يضمن العطالة (idempotency) -- إعادة إرسال نفس مجموعة التغييرات لا تؤدي إلى أخطاء أو تكرار البيانات.

ترتيب المزامنة

تُرسل التغييرات بالترتيب الزمني الصارم حسب clientTs. هذا أمر بالغ الأهمية للصحة:

• تسجيل حضور مشارك في 10:05 لا يمكن أن يُكتب فوقه بإلغاء تسجيل حضور في 10:03
• تسجيل دفع يدوي في 11:00 يُطبق بعد تغيير الحالة في 10:55

إذا اختلفت ساعة الجهاز عن وقت الخادم، يعوّض SyncEngine الفرق عند أول مزامنة ناجحة.

حجم التخزين المحلي

قاعدة بيانات IndexedDB المحلية لها حدود تعتمد على المتصفح والجهاز:

بالنسبة لفعالية نموذجية (حتى 2,000 مشارك) يبلغ حجم البيانات 5-20 ميجابايت، وهو بعيد جداً عن حدود أي متصفح.

عند الاقتراب من حد التخزين يعرض SyncEngine تحذيراً ويقترح مسح بيانات الفعاليات المنتهية.