# ⚙️ IFNEX Laravel Backend
### هسته مرکزی سیستم مدیریت لجستیک ایفنکس
[](https://laravel.com)
[](https://php.net)
[](https://filamentphp.com)
[](https://mysql.com)
[]()
---
**REST API + Admin Panel + Financial Engine + PDF Generator**
[🚀 نصب سریع](#-نصب-و-راهاندازی-سریع) • [📡 API Endpoints](#-api-endpoints) • [🗃️ Models](#-models) • [🎨 Filament Resources](#-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 (اختیاری) |
### مراحل نصب
```bash
# ۱. ورود به پوشه لاراول
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`
```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` | شبیهسازی پرداخت ناموفق |
### 📥 مثال: ثبت سفارش
```bash
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
```bash
# 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` برای دانلود | استفاده از `` با روت مستقیم |
| `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
```bash
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](../01_Documents/IFNEX_Phase0_Checklist.md) | چکلیست کامل فازها |
| [IFNEX_Roadmap.md](../01_Documents/IFNEX_Roadmap.md) | نقشه راه ۴ فازی |
| [IFNEX_File_Map.md](../01_Documents/IFNEX_File_Map.md) | نقشه ۱۰۰+ فایل |
| [DEPLOYMENT.md](../DEPLOYMENT.md) | راهنمای استقرار Production |
---
## 🚀 مراحل بعدی
- [ ] تستهای واحد (PHPUnit)
- [ ] تستهای Integration (Laravel Dusk)
- [ ] مستندات API (OpenAPI/Swagger)
- [ ] اتصال به APIهای ترکینگ زنده
- [ ] سیستم نمایندگی (فاز ۴)
- [ ] بهبود گزارشهای مالی
---
© 2026 VernaSoft Group. All Rights Reserved.