a1a6dbdd8a
This commit marks the completion of Phase 3 (Integration and Improvements) and updates the project status to reflect that Phases 0 through 3 are finished. Key changes include: - **Laravel (Backend):** - Added `calling_code` column to `countries` table via new migration. - Added scripts to update calling codes for all countries. - Updated `CustomerOrderController` to include `calling_code` in country data. - Registered `api_key` middleware alias in `bootstrap/app.php`. - Improved error handling to return JSON 401 for API authentication failures. - Updated `README.md` with detailed architecture and feature descriptions. - **WordPress (Frontend/Bridge):** - Added `ifnex_wallet_charge` shortcode and AJAX handler for wallet top-ups. - Implemented auto-fill for calling codes in the order form based on selected country. - Added real-time phone number validation (digits, +, spaces only). - Added English-only validation for name, city, and address fields with UI warnings. - Updated asset enqueuing logic and versioning for CSS/JS. - **Documentation:** - Updated `IFNEX_File_Map.md`, `IFNEX_Phase0_Checklist.md`, and `IFNEX_Roadmap.md` to reflect completed phases and new features. - Updated `DEPLOYMENT.md` with new environment variables (`IFNEX_BRIDGE_API_KEY`) and required WordPress pages. - Updated project `README.md` with comprehensive feature list and system architecture. |
||
|---|---|---|
| 01_Documents | ||
| 03_WordPress | ||
| 04_Laravel | ||
| .gitignore | ||
| DEPLOYMENT.md | ||
| README.md | ||
🚀 IFNEX Logistics Management System
پلتفرم جامع مدیریت لجستیک بینالمللی
جایگزینی فرآیندهای دستی مبتنی بر اکسل با معماری Headless مدرن
📖 درباره پروژه
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
- اعتبارسنجی فرمها شامل تشخیص خودکار زبان فارسی/انگلیسی و پیششماره خودکار
🏗️ معماری سیستم
این پروژه بر اساس الگوی 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 در سایدبار
- هشدار هوشمند زبان فارسی/انگلیسی در فرم سفارش (نام، شهر، آدرس)
- پیششماره تلفن خودکار بر اساس کشور انتخابی (۱۹۲ کشور)
- اعتبارسنجی تلفن (فقط اعداد، +، فاصله)
- استایل مدرن تراکنشها و دشبورد مشتری
- صفحه شارژ کیف پول با مبالغ آماده
- اصلاح متدهای Enum (isPaid, canBeCancelledByCustomer)
- میدلور API برای بازگرداندن JSON 401 به جای redirect
فاز ۴ (آینده) — سیستم نمایندگی 📋
- مدل نمایندگی کامل با کمیسیون و پنل جداگانه
- طرح مطالعاتی آماده — منتظر تأیید کارفرما
⚡ شروع سریع
پیشنیازها
- PHP 8.2+ با extensions: pdo_mysql, mbstring, xml, gd, zip
- Composer 2.x
- MySQL 8+
- WordPress 7.0+
نصب بکاند (Laravel)
# ۱. کلون مخزن
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)
# ۱. کپی پوشه 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 را ببینید.
🛠️ 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 | چکلیست کامل فازها | ⭐⭐⭐ |
| IFNEX_Roadmap.md | نقشه راه آینده | ⭐⭐⭐ |
| IFNEX_File_Map.md | نقشه ۱۰۰+ فایل پروژه | ⭐⭐⭐ |
| DEPLOYMENT.md | راهنمای استقرار Production | ⭐⭐ |
| 04_Laravel/README.md | راهنمای بکاند | ⭐⭐ |
| IFNEX_DEPRECATED_FILES_NOTICE.md | فایلهای منسوخ | ⭐ |
🚀 مراحل بعدی (فاز ۴)
- سیستم نمایندگی کامل با کمیسیون و پنل جداگانه
- اتصال به APIهای ترکینگ زنده (TrackingMore/17track)
- پلاگین SMS برای اطلاعرسانی خودکار
- مستندات API (OpenAPI/Swagger)
- راهنمای اپراتور (Operator Manual)
- تستهای واحد و Integration
- اپلیکیشن موبایل (احتمالی)
- ویرایش پروفایل مشتری + استان/شهر بر اساس کشور
📞 تماس
- توسعهدهنده: Kazem Alghasi
- شرکت: VernaSoft Group
- ایمیل: kazem@vernasoft.group
- مخزن: git.vernahost.ir/gitmodir110/ifnex
- سرور تست: api.ifnex.vernahost.ir (Laravel) | ifnex.vernahost.ir (WordPress)
📜 لایسنس
© 2026 VernaSoft Group. تمام حقوق محفوظ است.
این پروژه اختصاصی شرکت IFNEX است و کپی یا استفاده غیرمجاز ممنوع میباشد.