التكامل مع Strapi v5، وبوابات Webhooks والمزامنة التلقائية بدون Terminal

1. لماذا يتم تخزين مسارات Next.js 16 مؤقتاً بشكل إجباري (Force-Cache)؟

في نظام Next.js 16 App Router، يتم تخزين كافة طلبات fetch مؤقتاً بشكل افتراضي وقوي (Force-Cache) لضمان سرعة تحميل فائقة في أجزاء من الثانية. ولإلغاء وتحديث هذا الكاش فور تعديل المحتوى في Strapi أو Medusa، نعتمد معمارية On-Demand Cache Revalidation الذكية.

2. دليل خطوة بخطوة لإعداد الـ Webhooks في لوحة تحكم Strapi CMS

لضمان أن حفظ أو نشر أي صفحة في Strapi يقوم بتفريغ كاش الواجهة الأمامية فورياً دون الحاجة لإعادة تشغيل الخادم:

1. سجل الدخول إلى لوحة Strapi وتوجه إلى Settings > Webhooks.
2. انقر فوق زر Create new Webhook.
3. Name (الاسم): اختر اسماً مخصصاً، مثل Next.js Revalidation Webhook.
4. URL (الرابط): أدخل العنوان http://storefront:3000/api/revalidate (داخل شبكة Docker الداخلية) أو https://yourdomain.com/api/revalidate.
5. Events (الأحداث): حدد أحداث الـ Entry (إنشاء، تعديل، حذف، نشر، وإلغاء النشر).

• التحقق من صحة وموثوقية الطلب: استلام الرمز السري من ترويسة x-strapi-secret المخصصة أو معامل الاستعلام.
• إدارة الكاش الانتقائية: تفريغ وسوم الكاش (Cache Tags) المطابقة لنموذج Strapi المعني (مثل strapi-homepage).

import crypto from "node:crypto"
import { revalidateTag } from "next/cache"
import { NextRequest, NextResponse } from "next/server"
 
function isValidSecret(providedSecret: string | null): boolean {
  if (!providedSecret || !process.env.REVALIDATE_SECRET) return false
  const actual = new Uint8Array(crypto.createHash("sha256").update(providedSecret).digest())
  const expected = new Uint8Array(crypto.createHash("sha256").update(process.env.REVALIDATE_SECRET).digest())
  return crypto.timingSafeEqual(actual, expected)
}
 
export async function POST(request: NextRequest) {
  const secret = request.headers.get("x-strapi-secret") || request.nextUrl.searchParams.get("secret")
 
  if (!isValidSecret(secret)) {
    return NextResponse.json({ message: "Invalid secret" }, { status: 401 })
  }
 
  const body = await request.json()
  
  if (body.model) {
    revalidateTag(`strapi-${body.model}`)
  }
 
  return NextResponse.json({ revalidated: true, now: Date.now() })
}

3. هيكلية البيانات وربط Dynamic Zones بالواجهة الأمامية

يتم جلب كتل Dynamic Zone من Strapi عبر استعلام GraphQL أو REST مُحسَّن. يحتوي كل كائن كتلة على خاصية __component تحدد نوع الكتلة وخاصية style تحدد رقم النمط المختار.

4. معالجة الصور وتحسين الأصول عبر MinIO S3

يتم تخزين كافة الصور والملفات المرفوعة عبر Strapi في حاوية MinIO S3 المحلية المتوافقة مع معايير AWS S3، مع تحويل الصور تلقائياً إلى صيغة WebP الحديثة وتقديمها عبر شبكة Caddy الآمنة.

# Trigger component style sync via Strapi Admin API:
POST /api/storefront/sync-component
{
  "componentName": "home/components/ProductShowcase",
  "style": "style-2",
  "action": "add",
  "autoDeploy": false
}
 
# Trigger batch production build to GitHub Actions:
POST /api/storefront/build

تسمح هذه المعمارية بتوزيع الصور بسرعة البرق مع عزل كامل بين ملفات النظام والوسائط المرفوعة.