تجربة المسح في بوابة الحفل
المسار: تطوير نظام إدارة الأعراس ودعوات QR الوحدة: توليد وقراءة رموز QR
مدخل إلى الدرس: تجربة المسح في بوابة الحفل
تجربة المسح في بوابة الحفل — نظام إدارة الأعراس والمناسبات ودعوات QR | Next.js وPrisma | أديب الصلوي
طريقة الدراسة: اقرأ التعريف، تتبّع المثال في الشرح، نفّذه بنفسك، ثم اختبر النتيجة والحالات الاستثنائية قبل الانتقال.
أهداف هذا الدرس
- تصميم صفحة مسح Point-of-View لموظف الفرزة.
- بناء دالة مسح بالكاميرا تلتقط المحتوى عبر navigator.
- ترجمة نتيجة API إلى شاشة نجاح/خطأ ناطقة.
مثال
// app/admin/scan/page.tsx + ScanBox component
"use client";
import { useEffect, useRef, useState } from "react";
export default function ScanPage() {
const videoRef = useRef(null);
const [result, setResult] = useState(null);
const [state, setState] = useState<"idle" | "scanning" | "ok" | "err">("idle");
useEffect(() => {
let stream: MediaStream | undefined;
(async () => {
stream = await navigator.mediaDevices.getUserMedia({
video: { facingMode: "environment" }, // كاميرا خلفية
});
if (videoRef.current) {
videoRef.current.srcObject = stream;
await videoRef.current.play();
}
})().catch(() => setState("err"));
return () => stream?.getTracks().forEach((t) => t.stop());
}, []);
async function onDetected(text: string) {
// text = "https://site/i/TOKEN?sig=SIG"
const m = text.match(/\/i\/([^?]+)\?sig=(\w+)/);
if (!m) return setResult("رمز غير صالح");
const [, token, sig] = m;
const res = await fetch("/api/checkin", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ token, sig, eventId: "EVENT_ID" }),
});
const body = await res.json();
setResult(body.ok ? `تم استقبال ${body.data.guest}` : body.error);
setState(body.ok ? "ok" : "err");
}
return (
بوابة المسح
{result ?? "وجّه الكاميرا نحو رموز QR"}
);
} المخطط: تفاعل جهاز الفرزة مع النظام لحظة المسح
flowchart TD
A["الكاميرا → اكتشاف رمز → (token,sig)"] --> P["POST /api/checkin"]
P --> R{"النتيجة"}
R -->|ok| G["شاشة خضراء — تم استقبال {name}"]
R -->|409| D["مكرر — سبق تسجيله + firstSeen"]
R -->|403/404| E["شاشة حمراء — أمن / غير موجود"]
تجربة الفرزة
المسح يتلاعب بمسار الوسائط النظيف: تفعّل الكاميرا في صفحات مستقلة، وتوقف تدفقها عند مغادرة الشاشة. ودرّب الموظف: عند الوضع الأحمر أعِد المسح بعد لحظات دون محاولة إدخال يدوي للرمز.
تمرين تطبيقي: أضف إشارة صوتية عند النجاح بوسيلة new Audio() واهتزازاً عبر navigator.vibrate لتنبيه الموظف بين الفرزتين دون النظر للشاشة.
أخطاء شائعة يجب تفاديها
- تشغيل getUserMedia بلا try/catch فتبقى صفحة بيضاء.
- فتح الكاميرا مرتين (عند إعادة النقر) دون إيقاف المسار السابق.
- عدم إغلاق الشاشة بعد نتيجة ناجحة فيعود المسح مراراً لنفس الضيف.
معجم مصطلحات الدرس
- facingMode environment
- طلب الكاميرا الخلفية في المتصفح.
- regexp /i/...
- استخرج token وطابع من نص الرابط.
- نظف المسار
- فتح وإيقاف دفق MediaStream عند انتهاء المكوّن.
مراجعة وتمرين تثبيت المهارة
اختبار سريع: اشرح بعبارتك معنى «تجربة المسح في بوابة الحفل»، ثم بيّن أين ستستخدمه داخل نظام تسجيل حضور دعوات مناسبة عبر رمز QR، وما الخطأ الذي يجب اختباره قبل الاعتماد على الحل.
تحدٍّ إضافي: غيّر شرطًا واحدًا في التطبيق، وتوقع النتيجة، ثم نفّذ الاختبار وفسّر الاختلاف.
الدرس التالي: واجهة تتفهم حالة الحضور والحصر. من الأفضل إنهاء التجربة الحالية قبل متابعة الدرس التالي.
