واجهات الضيوف الإضافة والقائمة
المسار: تطوير نظام إدارة الأعراس ودعوات QR الوحدة: واجهات API والبنية الخلفية
مدخل إلى الدرس: واجهات الضيوف الإضافة والقائمة
واجهات الضيوف الإضافة والقائمة — نظام إدارة الأعراس والمناسبات ودعوات QR | Next.js وPrisma | أديب الصلوي
طريقة الدراسة: اقرأ التعريف، تتبّع المثال في الشرح، نفّذه بنفسك، ثم اختبر النتيجة والحالات الاستثنائية قبل الانتقال.
أهداف هذا الدرس
- بناء POST/GET لواجهة الضيوف مع فهرس eventId.
- توليد token وtokenHash عند إنشاء كل ضيف.
- تبسيط إضافة المدعوين بلا أعمدة معلقة.
مثال
// lib/tsign.ts — قبض المفاتيح (سيُشرح بكامله في فصل QR)
import { createHmac, randomBytes, timingSafeEqual } from "crypto";
const SECRET = process.env.SIGNING_SECRET!;
export function makeToken() {
return randomBytes(24).toString("base64url");
}
export function tokenHashOf(token: string) {
return createHmac("sha256", SECRET).update(token).digest("hex");
}
export function signatureOf(token: string) {
return createHmac("sha256", SECRET).update("guest:" + token).digest("hex");
}مثال
// app/api/guests/route.ts
import { NextResponse } from "next/server";
import { prisma } from "@/lib/prisma";
import { makeToken, tokenHashOf } from "@/lib/tsign";
export async function POST(req: Request) {
const { eventId, name, phone, category, tableNo } = await req.json();
const token = makeToken();
const guest = await prisma.guest.create({
data: {
eventId, name,
phone: phone ?? null,
category: category ?? "general",
tableNo: tableNo ?? null,
tokenHash: tokenHashOf(token),
},
});
// الرمز الصريح يُلتقط الآن فقط ليُبنى منه الرابط/QR
return NextResponse.json({ ok: true, data: { ...guest, token } }, { status: 201 });
}المخطط: أين يلتقط المفضّل token؟
flowchart TD
A["POST /api/guests"] --> T["makeToken() — token صريح (لحظة واحدة)"]
A --> H["tokenHashOf — نخزّن في العمود UNIQUE"]
A --> CR["إنشاء الصف"]
A --> R["الرد: /i/TOKEN?sig=SIG
لا نخزّن TOKEN أبداً"]
الأداء + الأمان
من هنا نرى لماذا يجب أن تكون العمود tokenHash مفهرساً وفريداً: عند المسح يُشمَّس البحث بالهاش مباشرة بدل البحث بالرمز الصريح.
تمرين تطبيقي: أضف GET يعيد ضيوف مناسبة معينة عبر where { eventId } ثم عدّها بفهرس eventId وراقب خطته explain في psql.
أخطاء شائعة يجب تفاديها
- إعادة token داخل كل استجابة لاحقة — يصبح مسرباً بلا غرض.
- عدم إنشاء tokenHash فريد فيبطئ النظام ويسمح تضارباً.
- تحويل phone trivially rcعند قراءته في القائمة.
معجم مصطلحات الدرس
- tokenHash
- هاش محفوظ بدل الرمز الصريح لضمان السرية.
- findMany by eventId
- استعلام قائمة ضيوف مناسبة محددة.
- القراءة بعد الإنشاء
- بند الأمان: لا نفضحي الرمز الصريح في قوائم لاحقة.
مراجعة وتمرين تثبيت المهارة
اختبار سريع: اشرح بعبارتك معنى «واجهات الضيوف الإضافة والقائمة»، ثم بيّن أين ستستخدمه داخل نظام تسجيل حضور دعوات مناسبة عبر رمز QR، وما الخطأ الذي يجب اختباره قبل الاعتماد على الحل.
تحدٍّ إضافي: غيّر شرطًا واحدًا في التطبيق، وتوقع النتيجة، ثم نفّذ الاختبار وفسّر الاختلاف.
الدرس التالي: واجهة تسجيل الحضور POST /api/checkin. من الأفضل إنهاء التجربة الحالية قبل متابعة الدرس التالي.
