توليد صورة QR من قاعدة الدعوة
المسار: تطوير نظام إدارة الأعراس ودعوات QR الوحدة: توليد وقراءة رموز QR
مدخل إلى الدرس: توليد صورة QR من قاعدة الدعوة
توليد صورة QR من قاعدة الدعوة — نظام إدارة الأعراس والمناسبات ودعوات QR | Next.js وPrisma | أديب الصلوي
طريقة الدراسة: اقرأ التعريف، تتبّع المثال في الشرح، نفّذه بنفسك، ثم اختبر النتيجة والحالات الاستثنائية قبل الانتقال.
أهداف هذا الدرس
- تثبيت مكتبة qrcode واستخدامها بأدق الخيارات.
- إنتاج صورة QR تحمل الرابط الموقّع كاملاً.
- دمج التوليد في مسارات API مع قيم errorCorrection وmargin.
مثال
npm install qrcode npm install --save-dev @types/qrcode
مثال
// app/api/guests/[id]/qr/route.ts
import { QRCodeToDataURLOptions } from "qrcode";
import QRCode from "qrcode";
import { prisma } from "@/lib/prisma";
import { signatureOf } from "@/lib/tsign";
export async function GET(
req: Request,
ctx: { params: Promise<{ id: string }> }
) {
const { id } = await ctx.params;
const guest = await prisma.guest.findUnique({ where: { id } });
if (!guest || !guest.tokenHash) {
return new Response(JSON.stringify({ ok: false, error: "لا ضيف" }), { status: 404 });
}
// ملاحظة: الرمز الصريح لا يُخزَّن في قاعدة البيانات،
// بل نمرّره إلى هذه الواجهة من مكوّن الإنشاء لحظة ولادته فقط.
// أما هنا فنحتفظ للمستقبل: قراءة رابطٍ من مخزن آمن أو من prop.
const opts: QRCodeToDataURLOptions = {
errorCorrectionLevel: "M",
margin: 2,
width: 384,
};
return NextResponse.json({ ok: true, qr: url, url });
}المخطط: مجرى إنشاء QR من بيانات الضيف
flowchart TD
G["ضيف (id, tokenHash)"] --> L["الرابط: /i/{token}?sig=..."]
L --> QR["QRCode.toDataURL(url)
errorCorrectionLevel: M
margin 2 · width 384"]
QR --> S["تحفظ dataURL/path في qrPath
جاهز للمسح"]
لماذا M لا H؟
مستوى التصحيح H يزيد الكثافة ويصعب على الكاميرا القديمة القراءة. مستوى M (15%) يوازن حجم المكتوب مع الخط المطبعي؛ تكفي احتياجاتنا لمسح شاشة أو ورقة.
أمان مستقبلي
قرار معياري: لا تجلب الرمز الصريح من قاعدة البيانات لاحقاً — تُنمّراته إلى واجهة توليد QR لحظة ولادته فقط، حتى لا تتحول قاعدة مُساربة إلى مفتاح روابط صحيحة.
تمرين تطبيقي: نفّذ توليد QR لضيف حقيقي وامسحه من شاشة هاتفك — تحقق أنه يفتح الدعوة ويستقبل التوقيع بنجاح دون أي خطأ إصدار.
أخطاء شائعة يجب تفاديها
- اختيار مستوى تصحيح مرتفع للغاية (H) فيزيد الكثافة ويصعب المسح.
- استخدام margin 0 فيعجز الماسح عن تمييز الحدود.
- توليد QR في كل طلب بدل الكاشف المحفوظ في qrPath.
معجم مصطلحات الدرس
- قابلية الخطأ
- قدرة رمز القراءة واستعادته للبيانات عند تلفه.
- toDataURL
- تحويل محتوى QR إلى سلسلة صورة قاعدة بيانات.
- qrcode
- مكتبة Node منخفضة تعتمد إعدادات تشفير قوالب.
مراجعة وتمرين تثبيت المهارة
اختبار سريع: اشرح بعبارتك معنى «توليد صورة QR من قاعدة الدعوة»، ثم بيّن أين ستستخدمه داخل نظام تسجيل حضور دعوات مناسبة عبر رمز QR، وما الخطأ الذي يجب اختباره قبل الاعتماد على الحل.
تحدٍّ إضافي: غيّر شرطًا واحدًا في التطبيق، وتوقع النتيجة، ثم نفّذ الاختبار وفسّر الاختلاف.
الدرس التالي: تجربة المسح في بوابة الحفل. من الأفضل إنهاء التجربة الحالية قبل متابعة الدرس التالي.
