ifnex/04_Laravel/README.md

⚙️ IFNEX Laravel Backend

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

---

REST API + Admin Panel + Financial Engine

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

---

🎯 نمای کلی

این پوشه شامل هسته مرکزی سیستم IFNEX است:

• REST API کامل برای ارتباط با WordPress
• پنل مدیریت Filament
• موتور قیمت‌گذاری با ۴ زون و ۳ نوع سرویس
• سیستم کیف پول و پرداخت
• تولید PDF (AWB, Invoice, Label) با بارکد
• سیستم اعلان‌ها و تاریخچه تغییرات

---

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

پیش‌نیازها

ابزار	حداقل نسخه
PHP	8.2+
Composer	2.x
MySQL	8.0+

مراحل نصب

# ۱. ورود به پوشه لاراول
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 و تنظیم DB_DATABASE, DB_USERNAME, DB_PASSWORD

# ۶. اجرای migrations و seeders
php artisan migrate --force
php artisan db:seed --force

# ۷. اجرای سرور
php artisan serve

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

آیتم	مقدار
URL پنل	http://localhost:8000/panel
ایمیل ادمین	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
IFNEX_API_KEY=ifnex-local-dev-key
IFNEX_TRACKING_RATE_LIMIT=60

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

# PAYMENT GATEWAY (Zarinpal)
ZARINPAL_MERCHANT_ID=your_merchant_id
ZARINPAL_SANDBOX=true

---

📡 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	خروج

🔐 API مشتری (Sanctum Token)

متد	Endpoint	توضیح
GET	/api/v1/customer/profile	پروفایل و آمار
GET	/api/v1/customer/countries	لیست کشورها
GET	/api/v1/customer/orders	لیست سفارشات
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	تراکنش‌ها

💳 API پرداخت

متد	Endpoint	توضیح
POST	/api/v1/payment/redirect	انتقال به درگاه
GET	/api/v1/payment/check/{id}	بررسی وضعیت
ANY	/api/v1/payment/callback	Callback درگاه

🧪 Mock Gateway (تست)

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

---

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

04_Laravel/
├── app/
│   ├── Enums/                  # ShipmentStatus, ShipmentDirection, ShipmentType
│   ├── Filament/
│   │   ├── Resources/          # Shipment, Country, ShippingRate, Currency
│   │   ├── Pages/              # Settings, ImportRates, PriceTest
│   │   └── Widgets/            # Dashboard Widgets
│   ├── Http/
│   │   ├── Controllers/Api/    # Track, Pricing, Auth, Bridge, Customer, Wallet, Payment
│   │   └── Middleware/         # ApiKeyMiddleware
│   ├── Models/                 # Eloquent Models (13 مدل)
│   ├── Notifications/          # ShipmentUpdatedNotification
│   ├── Services/               # PriceCalculator, Pdf, Tracking, OrderPayment
│   └── Imports/                # OldShipments, ShippingRates
│
├── database/
│   ├── migrations/             # 15+ migrations
│   └── seeders/                # Countries, SystemSettings, DatabaseSeeder
│
├── resources/views/
│   └── pdfs/                   # awb.blade, invoice.blade, label.blade
│
├── routes/
│   ├── api.php                 # REST API
│   └── web.php                 # Web + Download Template

└── config/
    └── ifnex.php               # تنظیمات اختصاصی

---

🗃️ Models

Model	جدول	توضیح
Country	countries	۲۳۳ کشور با ۴ زون
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	ارزهای پشتیبانی
User	users	کاربران سیستم
Wallet	wallets	کیف پول کاربران
WalletTransaction	wallet_transactions	تراکنش‌ها

---

🎨 Filament Resources

Resource	توضیح
ShipmentResource	مدیریت مرسوله‌ها (جدول + فرم + جزئیات + CSV)
CountryResource	مدیریت کشورها
ShippingRateResource	مدیریت تعرفه‌ها
CurrencyResource	مدیریت ارزها

RelationManagers

RelationManager	والد	توضیح
TrackingEventsRelationManager	Shipment	رویدادهای ترکینگ
CarrierMappingsRelationManager	Shipment	نگاشت شرکت‌های حمل
ItemsRelationManager	Shipment	اقلام گمرکی

صفحات سفارشی

صفحه	توضیح
SettingsPage	تنظیمات سیستم (key-value)
PriceTestPage	تست محاسبه قیمت
ImportRatesPage	آپلود اکسل نرخ‌ها

---

🔴 خط قرمزها

❌ هرگز	✅ همیشه
برگرداندن countries به ۲ زون	۴ زون مجزا
استفاده از ۲ نوع سرویس	۳ نوع (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

---

📚 مستندات

فایل	محتوا
IFNEX_Phase0_Checklist.md	چک‌لیست کامل
IFNEX_Roadmap.md	نقشه راه
IFNEX_File_Map.md	نقشه فایل‌ها
DEPLOYMENT.md	راهنمای استقرار

---

© 2026 VernaSoft Group. All Rights Reserved.