# 🚀 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 و محاسبهٔ لحظه‌ای قیمت
- **پشتیبانی چندبسته‌ای** (Multi-Package) در یک سفارش با محاسبهٔ خودکار وزن حجمی
- **تولید خودکار اسناد** (AWB، Invoice، Label، فاکتور واردات) با بارکد Code-128 و پشتیبانی کامل از زبان انگلیسی
- **پورتال مشتری کامل** با کیف پول، پرداخت آنلاین، تراکنش‌ها، اعلان‌ها و رهگیری مرسوله
- **فلوی تأیید سفارش** با مسیر `pending_approval → approved → paid → processed`
- **چرخهٔ تعهدنامه** با فلوی کامل End-to-End (دانلود قالب ← آپلود امضاشده ← تأیید یا رد ادمین ← اعلان مشتری)
- **سیستم اعتبار چندارزی** — بدهی به همان ارز ثبت می‌شود، تسویه با نرخ روز
- **مانده حساب** با نمایش موجودی کیف پول منهای بدهی‌های تأییدشده
- **وضعیت مالی مشتری** — صفحهٔ جامع در پنل ادمین (۴ KPI + بدهی‌های ارزی + سفارش‌ها و تراکنش‌ها)
- **ویجت هشدار بدهی‌های ارزی** روی داشبورد به‌همراه badge روی منو
- **چک‌لیست خودکار کارمند** — نمونه‌سازی از قالب پس از تأیید سفارش
- **ایمپورت گروهی وضعیت ترکینگ** با فایل CSV در پنل مدیریت
- **سیستم Audit Log** برای ثبت لاگ تغییرات مدیر
- **پنل مدیریت قدرتمند Filament** شامل مدیریت مرسوله‌ها، نرخ‌ها، ارزها، کاربران و گزارش‌ها
- **سیستم ترکینگ** با مهاجرت داده‌های تاریخی و تایم‌لاین کامل
- **اعلان‌های دیتابیس** برای ادمین و مشتری با badge unread در سایدبار
- **Rate Limiting** روی همهٔ APIها (۶ لایه: auth / sms / public / customer / wallet / staff)
- **پشتیبانی از ۱۹۲ کشور** با پیش‌شمارهٔ تلفن استاندارد ISO 3166-1
- **اعتبارسنجی فرم‌ها** با تشخیص خودکار زبان فارسی/انگلیسی و پیش‌شمارهٔ خودکار
- **سرویس پیامک Kavenegar** برای تأیید موبایل و ارسال اعلان وضعیت سفارش
---
## 🏗️ معماری سیستم
این پروژه بر اساس الگوی **Headless** طراحی شده است — فرانت‌اند (WordPress) و بک‌اند (Laravel) کاملاً جدا و فقط از طریق REST API با هم ارتباط دارند. این جداسازی امکان مقیاس‌پذیری مستقل هر لایه، بهبود امنیت و افزودن فرانت‌اندهای آینده (مثل اپلیکیشن موبایل) را می‌دهد.
```text
┌──────────────────────────────────────────────────────┐
│ 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 │
│ (52 migrations, 22 │
│ models) │
└─────────────────────────┘
```
### جریان احراز هویت
```text
┌──────────┐ ┌─────────────────┐ ┌──────────────┐
│ WordPress│ ──POST /bridge/login──> │ Laravel Bridge │ ──> │ Sanctum Token│
│ Plugin │ <──token + user info── │ Controller │ <── │ (30 days) │
└──────────┘ └─────────────────┘ └──────────────┘
│ │
│ ──────── All subsequent API calls with Bearer Token ──────────────>│
└─────────────────────────────────────────────────────────────────────────┘
```
---
## 📁 ساختار پروژه
```text
IFNEX-Logistics/
├── 📄 01_Documents/ # مستندات فنی پروژه
│ ├── IFNEX_File_Map.md # نقشهٔ کامل ۱۰۰+ فایل
│ ├── IFNEX_Roadmap.md # نقشهٔ راه فازی
│ ├── IFNEX_Phase0_Checklist.md # چک‌لیست تکمیل فازها
│ ├── IFNEX_ADR.md # تصمیمات معماری (ADR-001 تا 009)
│ └── 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 + 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/ # ۱۷ Resource (Shipment، Country و…)
│ │ │ ├── Pages/ # Settings، ImportRates، PriceTest، Reports
│ │ │ └── Widgets/ # داشبورد
│ │ ├── Http/
│ │ │ ├── Controllers/Api/ # Track، Pricing، Auth، Bridge، Customer، Wallet، Payment
│ │ │ └── Middleware/ # ApiKeyMiddleware
│ │ ├── Models/ # ۲۶ مدل Eloquent
│ │ ├── Notifications/ # اعلان‌های دیتابیسی
│ │ ├── Services/ # PriceCalculator، Pdf، Tracking، OrderPayment
│ │ └── Imports/ # ایمپورت اکسل (OldShipments، ShippingRates)
│ ├── database/
│ │ ├── migrations/ # ۵۲ migration
│ │ └── seeders/ # Countries، SystemSettings، DatabaseSeeder
│ ├── resources/views/
│ │ ├── pdfs/ # awb، invoice، label، import-invoice
│ │ └── filament/ # Blade views
│ └── routes/
│ ├── api.php # ۴۰+ endpoint
│ └── web.php # روت‌های وب + دانلود Template
│
├── 📋 README.md # همین فایل
├── 📋 AGENT.md # راهنمای ایجنت
├── 📋 CLIENT_DELIVERY.md # چک‌لیست وضعیت تحویل مشتری (منبع اصلی)
├── 📋 DEPLOYMENT.md # راهنمای استقرار Production
└── 📋 DEPLOYMENT_HANDOFF.md # تحویل استقرار به تیم IT کارفرما
```
---
## ✨ ویژگی‌ها بر اساس فازها
### فاز ۰ — بنیان سیستم ✅ (۱۰۰٪)
- اسکیمای دیتابیس مدرن با ۴ زون مجزا (Export/Import × Parcel/Doc)
- مهاجرت ۳۹۵۰ رکورد تاریخی از اکسل به دیتابیس
- پنل مدیریت Filament با UX تخصصی اپراتور
- API ترکینگ با امنیت کلید API و Rate Limiting
- پلاگین WordPress Bridge برای ارتباط با فرانت‌اند
### فاز ۱ — پورتال مشتری ✅ (۱۰۰٪)
- احراز هویت Laravel Sanctum + Bridge Auth (بدون نیاز به رمز عبور)
- فرم ثبت سفارش چندمرحله‌ای با Wizard (مسیر، اطلاعات تماس، تخفیف، تأیید)
- داشبورد جامع مشتری: داشبورد، سفارش‌ها، ثبت سفارش، کیف پول، تراکنش‌ها، رهگیری، اعلان‌ها، پروفایل
- سیستم ترکینگ با تایم‌لاین و تاریخچهٔ کامل
### فاز ۲ — مالی و کیف پول ✅ (۱۰۰٪)
- سیستم کیف پول کامل با تراکنش‌ها و تاریخچه
- درگاه پرداخت Zarinpal + Mock Gateway برای تست لوکال
- مدیریت ارزهای چندگانه (IRR، AED، USD، EUR، CNY)
- کدهای تخفیف با اعتبارسنجی و محدودیت مصرف
- تولید PDF حرفه‌ای (AWB، Invoice، Label) با بارکد استاندارد
- پشتیبانی از چند بسته در یک سفارش (Multi-Package)
- تاریخچهٔ تغییرات وضعیت (ShipmentStatusHistory)
### فاز ۳ — بهبود و یکپارچه‌سازی ✅ (۱۰۰٪)
- ایمپورت/اکسپورت نرخ‌ها با دانلود Template اکسل
- سیستم اعلان‌های دیتابیس (ادمین + مشتری) با badge unread در سایدبار
- هشدار هوشمند زبان فارسی/انگلیسی در فرم سفارش (نام، شهر، آدرس)
- پیش‌شمارهٔ تلفن خودکار بر اساس کشور انتخابی (۱۹۲ کشور)
- اعتبارسنجی تلفن (فقط اعداد، `+` و فاصله)
- استایل مدرن تراکنش‌ها و داشبورد مشتری
- صفحهٔ شارژ کیف پول با مبالغ آماده
- بازطراحی PDFها (AWB، Invoice، Label) با بارکد مطابق نمونهٔ کارفرما
- اصلاح متدهای Enum (`isPaid`، `canBeCancelledByCustomer`)
- میدلور API برای بازگرداندن JSON 401 به‌جای redirect
### فاز ۳.۵ — اصلاحات اساسی ✅ (۹۰٪)
- Multi-Package در فرم سفارش مشتری (چند بسته در یک سفارش)
- فرم Invoice برای محموله‌های PARCEL (اقلام گمرکی با HS Code)
- بازطراحی PDFها (AWB، Invoice، Label) با بارکد مطابق نمونهٔ کارفرما
- تست کامل ترکینگ با تایم‌لاین چندمرحله‌ای
- محاسبهٔ خودکار وزن حجمی از ابعاد (فرمول: `L × W × H / 5000`)
- ساختار ۵ مرحله‌ای فرم سفارش (مسیر ← تماس ← اقلام ← تخفیف ← تأیید)
- اصلاحات فنی (Enum casts، migration، model)
- پشتیبانی چندزبانه (i18n) — منتقل شد به زمان دیپلوی
### فاز ۳.۶ — اصلاحات جلسهٔ کارفرما ✅ (۹۵٪)
- [x] فلوی تأیید سفارش `pending_approval → approved → پرداخت → processed` — تست End-to-End
- [x] تعهدنامه‌ها با فلوی کامل (دانلود قالب ← آپلود امضاشده ← تأیید/رد ادمین ← اعلان مشتری)
- [x] دانلود اسناد سفارش (AWB، Invoice، Label، فاکتور واردات) در پورتال مشتری
- [x] صفحهٔ «وضعیت مالی مشتری» در پنل ادمین (۴ KPI + بدهی ارزی + سفارش‌ها و تراکنش‌ها)
- [x] سیستم اعتبار چندارزی کامل (درخواست ۹) — `CustomerCreditService` + نمایش در پورتال مشتری
- [x] ویجت هشدار بدهی‌های ارزی روی داشبورد + badge قرمز روی منو
- [x] چک‌لیست خودکار پس از تأیید سفارش (درخواست ۵) — `instantiateChecklist()`
- [x] Rate Limiting روی همهٔ APIها (۶ لایه throttle)
- [x] ایمپورت گروهی وضعیت ترکینگ با CSV در پنل (`BulkTrackingImport`)
- [x] Audit Log برای مدل‌های اصلی + `ShipmentStatusHistory` با `from_status` / `to_status`
- [x] اتصال SMS کاوه‌نگار: تأیید/رد سفارش، پرداخت موفق، به‌روزرسانی ترکینگ + تنظیمات پنل
- [x] فاکتور واردات (Import Invoice) با فیلدهای جدید shipments + قالب PDF
- [x] مانده حساب (موجودی منهای بدهی‌های تأییدشده) در پروفایل مشتری
- [x] بازطراحی داشبورد و Login فیلمنت (هویت بصری navy + amber)
- [x] بازطراحی AWB، Invoice و Label (dompdf، چیدمان جدولی، سبک DHL)
- [x] استایل‌دهی صفحهٔ پروفایل مشتری در وردپرس
- [x] پاک‌سازی کد — حذف فایل‌های تستی، تأیید تمیزی `opcache_reset` / `dd` / `dump`
### فاز ۴ (آینده) — سیستم نمایندگی 📋
- مدل نمایندگی کامل با کمیسیون و پنل جداگانه
- طرح مطالعاتی آماده — منتظر تأیید کارفرما
### فاز ۵ (آینده) — تجاری‌سازی 📋
- مدل پولی چندلایه: Starter / Business / Enterprise
- فرم‌ساز Drag & Drop
- White-label branding
- API Gateway برای توسعه‌دهندگان
---
## ⚡ شروع سریع
### پیش‌نیازها
- PHP 8.2+ با اکستنشن‌های `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)
1. پوشهٔ `03_WordPress` را در `htdocs` (XAMPP) یا `public_html` (سرور) کپی کنید.
2. دیتابیس وردپرس را بسازید و نصب را اجرا کنید.
3. قالب IFNEX و پلاگین IFNEX Bridge را فعال کنید.
4. تنظیمات پلاگین را کامل کنید (پنل وردپرس ← منوی IFNEX):
| تنظیم | مقدار |
|--------|--------|
| API URL | `http://localhost:8000/api/v1` |
| API Key (عمومی) | همان مقدار `IFNEX_API_KEY` در `.env` لاراول |
| Bridge API Key | همان مقدار `IFNEX_BRIDGE_API_KEY` در `.env` لاراول |
5. صفحات را با شورت‌کدها بسازید:
| صفحه | شورت‌کد |
|------|---------|
| `/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) و [DEPLOYMENT_HANDOFF.md](DEPLOYMENT_HANDOFF.md) را ببینید.
---
## 🛠️ استک فنی
### بک‌اند (Laravel)
| تکنولوژی | نسخه | کاربرد |
|-----------|-------|--------|
| Laravel | 11.x | فریمورک اصلی |
| PHP | 8.2+ | زبان برنامه‌نویسی |
| Filament | 3.3.x | پنل مدیریت ادمین |
| MySQL | 8+ | دیتابیس |
| Dompdf | Latest | تولید PDF |
| Laravel Excel | Latest | Import / Export |
| Sanctum | Latest | احراز هویت API |
| Morilog Jalali | 3.x | تاریخ شمسی |
| picqer/php-barcode | Latest | تولید بارکد |
### فرانت‌اند (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 | ۱۷ |
| تعداد مدل‌ها | ۲۶ |
| تعداد شورت‌کدهای وردپرس | ۱۰+ |
| تعداد کشورها با پیش‌شماره | ۱۹۲ |
| رکوردهای تاریخی مهاجرت‌شده | ۳۹۵۰ |
| خطوط کد (تخمینی) | ۲۰۰۰۰+ |
---
## 📚 مستندات
برای مطالعهٔ دقیق منطق‌های سیستم:
| فایل | محتوا | اولویت |
|------|-------|---------|
| [CLIENT_DELIVERY.md](CLIENT_DELIVERY.md) | **چک‌لیست وضعیت تحویل مشتری (منبع اصلی)** | ⭐⭐⭐ |
| [DEPLOYMENT_HANDOFF.md](DEPLOYMENT_HANDOFF.md) | راهنمای استقرار برای تیم IT کارفرما | ⭐⭐⭐ |
| [AGENT.md](AGENT.md) | راهنمای ایجنت، مفاهیم کلیدی و خط قرمزها | ⭐⭐⭐ |
| [01_Documents/IFNEX_Phase0_Checklist.md](01_Documents/IFNEX_Phase0_Checklist.md) | چک‌لیست کامل فازها | ⭐⭐ |
| [01_Documents/IFNEX_Roadmap.md](01_Documents/IFNEX_Roadmap.md) | نقشهٔ راه آینده (فاز ۴ و ۵) | ⭐⭐ |
| [01_Documents/IFNEX_File_Map.md](01_Documents/IFNEX_File_Map.md) | نقشهٔ ۱۰۰+ فایل پروژه | ⭐⭐ |
| [DEPLOYMENT.md](DEPLOYMENT.md) | راهنمای استقرار Production | ⭐⭐ |
| [04_Laravel/README.md](04_Laravel/README.md) | راهنمای بک‌اند | ⭐⭐ |
| [01_Documents/IFNEX_I18N_Strategy.md](01_Documents/IFNEX_I18N_Strategy.md) | استراتژی چندزبانه (Polylang) | ⭐ |
| [01_Documents/IFNEX_Commercial_Model.md](01_Documents/IFNEX_Commercial_Model.md) | مدل تجاری و پلن‌های فروش | ⭐ |
---
## 🚀 مراحل بعدی
> 📌 **فهرست دقیق و به‌روزِ وضعیت تحویل در [CLIENT_DELIVERY.md](CLIENT_DELIVERY.md) نگهداری می‌شود** — این بخش فقط نمای کلی است.
### باقی‌ماندهٔ فاز ۳.۶
- ⏳ چندزبانه (i18n) با Polylang — موکول به زمان دیپلوی
- ⏳ سند پیشنهادی سیستم مالی (درخواست ۱۳ کارفرما) — موکول به آینده
- ⏳ تست نهایی UAT کارفرما
- ⏳ دیپلوی روی سرور Production
> ✅ همهٔ موارد اصلی فاز ۳.۶ در ۲۰۲۶-۱۰-۰۴ تکمیل شد: فلوی End-to-End، اعتبار چندارزی، Rate Limiting، چک‌لیست خودکار، بازطراحی UI و PDF، و پاک‌سازی کد.
### فاز ۴ (آینده)
- سیستم نمایندگی کامل با کمیسیون و پنل جداگانه
### فاز ۵ (آینده — تجاری‌سازی)
- مدل پولی چندلایه: 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://www.git.vernahost.ir/gitmodir110/ifnex) |
---
📜 لایسنس
© 2026 VernaSoft Group. تمام حقوق محفوظ است.
این پروژه طبق سفارش IFNEX و مالکیت آن برای گروه ورناسافت است و کپی یا استفادهٔ غیرمجاز ممنوع می‌باشد.