ifnex/README.md

# 🚀 IFNEX Logistics Management System
> جایگزینی فرآیندهای دستی مبتنی بر اکسل با یک معماری Headless مدرن

| مورد | توضیحات |
| :--- | :--- |
| **ویرایش سند** | v2.0 (نقشه راه ۴ فازی) |
| **توسعه‌دهنده** | VernaSoft Group — Kazem Alghasi |
| **مشتری** | شرکت حمل و نقل بین‌المللی ایف‌نکس (IFNEX) — اصفهان |

---

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

### چرا این پروژه متفاوت است؟
به‌جای آنکه اپراتورها وزن حجمی را محاسبه کنند، زون‌ها را در ۴ شیت مختلف جستجو کنند و با ماشین‌حساب قیمت نهایی را حساب کنند، اکنون تمام این فرآیند در کسر از ثانیه و بدون هیچ خطای انسانی انجام می‌شود. همچنین، به دلیل تحریم‌های بین‌المللی و مسدود بودن دسترسی مستقیم به API شرکت‌های DHL/FedEx/UPS از ایران، این سیستم از طریق یک سرور VPS پل (در فاز ۳) مشکل ترکینگ خودکار را حل می‌کند.

---

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

| لایه | تکنولوژی | نقش |
| :--- | :--- | :--- |
| **فرانت‌اند** | WordPress | مدیریت ظاهر، منوها، لندینگ پیج‌ها، صفحات ثابت، وبلاگ سئو |
| **بک‌اند** | Laravel 11 | API سرور، پنل ادمین (Filament)، موتور قیمت‌گذاری، صدور PDF، کیف پول |
| **پل ارتباطی** | پلاگین اختصاصی IFNEX Bridge | ارسال درخواست‌های کاربر از وردپرس به لاراول |
| **زیرساخت رهگیری** | VPS خارج از کشور (در فاز ۳) | واسط برای دسترسی به APIهای رهگیری بین‌المللی |

---

## 🗺️ نقشه راه ۴ فازی
این پروژه به چهار فاز تقسیم شده تا هم تحویل تدریجی ارزش به مشتری حفظ شود و هم ریسک دوباره‌کاری حذف گردد.

| فاز | هدف اصلی | مدت زمان | وضعیت |
| :--- | :--- | :--- | :--- |
| **فاز ۰** | بنیان داده + وب‌سایت + ترکینگ دستی + مهاجرت داده‌های تاریخی | ۴ هفته | 🚧 در دست اقدام |
| **فاز ۱** | موتور قیمت‌گذاری کامل + ثبت سفارش آنلاین + تولید PDFها | ۴-۶ هفته | ⏳ در صف |
| **فاز ۲** | حساب کاربری مشتری + کیف پول + حسابداری ساده + تخفیف حجمی | ۴ هفته | ⏳ در صف |
| **فاز ۳** | VPS پل + API ترکینگ زنده + CRM + داشبورد مالی تحلیلی | ۶-۸ هفته | ⏳ در صف |

> 💡 جزئیات کامل هر فاز، اسکیمای دیتابیس، جدول زمانی و معیارهای پذیرش در سند `01_Documents/Phase0_Proposal.md` آمده است.

---

## ✨ ویژگی‌های کلیدی فاز ۰ (مورد اجرا)

### ۱. اسکیمای دیتابیس اصلاح‌شده (بر اساس فایل اکسل عملیاتی)
- جدول `countries` با ۴ زون مجزا (صادرات/واردات × پارسل/داکیومنت) — به‌جای ۲ زون قبلی
- پشتیبانی از ۳ نوع سرویس: `DOC_NORMAL`, `DOC_ECONOMY`, `PARCEL`
- جدول `shipment_carrier_mappings` برای نگاشت چند شرکت حمل به هر بارنامه
- جدول `shipment_tracking_events` برای ذخیره تایم‌لاین کامل رویدادهای هر مرسوله

### ۲. پنل مدیریت اختصاصی (Laravel Filament)
- مدیریت ۲۳۳ کشور با زون‌های صادرات و واردات
- ماژول ایمپورت اکسل تعرفه‌ها (در فاز ۱)
- فرم تنظیمات سیستم: تغییر سریع ارزها و ضریب سود بدون دستکاری کد
- UX تخصصی اپراتور ترکینگ: افزودن رویداد در چند ثانیه با فیلدهای از پیش پر شده

### ۳. ارتباطات API و فرانت‌اند
- **API استعلام قیمت (در فاز ۱):** `POST /api/calculate-price`
- **API ترکینگ (در فاز ۰):** `GET /api/track/{awb_no}`
- **پلاگین IFNEX Bridge:** شورت‌کد `[ifnex_tracking_form]` برای فرم رهگیری در وردپرس
- **امنیت:** API Key + Rate Limiting + CORS whitelist + Form Request Validation

### ۴. مهاجرت داده‌های تاریخی
- انتقال ۳۹۵۰ رکورد تاریخی از فایل اکسل به دیتابیس جدید
- اعتبارسنجی و پاکسازی خودکار داده‌ها
- در دسترس قرار دادن تاریخچه‌ی کامل برای مشتریان قدیمی

---

## 📁 ساختار پروژه
```text
IFNEX-Logistics/
├── 01_Documents/                  # مستندات فنی پروژه
│   ├── PRD_v2.md                  # سند نیازمندی‌ها (نسخه قدیمی — به‌زودی بازنویسی)
│   ├── Phase0_Proposal.md         # ⭐ سند پیشنهاد فاز ۰ (نقشه راه جدید)
│   └── Project_Roadmap.md         # نقشه راه و چک‌لیست (به‌زودی به‌روزرسانی)
│
├── 02_Design/                     # فایل‌های UI/UX و فیگما
│   └── Assets/                    # لوگوها، آیکون‌ها
│
├── 03_WordPress/                  # سیستم مدیریت محتوا (فرانت‌اند)
│   └── wp-content/plugins/
│       └── ifnex-bridge/          # پلاگین اختصاصی ارتباط با لاراول
│
└── 04_Laravel/                    # هسته مرکزی سیستم (بک‌اند)
    ├── app/
    │   ├── Models/                # Country, Shipment, ShipmentTrackingEvent, ...
    │   ├── Services/              # PriceCalculatorService (فاز ۱), TrackingService
    │   ├── Http/Controllers/Api/  # TrackController, PricingController, ...
    │   ├── Imports/               # ShippingRatesImport, HistoricalShipmentsImport
    │   └── Filament/              # پنل مدیریت ادمین
    ├── database/
    │   ├── migrations/            # جداول دیتابیس
    │   └── seeders/               # داده‌های اولیه (۲۳۳ کشور)
    └── config/                    # تنظیمات سیستم


🚀 راه‌اندازی و اجرا (Localhost)
پیش‌نیازها
XAMPP یا مشابه (PHP 8.2+ و MySQL 8+)
Composer
Node.js و NPM (برای ابزارهای وردپرس/المنتور)
مراحل نصب (بخش لاراول)

# ۱. کلون مخزن و وارد شدن به پوشه لاراول
git clone https://www.git.vernahost.ir/gitmodir110/ifnex.git
cd ifnex/04_Laravel

# ۲. نصب پکیج‌ها
composer install

# ۳. کپی فایل محیط و تنظیم دیتابیس
cp .env.example .env
# فایل .env را ویرایش کرده و اطلاعات دیتابیس XAMPP را وارد کنید

# ۴. تولید کلید اپلیکیشن
php artisan key:generate

# ۵. اجرای Migration ها
php artisan migrate

# ۶. درج داده‌های اولیه (کشورها و نرخ ارز اولیه)
php artisan db:seed

# ۷. اجرای سرور توسعه
php artisan serve


مراحل نصب (بخش وردپرس)
۱. پوشه‌ی 03_WordPress را در htdocs یا مسیر هاست وردپرس قرار دهید.

۲. وردپرس را به‌صورت معمول نصب کنید.

۳. پلاگین ifnex-bridge را از مسیر wp-content/plugins/ifnex-bridge فعال کنید.

۴. در تنظیمات پلاگین، URL لاراول و API Key را وارد کنید.

۵. شورت‌کد [ifnex_tracking_form] را در صفحه‌ی «رهگیری مرسوله» قرار دهید.

⚠️ نکات امنیتی و تولید (Production)
هرگز فایل .env را در مخزن کد (Git) کامیت نکنید (در .gitignore تأیید شده).
در محیط تولید، APP_DEBUG=false را در .env تنظیم کنید.
برای محیط تولید، پیکربندی وب‌سرور (Nginx/Apache) و تنظیمات CORS برای ارتباط WP و Laravel ضروری است.
برای API ترکینگ خودکار (فاز ۳)، سرور VPS پل در خارج از کشور راه‌اندازی شود — راهنمای کامل در سند فاز ۳.
📚 مستندات بیشتر
برای مطالعه دقیق منطق‌های سیستم، حتماً فایل‌های داخل پوشه 01_Documents را مطالعه کنید:

فایل	محتوا
Phase0_Proposal.md	⭐ سند پیشنهاد فاز ۰ — شامل اسکیمای دیتابیس، جدول زمانی، ریسک‌ها، معیارهای پذیرش
PRD_v2.md	سند نیازمندی‌ها (نسخه قدیمی — برخی بخش‌های آن در سند فاز ۰ بازنویسی شده)
Project_Roadmap.md	چک‌لیست کارهای انجام‌شده و در دست اقدام (به‌زودی به‌روزرسانی می‌شود)
🔐 امنیت و گزارش مشکلات
اگر آسیب‌پذیری امنیتی کشف کردید، لطفاً مستقیماً به kazem@vernasoft.group (یا ایمیل جایگزین تعیین‌شده) اطلاع دهید و آن را در Issue عمومی مخزن قرار ندهید.

📜 لایسنس
© 2026 VernaSoft Group (Kazem Alghasi). All rights reserved.

این پروژه اختصاصی شرکت IFNEX است و کپی یا استفاده‌ی غیرمجاز از آن ممنوع است.