ifnex/DEPLOYMENT_HANDOFF.md

# راهنمای استقرار IFNEX — ویژهٔ تیم IT کارفرما

> **مخاطب:** مسئول IT شرکت IFNEX
> **تاریخ تحویل:** ۲۰۲۶-۱۰-۰۴
> **نسخه:** ۱.۰
> **تهیه‌کننده:** VernaSoft Group — Kazem Alghasi

---

## ۱. معماری استقرار

این سیستم از دو بخش مستقل تشکیل شده است که هرکدام روی دامنهٔ جداگانه میزبانی می‌شوند و فقط از طریق REST API با هم ارتباط دارند.

| بخش | دامنه | روش تحویل | مسیر وب‌سرور |
|------|-------|------------|--------------|
| لاراول (API + پنل مدیریت Filament) | `system.ifnex.ir` | کلون گیت | `/var/www/system.ifnex.ir/public` |
| وردپرس (وب‌سایت + پورتال مشتری) | `ifnex.ir` | فایل ZIP + فایل SQL | `/var/www/ifnex.ir` |

**پیش‌نیازهای هر دو بخش:**

- PHP 8.2 یا بالاتر با اکستنشن‌های `pdo_mysql`، `mbstring`، `xml`، `gd`، `zip`
- MySQL 8 یا بالاتر
- Composer 2.x (فقط برای لاراول)
- Nginx یا Apache + PHP-FPM
- گواهی SSL از Let's Encrypt برای هر دو دامنه

---

## ۲. استقرار لاراول — `system.ifnex.ir`

### ۲.۱ کلون مخزن

```bash
cd /var/www/system.ifnex.ir

git clone https://www.git.vernahost.ir/gitmodir110/ifnex.git tmp

cp -r tmp/04_Laravel/* .
cp tmp/04_Laravel/.env.example .env

rm -rf tmp
```

### ۲.۲ نصب پکیج‌ها

```bash
composer install --no-dev --optimize-autoloader
```

### ۲.۳ تنظیم فایل `.env`

```bash
nano .env
```

مقادیر زیر را حتماً تنظیم کنید:

```dotenv
APP_NAME=IFNEX
APP_ENV=production
APP_DEBUG=false
APP_URL=https://system.ifnex.ir

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=ifnex_laravel
DB_USERNAME=YOUR_DB_USER
DB_PASSWORD=YOUR_DB_PASSWORD

IFNEX_API_KEY=change-this-secret-key
IFNEX_BRIDGE_API_KEY=change-this-secret-key
CORS_ALLOWED_ORIGINS=https://ifnex.ir

ZARINPAL_SANDBOX=false
ZARINPAL_MERCHANT_ID=YOUR_REAL_MERCHANT_ID
ZARINPAL_CALLBACK_URL=https://system.ifnex.ir/api/v1/payment/callback
ZARINPAL_FRONTEND_FAILURE_URL=https://ifnex.ir/wallet

KAVENEGAR_API_KEY=
KAVENEGAR_SENDER=
```

> ⚠️ **نکتهٔ امنیتی — الزامی:** هر دو مقدار `IFNEX_API_KEY` و `IFNEX_BRIDGE_API_KEY` باید پیش از استقرار با یک رشتهٔ تصادفی و طولانی (مثلاً خروجی `openssl rand -hex 32`) جایگزین شوند.
>
> مقدار `change-this-secret-key` عمداً انتخاب شده است، چون کد سمت لاراول (`BridgeAuthController`) دقیقاً همین مقدار را رد می‌کند و خطای ۵۰۰ می‌دهد. یعنی اگر جایگزینی فراموش شود، سیستم **بی‌سروصدا کار نمی‌کند** و به‌جای آن لو می‌دهد. هر مقدار دیگری — از جمله مواردی که شبیه placeholder باشند — به‌عنوان یک کلید معتبر پذیرفته می‌شود.
>
> `IFNEX_BRIDGE_API_KEY` باید عیناً در پلاگین وردپرس هم تنظیم شود. `IFNEX_API_KEY` کلید عمومی بخش رهگیری است و آن هم باید در پلاگین تنظیم شود.

### ۲.۴ راه‌اندازی اولیه

```bash
php artisan key:generate
php artisan migrate --force

# داده‌های مرجع — بدون این مرحله قیمت‌گذاری و فرم سفارش کار نمی‌کنند
php artisan db:seed --class=CountriesTableSeeder --force
php artisan db:seed --class=SystemSettingSeeder --force
php artisan db:seed --class=RoleAndPermissionSeeder --force

php artisan storage:link
php artisan config:cache
php artisan route:cache
php artisan view:cache
```

> ℹ️ **دربارهٔ seedها:** جدول `countries` فقط توسط `CountriesTableSeeder` پر می‌شود و موتور قیمت‌گذاری با `Country::where('iso_code', …)->firstOrFail()` کشور را پیدا می‌کند؛ اگر این seed اجرا نشود، همهٔ استعلام‌های قیمت با خطای 404 مواجه می‌شوند و لیست کشورها در فرم سفارش وردپرس خالی می‌ماند. جدول `system_settings` نیز فقط توسط `SystemSettingSeeder` پر می‌شود.

تنظیم دسترسی پوشه‌ها:

```bash
chown -R www-data:www-data storage bootstrap/cache
chmod -R 775 storage bootstrap/cache
```

### ۲.۵ ساخت حساب ادمین پنل

پنل مدیریت فقط به کاربرانی اجازهٔ ورود می‌دهد که نقش Spatie یکی از `super_admin`، `admin` یا `staff` را داشته باشند. برای ساخت اولین مدیر:

```bash
php artisan make:filament-user
```

سپس در یک محیط تعاملی (Tinker) نقش را اعطا کنید:

```bash
php artisan tinker
```

```php
$user = User::where('email', 'admin@ifnex.ir')->first();
$user->assignRole('super_admin');
```

> ⚠️ اگر این مرحله انجام نشود، صفحهٔ `/panel/login` باز می‌شود ولی هیچ حسابی نمی‌تواند وارد شود.

### ۲.۶ همگام‌سازی کاربران وردپرس

ورود مشتری از طریق Bridge انجام می‌شود و کاربر را بر اساس ایمیل در دیتابیس لاراول پیدا می‌کند. برای اینکه مشتریان وردپرس بتوانند وارد شوند، باید یک‌بار کاربران را همگام کنید (این دستور پس از راه‌اندازی هر دو دیتابیس اجرا می‌شود):

```bash
php artisan ifnex:sync-wp-users \
  --wp-db-host=127.0.0.1 \
  --wp-db-name=ifnex_wordpress \
  --wp-db-user=YOUR_WP_DB_USER \
  --wp-db-pass=YOUR_WP_DB_PASSWORD
```

> اگر پیشوند جدول‌های وردپرس شما `wp_` نیست، گزینهٔ `--wp-table-prefix` را هم اضافه کنید.

### ۲.۷ تنظیمات پیامک (کاوه‌نگار)

ارسال پیامک در این سیستم از جدول `system_settings` خوانده می‌شود، نه از فایل `.env`. بنابراین مقداردهی `KAVENEGAR_API_KEY` در `.env` به‌تنهایی کافی نیست و باید از پنل مدیریت وارد شود:

**پنل ادمین ← تنظیمات سیستم ← سرویس پیامک**

| فیلد | مقدار |
|------|--------|
| Kavenegar API Key | کلید دریافتی از پنل کاوه‌نگار |
| Kavenegar Sender | شمارهٔ فرستندهٔ تأییدشده |

پس از وارد کردن، سوییچ‌های ارسال برای هر رویداد (تأیید سفارش، رد سفارش، پرداخت موفق، تغییر ترکینگ) را نیز در همان صفحه فعال کنید.

### ۲.۸ تنظیم Cron

این پروژه در حال حاضر هیچ زمان‌بندی ثبت‌شده‌ای (Schedule) ندارد. تنها وظیفهٔ زمان‌بندی‌شده، به‌روزرسانی نرخ ارز است که باید مستقیم صدا زده شود:

```cron
0 2 * * * cd /var/www/system.ifnex.ir && php artisan ifnex:update-rates >> /dev/null 2>&1
```

> ℹ️ دربارهٔ صف: در نسخهٔ فعلی هیچ Job یا اعلانی که `ShouldQueue` را پیاده‌سازی کند وجود ندارد و `QUEUE_CONNECTION` روی `database` است. بنابراین نیازی به `queue:work` نیست. اگر در آینده صف اضافه شد، آن را با systemd یا supervisor مدیریت کنید، نه با کرون.

---

## ۳. استقرار وردپرس — `ifnex.ir`

### ۳.۱ نصب فایل‌ها

1. فایل ZIP وردپرس را در `/var/www/ifnex.ir` اکسترکت کنید.
2. فایل SQL دیتابیس را ایمپورت کنید.

### ۳.۲ تنظیم `wp-config.php`

```php
define('DB_NAME', 'ifnex_wordpress');
define('DB_USER', 'YOUR_WP_DB_USER');
define('DB_PASSWORD', 'YOUR_WP_DB_PASSWORD');
define('DB_HOST', '127.0.0.1');
define('DB_CHARSET', 'utf8mb4');
define('DB_COLLATE', '');

define('WP_HOME', 'https://ifnex.ir');
define('WP_SITEURL', 'https://ifnex.ir');

// غیرفعال کردن دیباگ در Production
define('WP_DEBUG', false);
define('WP_DEBUG_LOG', false);
define('WP_DEBUG_DISPLAY', false);

// امنیت پیشخوان
define('DISALLOW_FILE_EDIT', true);
define('DISALLOW_FILE_MODS', true);
define('FS_METHOD', 'direct');
```

**ساخت کلیدها و Saltهای اختصاصی — الزامی:**

فایل `wp-config.php` که همراه بسته تحویل داده می‌شود دارای `WP_DEBUG = true` و کلیدها و Saltهای ثابت است که در مخزن گیت قرار دارند. این مقادیر **نباید** در Production استفاده شوند. پیش از راه‌اندازی، مقادیر `AUTH_KEY`، `SECURE_AUTH_KEY`، `LOGGED_IN_KEY`، `NONCE_KEY`، `AUTH_SALT`، `SECURE_AUTH_SALT`، `LOGGED_IN_SALT` و `NONCE_SALT` را با مقادیر تصادفی اختصاصی جایگزین کنید. ساده‌ترین روش، دریافت هشت مقدار آماده از سرویس رسمی وردپرس است:

```
https://api.wordpress.org/secret-key/1.1/salt/
```

> ⚠️ استفاده از Saltهای مشترک بین چند نصب، امنیت کوکی‌های احراز هویت را به‌طور کامل از بین می‌برد.

### ۳.۳ فعال‌سازی قالب و پلاگین

قالب `IFNEX Theme` و پلاگین `IFNEX Bridge` را از بخش افزونه‌های وردپرس فعال کنید.

### ۳.۴ تنظیمات پلاگین IFNEX Bridge

از مسیر **پنل وردپرس → تنظیمات IFNEX**، هر سه فیلد زیر را پر کنید:

| تنظیم | مقدار |
|--------|--------|
| API URL | `https://system.ifnex.ir/api/v1` |
| API Key (عمومی) | همان مقدار `IFNEX_API_KEY` در فایل `.env` لاراول |
| Bridge API Key | همان مقدار `IFNEX_BRIDGE_API_KEY` در فایل `.env` لاراول |

> ⚠️ اگر `API Key (عمومی)` خالی بماند، صفحهٔ `/tracking/` خطای «API Key تنظیم نشده است» نشان می‌دهد و اندپوینت رهگیری کار نمی‌کند. این مقدار را با یک رشتهٔ تصادفی در `.env` تنظیم کنید.

### ۳.۵ اصلاح آدرس‌ها در دیتابیس

اگر سایت از محیط لوکال به سرور منتقل می‌شود، آدرس‌های ذخیره‌شده را اصلاح کنید:

```sql
UPDATE wp_options
   SET option_value = REPLACE(option_value, 'http://localhost/IFNEX-Logistics/03_WordPress', 'https://ifnex.ir')
 WHERE option_name IN ('home', 'siteurl');

UPDATE wp_posts
   SET guid = REPLACE(guid, 'http://localhost/IFNEX-Logistics/03_WordPress', 'https://ifnex.ir');

UPDATE wp_posts
   SET post_content = REPLACE(post_content, 'http://localhost/IFNEX-Logistics/03_WordPress', 'https://ifnex.ir');

UPDATE wp_postmeta
   SET meta_value = REPLACE(meta_value, 'http://localhost/IFNEX-Logistics/03_WordPress', 'https://ifnex.ir');
```

سپس کش وردپرس را پاک کنید (اگر افزونهٔ کش دارید) و یک‌بار به پیشخوان وردپرس بروید.

---

## ۴. تنظیمات وب‌سرور

### ۴.۱ لاراول — `system.ifnex.ir`

- **Document Root:** `/var/www/system.ifnex.ir/public`

### ۴.۲ وردپرس — `ifnex.ir`

- **Document Root:** `/var/www/ifnex.ir`

### ۴.۳ گواهی SSL

هر دو دامنه به گواهی SSL از Let's Encrypt نیاز دارند. پس از نصب گواهی، مطمئن شوید ریدایرکت HTTP به HTTPS فعال است.

---

## ۵. چک‌لیست نهایی

### ۵.۱ لاراول

- [ ] کلون مخزن انجام شد
- [ ] `composer install` اجرا شد
- [ ] فایل `.env` تنظیم شد (دیتابیس، `APP_URL`، CORS، Zarinpal)
- [ ] `IFNEX_API_KEY` و `IFNEX_BRIDGE_API_KEY` با رشتهٔ تصادفی جایگزین شدند (مقدار `change-this-secret-key` باقی نمانده)
- [ ] `php artisan key:generate` اجرا شد
- [ ] `php artisan migrate` اجرا شد
- [ ] seedها اجرا شدند (`CountriesTableSeeder`، `SystemSettingSeeder`، `RoleAndPermissionSeeder`)
- [ ] جدول `countries` پر است (۱۹۲ کشور)
- [ ] حساب ادمین با نقش `super_admin` ساخته شد
- [ ] `php artisan storage:link` اجرا شد
- [ ] دسترسی `storage/` و `bootstrap/cache/` تنظیم شد
- [ ] `php artisan config:cache` اجرا شد
- [ ] کاوه‌نگار در «تنظیمات سیستم» پنل تنظیم شد
- [ ] کرون به‌روزرسانی نرخ ارز اضافه شد
- [ ] آدرس `https://system.ifnex.ir/panel/login` باز می‌شود و ورود ادمین کار می‌کند

### ۵.۲ وردپرس

- [ ] فایل‌ها اکسترکت شدند
- [ ] دیتابیس ایمپورت شد
- [ ] `wp-config.php` تنظیم شد
- [ ] `WP_DEBUG` روی `false` تنظیم شد
- [ ] کلیدها و Saltهای وردپرس با مقادیر اختصاصی جایگزین شدند
- [ ] آدرس‌ها در دیتابیس جایگزین شدند
- [ ] قالب و پلاگین IFNEX Bridge فعال شدند
- [ ] پلاگین تنظیم شد (API URL + API Key عمومی + Bridge API Key)
- [ ] `ifnex:sync-wp-users` اجرا شد و کاربران مشتری به لاراول منتقل شدند
- [ ] آدرس `https://ifnex.ir` باز می‌شود
- [ ] لاگین مشتری کار می‌کند

### ۵.۳ ارتباط بین‌سامانه‌ای

- [ ] وردپرس به API لاراول وصل می‌شود (تست: لاگین مشتری)
- [ ] خطای CORS داده نمی‌شود
- [ ] صفحهٔ `/tracking/` با یک شمارهٔ AWB نتیجه برمی‌گرداند
- [ ] پرداخت درگاه کار می‌کند (`ZARINPAL_MERCHANT_ID` تنظیم شده و `ZARINPAL_SANDBOX=false`)
- [ ] ارسال پیامک Kavenegar تست شد
- [ ] بارگذاری فایل (آپلود تعهدنامه) کار می‌کند
- [ ] بکاپ دیتابیس تنظیم شده است

---

## ۶. اطلاعات تماس

| مورد | مقدار |
|------|-------|
| توسعه‌دهنده | VernaSoft Group — Kazem Alghasi |
| ایمیل | kazem@vernasoft.group |
| مخزن گیت | [git.vernahost.ir/gitmodir110/ifnex](https://www.git.vernahost.ir/gitmodir110/ifnex) |