# دليل نشر تطبيق HalaVoice AI على Salla و Zid

## المتطلبات الأساسية

- Laravel 13.17+ على خادم مع PHP 8.3
- PostgreSQL 13+
- Redis (للجلسات والـ queue)
- Composer 2.x
- Node.js 20+ و Yarn 4.x (لبناء الأصول إن وجدت)
- Supervisor (لتشغيل queue workers)
- Domain HTTPS (للـ webhooks و OAuth)
- حساب Salla Partner (https://salla.dev)
- حساب Zid Partner (https://zid.sa/partners)

## متغيرات البيئة (.env)

```env
APP_NAME=HalaVoiceAI
APP_ENV=production
APP_DEBUG=false
APP_URL=https://your-domain.com

# قاعدة البيانات
DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=halavoice_salla
DB_USERNAME=postgres
DB_PASSWORD=

# Salla
SALLA_CLIENT_ID=
SALLA_CLIENT_SECRET=
SALLA_REDIRECT_URI=https://your-domain.com/oauth/callback
SALLA_WEBHOOK_SECRET=توليد_قيمة_عشوائية_آمنة

# Zid
ZID_CLIENT_ID=
ZID_CLIENT_SECRET=

# HalaVoice API
HALAVOICE_API_URL=https://api.halavoice.store
HALAVOICE_API_KEY=
HALAVOICE_API_SECRET=
HALAVOICE_API_URL=http://localhost:5003/api

# واتساب
WHATSAPP_PROVIDER=evolution_api
WHATSAPP_INSTANCE_ID=
WHATSAPP_API_KEY=
WHATSAPP_API_URL=https://whatsapp.halavoice.store

# الأمان
APP_KEY=توليد_بـ_php_artisan_key:generate
SESSION_DRIVER=redis
QUEUE_CONNECTION=database
```

## نشر التطبيق

### 1. رفع الملفات

```bash
# نسخ الملفات إلى الخادم
scp -r salla-app/ user@server:/var/www/halavoice-salla/

# الدخول إلى الخادم
ssh user@server
cd /var/www/halavoice-salla
```

### 2. تثبيت الاعتماديات

```bash
/opt/cpanel/ea-php83/root/usr/bin/php composer install --no-dev --optimize-autoloader
```

### 3. إعداد البيئة

```bash
cp .env.example .env
# عدّل .env بالقيم الصحيحة
/opt/cpanel/ea-php83/root/usr/bin/php artisan key:generate
```

### 4. تشغيل الترحيلات

```bash
/opt/cpanel/ea-php83/root/usr/bin/php artisan migrate --force
```

### 5. تحسين الأداء

```bash
/opt/cpanel/ea-php83/root/usr/bin/php artisan config:cache
/opt/cpanel/ea-php83/root/usr/bin/php artisan route:cache
/opt/cpanel/ea-php83/root/usr/bin/php artisan view:cache
```

### 6. إعداد Supervisor (لتشغيل الـ queue)

ملف `/etc/supervisor/conf.d/halavoice-worker.conf`:

```ini
[program:halavoice-worker]
process_name=%(program_name)s_%(process_num)02d
command=/opt/cpanel/ea-php83/root/usr/bin/php /var/www/halavoice-salla/artisan queue:work --sleep=3 --tries=3 --max-time=3600
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=root
numprocs=2
redirect_stderr=true
stdout_logfile=/var/www/halavoice-salla/storage/logs/worker.log
stopwaitsecs=3600
```

```bash
supervisorctl reread
supervisorctl update
supervisorctl start all
```

### 7. إعداد Cron (للأوامر المجدولة)

```bash
* * * * * /opt/cpanel/ea-php83/root/usr/bin/php /var/www/halavoice-salla/artisan schedule:run >> /dev/null 2>&1
```

### 8. إعداد Nginx

```nginx
server {
    listen 443 ssl;
    server_name your-domain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    root /var/www/halavoice-salla/public;
    index index.php;

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

    location ~ \.php$ {
        fastcgi_pass 127.0.0.1:9000;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.ht {
        deny all;
    }

    # زيادة الحد الأقصى للـ webhooks
    client_max_body_size 10M;
}
```

## النشر على Salla

### 1. إنشاء تطبيق في Salla Partners

1. اذهب إلى https://partners.salla.dev
2. سجل الدخول → "Create App"
3. اختر "Public App" أو "Private App"
4. الإعدادات الأساسية:
   - **App Name**: HalaVoice AI Agent
   - **Description**: مساعد ذكي لإدارة طلبات COD والواتساب والمكالمات الصوتية
   - **Redirect URI**: `https://your-domain.com/oauth/callback`
   - **Webhook URL**: `https://your-domain.com/webhook`

### 2. الصلاحيات المطلوبة

في قسم **Permissions**، اختر:

| الصلاحية | السبب |
|----------|-------|
| `orders.read` | قراءة الطلبات للتأكيد والمتابعة |
| `orders.write` | تحديث حالة الطلب بعد التأكيد |
| `customers.read` | الوصول لمعلومات العميل للاتصال |
| `products.read` | (اختياري) معلومات المنتج |
| `carts.read` | استرداد العربات المتروكة |
| `settings.read` | قراءة إعدادات المتجر |
| `settings.write` | حفظ إعدادات التطبيق |
| `webhooks.read_write` | إدارة الـ webhooks تلقائياً |
| `offline_access` | تجديد التوكن تلقائياً |

### 3. أحداث الـ Webhook

في قسم **Webhook Events**، اشترك في:

```
order.created, order.updated, order.status.updated,
order.cancelled, order.payment.updated,
abandoned.cart, customer.created, customer.updated,
shipment.created, shipment.updated, review.added
```

**أحداث التطبيق** (App Events):

```
app.installed, app.uninstalled, app.store.authorize,
app.subscription.started, app.subscription.expired,
app.subscription.canceled, app.subscription.renewed
```

### 4. Easy Mode (OAuth بدون Custom Callback)

Salla يرسل التوكن عبر webhook `app.store.authorize` مباشرة.
لا حاجة لإعداد صفحة Callback معقدة — تأكد فقط من أن `Redirect URI` تطابق عنوان التطبيق.

### 5. رفع الشعار والصور

- **App Icon**: 512×512px PNG
- **Cover Image**: 1200×600px
- **Screenshots**: يفضل صور لوحة التحكم بالعربية (4-6 صور)

### 6. مراجعة ونشر

- قدم التطبيق للمراجعة (للتطبيقات العامة)
- أو استخدم Private App للاختبار الداخلي

## النشر على Zid

### 1. التسجيل في منصة Zid Partners

1. اذهب إلى https://partners.zid.sa
2. سجل حساب مطور
3. أنشئ تطبيق جديد

### 2. إعداد التطبيق

- **App Name**: HalaVoice AI Agent
- **Webhook URL**: `https://your-domain.com/zid/webhook`
- **Redirect URL**: `https://your-domain.com/oauth/callback`

### 3. الأحداث المطلوبة

```
order.created, order.paid, order.updated,
order.status_changed, order.cancelled, order.refunded,
cart.abandoned, app.installed, app.uninstalled
```

### 4. طريقة عمل Zid

Zid يستخدم API Keys بدلاً من OAuth 2.0:
- المتجر يزودك بـ `API Key` عند التثبيت
- ترسله عبر webhook `app.installed`
- تخزنه في جدول `zid_stores`

## اختبار التكامل

### اختبار Salla OAuth

```bash
# محاكاة تثبيت التطبيق (بدون Salla حقيقي)
curl -X POST https://your-domain.com/webhook \
  -H "Content-Type: application/json" \
  -d '{
    "event": "app.store.authorize",
    "data": {
      "store": {"id": "test_123", "name": "متجر تجريبي"},
      "access_token": "test_token",
      "refresh_token": "test_refresh"
    }
  }'
```

### اختبار Webhook Zid

```bash
curl -X POST https://your-domain.com/zid/webhook \
  -H "Content-Type: application/json" \
  -H "X-Zid-Signature: your_signature" \
  -d '{
    "event": "app.installed",
    "store_id": "zid_test_456",
    "store": {"name": "متجر Zid تجريبي"}
  }'
```

### اختبار الصحة

```bash
curl https://your-domain.com/health
# → {"status":"healthy","checks":{"app":true,"database":true,"halavoice_api":true,"queue_pending":0}}
```

## استكشاف الأخطاء

### مشكلة: التوكن منتهي

```bash
# تشغيل تحديث التوكن يدوياً
php artisan halavoice:refresh-tokens
```

### مشكلة: الـ Queue لا يعمل

```bash
# التحقق من حالة Supervisor
supervisorctl status

# تشغيل الـ worker يدوياً للتشخيص
php artisan queue:work --once --verbose
```

### مشكلة: Webhook لا يصل

```bash
# عرض آخر الأحداث المسجلة
php artisan tinker
> App\Models\WebhookEvent::latest()->take(10)->get();
```

### مشكلة: HalaVoice API لا يستجيب

```bash
php artisan halavoice:check-connection
```

## الصيانة الدورية

```bash
# تنظيف البيانات القديمة
php artisan halavoice:cleanup

# تحديث التوكنات المنتهية
php artisan halavoice:refresh-tokens
```

## الأمان

- جميع التوكنات مشفرة في قاعدة البيانات (Laravel `encrypted` cast)
- توكنات Salla تنتهي بعد 14 يوم — تُحدّث تلقائياً
- تواقيع HMAC-SHA256 للـ webhooks
- معدل الطلبات محدود بـ 60 طلب/دقيقة لكل متجر
- الـ Queue يعالج الطلبات بشكل غير متزامن

## موارد مفيدة

- [Salla API Documentation](https://docs.salla.dev)
- [Salla Partners Portal](https://partners.salla.dev)
- [Zid API Documentation](https://docs.zid.sa)
- [Laravel Deployment](https://laravel.com/docs/deployment)