ifnex/DEPLOYMENT.md

# 📦 راهنمای دپلوی IFNEX Logistics Platform

راهنمای کامل انتقال پروژه از محیط توسعه (XAMPP) به سرور Production

**نسخه:** 1.0.0  
**تاریخ:** 2026-08-10  
**نویسنده:** تیم توسعه IFNEX

---

## 📋 فهرست مطالب

1. [پیش‌نیازهای سرور](#۱-پیشنیازهای-سرور)
2. [ساختار پروژه](#۲-ساختار-پروژه)
3. [دپلوی Laravel (Backend)](#۳-دپلوی-laravel-backend)
4. [دپلوی WordPress (Frontend)](#۴-دپلوی-wordpress-frontend)
5. [اتصال دو سیستم (Bridge)](#۵-اتصال-دو-سیستم-bridge)
6. [تنظیمات امنیتی](#۶-تنظیمات-امنیتی)
7. [Cron Jobs](#۷-cron-jobs)
8. [Backup Strategy](#۸-backup-strategy)
9. [چک‌لیست نهایی](#۹-چکلیست-نهایی)
10. [Troubleshooting](#۱۰-troubleshooting)

---

## ۱. پیش‌نیازهای سرور

### حداقل نیازمندی‌ها

| مورد | حداقل | پیشنهادی |
|------|-------|----------|
| PHP | 8.2 | 8.3 |
| MySQL | 8.0 | 8.0+ |
| RAM | 2GB | 4GB |
| Disk | 20GB SSD | 50GB NVMe |
| Web Server | Apache 2.4 / Nginx 1.24 | Nginx |

### افزونه‌های PHP مورد نیاز

```bash
php -m | grep -E "pdo_mysql|mbstring|openssl|tokenizer|xml|ctype|json|bcmath|gd|zip|curl|intl"
```

لیست کامل:
- `pdo_mysql` - اتصال به MySQL
- `mbstring` - پشتیبانی UTF-8 (فارسی)
- `openssl` - رمزنگاری
- `tokenizer` - Laravel
- `xml` - Laravel
- `ctype` - Laravel
- `json` - Laravel
- `bcmath` - محاسبات مالی
- `gd` یا `imagick` - پردازش تصویر
- `zip` - Composer
- `curl` - درخواست‌های HTTP
- `intl` - تاریخ شمسی (Jalali)

### نصب Composer و Node

```bash
# Composer
curl -sS https://getcomposer.org/installer | php
mv composer.phar /usr/local/bin/composer

# بررسی نسخه
composer --version
```

---

## ۲. ساختار پروژه

```
IFNEX-Logistics/
├── 01_WordPress/          # (قدیمی - قابل حذف بعد از مهاجرت)
├── 03_WordPress/          # ✅ وردپرس اصلی (Frontend مشتری)
│   └── wp-content/
│       ├── plugins/
│       │   └── ifnex-bridge/    # ✅ پلاگین اتصال به Laravel
│       └── themes/
│           └── ifnex/           # ✅ قالب اختصاصی
├── 04_Laravel/            # ✅ Laravel (Backend + پنل ادمین)
│   ├── app/
│   ├── database/
│   ├── public/            # Document root برای Laravel
│   └── routes/
└── DEPLOYMENT.md          # این فایل
```

### Document Roots روی سرور

| دامنه | مسیر |
|-------|------|
| `ifnex.com` | `/var/www/IFNEX/03_WordPress` |
| `api.ifnex.com` یا `ifnex.com/api` | `/var/www/IFNEX/04_Laravel/public` |

---

## ۳. دپلوی Laravel (Backend)

### گام ۱: آپلود فایل‌ها

```bash
# از سیستم محلی به سرور
scp -r 04_Laravel user@server:/var/www/IFNEX/

# یا با rsync (پیشنهادی)
rsync -avz --exclude 'vendor' --exclude 'node_modules' \
  04_Laravel/ user@server:/var/www/IFNEX/04_Laravel/
```

### گام ۲: نصب Dependencies

```bash
cd /var/www/IFNEX/04_Laravel

# نصب بدون dev packages (برای production)
composer install --optimize-autoloader --no-dev --no-interaction
```

### گام ۳: تنظیم `.env`

فایل `.env` را برای production تنظیم کن:

```env
# ─── تنظیمات پایه ───────────────────────────
APP_NAME="IFNEX Logistics"
APP_ENV=production
APP_KEY=base64:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
APP_DEBUG=false
APP_URL=https://api.ifnex.com

# ─── دیتابیس ─────────────────────────────────
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=ifnex_laravel
DB_USERNAME=ifnex_user
DB_PASSWORD=StrongPassword@123

# ─── Session و Cache ─────────────────────────
SESSION_DRIVER=database
CACHE_STORE=redis
QUEUE_CONNECTION=database

# ─── Sanctum ─────────────────────────────────
SANCTUM_STATEFUL_DOMAINS=ifnex.com,www.ifnex.com
SESSION_DOMAIN=.ifnex.com

# ─── IFNEX Bridge ────────────────────────────
# ⚠️ مهم: این کلید باید با وردپرس یکسان باشد
IFNEX_BRIDGE_API_KEY=your-very-strong-random-key-here

# ─── Zarinpal ────────────────────────────────
ZARINPAL_MERCHANT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
ZARINPAL_SANDBOX=false

# ─── Mail ────────────────────────────────────
MAIL_MAILER=smtp
MAIL_HOST=smtp.ifnex.com
MAIL_PORT=587
MAIL_USERNAME=noreply@ifnex.com
MAIL_PASSWORD=xxxxx
MAIL_ENCRYPTION=tls
```

**تولید کلید امن:**
```bash
php artisan key:generate --show
openssl rand -hex 32   # برای BRIDGE_API_KEY
```

### گام ۴: ساخت دیتابیس

```bash
mysql -u root -p
```

```sql
CREATE DATABASE ifnex_laravel CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'ifnex_user'@'localhost' IDENTIFIED BY 'StrongPassword@123';
GRANT ALL PRIVILEGES ON ifnex_laravel.* TO 'ifnex_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;
```

### گام ۵: Import دیتابیس از توسعه

```bash
# از سیستم محلی (XAMPP)
mysqldump -u root ifnex_laravel > ifnex_backup.sql

# آپلود به سرور
scp ifnex_backup.sql user@server:/tmp/

# Import روی سرور
mysql -u ifnex_user -p ifnex_laravel < /tmp/ifnex_backup.sql
```

### گام ۶: Migrations و Cache

```bash
cd /var/www/IFNEX/04_Laravel

# اجرای migrations
php artisan migrate --force

# Seed داده‌های اولیه (نرخ ارز، zones، ...)
php artisan db:seed --class=SampleShippingRatesSeeder --force

# ساخت cache ها برای سرعت
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan event:cache

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

### گام ۷: تنظیم Nginx

فایل `/etc/nginx/sites-available/ifnex-api`:

```nginx
server {
    listen 80;
    server_name api.ifnex.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name api.ifnex.com;

    root /var/www/IFNEX/04_Laravel/public;
    index index.php;

    # SSL
    ssl_certificate /etc/letsencrypt/live/api.ifnex.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.ifnex.com/privkey.pem;

    # Security headers
    add_header X-Frame-Options SAMEORIGIN;
    add_header X-Content-Type-Options nosniff;
    add_header X-XSS-Protection "1; mode=block";

    # Upload limits
    client_max_body_size 50M;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    # مسدود کردن فایل‌های حساس
    location ~ /\.(env|git) {
        deny all;
    }
}
```

فعال‌سازی:
```bash
ln -s /etc/nginx/sites-available/ifnex-api /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx
```

### گام ۸: SSL رایگان با Let's Encrypt

```bash
apt install certbot python3-certbot-nginx
certbot --nginx -d api.ifnex.com
```

---

## ۴. دپلوی WordPress (Frontend)

### گام ۱: آپلود فایل‌ها

```bash
rsync -avz --exclude 'wp-content/uploads' \
  03_WordPress/ user@server:/var/www/IFNEX/03_WordPress/
```

### گام ۲: تنظیم `wp-config.php`

```php
<?php
// ─── دیتابیس ─────────────────────────────
define('DB_NAME', 'ifnex_wp');
define('DB_USER', 'ifnex_wp_user');
define('DB_PASSWORD', 'StrongPassword@456');
define('DB_HOST', 'localhost');
define('DB_CHARSET', 'utf8mb4');

// ─── کلیدهای امنیتی ──────────────────────
// از https://api.wordpress.org/secret-key/1.1/salt/ بگیرید
define('AUTH_KEY',         'xxxxx');
define('SECURE_AUTH_KEY',  'xxxxx');
define('LOGGED_IN_KEY',    'xxxxx');
define('NONCE_KEY',        'xxxxx');

// ─── Production ──────────────────────────
define('WP_DEBUG', false);
define('WP_DEBUG_LOG', false);
define('WP_DEBUG_DISPLAY', false);
define('SCRIPT_DEBUG', false);

// ─── Performance ─────────────────────────
define('WP_CACHE', true);

define('ABSPATH', __DIR__ . '/');
require_once ABSPATH . 'wp-settings.php';
```

### گام ۳: Import دیتابیس وردپرس

```bash
mysqldump -u root ifnexwp > ifnexwp_backup.sql
scp ifnexwp_backup.sql user@server:/tmp/
mysql -u ifnex_wp_user -p ifnex_wp < /tmp/ifnexwp_backup.sql
```

**اصلاح URLها در دیتابیس:**
```sql
UPDATE wp_options SET option_value = 'https://ifnex.com' 
WHERE option_name IN ('siteurl', 'home');

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

### گام ۴: تنظیم Nginx برای وردپرس

فایل `/etc/nginx/sites-available/ifnex-wp`:

```nginx
server {
    listen 443 ssl http2;
    server_name ifnex.com www.ifnex.com;

    root /var/www/IFNEX/03_WordPress;
    index index.php;

    ssl_certificate /etc/letsencrypt/live/ifnex.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/ifnex.com/privkey.pem;

    client_max_body_size 50M;

    location / {
        try_files $uri $uri/ /index.php?$args;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    # کش فایل‌های استاتیک
    location ~* \.(jpg|jpeg|png|gif|css|js|svg|woff2)$ {
        expires 30d;
        add_header Cache-Control "public, immutable";
    }

    location ~ /\.(env|git) {
        deny all;
    }
}
```

### گام ۵: Permissions

```bash
chown -R www-data:www-data /var/www/IFNEX/03_WordPress
find /var/www/IFNEX/03_WordPress -type d -exec chmod 755 {} \;
find /var/www/IFNEX/03_WordPress -type f -exec chmod 644 {} \;
chmod -R 775 /var/www/IFNEX/03_WordPress/wp-content/uploads
```

---

## ۵. اتصال دو سیستم (Bridge)

### گام ۱: تنظیم پلاگین IFNEX Bridge

در پیشخوان وردپرس:
**IFNEX → تنظیمات**

| فیلد | مقدار |
|------|-------|
| API URL | `https://api.ifnex.com/api/v1` |
| API Key | (کلید عمومی از Laravel) |
| Bridge API Key | (همان مقدار `.env` لاراول) |

### گام ۲: بررسی اتصال

در وردپرس یک صفحه تست بساز با شورت‌کد:
```
[ifnex_wallet_balance]
```

اگر موجودی نمایش داده شد، اتصال برقرار است. ✅

### گام ۳: Sync کاربران

```bash
cd /var/www/IFNEX/04_Laravel
php artisan ifnex:sync-wp-users \
  --wp-db-name=ifnex_wp \
  --wp-db-user=ifnex_wp_user \
  --wp-db-pass=StrongPassword@456
```

---

## ۶. تنظیمات امنیتی

### چک‌لیست امنیتی

- [ ] `APP_DEBUG=false` در Laravel
- [ ] `WP_DEBUG=false` در WordPress
- [ ] SSL فعال روی هر دو دامنه
- [ ] فایل‌های `.env` و `.git` مسدود شده‌اند
- [ ] رمزهای قوی برای دیتابیس
- [ ] `IFNEX_BRIDGE_API_KEY` قوی و تصادفی
- [ ] حذف فایل‌های debug از production:
  ```bash
  rm -f debug-payment.php check-*.php test-*.php
  ```
- [ ] محدودیت دسترسی به `/admin` (اختیاری: IP whitelist)

### Firewall (UFW)

```bash
ufw allow 22/tcp    # SSH
ufw allow 80/tcp    # HTTP
ufw allow 443/tcp   # HTTPS
ufw enable
```

---

## ۷. Cron Jobs

### Laravel Scheduler

```bash
crontab -e
```

```cron
* * * * * cd /var/www/IFNEX/04_Laravel && php artisan schedule:run >> /dev/null 2>&1
```

### Cron آپدیت نرخ ارز (هر ساعت)

اگر از scheduler استفاده نمی‌کنید:

```cron
0 * * * * cd /var/www/IFNEX/04_Laravel && php artisan ifnex:update-rates >> /dev/null 2>&1
```

### Cron Backup روزانه (ساعت ۲ بامداد)

```cron
0 2 * * * /var/www/IFNEX/scripts/backup.sh >> /var/log/ifnex-backup.log 2>&1
```

---

## ۸. Backup Strategy

### اسکریپت `backup.sh`

فایل `/var/www/IFNEX/scripts/backup.sh`:

```bash
#!/bin/bash
# ─── IFNEX Backup Script ───────────────────

BACKUP_DIR="/var/backups/ifnex"
DATE=$(date +%Y%m%d_%H%M%S)
RETENTION_DAYS=7

mkdir -p $BACKUP_DIR

# Backup دیتابیس Laravel
mysqldump -u ifnex_user -p'StrongPassword@123' ifnex_laravel \
  | gzip > $BACKUP_DIR/laravel_$DATE.sql.gz

# Backup دیتابیس WordPress
mysqldump -u ifnex_wp_user -p'StrongPassword@456' ifnex_wp \
  | gzip > $BACKUP_DIR/wordpress_$DATE.sql.gz

# Backup فایل‌های آپلود وردپرس
tar -czf $BACKUP_DIR/uploads_$DATE.tar.gz \
  -C /var/www/IFNEX/03_WordPress/wp-content uploads

# حذف backup های قدیمی
find $BACKUP_DIR -name "*.gz" -mtime +$RETENTION_DAYS -delete

echo "✅ Backup completed: $DATE"
```

اجرا:
```bash
chmod +x /var/www/IFNEX/scripts/backup.sh
```

---

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

### قبل از Go-Live

**Laravel:**
- [ ] `php artisan migrate --force` بدون خطا
- [ ] `php artisan config:cache` موفق
- [ ] ورود به `/admin` با ادمین
- [ ] داشبورد بدون خطا لود می‌شود
- [ ] ویجت‌های نرخ ارز نمایش داده می‌شوند

**WordPress:**
- [ ] صفحه اصلی بدون خطا
- [ ] ورود مشتری کار می‌کند
- [ ] `/new-order/` فرم را نمایش می‌دهد
- [ ] `/my-orders/` لیست سفارشات را نشان می‌دهد
- [ ] تست کامل: ثبت سفارش → پرداخت → تغییر status

**اتصال:**
- [ ] Bridge API Key یکسان در هر دو طرف
- [ ] تست پرداخت از کیف پول موفق
- [ ] Tracking event ثبت می‌شود

### بعد از Go-Live

- [ ] مانیتورینگ لاگ‌ها:
  ```bash
  tail -f /var/www/IFNEX/04_Laravel/storage/logs/laravel.log
  ```
- [ ] بررسی cron jobs: `crontab -l`
- [ ] تست backup و restore

---

## ۱۰. Troubleshooting

### مشکل: خطای 500 در Laravel

```bash
# بررسی لاگ
tail -100 storage/logs/laravel.log

# پاک کردن cache
php artisan config:clear
php artisan cache:clear

# بررسی permissions
chmod -R 775 storage bootstrap/cache
```

### مشکل: وردپرس به Laravel وصل نمی‌شود

```bash
# تست اتصال از سرور وردپرس
curl -X POST https://api.ifnex.com/api/v1/bridge/login \
  -H "Content-Type: application/json" \
  -d '{"bridge_api_key":"YOUR_KEY","wp_user_id":1,"wp_user_email":"test@test.com"}'
```

### مشکل: خطای "توکن احراز هویت یافت نشد"

1. بررسی کنید کاربر در Laravel وجود دارد (sync شده)
2. توکن‌های قدیمی را پاک کنید:
   ```sql
   DELETE FROM wp_usermeta WHERE meta_key LIKE 'ifnex_laravel%';
   ```
3. دوباره لاگین کنید

### مشکل: SSL certificate error

```bash
certbot renew --dry-run
certbot renew
```

### مشکل: خطای CORS

در `config/cors.php` لاراول:
```php
'paths' => ['api/*', 'sanctum/csrf-cookie'],
'allowed_origins' => ['https://ifnex.com', 'https://www.ifnex.com'],
```

---

## 📞 پشتیبانی

در صورت بروز مشکل:
- ایمیل: dev@ifnex.com
- مستندات Laravel: https://laravel.com/docs
- مستندات WordPress: https://wordpress.org/documentation/

---

**پایان راهنمای دپلوی**  
🎉 موفق باشید!