تدفق الدعوة وقراءة QR من التوليد إلى الحضور
المسار: تطوير نظام إدارة الأعراس ودعوات QR الوحدة: التحليل والتصميم
مدخل إلى الدرس: تدفق الدعوة وقراءة QR من التوليد إلى الحضور
تدفق الدعوة وقراءة QR من التوليد إلى الحضور — نظام إدارة الأعراس والمناسبات ودعوات QR | Next.js وPrisma | أديب الصلوي
طريقة الدراسة: اقرأ التعريف، تتبّع المثال في الشرح، نفّذه بنفسك، ثم اختبر النتيجة والحالات الاستثنائية قبل الانتقال.
أهداف هذا الدرس
- رسم رحلة رمز QR بالكامل: توليد → توقيع → فتح → قراءة الخطوة.
- تمييز مكان التحقق من التوقيع ومكان منع التكرار.
- فهم لماذا الفحص يُسجّل عبر POST وليس مجرد فتح رابط.
المخطط: مخطط تسلسل (Sequence) لرحلة الرمز من البداية إلى النهاية
sequenceDiagram
participant Org as منظّم
participant S as خادم Next.js
participant DB as قاعدة البيانات
Org->>S: إضافة مدعو
S->>S: توليد token + توقيع HMAC
S->>DB: جلب المخزّن: token_hash
S-->>Org: (token, signature)
Note over Org: بناء رابط /i/token?sig ثم طباعة QR
participant Gst as مدعو
Gst->>S: فتح الرابط (فحص QR)
S->>S: تحقّق التوقيع
S->>DB: قراءة guest عبر hash
S-->>Gst: صفحة الدعوة + RSVP
participant Gate as بوابة الفرزة
Gate->>S: مسح QR / POST /api/checkin
S->>DB: فحص حضور سابق
S->>DB: إنشاء CheckIn (لا تكرار)
S-->>Gate: {ok, guest name}
لماذا التوقيع وليس مجرد معرّف؟
لو حمل الرمز guestId فقط (/i/42)، فيستطيع أي زائر تخمين رقم ضيف آخر وفتح دعوته أو تسجيل الحضور بدله. التوقيع HMAC يجعل الرابط مغلقاً: تعديل المعرّف يكسر التوقيع فيُرْفض الطلب بمقارنة ثابتة الزمن (timingSafeEqual).
لماذا التسجيل عبر POST وليس فتح الرابط؟
- فتح صفحة الدعوة مجرد قراءة — لا تغيّر حالة.
- تسجيل الحضور تغيير حالة (إنشاء سطر) فوجب أن يكون POST صريحاً وقراراً إنسانياً من موظف الفرزة.
- الفصل المذكور يمنع أن يُحتسب ضيف حاضراً لمجرد أنه فتح الدعوة على هاتفه.
أمان البيانات
الروابط الموقّعة مخزونة بالهاش فقط: لو تسرّبت قاعدة البيانات لا تقود المهاجم إلى إعادة توليد رابط صحيح، لأن الرمز الأصلي غير مخزّن.
الخلاصة السريعة
- الرابط = token + توقيع HMAC، ويُخزَّن الهاش فقط.
- صفحة الدعوة تقرأ فقط؛ التسجيل قرار POST عند البوابة.
- منع التكرار يقع في قاعدة البيانات وفي الواجهة معاً.
تمرين تطبيقي: ارسم الخطوات 10-15 من مخطط التسلسل أعلاه (من لحظة وصول طلب checkin إلى الاستجابة) على ورقة باستخدام أسهم مسطحة.
أخطاء شائعة يجب تفاديها
- وضع التوقيع في عنوان URL دون تحقق منقذ — استخدم المقارنة الآمنة زمنياً.
- تسجيل الحضور من فتح بسيط للرابط.
- تخزين الرمز الصريح في الجدول بدل الهاش.
معجم مصطلحات الدرس
- توقيع HMAC
- رمز تحقق يُحسب بسر الخادم من نص الرابط لمنع التلاعب.
- تسلسل Sequence
- مخطط يصف تبادل الرسائل بين كائنات النظام عبر الزمن.
- هاش token
- قيمة محسوبة من الرمز (SHA-256) تُخزَّن بدل الرمز الصريح.
مراجعة وتمرين تثبيت المهارة
اختبار سريع: اشرح بعبارتك معنى «تدفق الدعوة وقراءة QR من التوليد إلى الحضور»، ثم بيّن أين ستستخدمه داخل نظام تسجيل حضور دعوات مناسبة عبر رمز QR، وما الخطأ الذي يجب اختباره قبل الاعتماد على الحل.
تحدٍّ إضافي: غيّر شرطًا واحدًا في التطبيق، وتوقع النتيجة، ثم نفّذ الاختبار وفسّر الاختلاف.
الدرس التالي: سيناريو المشروع وقواعد العمل. من الأفضل إنهاء التجربة الحالية قبل متابعة الدرس التالي.
