🚀 IFNEX Logistics Management System

Replacing Manual Excel Workflows with a Modern Headless Architecture

Author: VernaSoft Group (Kazem Alghasi)

---

📖 درباره پروژه

سیستم مدیریت لجستیک ایف‌نکس (IFNEX) یک راه‌حل جامع برای جایگزینی فرآیندهای مبتنی بر فایل‌های اکسل در شرکت‌های حمل و نقل بین‌المللی است. این سیستم با استفاده از معماری هدلس (Headless)، وردپرس را برای ظاهر سایت و سئو، و لاراول را به عنوان قلب تپنده و موتور محاسباتی به کار می‌گیرد.

چرا این پروژه متفاوت است؟

به جای اینکه اپراتورها وزن حجمی را محاسبه کنند، زون‌ها را در ۴ شیت مختلف جستجو کنند و با ماشین حساب قیمت نهایی را حساب کنند، اکنون تمام این فرآیند در کسر از ثانیه و بدون هیچ خطای انسانی انجام می‌شود.

---

🏗️ معماری سیستم (Tech Architecture)

سیستم بر اساس الگوی Headless توسعه یافته است. این یعنی فرانت‌اند (وردپرس) و بک‌اند (لاراول) کاملاً از هم جدا شده‌اند و فقط از طریق REST API با هم ارتباط دارند.

• فرانت‌اند (WordPress): وظیفه مدیریت ظاهر، منوها، لندینگ پیج‌ها (طراحی شده مشابه DHL) و سئو.
• بک‌اند (Laravel 12): وظیفه مدیریت دیتابیس، پنل ادمین (Filament)، موتور فرمول‌نویسی قیمت، و ارائه API ها.
• پل ارتباطی (Custom WP Plugin): یک پلاگین اختصاصی برای وردپرس که درخواست‌های کاربران را به لاراول ارسال می‌کند.

---

✨ ویژگی‌های کلیدی (فاز ۱ - تکمیل شده)

۱. موتور قیمت‌گذاری هوشمند (Pricing Engine)

محاسبه دقیق هزینه ارسال بر اساس فرمول‌های استاندارد جهانی:

• محاسبه خودکار وزن حجمی (طول × عرض × ارتفاع / 5000).
• استخراج خودکار زون مقصد بر اساس جدول کشورها و نوع ارسال (صادرات/واردات).
• اعمال نرخ لحظه‌ای ارز (درهم/دلار/یوان/یورو) و ضریب سود شرکت.

۲. پنل مدیریت اختصاصی (Laravel Filament)

• مدیریت کامل ۲۳۳ کشور با زون‌های صادرات و واردات.
• ماژول ایمپورت اکسل: آپلود مستقیم فایل‌های اکسل تعرفه‌ها توسط ادمین (خواندن خودکار شیت‌های Import/Export).
• فرم تنظیمات سیستم: تغییر سریع ارزها و ضریب سود بدون دستکاری در کد.

۳. ارتباطات API و فرانت‌اند

• API استعلام قیمت: ایجاد POST /api/calculate-price برای دریافت اطلاعات وردپرس.
• پلاگین وردپرس (IFNEX Bridge): توسعه یک افزونه مستقل از قالب وردپرس.
• شورت‌کد استعلام قیمت: فرم مدرن با جاوااسکریپت برای دریافت و نمایش آنی شمارش (ریال/درهم) در سایت.

---

📁 ساختار پروژه (Project Structure)

IFNEX-Logistics/
├── 01_Documents/                  # مستندات و اسناد فنی پروژه
│   ├── PRD_v2.md                  # سند نیازمندی‌ها (توضیح دیتابیس، منطق فرمول‌ها و فازبندی‌ها)
│   └── Project_Roadmap.md         # نقشه راه و چک‌لیست کارهای انجام شده و در دست اقدام
│
├── 02_Design/                     # فایل‌های مربوط به رابط کاربری (UI/UX و فیگما)
│   └── Assets/                    # لوگوها، آیکون‌ها و...
│
├── 03_WordPress/                  # سیستم مدیریت محتوای سایت (فرانت‌اند)
│   └── wp-content/
│       └── plugins/
│           └── ifnex-bridge/      # پلاگین اختصاصی ما برای ارتباط با لاراول
│
└── 04_Laravel/                    # هسته مرکزی سیستم (بک‌اند)
    ├── app/
    │   ├── Models/                # مدل‌های دیتابیس (Country, ShippingRate, Shipment, SystemSetting)
    │   ├── Services/              # کلاس‌های منطقی تجاری (مثل PriceCalculatorService)
    │   ├── Http/Controllers/Api/  # کنترلرهای API
    │   ├── Imports/               # کلاس‌های خواندن فایل‌های اکسل (ShippingRatesImport)
    │   └── Filament/              # پنل مدیریت ادمین (Resources و Pages)
    ├── database/
    │   ├── migrations/            # فایل‌های ساخت جداول دیتابیس
    │   └── seeders/               # داده‌های اولیه (کشورها)
    ├── config/                    # تنظیمات سیستم (فایل‌های .php)
    └── resources/                 # فایل‌های ویو (Blade) برای پنل و ایمپورتورها

---

🚀 راه‌اندازی و اجرای پروژه (Localhost)
پیش‌نیازها
XAMPP (شامل PHP 8.2+ و MySQL)
Composer
Node.js و NPM (برای ابزارهای پیش‌فرض وردپرس/المنتور)
مراحل نصب
مخزن کد را کلون کنید و وارد پوشه 04_Laravel شوید.
دستور composer install را برای نصب پکیج‌های لاراول اجرا کنید.
فایل .env.example را به .env کپی کرده و اطلاعات دیتابیس XAMPP را وارد کنید.
دستور php artisan key:generate را برای ایجاد کلید اپلیکیشن اجرا کنید.
دستور php artisan migrate را برای ساخت جداول اجرا کنید.
دستور php artisan db:seed را برای درج داده‌های اولیه (کشورها و تنظیمات ارز) بزنید.
برای پنل ادمین دستور php artisan serve و برای وردپرس از لوکال هاست وردپرس استفاده کنید.
⚠️ نکات امنیتی و تولید (Production)
هرگز فایل .env را در مخزن کد (Git) کامیت نکنید.
در محیط سرور واقعی، حتماً APP_DEBUG=false را در .env تنظیم کنید.
برای محیط سرور واقعی، نیاز به پیکربندی وب‌سرور (Nginx/Apache) و تنظیمات CORS برای ارتباط WP و Laravel دارید.
📜 مستندات بیشتر
برای مطالعه دقیق منطق‌های سیستم، حتماً فایل‌های داخل پوشه 01_Documents را مطالعه کنید:

PRD_v2.md: شامل معماری دقیق دیتابیس (Schema) استخراج شده از فایل اکسل عملیاتی شرکت.
Project_Roadmap.md: شامل لیست کارهای انجام شده و کارهای در دست اقدام (Checklist) بر اساس فازبندی پروژه.
© 2024 Vernasoft Group (Kazem Alghasi). All rights reserved.