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

| مورد | توضیحات |
| :--- | :--- |
| **ویرایش سند** | v4.0 (Laravel 11 + Filament 3.3 + فاز ۰ کامل + فاز ۱ در حال اجرا) |
| **توسعه‌دهنده** | VernaSoft Group — Kazem Alghasi |
| **مشتری** | شرکت حمل و نقل بین‌المللی ایف‌نکس (IFNEX) — اصفهان |

---

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

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

---

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

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

---

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

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

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

---

## ✨ ویژگی‌های کلیدی

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

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

3. ارتباطات API و فرانت‌اند
   - **API ترکینگ:** `GET /api/track/{awb_no}` با API Key + Rate Limiting + CORS
   - **پلاگین IFNEX Bridge:** شورت‌کد `[ifnex_tracking_form]` برای فرم رهگیری در وردپرس
   - **امنیت:** API Key + Rate Limiting + CORS whitelist + Form Request Validation

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

### فاز ۱ (در حال اجرا)
1. موتور قیمت‌گذاری کامل (`PriceCalculatorService`)
   - محاسبه خودکار قیمت بر اساس وزن، زون، نوع سرویس و جهت ارسال
   - پشتیبانی از ۴ زون مجزا (export/import × doc/parcel)
   - اعمال ضریب سود، VAT و هزینه‌های اضافی

2. فرم ثبت سفارش آنلاین
   - فرم عمومی برای مشتریان با ۹ ردیف کالای گمرکی
   - اعتبارسنجی خودکار و محاسبه لحظه‌ای قیمت
   - تولید AWB number خودکار

3. تولید PDFهای حرفه‌ای
   - **AWB:** بارنامه هوایی با لوگوی IFNEX
   - **INVOICE:** فاکتور تجاری با جدول ۹ ردیف کالای گمرکی
   - **LABEL:** لیبل چاپی برای بسته‌ها (پرینتر لیزری + کاغذ چسبان A4)
   - تطبیق اولیه با قالب‌های اکسل + لوگوی استخراج‌شده

4. صفحه استعلام قیمت واقعی
   - رابط کاربری عمومی برای محاسبه قیمت تقریبی حمل
   - نمایش قیمت پایه (درهم) و قیمت نهایی (ریال)

5. ماژول ایمپورت اکسل تعرفه‌ها
   - کامند `php artisan ifnex:import:rates` با قابلیت‌های `--clear` و `--dry-run`
   - پشتیبانی از شیت‌های Export Rate، Import Rate و DocEco
   - تبدیل خودکار واحد قیمت (ریال → درهم) برای شیت‌های DocNor/DocEco

---

## 📁 ساختار پروژه
```text
IFNEX-Logistics/
├── 01_Documents/                  # مستندات فنی پروژه
│   ├── STATUS.md                  # ⭐ وضعیت فعلی و گزارش پیشرفت
│   ├── IFNEX_Phase0_Checklist.md  # ⭐ چک‌لیست دقیق فاز ۰
│   ├── Phase0_Proposal.md         # ⭐ سند پیشنهاد فاز ۰ (نقشه راه جدید)
│   ├── EXCEL_ANALYSIS.md          # ⭐ تحلیل فایل‌های اکسل
│   ├── PRD_v2.md                  # سند نیازمندی‌ها (نسخه قدیمی — به‌زودی بازنویسی)
│   └── Project_Roadmap.md         # نقشه راه و چک‌لیست (به‌زودی به‌روزرسانی)
│
├── 02_Design/                     # فایل‌های UI/UX و فیگما
│   └── Assets/                    # لوگوها، آیکون‌ها
│
├── 03_WordPress/                  # سیستم مدیریت محتوا (فرانت‌اند)
│   └── wp-content/plugins/
│       └── ifnex-bridge/          # پلاگین اختصاصی ارتباط با لاراول
│
└── 04_Laravel/                    # هسته مرکزی سیستم (بک‌اند)
    ├── app/
    │   ├── Models/                # Country, Shipment, ShipmentItem, ShipmentRate, ...
    │   ├── Enums/                 # ShipmentDirection, ShipmentType, ShipmentStatus, ...
    │   ├── Services/              # PriceCalculatorService, PdfService, ...
    │   ├── Http/
    │   │   ├── Controllers/
    │   │   │   ├── Api/           # PricingController, TrackController
    │   │   │   ├── OrderController.php       # فرم ثبت سفارش آنلاین
    │   │   │   ├── PricingPageController.php # صفحه استعلام قیمت
    │   │   │   └── ShipmentPdfController.php # تولید PDF
    │   │   ├── Middleware/        # ApiKeyMiddleware
    │   │   └── Requests/          # Form Request Validation classes
    │   ├── Imports/               # ShippingRatesImport
    │   ├── Console/Commands/      # ImportShippingRates
    │   └── Filament/              # پنل مدیریت ادمین
    │       ├── Resources/         # Country, Shipment, ShippingRate, ShipmentItem
    │       └── Pages/             # Settings, Dashboard, Custom pages
    ├── database/
    │   ├── migrations/            # ۷ migration فاز ۰
    │   └── seeders/               # CountriesSeeder, SystemSettingSeeder
    ├── routes/
    │   ├── web.php                # روت‌های عمومی: /order, /pricing, PDF download
    │   └── api.php                # API: /api/v1/calculate, /api/v1/track/{awb}
    ├── resources/views/
    │   ├── layouts/app.blade.php  # لایاوت عمومی صفحات
    │   ├── orders/                # فرم ثبت سفارش + صفحه موفقیت
    │   ├── pricing/               # صفحه استعلام قیمت
    │   └── pdfs/                   # قالب‌های PDF: AWB, INVOICE, LABEL
    ├── config/
    │   ├── ifnex.php
    │   └── cors.php
    └── bootstrap/
        └── app.php


🚀 راه‌اندازی و اجرا (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 --force

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

# ۷. اجرای سرور توسعه
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 را مطالعه کنید:

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

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

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