ifnex/04_Laravel

⚙️ IFNEX Laravel Backend

هسته مرکزی سیستم مدیریت لجستیک ایف‌نکس

---

REST API + Admin Panel + Financial Engine + PDF Generator

🚀 نصب سریع • 📡 API Endpoints • 🗃️ Models • 🎨 Filament Resources • 📚 مستندات

---

🎯 نمای کلی

این پوشه شامل هسته مرکزی سیستم IFNEX است که شامل چهار بخش اصلی می‌شود:

۱. REST API کامل

ارتباط با WordPress از طریق Sanctum Token + Bridge Auth (بدون رمز عبور) — ۳۰+ endpoint برای تمام عملیات مشتری (سفارش، پرداخت، کیف پول، نوتیفیکیشن، رهگیری).

۲. پنل مدیریت Filament 3.3

پنل کامل برای اپراتورها و مدیران شامل مدیریت مرسوله‌ها، نرخ‌ها، ارزها، کاربران، گزارش‌های مالی و تنظیمات سیستم.

۳. موتور قیمت‌گذاری

محاسبه قیمت بر اساس ۴ زون (Export/Import × Parcel/Doc) و ۳ نوع سرویس با پشتیبانی از تخفیف، VAT، هزینه‌های داخلی و تبدیل ارز (درهم ↔ ریال).

۴. سیستم مالی و سندسازی

کیف پول دیجیتال، درگاه پرداخت Zarinpal، تولید خودکار PDF (AWB, Invoice, Label) با بارکد استاندارد و سیستم نوتیفیکیشن دیتابیس.

---

🚀 نصب و راه‌اندازی سریع

پیش‌نیازها

ابزار	حداقل نسخه	توضیحات
PHP	8.2+	با extensions: pdo_mysql, mbstring, xml, gd, zip
Composer	2.x	مدیریت وابستگی‌ها
MySQL	8.0+	دیتابیس اصلی
Node.js	18+	برای build assets (اختیاری)

مراحل نصب

# ۱. ورود به پوشه لاراول
cd 04_Laravel

# ۲. نصب وابستگی‌ها
composer install

# ۳. تنظیم فایل محیط
cp .env.example .env
php artisan key:generate

# ۴. ایجاد دیتابیس
mysql -u root -p -e "CREATE DATABASE ifnex_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

# ۵. ویرایش .env — مقادیر کلیدی (مشاهده جدول زیر)
# ۶. اجرای migrations و seeders
php artisan migrate --force
php artisan db:seed --force

# ۷. اجرای سرور
php artisan serve
# پنل ادمین: http://127.0.0.1:8000/panel

🔐 دسترسی پیش‌فرض

آیتم	مقدار
URL پنل ادمین	http://localhost:8000/panel
URL API	http://localhost:8000/api/v1
ایمیل ادمین	(از seeder) admin@ifnex.local
رمز عبور	password

⚙️ تنظیمات مهم .env

# DATABASE
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=ifnex_db
DB_USERNAME=root
DB_PASSWORD=

# IFNEX API
IFNEX_API_KEY=ifnex-local-dev-key
IFNEX_BRIDGE_API_KEY=ifnex-bridge-secret-key-2026-vernasoft  # مهم برای وردپرس
IFNEX_TRACKING_RATE_LIMIT=60

# CORS (فقط دامنه‌های مجاز وردپرس)
CORS_ALLOWED_ORIGINS=http://localhost,http://127.0.0.1

# PAYMENT GATEWAY (Zarinpal)
ZARINPAL_MERCHANT_ID=fake-merchant-id-for-testing  # برای Mock Mode
ZARINPAL_SANDBOX=true
ZARINPAL_CALLBACK_URL=http://localhost:8000/api/v1/payment/callback
ZARINPAL_FRONTEND_SUCCESS_URL=http://localhost/IFNEX-Logistics/03_WordPress/wallet
ZARINPAL_FRONTEND_FAILURE_URL=http://localhost/IFNEX-Logistics/03_WordPress/wallet

# CURRENCY API (برای بروزرسانی نرخ ارز)
CURRENCY_API_KEY=your_api_key_here
CURRENCY_API_URL=https://api.freecurrencyapi.com/v1/latest

# WALLET
WALLET_MIN_DEPOSIT=10000
WALLET_MAX_DEPOSIT=500000000
WALLET_AUTO_CREATE=true
WALLET_ALLOW_WITHDRAWAL=false

⚠️ نکته مهم: اگر ZARINPAL_MERCHANT_ID برابر fake-merchant-id-for-testing باشد، سیستم از MockZarinpalService استفاده می‌کند که برای تست لوکال مناسب است.

---

📡 API Endpoints

🔓 API عمومی (با API Key)

متد	Endpoint	توضیح
GET	/api/v1/track/{awb_no}	رهگیری مرسوله
POST	/api/v1/calculate	محاسبه قیمت
GET	/api/v1/discount-codes	لیست کدهای تخفیف
POST	/api/v1/discount-codes/validate	اعتبارسنجی کد تخفیف
POST	/api/v1/bridge/login	Bridge Auth (وردپرس ← لاراول)
POST	/api/v1/auth/login	ورود مشتری (ایمیل + رمز)
POST	/api/v1/auth/logout	خروج (Sanctum)

🔐 API مشتری (Sanctum Token)

متد	Endpoint	توضیح
GET	/api/v1/customer/profile	پروفایل + آمار سفارشات
GET	/api/v1/customer/countries	لیست کشورها با پیش‌شماره
GET	/api/v1/customer/orders	لیست سفارشات (paginated)
POST	/api/v1/customer/orders	ثبت سفارش جدید
GET	/api/v1/customer/orders/{id}	جزئیات سفارش
POST	/api/v1/customer/orders/{id}/cancel	لغو سفارش
POST	/api/v1/customer/orders/{id}/pay-wallet	پرداخت با کیف پول
POST	/api/v1/customer/orders/{id}/pay-gateway	پرداخت با درگاه
GET	/api/v1/customer/notifications	لیست اعلان‌ها
POST	/api/v1/customer/notifications/{id}/read	علامت‌گذاری خوانده‌شده

💰 API کیف پول (Sanctum Token)

متد	Endpoint	توضیح
GET	/api/v1/wallet/balance	موجودی + آمار
GET	/api/v1/wallet/transactions	تراکنش‌ها (paginated)
GET	/api/v1/wallet/{wallet}/activity-log	لاگ فعالیت‌ها
POST	/api/v1/wallet/{wallet}/freeze	مسدود کردن کیف پول (admin)
POST	/api/v1/wallet/{wallet}/unfreeze	آزاد کردن کیف پول (admin)
POST	/api/v1/wallet/admin-adjust	تراکنش دستی (admin)

💳 API پرداخت

متد	Endpoint	توضیح
POST	/api/v1/payment/redirect	انتقال به درگاه (شارژ کیف پول)
GET	/api/v1/payment/check/{transaction}	بررسی وضعیت تراکنش
ANY	/api/v1/payment/callback	Callback از درگاه (Zarinpal)

🧪 Mock Gateway (تست لوکال)

متد	Endpoint	توضیح
GET	/api/v1/payment/mock-gateway	صفحه شبیه‌سازی درگاه
GET	/api/v1/payment/mock-gateway/success	شبیه‌سازی پرداخت موفق
GET	/api/v1/payment/mock-gateway/failure	شبیه‌سازی پرداخت ناموفق

📥 مثال: ثبت سفارش

curl -X POST http://localhost:8000/api/v1/customer/orders \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "direction": "export",
    "type": "PARCEL",
    "from_country_id": 1,
    "to_country_id": 2,
    "weight": 2.5,
    "volumetric_weight": 2.5,
    "sender_name": "John Doe",
    "sender_phone": "+98 9123456789",
    "sender_city": "Tehran",
    "sender_address": "No 1, ValiAsr Street",
    "receiver_name": "Ahmed Ali",
    "receiver_phone": "+971 501234567",
    "receiver_city": "Dubai",
    "receiver_address": "Sheikh Zayed Road 100"
  }'

---

🗂️ ساختار پروژه

04_Laravel/
├── app/
│   ├── Enums/                       # ShipmentStatus, ShipmentDirection, ShipmentType, PaymentGateway, TransactionStatus
│   ├── Filament/
│   │   ├── Resources/               # 10+ Resources
│   │   │   ├── ShipmentResource/    # مدیریت مرسوله‌ها (با RelationManagers)
│   │   │   ├── CountryResource/     # مدیریت کشورها + calling_code
│   │   │   ├── ShippingRateResource/
│   │   │   ├── CurrencyResource/    # مدیریت ارزها
│   │   │   ├── UserResource/        # مدیریت کاربران
│   │   │   ├── WalletResource/      # کیف پول‌ها
│   │   │   ├── WalletTransactionResource/
│   │   │   ├── PaymentResource/     # پرداخت‌ها
│   │   │   ├── DiscountCodeResource/
│   │   │   ├── ShipmentItemResource/
│   │   │   ├── ExchangeRateHistoryResource/
│   │   │   └── RoleResource/        # مدیریت نقش‌ها
│   │   ├── Pages/
│   │   │   ├── IfnexSettingsPage.php        # تنظیمات سیستم (key-value)
│   │   │   ├── PriceTestPage.php            # تست محاسبه قیمت
│   │   │   ├── ImportRatesPage.php          # آپلود اکسل نرخ‌ها
│   │   │   └── Reports/FinancialReport.php  # گزارش مالی
│   │   └── Widgets/                 # Dashboard Widgets
│   ├── Http/
│   │   ├── Controllers/
│   │   │   ├── Api/
│   │   │   │   ├── AuthController.php        # لاگین/لاگاوت مشتری
│   │   │   │   ├── BridgeAuthController.php  # Bridge Auth (وردپرس)
│   │   │   │   ├── TrackController.php       # رهگیری عمومی
│   │   │   │   ├── PricingController.php     # محاسبه قیمت
│   │   │   │   ├── DiscountCodeController.php
│   │   │   │   ├── PaymentController.php     # درگاه + Callback
│   │   │   │   ├── MockGatewayController.php # شبیه‌سازی درگاه
│   │   │   │   ├── WalletController.php
│   │   │   │   └── Customer/
│   │   │   │       └── CustomerOrderController.php  # سفارشات + نوتیفیکیشن
│   │   │   ├── ShipmentPdfController.php     # AWB/Invoice/Label PDFs
│   │   │   └── OrderController.php           # صفحات public سفارش
│   │   └── Middleware/
│   │       └── ApiKeyMiddleware.php          # برای APIهای عمومی
│   ├── Models/                      # 13 مدل Eloquent
│   ├── Notifications/               # ShipmentUpdatedNotification
│   ├── Services/
│   │   ├── PriceCalculatorService.php        # موتور قیمت‌گذاری
│   │   ├── WalletService.php                 # مدیریت کیف پول
│   │   ├── OrderPaymentService.php           # پرداخت سفارش
│   │   ├── ZarinpalService.php               # درگاه واقعی
│   │   ├── MockZarinpalService.php           # درگاه شبیه‌سازی
│   │   └── TrackingService.php
│   ├── Imports/                     # Excel imports (OldShipments, ShippingRates)
│   ├── Exports/                     # ShippingRatesTemplateExport
│   └── Console/Commands/
│       ├── ImportShippingRates.php
│       ├── ImportTrackingData.php
│       ├── UpdateExchangeRates.php
│       ├── GenerateApiToken.php
│       └── SyncWordPressUsers.php
│
├── database/
│   ├── migrations/                  # 23 migrations
│   └── seeders/
│       ├── CountrySeeder.php        # 233 کشور + calling_code
│       ├── SystemSettingSeeder.php
│       └── DatabaseSeeder.php
│
├── resources/views/
│   ├── pdfs/
│   │   ├── awb.blade.php            # Air Waybill PDF
│   │   ├── invoice.blade.php        # فاکتور PDF
│   │   └── label.blade.php          # لیبل پستی با بارکد
│   └── filament/
│       └── pages/                   # صفحات Filament
│
├── routes/
│   ├── api.php                      # 30+ REST API endpoints
│   └── web.php                      # Web + Download Template
│
└── config/
    └── ifnex.php                    # تنظیمات اختصاصی IFNEX

---

🗃️ Models

Model	جدول	توضیح	فاز
Country	countries	۲۳۳ کشور با ۴ زون + calling_code	۰
Shipment	shipments	مرسوله‌ها (مدل مرکزی)	۰
ShipmentItem	shipment_items	اقلام گمرکی	۰
ShipmentPackage	shipment_packages	بسته‌های چندگانه	۲
ShipmentCarrierMapping	shipment_carrier_mappings	نگاشت شرکت‌های حمل	۰
ShipmentTrackingEvent	shipment_tracking_events	رویدادهای ترکینگ	۰
ShipmentStatusHistory	shipment_status_histories	تاریخچه تغییرات وضعیت	۲
ShippingRate	shipping_rates	تعرفه‌های حمل	۰
SystemSetting	system_settings	تنظیمات key-value	۰
Currency	currencies	ارزهای پشتیبانی (IRR, AED, USD, EUR, CNY)	۲
ExchangeRateHistory	exchange_rate_histories	تاریخچه نرخ ارز	۲
User	users	کاربران سیستم (admin + customer)	۰
Wallet	wallets	کیف پول کاربران	۲
WalletTransaction	wallet_transactions	تراکنش‌های کیف پول	۲
WalletActivityLog	wallet_activity_logs	لاگ فعالیت‌های کیف پول	۲
DiscountCode	discount_codes	کدهای تخفیف	۲
Payment	payments	پرداخت‌ها	۲

---

🎨 Filament Resources

Resources اصلی

Resource	توضیح	ویژگی‌ها
ShipmentResource	مدیریت مرسوله‌ها	جدول + فرم + View + CSV Export + Bulk Actions
CountryResource	مدیریت کشورها	CRUD + calling_code + ۴ زون
ShippingRateResource	مدیریت تعرفه‌ها	CRUD + فیلتر + Import از اکسل
CurrencyResource	مدیریت ارزها	CRUD + بروزرسانی خودکار نرخ
UserResource	مدیریت کاربران	CRUD + Role + Wallet link
WalletResource	مدیریت کیف پول	View + Freeze/Unfreeze + Activity Log
WalletTransactionResource	تراکنش‌ها	View + فیلتر + گزارش
PaymentResource	پرداخت‌ها	View + بررسی وضعیت
DiscountCodeResource	کدهای تخفیف	CRUD + اعتبارسنجی
RoleResource	نقش‌ها	مدیریت Roles + Permissions

RelationManagers

RelationManager	والد	توضیح
TrackingEventsRelationManager	Shipment	رویدادهای ترکینگ با فیلد source
CarrierMappingsRelationManager	Shipment	نگاشت شرکت‌های حمل
ItemsRelationManager	Shipment	اقلام گمرکی
PackagesRelationManager	Shipment	بسته‌های چندگانه
StatusHistoriesRelationManager	Shipment	تاریخچه تغییرات وضعیت

صفحات سفارشی

صفحه	توضیح
IfnexSettingsPage	تنظیمات سیستم (key-value) — نرخ درهم، VAT، حاشیه سود
PriceTestPage	تست محاسبه قیمت با پارامترهای مختلف
ImportRatesPage	آپلود اکسل نرخ‌ها + دانلود Template
FinancialReport	گزارش مالی (درآمد، تخفیف، کارمزد)

---

🔧 Artisan Commands

# Import / Migration
php artisan ifnex:import-rates           # ایمپورت نرخ‌ها از اکسل
php artisan ifnex:import-tracking        # ایمپورت داده‌های ترکینگ تاریخی
php artisan ifnex:sync-wp-users          # همگام‌سازی کاربران وردپرس با لاراول

# Currency
php artisan ifnex:update-exchange-rates  # بروزرسانی نرخ ارز از API

# Token
php artisan ifnex:generate-api-token     # تولید API Token برای ادمین

# Standard
php artisan migrate                      # اجرای migrations
php artisan db:seed                      # اجرای seeders
php artisan serve                        # اجرای سرور
php artisan tinker                       # محیط تعاملی
php artisan route:list                   # لیست روت‌ها
php artisan config:clear                 # پاک‌سازی کش کانفیگ

---

🔴 خط قرمزها (ممنوعیت‌ها)

❌ هرگز	✅ همیشه
برگرداندن countries به ۲ زون	۴ زون مجزا (Export/Import × Parcel/Doc)
استفاده از ۲ نوع سرویس	۳ نوع (DOC_NORMAL, DOC_ECONOMY, PARCEL)
ذخیره تاریخ شمسی در DB	ذخیره timestamp میلادی + تبدیل در نمایش
CORS * در Production	CORS محدود به دامنه وردپرس
کامیت .env در Git	در .gitignore باشد
APP_DEBUG=true در Production	APP_DEBUG=false
PDF فارسی (AWB/Invoice/Label)	همیشه انگلیسی (برای حمل بین‌المللی)
کپی از DHL	طراحی منحصر به فرد IFNEX
استفاده از wire:click برای دانلود	استفاده از <a href> با روت مستقیم
getFormActions() در Custom Pages	استفاده از wire:click در Blade
هدایت AJAX به redirect()	استفاده از payment_url در response JSON
متدهای نوتیفیکیشن بیرون از کلاس	داخل کلاس IFNEX_User_Bridge

---

🧪 تست

Mock Gateway

برای تست پرداخت بدون اتصال به Zarinpal واقعی، ZARINPAL_MERCHANT_ID=fake-merchant-id-for-testing را در .env تنظیم کنید. سپس:

• پرداخت‌ها از طریق MockZarinpalService پردازش می‌شوند
• URL پرداخت: /api/v1/payment/mock-gateway
• شبیه‌سازی موفق: /api/v1/payment/mock-gateway/success
• شبیه‌سازی ناموفق: /api/v1/payment/mock-gateway/failure

Bridge Token Test

curl -X POST http://localhost:8000/api/v1/bridge/login \
  -H "Content-Type: application/json" \
  -d '{
    "bridge_api_key": "YOUR_BRIDGE_KEY",
    "wp_user_id": 1,
    "wp_user_email": "user@example.com",
    "wp_user_name": "Test User",
    "token_name": "test"
  }'

---

📚 مستندات

فایل	محتوا
IFNEX_Phase0_Checklist.md	چک‌لیست کامل فازها
IFNEX_Roadmap.md	نقشه راه ۴ فازی
IFNEX_File_Map.md	نقشه ۱۰۰+ فایل
DEPLOYMENT.md	راهنمای استقرار Production

---

🚀 مراحل بعدی

• تست‌های واحد (PHPUnit)
• تست‌های Integration (Laravel Dusk)
• مستندات API (OpenAPI/Swagger)
• اتصال به APIهای ترکینگ زنده
• سیستم نمایندگی (فاز ۴)
• بهبود گزارش‌های مالی

---

© 2026 VernaSoft Group. All Rights Reserved.