# تست PWA و Web Push روی گوشی واقعی با HTTPS محلی

این راهنما برای همین پروژه (`C:\xampp\htdocs\ecommerce`) و XAMPP روی Windows نوشته شده است. هدف این است که گوشی واقعی، سایت را روی یک مبدأ امن (`https://...`) باز کند و بتواند Service Worker، نصب PWA و اعلان Push را دریافت کند.

## چرا `http://localhost` روی گوشی کافی نیست؟

مرورگرها `localhost` و `127.0.0.1` را استثنائاً یک «مبدأ امن» می‌دانند. بنابراین روی همان کامپیوتر می‌توانید با `http://localhost:81/ecommerce/public` سرویس‌ورکر را تست کنید؛ اما وقتی گوشی آدرس `http://192.168.x.x:81/...` را باز می‌کند، این آدرس امن نیست و معمولاً:

- `navigator.serviceWorker` ثبت نمی‌شود.
- `PushManager` در دسترس نیست.
- نصب PWA و دریافت اعلان کار نمی‌کند.

در کد این پروژه هم `App\Support\Pwa::secureContext()` فقط درخواست HTTPS یا هاست‌های `localhost`/`127.0.0.1` را امن می‌داند. بنابراین برای تست روی گوشی باید HTTPS واقعی و قابل‌اعتماد داشته باشید.

> گواهی self-signed بدون نصب CA روی گوشی، اگر هم با هشدار مرورگر باز شود، برای Service Worker و Push قابل‌اتکا نیست. روش پیشنهادی، ساخت CA محلی با **mkcert** و نصب آن روی گوشی است.

## روش پیشنهادی: mkcert + Apache روی شبکه محلی

این روش برای تست پایدار روی گوشی مناسب است، چون آدرس و مبدأ (origin) ثابت می‌ماند و Proxy یا تونل خارجی لازم ندارد.

### ۱. پیش‌نیازها

- کامپیوتر و گوشی روی یک Wi-Fi/شبکه محلی باشند.
- XAMPP و Apache روی کامپیوتر در حال اجرا باشند.
- در این نصب، سایت فعلی روی `http://localhost:81/ecommerce/public` است. برای HTTPS یک پورت جدا مثل **8443** استفاده می‌کنیم تا با HTTP فعلی تداخل نداشته باشد.

### ۲. نصب mkcert

در PowerShell (یا CMD) یکی از روش‌های زیر:

```powershell
# اگر Chocolatey دارید
choco install mkcert -y

# یا با Scoop
scoop bucket add extras
scoop install mkcert
```

سپس یک‌بار CA محلی را در Windows نصب کنید:

```powershell
mkcert -install
```

### ۳. پیدا کردن IP کامپیوتر در شبکه محلی

```powershell
ipconfig
```

آدرس IPv4 کارت Wi-Fi/Ethernet را بردارید؛ مثلاً `192.168.1.50`. در ادامه هرجا `<LAN-IP>` نوشته شده، همین آدرس را بگذارید.

پیشنهاد: در تنظیمات Router برای این کامپیوتر **DHCP Reservation** بگذارید تا IP عوض نشود؛ وگرنه بعد از تغییر IP باید گواهی را دوباره بسازید.

### ۴. ساخت گواهی برای IP و localhost

پوشه‌ای امن خارج از پروژه بسازید (کلید خصوصی را داخل پروژه یا Git نگذارید):

```powershell
mkdir C:\xampp\apache\conf\ssl -Force
cd C:\xampp\apache\conf\ssl

mkcert -key-file mandano-lan-key.pem `
  -cert-file mandano-lan-cert.pem `
  localhost 127.0.0.1 <LAN-IP>
```

مثال:

```powershell
mkcert -key-file mandano-lan-key.pem -cert-file mandano-lan-cert.pem localhost 127.0.0.1 192.168.1.50
```

مسیر CA ساخته‌شده را نگه دارید؛ بعداً برای نصب روی گوشی لازم می‌شود:

```powershell
mkcert -CAROOT
```

فایل `rootCA.pem` داخل آن پوشه قرار دارد.

### ۵. فعال کردن SSL در Apache

فایل `C:\xampp\apache\conf\httpd.conf` را باز کنید و مطمئن شوید این ماژول‌ها بدون `#` هستند:

```apache
LoadModule ssl_module modules/mod_ssl.so
LoadModule socache_shmcb_module modules/mod_socache_shmcb.so
```

اگر این خط در انتهای فایل کامنت است، آن را فعال کنید:

```apache
Include conf/extra/httpd-vhosts.conf
```

یک فایل جدید به نام `C:\xampp\apache\conf\extra\httpd-mandano-ssl.conf` بسازید:

```apache
Listen 8443

<VirtualHost *:8443>
    ServerName <LAN-IP>
    ServerAlias localhost

    DocumentRoot "C:/xampp/htdocs/ecommerce/public"

    SSLEngine on
    SSLCertificateFile "C:/xampp/apache/conf/ssl/mandano-lan-cert.pem"
    SSLCertificateKeyFile "C:/xampp/apache/conf/ssl/mandano-lan-key.pem"

    <Directory "C:/xampp/htdocs/ecommerce/public">
        AllowOverride All
        Options FollowSymLinks
        Require all granted
    </Directory>
</VirtualHost>
```

سپس در `httpd.conf` این خط را اضافه کنید (اگر قبلاً اضافه نشده):

```apache
Include conf/extra/httpd-mandano-ssl.conf
```

نکته مهم: `DocumentRoot` باید به پوشه `public` اشاره کند، نه ریشه پروژه. با این تنظیم آدرس نهایی این است:

```text
https://<LAN-IP>:8443/
```

اگر می‌خواهید همان مسیر `/ecommerce/public` را حفظ کنید، باید Alias مناسبی تعریف کنید؛ ولی ساده‌تر و کم‌خطاتر این است که DocumentRoot را روی `public` بگذارید.

### ۶. باز کردن پورت در Firewall ویندوز

PowerShell را با دسترسی Administrator باز کنید:

```powershell
New-NetFirewallRule `
  -DisplayName "Mandano local HTTPS 8443" `
  -Direction Inbound `
  -Protocol TCP `
  -LocalPort 8443 `
  -Action Allow
```

اگر قبلاً قانونی ساخته‌اید، لازم نیست دوباره بسازید. برای بررسی:

```powershell
Get-NetFirewallRule -DisplayName "Mandano local HTTPS 8443"
```

### ۷. تست پیکربندی و ری‌استارت Apache

```powershell
C:\xampp\apache\bin\httpd.exe -t
```

باید پیام `Syntax OK` ببینید. سپس Apache را از XAMPP Control Panel متوقف/شروع کنید (Stop و Start). اگر Apache بالا نیامد، لاگ‌های `C:\xampp\apache\logs\error.log` را بررسی کنید؛ معمولاً پورت اشغال است یا مسیر گواهی اشتباه است.

### ۸. تنظیم `.env` پروژه

در `.env` این مقادیر را برای تست HTTPS تنظیم کنید:

```dotenv
APP_URL=https://<LAN-IP>:8443

# اختیاری: اگر می‌خواهید کوکی‌ها فقط روی HTTPS ارسال شوند
SESSION_SECURE_COOKIE=true
```

سپس کش‌های Laravel را پاک کنید:

```powershell
php artisan optimize:clear
```

اگر از `SESSION_SECURE_COOKIE=true` استفاده کردید، بعد از پایان تست HTTPS و برگشت به `http://localhost:81` آن را حذف کنید یا `false` بگذارید؛ وگرنه ورود/نشست روی HTTP ممکن است درست کار نکند.

بررسی کنید که `APP_URL` دقیقاً همین مبدأ باشد؛ بدون `/` انتهایی و با همان پورت:

```text
https://192.168.1.50:8443
```

`APP_URL` اشتباه باعث می‌شود `scope` مانیفست، `start_url` و آدرس Service Worker با آدرسی که در گوشی باز کرده‌اید یکی نباشد.

### ۹. نصب CA روی گوشی

بدون این مرحله، گوشی به گواهی mkcert اعتماد نمی‌کند و مرورگر هشدار می‌دهد.

#### اندروید

1. فایل `rootCA.pem` را به گوشی منتقل کنید (کابل USB، Google Drive یا ایمیل).
   اگر گوشی پسوند `.pem` را نشناخت، نام فایل را به `rootCA.crt` تغییر دهید.
2. در تنظیمات گوشی به مسیر گواهی‌ها بروید. مسیر در نسخه‌های مختلف کمی متفاوت است؛ معمولاً:
   `Settings → Security → More security settings → Encryption & credentials → Install a certificate → CA certificate`
3. فایل را انتخاب کنید و نصب را تأیید کنید.
4. Chrome را کامل ببندید و دوباره باز کنید.

#### iPhone / iPad

1. `rootCA.pem` را با AirDrop یا Files به گوشی بفرستید.
   اگر iOS فایل را به‌عنوان پروفایل نشناخت، آن را با پسوند `.crt` یا `.cer` امتحان کنید.
2. روی فایل بزنید تا پروفایل نصب شود: `Settings → General → VPN & Device Management`.
3. سپس حتماً به `Settings → General → About → Certificate Trust Settings` بروید و برای این CA گزینه **Enable Full Trust** را روشن کنید.
4. Safari را ببندید و دوباره باز کنید.

> CA محلی فقط برای دستگاه‌های تست خودتان باشد. بعد از پایان تست، پروفایل/گواهی را از گوشی حذف کنید. کلید خصوصی و فایل‌های گواهی را در Git قرار ندهید.

### ۱۰. باز کردن سایت روی گوشی

در مرورگر گوشی:

```text
https://<LAN-IP>:8443/
```

اگر آدرس باز نشد:

- IP را دوباره با `ipconfig` چک کنید.
- Firewall و پورت 8443 را بررسی کنید.
- مطمئن شوید گوشی روی همان شبکه است و Router گزینه **AP Isolation / Client Isolation** را فعال نکرده باشد.
- از خود کامپیوتر `https://localhost:8443` را باز کنید تا مشکل را جدا کنید.

قبل از تست PWA، این دو آدرس را در مرورگر گوشی باز کنید:

```text
https://<LAN-IP>:8443/manifest.webmanifest
https://<LAN-IP>:8443/service-worker.js
```

- مانیفست باید JSON برگرداند و `start_url` و `scope` آن با همین مبدأ HTTPS شروع شوند.
- فایل Service Worker باید با موفقیت برگردد و در Network، نوع آن JavaScript باشد.

## گزینه سریع‌تر: تونل HTTPS

اگر نمی‌خواهید گواهی محلی نصب کنید، می‌توانید از Cloudflare Tunnel یا ngrok استفاده کنید. این روش برای یک تست سریع خوب است، اما برای تست پایدار Push توصیه نمی‌شود.

### Cloudflare Tunnel

```powershell
cloudflared tunnel --url http://localhost:81
```

سپس آدرسی شبیه `https://random-name.trycloudflare.com` می‌گیرید. اگر سایت هنوز زیر مسیر `/ecommerce/public` است، آدرس کامل می‌شود:

```text
https://random-name.trycloudflare.com/ecommerce/public
```

`APP_URL` را دقیقاً همان آدرس کامل (با مسیر، در صورت وجود) بگذارید و `php artisan optimize:clear` را اجرا کنید.

محدودیت‌ها:

- URL رایگان در هر اجرا عوض می‌شود و Subscriptionهای قبلی Push دیگر معتبر نیستند.
- Laravel پشت Proxy باید `X-Forwarded-Proto` را باور کند؛ در غیر این صورت `request()->isSecure()` ممکن است `false` بماند و Service Worker ثبت نشود. اگر از تونل استفاده می‌کنید، Trusted Proxy را فقط در محیط Local تنظیم کنید و بعداً برندارید.
- آدرس تونل عمومی است. هنگام تست، آن را در اختیار دیگران نگذارید و بعد از تست تونل را ببندید.
- برای تست پایدار، یک Named Tunnel با دامنه ثابت بهتر است.

اگر Service Worker با تونل ثبت نشد، Laravel باید بداند درخواست از یک Proxy امن آمده است. فقط برای محیط Local و فقط در مدت تست، در `bootstrap/app.php` داخل `withMiddleware` اضافه کنید:

```php
$middleware->trustProxies(at: '*');
```

بعد `php artisan optimize:clear` را اجرا کنید. این تنظیم را در Production نگه ندارید؛ Proxyهای واقعی باید مشخص و محدود باشند.

### ngrok

```powershell
ngrok http 81
```

مانند Cloudflare، آدرس HTTPS عمومی می‌گیرید، `APP_URL` را به‌روزرسانی می‌کنید و همان محدودیت Trusted Proxy و تغییر URL را دارید.

## نکات مهم Push

- Web Push علاوه بر HTTPS به کلیدهای **VAPID** نیاز دارد. در پنل مدیریت، بخش PWA، وضعیت کلیدها باید «آماده» باشد. این پروژه در صورت نبود کلید، خودش تلاش می‌کند کلید بسازد؛ اگر OpenSSL مشکل داشت، خطا را در همان صفحه ببینید.
- بعد از تغییر دامنه/پورت (مثلاً از `localhost` به IP گوشی)، مبدأ عوض می‌شود. PWA نصب‌شده قبلی و Subscription قدیمی را دور بیندازید و از نو نصب/اشتراک بگیرید.
- در Android، اعلان نیاز به اجازه مرورگر و در برخی نسخه‌ها کانال اعلان دارد. اگر قبلاً اجازه را رد کرده‌اید، از تنظیمات سایت (Site settings → Notifications) آن را Reset کنید.
- در iPhone/iPad، Web Push از **iOS 16.4** به بعد و فقط برای PWA نصب‌شده روی Home Screen کار می‌کند. Safari معمولی کافی نیست. نصب PWA و سپس اجازه اعلان لازم است.
- گوشی باید اینترنت داشته باشد تا سرویس Push (FCM/APNs) پیام را تحویل دهد؛ صرفاً وصل بودن به Wi-Fi بدون اینترنت کافی نیست.
- اگر کامپیوتر خاموش شود یا Apache متوقف شود، Push محلی ارسال نمی‌شود. برای تست، کامپیوتر و Apache باید روشن بمانند.
- اگر Push نمی‌رسد، ابتدا از پنل PWA یک اعلان آزمایشی بفرستید و وضعیت Subscription را در همان صفحه بررسی کنید.

## چک‌لیست تست روی گوشی

1. `https://<LAN-IP>:8443/` بدون هشدار گواهی باز می‌شود.
2. `manifest.webmanifest` با موفقیت لود می‌شود و `scope`/`start_url` همان مبدأ HTTPS هستند.
3. `service-worker.js` با موفقیت لود می‌شود.
4. در Chrome Desktop با `chrome://inspect` (اندروید) یا Safari Web Inspector (iOS) ثبت Service Worker را می‌بینید.
5. PWA را نصب می‌کنید و از Home Screen باز می‌شود.
6. در صفحه PWA دکمه اعلان‌ها را می‌زنید و اجازه می‌دهید.
7. در پنل مدیریت، بخش PWA، مشترک جدید دیده می‌شود.
8. یک اعلان آزمایشی می‌فرستید و آن را در حالت باز، Background و قفل صفحه بررسی می‌کنید.
9. بعد از تغییر فایل‌ها/استایل‌ها، نسخه کش PWA را از پنل مدیریت پاک می‌کنید یا نسخه Cache را افزایش می‌دهید؛ در غیر این صورت ممکن است نسخه قدیمی را ببینید.

## رفع اشکال سریع

| مشکل | علت محتمل | راه‌حل |
|---|---|---|
| `serviceWorker` ثبت نمی‌شود | مبدأ امن نیست یا گواهی مورد اعتماد نیست | HTTPS و نصب CA روی گوشی را بررسی کنید |
| صفحه روی گوشی باز نمی‌شود | Firewall، IP اشتباه یا AP Isolation | پورت 8443 و IP و شبکه Wi-Fi را بررسی کنید |
| مانیفست لود می‌شود ولی `scope` اشتباه است | `APP_URL` با آدرس گوشی یکی نیست | `APP_URL` را دقیقاً با پورت و مسیر درست تنظیم و کش را پاک کنید |
| Push subscribe خطا می‌دهد | VAPID آماده نیست، HTTPS نیست یا اجازه اعلان داده نشده | پنل PWA، کلیدها، HTTPS و Permission مرورگر را بررسی کنید |
| بعد از تغییر دامنه اعلان قبلی کار نمی‌کند | مبدأ/Subscription قبلی عوض شده | PWA را حذف و دوباره نصب کنید و Subscription جدید بسازید |
| خطای 419 یا ورود نمی‌شود | کوکی/Session یا `APP_URL` با مبدأ جدید هماهنگ نیست | `SESSION_SECURE_COOKIE`، `APP_URL` و `php artisan optimize:clear` را بررسی کنید |
| نسخه قدیمی UI دیده می‌شود | کش Service Worker | از پنل PWA کش را پاک کنید یا در DevTools گزینه Clear site data را بزنید |

## امنیت

- این تنظیمات فقط برای توسعه محلی است. گواهی و کلید خصوصی را در Git، بکاپ عمومی یا فایل‌های پروژه قرار ندهید.
- پورت HTTPS محلی را روی اینترنت باز نکنید. برای تست روی گوشی، همان شبکه محلی امن‌تر از تونل عمومی است.
- اگر از تونل عمومی استفاده می‌کنید، آدرس را محرمانه نگه دارید و بعد از تست آن را ببندید.
- از دیتابیس و اطلاعات واقعی مشتریان برای تست محلی استفاده نکنید؛ یک کپی/دیتابیس تست بسازید.
