صور المنتجات لا تظهر في المتجر الإلكتروني

١. المشكلة The problem

المنتج له صورة ظاهرة داخل Moon ERP، لكن نفس المنتج يظهر في المتجر الإلكتروني بدون صورة (صورة بديلة رمادية).

أي أن هذه ليست مشكلة في كود المتجر، ولا في التصميم، ولا في الكاش. هي فجوة معمارية في طبقة تخزين الصور في الباك-إند، وستظهر بنفس الشكل في تطبيق الموبايل وأي مستهلك عام آخر.

٢. الوضع الحالي — بالأدلة Current state, verified

٢.١ مساران مختلفان تمامًا لنفس الصورة

٢.٢ الكود المسؤول — تم قراءته سطرًا بسطر

أ) رفع المرفق يذهب للقرص الافتراضي (الخاص): Modules/Core/app/Http/Controllers/AttachmentController.php:106-115

$directory = "attachments/{$companyId}/".now()->format('Y-m');
$path = $file->store($directory);   // ← بدون تحديد disk ⇒ يستخدم FILESYSTEM_DISK
...
'file_path' => $path,

وفي .env: FILESYSTEM_DISK=local. وفي config/filesystems.php:33-45:

'local'  => root: storage_path('app/private')   ← خاص، بلا رابط عام
'public' => root: storage_path('app/public'),
           url:  https://moonui4.elbaset.com/moon-erp-be/storage   ← المنشور فعليًا

ب) الأكسسور يبني رابطًا عامًا لمسار خاص — وهنا الخطأ المباشر: Modules/Core/app/Models/Product.php:207-222

public function getImageUrlAttribute(): ?string
{
    if ($this->image) {
        return url('storage/'.$this->image);          // ✔ يعمل لو المسار داخل القرص العام
    }
    $attachment = ... $this->attachments()->first();
    if ($attachment) {
        return url('storage/'.$attachment->file_path); // ✘ file_path = attachments/… على القرص الخاص ⇒ 404 مضمون
    }
    return null;
}

٢.٣ التذكرة موجودة أصلًا ومعترف بها في الكود

التعليق في Modules/WebStore/app/Console/FixImagePaths.php:11-19 يصف المشكلة حرفيًا:

historical records store their image in the generic Attachment path
(attachments/{company}/{Y-m}/…). Those files live on the private `local`
disk, so /storage/attachments/… returns 404 for the storefront/mobile apps.
New uploads are already copied into the public area by
ensurePubliclyServable on save, but pre-existing rows were never re-saved.

أي أن الفريق شخّص المشكلة سابقًا (STORE-040) وكتب لها أمر إصلاح، لكن الإصلاح جزئي — انظر الفجوة في القسم ٤.

٢.٤ حالة قاعدة بيانات moonui4 اليوم تم القياس

٣. جذر المشكلة Root cause

هناك نظامان لتخزين الصور في Moon ERP، وُلدا في وقتين مختلفين ولم يتم توحيدهما:

الأول مصمَّم للنشر العام. الثاني مصمَّم للمستندات الداخلية (فواتير، عقود، تقارير) ولذلك هو خاص عمدًا وهذا صحيح أمنيًا. المشكلة أن صور المنتجات تُرفع أحيانًا عبر المسار الثاني، ثم يحاول getImageUrlAttribute() تقديمها كأنها من المسار الأول.

٣٫٥ سؤالان محدَّدان — بالإجابة والدليل Two direct questions, answered

س١: هل في جدول attachments أي علامة تقول «ده صورة المنتج»؟

لا. ولا واحدة. ده كل أعمدة الجدول — مقروءة من قاعدة البيانات مباشرةً:

id · company_id · attachable_type · attachable_id · file_name
file_path · file_size · mime_type · uploaded_by
created_at · updated_at · deleted_at

الإشارات المتاحة الوحيدة، وكل واحدة فيها ضعف:

س٢: خدمة رفع صورة المنتج في المتجر — بتفرّع Attachment ولا حاجة تانية؟

حاجة تانية خالص. مافيش أي تفريع. النظامان منفصلان تمامًا ولا يعرف أحدهما الآخر.

الدليل — HandlesImageUpload::resolveImageField() في app/Http/Controllers/Concerns/HandlesImageUpload.php:19-22:

if ($request->hasFile($field)) {
    $stored = $request->file($field)->store("uploads/{$folder}", 'public');
    // ← يكتب على القرص العام صراحةً، ولا يُنشئ أي صف Attachment
    return $stored;
}

وبحث شامل عن كل مواضع إنشاء المرفقات في المشروع كله:

$ grep -rn "Attachment::query()->create\|attachments()->create" Modules app

Modules/Core/.../AttachmentController.php:110        ← الـAPI العام
Modules/Clinic/.../SubmitExternalResult.php:51       ← نتائج معامل خارجية
Modules/Production/.../MfgCoaController.php:291      ← شهادات تحليل
Modules/Production/.../MfgTollContractController.php:391  ← عقود

→ ولا موضع واحد لصور المنتجات.

وماذا يعني هذا لخيار «ننقل الصور زي ما هي»؟

النقل الحرفي (نسخ ملفات attachments/ ونخلي الصفوف زي ما هي) لن يُصلِح شيئًا — لأن العطل مش في مكان الملف وبس، هو في إن لا وجود لعَلَم يربط المرفق بكونه صورة المنتج. الخيارات الواقعية:

(أ) و(ب) مش متعارضين: ممكن (أ) دلوقتي لأنها بتحل الاستيراد فورًا بلا migration، و(ب) لاحقًا كتنظيف معماري.

★ الحل الجذري — الجدول الصحيح موجود بالفعل ولم يُستخدم The radical fix

الاكتشاف

Moon ERP عنده أصلًا نظام كامل لصور المنتجات المتعددة، بعلامات صحيحة، على القرص العام — ومُهمَل تمامًا:

$ SHOW COLUMNS FROM product_images;
id · product_id · image · position · created_at · updated_at

$ SELECT COUNT(*) FROM product_images;
0   ← صفر صفوف. الجدول موجود ومربوط ولم يُستعمل قط.

والعلاقة موجودة ومرتّبة في Modules/Core/app/Models/Product.php:198-201:

public function images(): HasMany
{
    return $this->hasMany(ProductImage::class)->orderBy('position');
}

إذن ما الخطأ الحقيقي؟

الخطة الجذرية

'image' => $this->image,      // → "uploads/products/x.jpg" — مسار نسبي مكسور

٤. الفجوة The gap

الأمر webstore:fix-image-paths موجود ويعالج جزءًا من المشكلة، لكنه لا يكفي. ما يغطيه وما لا يغطيه:

٥. الملفات المتأثرة Affected files

٦. الحالات الحدّية Edge cases

• مرفق ليس صورة — PDF/Word يصبح "صورة المنتج". يجب الفلترة على mime_type LIKE 'image/%'.
• عدة مرفقات — "أول مرفق حسب الـid" اختيار عشوائي فعليًا. أي المرفقات هي الصورة الرئيسية؟ قرار مطلوب.
• تعارض أسماء الملفات — النسخ يستخدم basename($path) فقط. ملفان بنفس الاسم من شركتين مختلفتين ⇒ واحد يدهس الآخر، وتظهر صورة شركة في متجر شركة أخرى. خطر تسريب حقيقي عند التشغيل متعدد الشركات.
• مساحة القرص — النسخ يُضاعف الحجم. ١٧ ألف صورة × نسختين. يجب قياس الحجم قبل التنفيذ.
• ملف مصدر مفقود — لا حل برمجي؛ يحتاج قائمة بالأصناف المتأثرة لقرار بشري.
• الصورة تظهر ثم تختفي — لو صُحّح العمود ثم أُعيد الرفع من واجهة المرفقات، ترتد المشكلة. الإصلاح يجب أن يمنع التكرار لا أن ينظّف فقط.
• الكاش — الصور تُخدَم بكاش سنة كاملة في .htaccess؛ رابط صحّحناه قد يظل مكسورًا في متصفح العميل. أسماء الملفات ثابتة وليست مبصومة.

٧. خطة التنفيذ — كـ Work Packages Proposed plan

مقترحة فقط. لن يُكتب أي كود قبل موافقتك.

الترتيب مقصود: WP-IMG-1 وحده يجعل السلوك صادقًا فورًا (بديل بدل صورة مكسورة) حتى لو تأخر الباقي.

٨. قرارات تحتاج المالك Owner decisions

وسؤال معلّق من قبل، صار الآن مرتبطًا مباشرةً: استيراد منتجات مون — بصور أم بدونها؟ كل الأصناف أم عينة؟ وهل هي بيانات عميل حقيقية (لأن نشرها في متجر عام قرار مختلف تمامًا)؟

٩. ما تحقّقت منه مقابل ما استنتجته Verified vs inferred