ابنِ واجهة خلفية لمستند تعاوني

في هذا المختبر، ستبني واجهة خلفية كاملة لتحرير المستندات التعاونية بلغة Python. ستنفذ CRDTs للدمج الخالي من التعارضات، ومدير اتصالات WebSocket للاتصال الفوري، ومدير مستندات لتنسيق الحالة، ونظام حضور لتتبع المستخدمين النشطين ومواضع المؤشرات.

هذه هي البنية خلف أنظمة مثل Google Docs وFigma وNotion.

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

العميل A ──WebSocket──> مدير الاتصالات ──> معالج الرسائل
العميل B ──WebSocket──>      |                    |
العميل C ──WebSocket──>      |                    |
                             |                    v
                        نبضات القلب          مدير المستندات
                        وإعادة الاتصال            |
                             |              ┌──────┼──────┐
                             v              v      v      v
                        متتبع            G-Counter  LWW   Text CRDT
                        الحضور           PN-Counter  Reg   (RGA)

ما ستبنيه

ستنفذ 8 ملفات تشكل معًا واجهة خلفية عاملة للتحرير التعاوني:

1. server/crdt/counter.py — CRDTs للعدادات: G-Counter وPN-Counter مع عمليات الدمج
2. server/crdt/lww_register.py — سجل آخر كاتب يفوز مع حل التعارضات بالطابع الزمني
3. server/crdt/text_crdt.py — CRDT نصي (مبني على RGA) يدعم الإدراج والحذف والتحرير المتزامن
4. server/document/document_manager.py — إدارة حالة المستند: تطبيق العمليات، دمج النسخ، إنشاء الفروقات
5. server/websocket/connection_manager.py — مجمع اتصالات WebSocket: اتصال، قطع، نبضات قلب، بث
6. server/websocket/message_handler.py — توجيه الرسائل: تحليل العمليات الواردة، تطبيقها على المستند، بث التحديثات
7. server/presence/presence_tracker.py — نظام الحضور: تتبع المستخدمين النشطين لكل مستند، مواضع المؤشرات، كشف الخمول
8. server/main.py — نقطة الدخول: بدء الخادم، إدارة الاتصالات، إدارة المستندات

دليل خطوة بخطوة

الخطوة 1: CRDTs العدادات (الملف 1)

نفّذ GCounter وPNCounter. عداد G-Counter يتتبع عدادًا واحدًا لكل عقدة. قيمته هي مجموع جميع العدادات. الدمج يأخذ الحد الأقصى لكل عنصر. عداد PN-Counter يستخدم عدادي G-Counter — واحد للزيادات (p)، وواحد للنقصانات (n) — لذا القيمة هي p.value() - n.value().

الخصائص الأساسية التي يجب الحفاظ عليها:

• merge() تبادلية: a.merge(b) تنتج نفس الحالة مثل b.merge(a)
• merge() عديمة القوة: a.merge(b); a.merge(b) تنتج نفس الحالة مثل دمج واحد
• قيمة العداد دائمًا متسقة نهائيًا بعد الدمج

الخطوة 2: LWW-Register (الملف 2)

نفّذ سجل آخر كاتب يفوز الذي يخزن قيمة واحدة. عندما تتعارض كتابتان، الكتابة ذات الطابع الزمني الأعلى تفوز. إذا تساوت الطوابع الزمنية، استخدم معرّف العقدة ككاسر تعادل حتمي (مقارنة معجمية).

الخطوة 3: CRDT النصي (الملف 3)

نفّذ CRDT نصيًا مبنيًا على RGA. كل حرف يُمثل كعقدة مع:

• معرّف فريد: (node_id, sequence_number)
• قيمة الحرف
• مرجع للعقدة التي أُدرج بعدها
• علامة شاهد للأحرف المحذوفة

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

طريقة to_string() تُرجع فقط الأحرف غير المحذوفة بالترتيب.

الخطوة 4: مدير المستندات (الملف 4)

مدير المستندات يتتبع حالة المستند باستخدام CRDTs من الخطوات 1-3. يدعم:

• تطبيق العمليات الفردية (insert, delete, set_title, increment_counter)
• دمج حالة نسخة كاملة من عقدة أخرى
• إنشاء فرق بين الحالة الحالية ونسخة سابقة
• إرجاع لقطة من حالة المستند الكاملة

الخطوة 5: مدير اتصالات WebSocket (الملف 5)

ابنِ مدير اتصالات يتتبع اتصالات WebSocket لكل مستند. يجب أن:

• يسجل ويلغي تسجيل الاتصالات (ربط معرّفات العملاء بكائنات WebSocket)
• يتتبع أي مستند يحرره كل عميل
• يرسل نبضات قلب ويكتشف الاتصالات الميتة (نبضات قلب مفقودة > العتبة)
• يبث الرسائل لجميع العملاء الذين يحررون نفس المستند (باستثناء المرسل)

الخطوة 6: معالج الرسائل (الملف 6)

معالج الرسائل يستقبل رسائل WebSocket الخام (JSON)، يحللها إلى عمليات مُنوّعة، يطبقها على المستند عبر مدير المستندات، ويبث النتيجة للعملاء المتصلين الآخرين. يجب أن يتعامل مع الرسائل المشوهة برشاقة.

أنواع الرسائل المدعومة: insert، delete، set_title، cursor_move، presence_update.

الخطوة 7: متتبع الحضور (الملف 7)

تتبع المستخدمين النشطين لكل مستند مع:

• موضع المؤشر (سطر، عمود) لكل مستخدم
• طابع زمني لآخر نشاط لكشف الخمول
• عتبة خمول (مثلاً 5 دقائق) — المستخدمون الذين يتجاوزونها يُعلّمون كخاملين
• طرق للحصول على جميع المستخدمين النشطين (غير الخاملين) لمستند

الخطوة 8: نقطة الدخول الرئيسية (الملف 8)

اربط جميع المكونات معًا. فئة CollaborativeServer يجب أن:

• تهيّئ مدير المستندات ومدير الاتصالات ومعالج الرسائل ومتتبع الحضور
• تتعامل مع اتصالات العملاء الجديدة (تسجيل، إرسال حالة المستند الحالية)
• تتعامل مع قطع الاتصال (إلغاء التسجيل، إزالة الحضور)
• توجه الرسائل الواردة لمعالج الرسائل
• توفر طريقة للحصول على حالة الخادم (العملاء المتصلون، المستندات النشطة)

تلميحات

• لـ CRDT النصي، خزّن الأحرف في قائمة واستخدم بحثًا خطيًا لعمليات البحث عن الموضع. هذا O(n) لكنه صحيح وبسيط — التطبيقات الحقيقية تستخدم الأشجار لـ O(log n).
• استخدم time.time() للطوابع الزمنية في كل مكان. في الإنتاج، ستستخدم ساعات متجهية أو ساعات منطقية هجينة.
• كائنات WebSocket في هذا المختبر محاكاة — لا تحتاج مكتبة WebSocket فعلية. استخدم واجهة MockWebSocket المقدمة في الكود الأولي.
• جميع طرق merge() في CRDTs يجب أن تكون تبادلية وعديمة القوة. اختبر بدمج A في B ثم B في A — كلاهما يجب أن ينتجا حالات متطابقة.
• استخدم تلميحات الأنواع في Python على جميع الطرق العامة.