# ⚙️ IFNEX Laravel Backend ### هسته مرکزی سیستم مدیریت لجستیک ایف‌نکس [![Laravel](https://img.shields.io/badge/Laravel-11.x-FF2D20?logo=laravel&logoColor=white)](https://laravel.com) [![PHP](https://img.shields.io/badge/PHP-8.2+-777BB4?logo=php&logoColor=white)](https://php.net) [![Filament](https://img.shields.io/badge/Filament-3.3-EDB200?logo=laravel&logoColor=white)](https://filamentphp.com) [![MySQL](https://img.shields.io/badge/MySQL-8+-4479A1?logo=mysql&logoColor=white)](https://mysql.com) --- **REST API + Admin Panel + Financial Engine** [🚀 نصب سریع](#-نصب-و-راهاندازی-سریع) • [📡 API Endpoints](#-api-endpoints) • [🗃️ Models](#-models) • [📚 مستندات](#-مستندات)
--- ## 🎯 نمای کلی این پوشه شامل **هسته مرکزی سیستم IFNEX** است: - REST API کامل برای ارتباط با WordPress - پنل مدیریت Filament - موتور قیمت‌گذاری با ۴ زون و ۳ نوع سرویس - سیستم کیف پول و پرداخت - تولید PDF (AWB, Invoice, Label) با بارکد - سیستم اعلان‌ها و تاریخچه تغییرات --- ## 🚀 نصب و راه‌اندازی سریع ### پیش‌نیازها | ابزار | حداقل نسخه | |-------|-----------| | PHP | 8.2+ | | Composer | 2.x | | MySQL | 8.0+ | ### مراحل نصب ```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 و تنظیم 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 ```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](../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) | راهنمای استقرار | ---
© 2026 VernaSoft Group. All Rights Reserved.