02c29db696
Introduce a comprehensive set of commercial features including a multi-step order approval workflow, customer credit management, and specialized import service invoicing. Key changes: - Implement `pending_approval` and `approved` shipment statuses to allow staff verification before customer payment. - Add a credit system to `User` model with `credit_limit` and `credit_used` to manage customer balances and debts. - Develop a new `importInvoice` PDF generation service following the "Sheet ENG Invoice" specification for import services. - Add Filament resources for managing Audit Logs, Commitment Forms, Customer Credits, and Shipment Checklists. - Implement staff-specific APIs for order approval/rejection and customer financial status monitoring. - Integrate Kavenegar SMS service for mobile verification and notifications. - Add bulk tracking import functionality via CSV/Excel. - Update WordPress bridge assets (CSS/JS) to support the new multi-step order form UI and updated redirection logic. - Update deployment configurations and documentation to reflect new production domains and feature sets. |
||
|---|---|---|
| 01_Documents | ||
| 03_WordPress | ||
| 04_Laravel | ||
| .gitignore | ||
| AGENT.md | ||
| 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
- اعتبارسنجی فرمها شامل تشخیص خودکار زبان فارسی/انگلیسی و پیششماره خودکار
- سیستم تأیید سفارش با فلوی
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) — به زمان دیپلوی منتقل شد
فاز ۴ (آینده) — سیستم نمایندگی 📋
- مدل نمایندگی کامل با کمیسیون و پنل جداگانه
- طرح مطالعاتی آماده — منتظر تأیید کارفرما
فاز ۵ (آینده) — تجاریسازی 📋
- مدل پولی چندلایهای: 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)
# ۱. کلون مخزن
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 | نقشه ۱۰۰+ فایل پروژه | ⭐⭐⭐ |
| IFNEX_I18N_Strategy.md | استراتژی چندزبانه (Polylang) | ⭐⭐ |
| IFNEX_Commercial_Model.md | مدل تجاری و پلنهای فروش | ⭐⭐ |
| DEPLOYMENT.md | راهنمای استقرار Production | ⭐⭐ |
| 04_Laravel/README.md | راهنمای بکاند | ⭐⭐ |
| IFNEX_DEPRECATED_FILES_NOTICE.md | فایلهای منسوخ | ⭐ |
🚀 مراحل بعدی
فاز ۳.۵ — باقیمانده (زمان دیپلوی)
- پشتیبانی کامل چندزبانه (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
- سرور تست: api.ifnex.vernahost.ir (Laravel) | ifnex.vernahost.ir (WordPress)
📜 لایسنس
© 2026 VernaSoft Group. تمام حقوق محفوظ است.
این پروژه اختصاصی شرکت IFNEX است و کپی یا استفاده غیرمجاز ممنوع میباشد.