حل المشكلات

أكثر المشكلات شيوعًا، وكيف تعالج كل واحدة منها.

رسالة "AUTH_SECRET is missing or too short"

ملف .env غير موجود، أو أن AUTH_SECRET أقصر من 16 حرفًا. أنشئ .env من .env.example وضع فيه قيمة عشوائية طويلة، ثم أعد تشغيل الخادم.

رسالة "Settings row missing: run npm run db:seed"

قاعدة البيانات موجودة لكنها فارغة. شغّل npm run db:seed، فينشئ الإعدادات والمتجر التجريبي وحساب المالك، ولا يكتب فوق أي بيانات موجودة.

لا أستطيع الدخول إلى اللوحة

  • لا يُنشأ حساب المالك إلا إذا كان جدول المشرفين فارغًا. إن غيّرت OWNER_PASSWORD بعد التعبئة الأولى فكلمة المرور القديمة هي السارية.

  • لإعادة تعيينها، افتح الطرفية في مجلد المشروع وشغّل:

    node -e 'const{scryptSync,randomBytes}=require("crypto");const s=randomBytes(16);console.log("scrypt$"+s.toString("hex")+"$"+scryptSync("NEW-PASSWORD-HERE",s,64).toString("hex"))'
    

    ثم ضع الناتج في عمود passwordHash لحسابك باستخدام npx prisma studio.

  • بعد 10 محاولات في دقيقة من العنوان نفسه يتوقف الدخول دقيقة كاملة.

صفحة تقول «هذا القسم غير متاح لدورك»

دور الحساب لا يملك صلاحية هذا القسم. يستطيع المالك تغييرها من اللوحة > أدوار المشرفين، ويسري التغيير فورًا.

الدفع بالبطاقة لا يظهر عند إتمام الطلب

يجب أن تجتمع ثلاثة شروط: خيار الدفع بالبطاقة مفعّل في الإعدادات، والمفتاحان THAWANI_SECRET_KEY وTHAWANI_PUBLISHABLE_KEY موجودان في .env، والعملة هي الريال العماني. راجع الدفع.

طلب مدفوع بالبطاقة ما زال «بانتظار الدفع»

لا يُعلَّم الطلب مدفوعًا إلا بعد أن يسأل الخادم «ثواني» عن جلسة الدفع. إن أغلق العميل المتصفح قبل العودة، افتح الطلب في اللوحة: مرجع الدفع هو رقم جلسة «ثواني» ويمكنك مراجعته في بوابة التاجر. وتأكد أن SITE_URL هو عنوانك العام بـhttps:// لأن «ثواني» تعيد العميل إليه.

الصور المرفوعة تختفي بعد النشر

استُبدل المجلد public/uploads مع الإصدار الجديد. احتفظ به بين عمليات النشر (راجع التثبيت اليدوي).

رسالة «طلبات كثيرة»

يسمح إتمام الطلب بـ20 طلبًا في الدقيقة من العنوان نفسه، ونموذج التواصل بـ5 رسائل كل 10 دقائق، وتسجيل الدخول بـ10 محاولات في الدقيقة. إن كان المتجر خلف وسيط (proxy) فتأكد أنه يرسل X-Forwarded-For، وإلا عُدّ كل الزوار زائرًا واحدًا.

نص عربي يظهر باتجاه خاطئ

الرموز وأرقام SKU والهواتف موضوعة في الصنف ltr-nums لتبقى من اليسار إلى اليمين داخل النص العربي. إن أضفت حقولًا جديدة بنص مختلط فغلّفها بالطريقة نفسها (راجع اللغات).

فشل البناء بعد تعديل صفحة

شغّل npx tsc --noEmit لترى أخطاء الأنواع مع الملف والسطر. ملفات المسارات تحت src/app/api لا تصدّر إلا دوال HTTP (GET وPOST…) وإعدادات مثل dynamic؛ ضع الكود المشترك في src/lib.

الاختبار الشامل يفشل على متجر استخدمته

يتوقع scripts/e2e_api.py الكتالوج التجريبي (منتج «قفطان كتان» وكوبون WELCOME10 مثلًا). شغّله على قاعدة تجريبية جديدة: احذف prisma/souq.db، وشغّل npm run setup، ثم شغّل الخادم والاختبار.