# 🚀 IFNEX Logistics Management System
### پلتفرم جامع مدیریت لجستیک بینالمللی
[](https://laravel.com)
[](https://filamentphp.com)
[](https://filamentphp.com)
[](https://wordpress.org)
[](https://mysql.com)
[]()
[]()
---
*جایگزینی فرآیندهای دستی مبتنی بر اکسل با معماری Headless مدرن*
**[📚 مستندات](#-مستندات)** • **[⚡ شروع سریع](#-شروع-سریع)** • **[🏗️ معماری](#%EF%B8%8F-معماری-سیستم)** • **[📞 پشتیبانی](#-تماس)**
---
## 📖 درباره پروژه
**IFNEX** یک راهحل جامع برای شرکتهای حملونقل بینالمللی است که فرآیندهای مبتنی بر فایلهای اکسل را با یک سیستم Headless مدرن جایگزین میکند. این سیستم با تکیه بر Laravel 11 به عنوان بکاند، WordPress به عنوان فرانتاند و Filament 3.3 به عنوان پنل مدیریت، تجربهای یکپارچه برای اپراتورها و مشتریان فراهم میآورد.
### ✨ امکانات کلیدی
- **موتور قیمتگذاری هوشمند** با ۴ زون مجزا (Export/Import × Parcel/Doc) و ۳ نوع سرویس (DOC_NORMAL, DOC_ECONOMY, PARCEL)
- **ثبت سفارش آنلاین چندمرحلهای** با Wizard و محاسبه لحظهای قیمت
- **تولید خودکار اسناد** (AWB, Invoice, Label) با بارکد استاندارد و پشتیبانی کامل از زبان انگلیسی
- **پورتال مشتری کامل** با کیف پول، پرداخت آنلاین، تراکنشها، اعلانها و رهگیری مرسوله
- **پنل مدیریت قدرتمند** با Filament 3.3 شامل مدیریت مرسولهها، نرخها، ارزها، کاربران و گزارشها
- **سیستم ترکینگ** با قابلیت مهاجرت دادههای تاریخی و تایملاین کامل
- **اعلانهای دیتابیس** برای ادمین و مشتری با badge unread در سایدبار
- **پشتیبانی از ۱۹۲ کشور** با پیششماره تلفن استاندارد ISO 3166-1
- **اعتبارسنجی فرمها** شامل تشخیص خودکار زبان فارسی/انگلیسی و پیششماره خودکار
- **سیستم تأیید سفارش** با فلوی `pending_approval → approved → paid → processed`
- **فرم تعهدنامه** با قابلیت آپلود فایل توسط مدیر و مشاهده توسط مشتری
- **فاکتور واردات** با طراحی مطابق Sheet ENG Invoice
- **مانده حساب** با نمایش موجودی کیف پول منهای بدهیها
- **وضعیت مالی مشتری** برای مدیر/کارمند با جزئیات بدهی به هر ارز
- **سیستم اعتباردهی (Credit)** با قابلیت افزایش/کاهش توسط مدیر کل
- **چکلیست کارمند** برای هر سفارش + تاریخچه مراحل
- **ایمپورت گروهی وضعیت ترکینگ** با فایل CSV
- **سیستم Audit Log** برای لاگ تغییرات مدیر
- **اتصال سرویس اساماس Kavenegar** برای تأیید موبایل و ارسال پیامک
---
## 🏗️ معماری سیستم
این پروژه بر اساس الگوی **Headless** طراحی شده است — فرانتاند (WordPress) و بکاند (Laravel) کاملاً جدا و فقط از طریق REST API با هم ارتباط دارند. این جداسازی به ما امکان میدهد تا هر لایه را مستقل مقیاسپذیر کنیم، امنیت را بهبود ببخشیم و در آینده فرانتاندهای دیگری (مثل اپلیکیشن موبایل) را اضافه کنیم.
```
┌──────────────────────────────────────────────────────┐
│ CLIENT BROWSER │
└────────────────────────┬─────────────────────────────┘
│
┌────────────────────────▼─────────────────────────────┐
│ WORDPRESS (Frontend) │
│ ┌───────────────────┐ ┌──────────────────────────┐ │
│ │ IFNEX Theme │ │ IFNEX Bridge Plugin │ │
│ │ (Landing Page) │ │ (REST Client + AJAX) │ │
│ └───────────────────┘ └────────────┬─────────────┘ │
└───────────────────────────────────────┼──────────────┘
│ REST API (Sanctum + Bridge Key)
┌───────────────────────────────────────▼──────────────┐
│ LARAVEL 11 (Backend) │
│ ┌─────────────────┐ ┌──────────────┐ ┌──────────┐ │
│ │ Filament │ │ API │ │ Services │ │
│ │ Admin Panel │ │ Controllers │ │ (Pricing,│ │
│ │ (/panel) │ │ (/api/v1) │ │ PDF, │ │
│ └─────────────────┘ └──────┬───────┘ │ Payment)│ │
└──────────────────────────────┼──────────┴──────────┘
│
┌────────────▼────────────┐
│ MySQL 8 Database │
│ (23 migrations, 13 │
│ models) │
└─────────────────────────┘
```
### جریان احراز هویت
```
┌──────────┐ ┌─────────────────┐ ┌──────────────┐
│ WordPress│ ──POST /bridge/login──> │ Laravel Bridge │ ──> │ Sanctum Token│
│ Plugin │ <──token + user info── │ Controller │ <── │ (30 days) │
└──────────┘ └─────────────────┘ └──────────────┘
│ │
│ ──────── All subsequent API calls with Bearer Token ──────────────>│
└─────────────────────────────────────────────────────────────────────────┘
```
---
## 📁 ساختار پروژه
```
IFNEX-Logistics/
├── 📄 01_Documents/ # مستندات فنی پروژه
│ ├── IFNEX_File_Map.md # نقشه کامل ۱۰۰+ فایل
│ ├── IFNEX_Roadmap.md # نقشه راه ۴ فازی
│ ├── IFNEX_Phase0_Checklist.md # چکلیست تکمیل فازها
│ ├── IFNEX_DEPRECATED_FILES_NOTICE.md
│ └── EXCEL_ANALYSIS.md # تحلیل دادههای تاریخی
│
├── 🌐 03_WordPress/ # فرانتاند (WordPress 7.0.3)
│ └── wp-content/
│ ├── themes/ifnex/ # قالب سفارشی IFNEX
│ └── plugins/
│ └── ifnex-bridge/ # پلاگین ارتباط با لاراول
│ ├── includes/
│ │ ├── api-client.php # مستقیم به API
│ │ ├── user-bridge.php # Bridge Auth + AJAX handlers
│ │ ├── shortcodes.php # ۱۰+ شورتکد
│ │ └── tracking-form.php # فرم رهگیری
│ └── assets/
│ ├── css/ifnex-orders.css # استایل دشبورد
│ └── js/ifnex-order-form.js # فرم چندمرحلهای
│
├── ⚙️ 04_Laravel/ # بکاند (Laravel 11)
│ ├── app/
│ │ ├── Enums/ # ShipmentStatus, Direction, Type
│ │ ├── Filament/
│ │ │ ├── Resources/ # 10+ Resource (Shipment, Country, ...)
│ │ │ ├── Pages/ # Settings, ImportRates, PriceTest, Reports
│ │ │ └── Widgets/ # Dashboard Widgets
│ │ ├── Http/
│ │ │ ├── Controllers/Api/ # Track, Pricing, Auth, Bridge, Customer, Wallet, Payment
│ │ │ └── Middleware/ # ApiKeyMiddleware
│ │ ├── Models/ # 13 مدل Eloquent
│ │ ├── Notifications/ # Database notifications
│ │ ├── Services/ # PriceCalculator, Pdf, Tracking, OrderPayment
│ │ └── Imports/ # Excel imports (OldShipments, ShippingRates)
│ ├── database/
│ │ ├── migrations/ # 23 migrations
│ │ └── seeders/ # Countries, SystemSettings, DatabaseSeeder
│ ├── resources/views/
│ │ ├── pdfs/ # awb, invoice, label
│ │ └── filament/ # Blade views
│ └── routes/
│ ├── api.php # 30+ REST API endpoints
│ └── web.php # Web routes + Download Template
│
├── 📋 README.md # این فایل
├── 📋 DEPLOYMENT.md # راهنمای استقرار Production
└── 📋 04_Laravel/README.md # راهنمای بکاند
```
---
## ✨ ویژگیهای کلیدی بر اساس فازها
### فاز ۰ — بنیان سیستم ✅ (تکمیل شده - 100%)
- اسکیمای دیتابیس مدرن با ۴ زون مجزا (Export/Import × Parcel/Doc)
- مهاجرت ۳۹۵۰ رکورد تاریخی از اکسل به دیتابیس
- پنل مدیریت Filament با UX تخصصی اپراتور
- API ترکینگ با امنیت API Key + Rate Limiting
- پلاگین WordPress Bridge برای ارتباط با فرانتاند
### فاز ۱ — پورتال مشتری ✅ (تکمیل شده - 100%)
- احراز هویت Laravel Sanctum + Bridge Auth (بدون نیاز به رمز عبور)
- فرم ثبت سفارش چندمرحلهای با Wizard (مسیر، اطلاعات تماس، تخفیف، تأیید)
- داشبورد جامع مشتری شامل: داشبورد، سفارشات، ثبت سفارش، کیف پول، تراکنشها، رهگیری، اعلانها، پروفایل
- سیستم ترکینگ با تایملاین و تاریخچه کامل
### فاز ۲ — مالی و کیف پول ✅ (تکمیل شده - 100%)
- سیستم کیف پول کامل با تراکنشها و تاریخچه
- درگاه پرداخت Zarinpal + Mock Gateway برای تست لوکال
- مدیریت ارزهای چندگانه (IRR, AED, USD, EUR, CNY)
- کدهای تخفیف با اعتبارسنجی و محدودیت مصرف
- تولید PDF حرفهای (AWB, Invoice, Label) با بارکد استاندارد
- پشتیبانی از چند بسته در یک سفارش (Multi-Package)
- تاریخچه تغییرات وضعیت (ShipmentStatusHistory)
### فاز ۳ — بهبود و یکپارچهسازی ✅ (تکمیل شده - 100%)
- ایمپورت/اکسپورت نرخها با دانلود Template اکسل
- سیستم اعلانهای دیتابیس (ادمین + مشتری) با badge unread در سایدبار
- هشدار هوشمند زبان فارسی/انگلیسی در فرم سفارش (نام، شهر، آدرس)
- پیششماره تلفن خودکار بر اساس کشور انتخابی (۱۹۲ کشور)
- اعتبارسنجی تلفن (فقط اعداد، +، فاصله)
- استایل مدرن تراکنشها و دشبورد مشتری
- صفحه شارژ کیف پول با مبالغ آماده
- بازطراحی PDFها (AWB, Invoice, Label) با بارکد مطابق نمونه کارفرما
- اصلاح متدهای Enum (isPaid, canBeCancelledByCustomer)
- میدلور API برای بازگرداندن JSON 401 به جای redirect
### فاز ۳.۵ — اصلاحات اساسی ✅ (تکمیل شده - 90%)
- **Multi-Package** در فرم سفارش مشتری (چند بسته در یک سفارش)
- **فرم Invoice** برای محمولههای PARCEL (اقلام گمرکی با HS Code)
- **بازطراحی PDFها** (AWB, Invoice, Label) با بارکد مطابق نمونه کارفرما
- **تست ترکینگ** کامل با timeline زیبا و چندمرحلهای
- محاسبه خودکار وزن حجمی از ابعاد (فرمول: L×W×H/5000)
- ساختار ۵ مرحلهای فرم سفارش (مسیر → تماس → اقلام → تخفیف → تأیید)
- اصلاحات فنی (Enum casts, migration, model)
- پشتیبانی چندزبانه (i18n) — به زمان دیپلوی منتقل شد
### فاز ۳.۶ — اصلاحات جلسه کارفرما 🟡 (در حال تکمیل - ۸۰٪)
**هدف:** پیادهسازی تغییرات درخواستی کارفرما پس از جلسه ارائه
- ✅ فلوی تأیید سفارش: `pending_approval → approved → (پرداخت) → processed` — مشتری بعد از ثبت منتظر تأیید کارمند میماند و سپس پرداخت (کیف پول/درگاه) باز میشود
- ✅ تعهدنامهها: آپلود توسط مدیر در Filament → نمایش/دانلود برای مشتری → آپلود فایل امضاشده توسط مشتری (جدول `shipment_commitment_forms`)
- ✅ دانلود اسناد سفارش (AWB, Invoice, Label, فاکتور واردات) در پورتال مشتری
- ✅ وضعیت مالی مشتری برای کارمند/مدیر: جستجوی مشتری + بدهی به تفکیک ارز + تراکنشها و سفارشات اخیر
- ✅ سیستم اعتبار مشتری (اسکلت: `credit_limit/credit_used` + CustomerCreditResource) — نیازمند بازطراحی چندارزی
- ✅ ایمپورت گروهی وضعیت ترکینگ با CSV در پنل (BulkTrackingImport)
- ✅ Audit Log برای مدلهای اصلی + ShipmentStatusHistory با from/to_status
- ✅ اتصال SMS کاوهنگار: تأیید/رد سفارش، پرداخت موفق، بروزرسانی ترکینگ + تنظیمات پنل
- ✅ فاکتور واردات (Import Invoice) با فیلدهای جدید shipments + قالب PDF مطابق شیت ENG
- ✅ مانده حساب (موجودی منهای بدهیهای تأییدشده) در پروفایل مشتری
- ✅ رفع باگ مراحل فرم سفارش (ریشه: div بستهنشده در shortcodes.php) و محاسبه مجموع USD اقلام
- ⏳ باقیمانده: تست انتهای فلو، امنیت روتهای staff، بازطراحی اعتبار چندارزی، چکلیست خودکار، سند سیستم مالی (جزئیات در AGENT.md)
### فاز ۴ (آینده) — سیستم نمایندگی 📋
- مدل نمایندگی کامل با کمیسیون و پنل جداگانه
- طرح مطالعاتی آماده — منتظر تأیید کارفرما
### فاز ۵ (آینده) — تجاریسازی 📋
- مدل پولی چندلایهای: Starter / Business / Enterprise
- فرمساز Drag & Drop
- White-label branding
- API Gateway برای توسعهدهندگان
---
## ⚡ شروع سریع
### پیشنیازها
- PHP 8.2+ با extensions: pdo_mysql, mbstring, xml, gd, zip
- Composer 2.x
- MySQL 8+
- WordPress 7.0+
### نصب بکاند (Laravel)
```bash
# ۱. کلون مخزن
git clone https://www.git.vernahost.ir/gitmodir110/ifnex.git
cd ifnex/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=ifnex_db
# DB_USERNAME=root
# DB_PASSWORD=your_password
# IFNEX_BRIDGE_API_KEY=your-secret-bridge-key # مهم برای وردپرس
# ZARINPAL_MERCHANT_ID=fake-merchant-id-for-testing # برای Mock Mode
# ZARINPAL_SANDBOX=true
# CORS_ALLOWED_ORIGINS=http://localhost,http://127.0.0.1
# ۶. اجرای migrations و seeders
php artisan migrate --force
php artisan db:seed --force
# ۷. اجرای سرور
php artisan serve
# پنل ادمین: http://127.0.0.1:8000/panel
```
### نصب فرانتاند (WordPress)
```bash
# ۱. کپی پوشه 03_WordPress به htdocs (XAMPP) یا public_html (سرور)
# ۲. ساخت دیتابیس وردپرس و اجرای نصب
# ۳. فعالسازی قالب IFNEX و پلاگین IFNEX Bridge
# ۴. تنظیمات پلاگین (admin → منوی IFNEX):
# - API URL: http://localhost:8000/api/v1
# - API Key (عمومی): همان مقدار IFNEX_API_KEY در .env لاراول
# - Bridge API Key: همان مقدار IFNEX_BRIDGE_API_KEY در .env لاراول
# ۵. ساخت صفحات با شورتکدها:
# - /my-account/ → [ifnex_customer_dashboard]
# - /my-orders/ → [ifnex_orders_list]
# - /new-order/ → [ifnex_order_form]
# - /wallet/ → [ifnex_wallet_charge]
# - /tracking/ → [ifnex_tracking_form]
```
> 📖 برای راهنمای کامل استقرار روی سرور، [DEPLOYMENT.md](DEPLOYMENT.md) را ببینید.
---
## 🛠️ Stack فنی
### Backend (Laravel)
| تکنولوژی | نسخه | کاربرد |
|-----------|------|--------|
| Laravel | 11.x | فریمورک اصلی |
| PHP | 8.2+ | زبان برنامهنویسی |
| Filament | 3.3.x | پنل مدیریت ادمین |
| MySQL | 8+ | دیتابیس |
| Dompdf | Latest | تولید PDF |
| Laravel Excel | Latest | Import/Export |
| Sanctum | Latest | API Authentication |
| Morilog Jalali | 3.x | تاریخ شمسی |
| picqer/php-barcode | Latest | تولید بارکد |
### Frontend (WordPress)
| تکنولوژی | نسخه | کاربرد |
|-----------|------|--------|
| WordPress | 7.0.3 | CMS |
| IFNEX Theme | Custom | قالب سفارشی |
| IFNEX Bridge | 1.7.0 | پلاگین ارتباطی |
| jQuery | 3.x | AJAX + DOM |
### زیرساخت
| سرویس | کاربرد |
|-------|--------|
| HestiaCP | پنل مدیریت سرور |
| Nginx | وبسرور |
| PHP-FPM | پردازش PHP |
| MySQL 8 | دیتابیس |
| Let's Encrypt | SSL رایگان |
| Git (Gitea) | مخزن کد |
---
## 📊 آمار پروژه
| معیار | مقدار |
|-------|-------|
| تعداد مایگریشنها | ۳۸ |
| تعداد API endpoints | ۴۰+ |
| تعداد Filament Resources | ۱۷ |
| تعداد مدلها | ۲۲ |
| تعداد شورتکدهای وردپرس | ۱۰+ |
| تعداد کشورها با پیششماره | ۱۹۲ |
| رکوردهای تاریخی مهاجرتشده | ۳۹۵۰ |
| خطوط کد (تخمینی) | ۲۰۰۰۰+ |
---
## 📚 مستندات
برای مطالعه دقیق منطقهای سیستم:
| فایل | محتوا | اولویت |
|------|-------|--------|
| [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) | نقشه ۱۰۰+ فایل پروژه | ⭐⭐⭐ |
| [IFNEX_I18N_Strategy.md](01_Documents/IFNEX_I18N_Strategy.md) | استراتژی چندزبانه (Polylang) | ⭐⭐ |
| [IFNEX_Commercial_Model.md](01_Documents/IFNEX_Commercial_Model.md) | مدل تجاری و پلنهای فروش | ⭐⭐ |
| [DEPLOYMENT.md](DEPLOYMENT.md) | راهنمای استقرار Production | ⭐⭐ |
| [04_Laravel/README.md](04_Laravel/README.md) | راهنمای بکاند | ⭐⭐ |
| [IFNEX_DEPRECATED_FILES_NOTICE.md](01_Documents/IFNEX_DEPRECATED_FILES_NOTICE.md) | فایلهای منسوخ | ⭐ |
---
## 🚀 مراحل بعدی
### فاز ۳.۶ — باقیمانده (تست و تکمیل)
- تست انتهای فلو: آپلود تعهدنامه → تأیید کارمند → پرداخت (کیف پول / درگاه)
- امنیت: چک نقش روی روتهای `/staff/*`، چک مالکیت PDF/تعهدنامه، ثبت شورتکد `[ifnex_wallet_charge]`، محدودسازی `GET /discount-codes`، rate limiting
- بازطراحی سیستم اعتبار مطابق نیاز کارفرما (بدهی به ارز سفارش + تسویه ریالی)
- چکلیست خودکار کارمند بعد از تأیید سفارش + نمایش در صفحه سفارش
- سند پیشنهادی سیستم مالی
- پاکسازی هکهای موقت دیباگ (opcache_reset، cache-buster، صفحات تستی)
### فاز ۳.۵ — باقیمانده (زمان دیپلوی)
- پشتیبانی کامل چندزبانه (i18n) با Polylang
### فاز ۴ (آینده)
- سیستم نمایندگی کامل با کمیسیون و پنل جداگانه
### فاز ۵ (آینده — تجاریسازی)
- مدل پولی چندلایهای: Starter / Business / Enterprise
- اتصال به APIهای ترکینگ زنده (TrackingMore/17track)
- پلاگین SMS برای اطلاعرسانی خودکار
- مستندات API (OpenAPI/Swagger)
- راهنمای اپراتور (Operator Manual)
- تستهای واحد و Integration
- اپلیکیشن موبایل (احتمالی)
- فرمساز Drag & Drop
- White-label branding
- API Gateway برای توسعهدهندگان
---
## 📞 تماس
- **توسعهدهنده:** Kazem Alghasi
- **شرکت:** VernaSoft Group
- **ایمیل:** kazem@vernasoft.group
- **مخزن:** [git.vernahost.ir/gitmodir110/ifnex](https://git.vernahost.ir/gitmodir110/ifnex)
- **سرور تست:** [api.ifnex.vernahost.ir](https://api.ifnex.vernahost.ir) (Laravel) | [ifnex.vernahost.ir](https://ifnex.vernahost.ir) (WordPress)
---
📜 لایسنس
© 2026 VernaSoft Group. تمام حقوق محفوظ است.
این پروژه اختصاصی شرکت IFNEX است و کپی یا استفاده غیرمجاز ممنوع میباشد.