# تقرير إصلاح: زرار تثبيت PWA لا يظهر على الصفحة الرئيسية

> **التاريخ:** 2026-08-23  
> **الملفات المعدّلة:** 3 ملفات  
> **الملفات المتأثرة من التعديل:** 0 ملفات أخرى

---

## المشاكل المكتشفة (3 مشاكل مترابطة)

### 🔴 المشكلة #1 — `manifest.json`: قيمة `purpose` غير صالحة

**الملف:** [`manifest.json`](file:///D:/Important%20Projects/Apex_Logistics/Dashboard/public/manifest.json)

**الكود القديم:**
```json
"purpose": "any maskable"
```

**المشكلة:** المتصفحات الحديثة (Chrome 116+) لا تقبل الجمع بين `any` و `maskable` في نفس القيمة. المتصفح يعتبر الأيقونة **غير صالحة بالكامل** → يعتبر إن الـ manifest **مفيش فيه أيقونات صالحة** → **لا يُطلق حدث `beforeinstallprompt` أبداً** → **الزرار لا يظهر أبداً**.

**الحل:** فصل الأيقونات إلى 3 entries منفصلة:
```diff
- { "purpose": "any maskable" }    ← entry واحد غير صالح
+ { "purpose": "any" }             ← 192x192 للشاشة الرئيسية
+ { "purpose": "any" }             ← 512x512 لشاشة البداية (splash)
+ { "purpose": "maskable" }        ← 512x512 للأيقونة المقنّعة (Android adaptive icons)
```

---

### 🔴 المشكلة #2 — `firebase-messaging-sw.js`: الـ Service Worker يفشل بالكامل لو Firebase مش متاح

**الملف:** [`firebase-messaging-sw.js`](file:///D:/Important%20Projects/Apex_Logistics/Dashboard/public/firebase-messaging-sw.js)

**الكود القديم:**
```javascript
// ← Firebase imports أول حاجة بتتنفذ (ممكن تفشل)
importScripts('https://www.gstatic.com/firebasejs/...');
firebase.initializeApp(firebaseConfig);        // ← لو فشلت، كل اللي بعدها مش بيتنفذ
const messaging = firebase.messaging();
messaging.onBackgroundMessage(...);

// ← PWA handlers في الآخر — مش بتتسجل لو Firebase فشل!
self.addEventListener('install', ...);
self.addEventListener('fetch', ...);
```

**المشكلة:** لو Firebase CDN مش متاح (شبكة بطيئة، حظر، خطأ)، أو لو الـ config فاضية، الـ `importScripts()` أو `firebase.initializeApp()` بتـ throw error **غير مُعالج** → الـ Service Worker **يفشل في التثبيت بالكامل** → الـ PWA handlers (`install`, `activate`, `fetch`) **ما بتتسجلش** → المتصفح **ما بيطلقش** `beforeinstallprompt` → **الزرار ما بيظهرش**.

**الحل:** إعادة هيكلة الملف:
1. الـ PWA handlers (`install`, `activate`, `fetch`, `notificationclick`) **أول حاجة بتتسجل** — مضمونة 100%
2. Firebase initialization ملفوفة في `try-catch` — لو فشلت، الـ PWA يفضل شغال
3. فحص `if (firebaseConfig.apiKey)` قبل محاولة تهيئة Firebase

```diff
+ // PWA handlers أولاً (دائماً نشطة)
+ self.addEventListener('install', ...);
+ self.addEventListener('activate', ...);
+ self.addEventListener('fetch', ...);
+ self.addEventListener('notificationclick', ...);

+ // Firebase في try-catch (اختياري)
+ try {
+     importScripts('...');
+     if (firebaseConfig.apiKey) {
+         firebase.initializeApp(firebaseConfig);
+         // ... messaging ...
+     }
+ } catch (e) {
+     console.warn('SW: Firebase initialization skipped:', e.message);
+ }
```

---

### 🔴 المشكلة #3 — `pwa-install-button.blade.php`: الـ Service Worker يتسجل متأخر جداً

**الملف:** [`pwa-install-button.blade.php`](file:///D:/Important%20Projects/Apex_Logistics/Dashboard/resources/views/filament/hooks/pwa-install-button.blade.php)

**المشكلة:** تسجيل الـ Service Worker كان يعتمد بالكامل على [`fcm-init.blade.php`](file:///D:/Important%20Projects/Apex_Logistics/Dashboard/resources/views/filament/hooks/fcm-init.blade.php) اللي بيشتغل في `BODY_END` كـ `<script type="module">` مع dynamic `import()`:

```
التسلسل الزمني:
HEAD_END   → manifest.json link ✅
PAGE_START → beforeinstallprompt listener يستنى ✅
BODY_END   → fcm-init module script (deferred) → import() من CDN → await register()
                                                   ↑
                                            هنا بيتأخر الـ SW كتير
```

الـ `type="module"` scripts **مؤجلة** بطبيعتها. وجوّاها `import()` ديناميكي بيحمّل ملفات من Google CDN. وبعده `await navigator.serviceWorker.register()`. كل ده بياخد وقت، والمتصفح مش بيطلق `beforeinstallprompt` غير لما الـ SW يبقى **active**.

**الحل:** إضافة تسجيل مبكر للـ Service Worker في الـ `pwa-install-button.blade.php` كـ **synchronous script** في `PAGE_START`:

```javascript
if ('serviceWorker' in navigator) {
    navigator.serviceWorker.register('/firebase-messaging-sw.js?apiKey=...&...')
        .catch(function(err) { console.warn('PWA: SW registration failed:', err); });
}
```

- بيستخدم **نفس الـ URL** بتاع `fcm-init` (مع نفس الـ Firebase config params)
- لما `fcm-init` يشتغل بعدها ويعمل `register()` بنفس الـ URL → **no-op** (مش بيسجل تاني، بيرجع الـ registration الموجودة)
- **صفر تعارض** مع الـ FCM

---

## ملخص التعديلات

| الملف | التغيير | الخطر | التأثير على باقي السيستم |
|-------|---------|-------|--------------------------|
| `public/manifest.json` | فصل `"any maskable"` لـ 3 entries منفصلة | **صفر** | لا يوجد — الملف ثابت (static) |
| `public/firebase-messaging-sw.js` | نقل PWA handlers قبل Firebase + try-catch | **صفر** | FCM شغال زي ما هو بالظبط — بس بقى أكثر أماناً |
| `resources/views/filament/hooks/pwa-install-button.blade.php` | إضافة SW registration مبكر | **صفر** | نفس الـ URL بتاع fcm-init → لا تعارض |

> [!IMPORTANT]
> **لم يتم تعديل أي شيء خارج هذه الـ 3 ملفات.** لا تعديل على الشاشات، لا تعديل على الـ AdminPanelProvider، لا تعديل على أي model أو controller أو route.

---

## ملاحظة مهمة للمستخدم

> [!NOTE]
> بعد نشر التعديلات، المستخدم محتاج يعمل **Hard Refresh** (Ctrl+Shift+R) أو يمسح الـ Service Worker القديم من DevTools → Application → Service Workers → Unregister، عشان الـ SW الجديد يتثبت ويبقى active.  
> لو التطبيق **مثبت من قبل**، الزرار مش هيظهر (ده سلوك طبيعي من المتصفح).


## 3. ?????? ?????? ?????? Filament/Livewire
**???????:** ??? ??? ?????? ??? ??? Header? ????? ?????? ???? ??????? Render Hook ??? ????? ?? ????? ?? CSS.
**????:** ?? ?????? ?? ???? ?? ?????? ?????? (???? ?? ????? ?? ??? ???????) ??? ????? `PwaInstallWidget` ???? ???? ???? ???? ????? ??? `AccountWidget` (?????? Admin) ??????? ??? ?????? ?? Inline Flexbox ????? ???? ?? ???? ??????? ???? ?????? ?????? ???? (Build) ????? Tailwind CSS.

## 4. ??? triggerPwaInstall is not defined
**???????:** ????? ????? ??? ??????? ??? ?????? ???? ??? JavaScript ???? ???? ????? DOM ?? Livewire (SPA Navigation) ???? ???? ??? `<script>` ??????? ?? ??? Widgets.
**????:** ?? ??? ????? ?????? ????? ??? ????? ??????? (Global Window Object) ?????? ?? ??? `HEAD_END` hook ??????? ?? `AdminPanelProvider` ????? ??????? ??? ????? ???? ????.

## 5. ??? ??????? ????? ????? ??????? ?????????
**???????:** ??????? ??? ????? ??? Manifest ??? ???? (Invalid) ???????? ?? ??? ???? ??? `beforeinstallprompt`. ????? ??? ?? ???????? ????????? ????? JPG? ?????? ?? ??? ?? ??????? ??????? (1254x1254) ?? ??? ????? ??????? ?????? ??? (192x192 ? 512x512).
**????:** ?? ????? ?????? PHP ??????? ?????? ??? ?????? ????? ?????? `192x192` ? `512x512` ????? PNG? ?????? ??? `manifest.json` ? `firebase-messaging-sw.js` ???? ??? ????? ???????. ???? ??? ??? Cache ?????? ???????? ???? ??????? ??? ??????? ???????? ?????.