لماذا تُعيد البحث نتائج فارغة؟

تكتب كلمة في شريط بحث VeloCMS ولا يظهر شيء — أو تظهر نتائج قليلة جداً في حين تعلم أنه ينبغي أن تكون عشرات. البحث في VeloCMS مدعوم بـPagefind، وهي مكتبة بحث للمواقع الثابتة تُفهرس المحتوى أثناء البناء. حين يتعطل البحث، تكون المشكلة شبه دائماً في مرحلة البناء لا في مرحلة التشغيل.

كيف يعمل Pagefind في VeloCMS

أثناء تنفيذ npm run build، تُنشئ Next.js ملفات HTML ثابتة لكل مسار مقالة مساعدة (/help/[slug]). بعد هذه الخطوة، يُشغّل سكريبت postbuild أداة Pagefind على مجلد .next/server/app ويكتب فهرس البحث في public/pagefind/. يُقدَّم هذا الفهرس كأصل ثابت إلى جانب الموقع. حين يبحث المستخدم، يُنزّل المتصفح الفهرس ويُجري البحث على جانب العميل كلياً — دون أي استعلام للخادم.

الفهرس مفقود كلياً

إن لم تُعِد عملية البحث أي نتائج حتى للكلمات الشائعة جداً، فالسبب الأرجح هو أن فهرس Pagefind غير موجود. يحدث هذا حين تُتخطى خطوة postbuild — مثلاً إن انقطع تنفيذ npm run build في منتصف الطريق، أو إن كنت تشغّل خادم التطوير (npm run dev لا يُشغّل postbuild). البحث يعمل فقط في نسخ الإنتاج.

# Check if the Pagefind index exists after a build:
ls public/pagefind/

# Expected output includes: pagefind-entry.json pagefind.js index/
# If the directory is empty or missing, rebuild:
npm run build

مقالات المساعدة لا تُبنى بـSSG

يُفهرس Pagefind ملفات HTML الثابتة. إن لم تُنشأ مسارات مقالات المساعدة بشكل ثابت، فلا يوجد HTML لـPagefind يُفهرسه. يستخدم VeloCMS generateStaticParams لتصيير جميع مسارات مقالات المساعدة مسبقاً عند البناء. يُخفق هذا بصمت إن كان أي مما يلي صحيحاً.

• يُستدعى cookies() أو headers() في مكان ما داخل شجرة المسار /help/[slug] — هذان الاستدعاءان يُحوّلان المسار إلى تصيير ديناميكي ويُعطّلان SSG.
• يُعيد generateStaticParams في src/app/help/[slug]/page.tsx مصفوفة فارغة — يحدث هذا إن كانت HELP_ARTICLES فارغة (خطأ في الاستيراد) عند البناء.
• أُضيف export const dynamic = 'force-dynamic' بالخطأ إلى صفحة help/[slug] — أزله. صفحات الإدارة تحتاجه؛ صفحات المساعدة يجب ألّا تحتوي عليه.
• يستدعي التخطيط الجذري cookies() أو headers() دون أن يُغلَّف في مقطع ديناميكي — هذا يُخرج التطبيق بأكمله من SSG.

الفهرس قديم

إن أضفت مقالات جديدة لكن البحث لا يجدها، فالفهرس قديم — وُلِد قبل إضافة المقالات. هذا سلوك متوقع: الفهرس لا يتحدث إلا عند بناء جديد. شغّل npm run build لإعادة توليد الفهرس بأحدث المقالات. في بيئة الإنتاج على Railway، يُشغّل كل git push بناءً كاملاً، لذا تُفهرَس المقالات الجديدة تلقائياً عند النشر التالي.

التحقق من التغطية بالبوابة المدمجة

يحتوي VeloCMS على سكريبت مدمج للتحقق من تغطية Pagefind يعمل كجزء من خطوة postbuild. بعد البناء، يقارن عدد مسارات /help/* المُصيَّرة مسبقاً مع عدد الصفحات في فهرس Pagefind ويُفشل البناء إن كان الفهرس أقل بكثير من العدد المتوقع. إن اجتاز بناؤك هذه البوابة، فـPagefind يعمل بشكل صحيح.

# Run the coverage gate manually (after a build):
node scripts/verify-pagefind-coverage.mjs

# Passing output example:
# [verify-pagefind] Prerendered /help/* routes : 164
# [verify-pagefind] Pagefind total page_count  : 180
# [verify-pagefind] Required minimum           : 164