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

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

---

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

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

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

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

---

## 🏗️ معماری سیستم

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

┌─────────────────┐ REST API ┌─────────────────┐
│ WordPress │ ←─────────────────────→ │ Laravel 11 │
│ (Frontend) │ پلاگین IFNEX Bridge │ (Backend) │
│ │ │ + Filament │
└─────────────────┘ └────────┬────────┘
│
┌────────┴────────┐
│ MySQL 8 │
└─────────────────┘
│
(فاز ۳) │
┌────────┴────────┐
│ VPS پل خارج │
│ (هلند/آلمان) │
└────────┬────────┘
│
┌────────┴────────┐
│ TrackingMore / │
│ 17track API │
└─────────────────┘


| لایه | تکنولوژی | نقش |
| :--- | :--- | :--- |
| **فرانت‌اند** | WordPress + Elementor | مدیریت ظاهر، منوها، لندینگ پیج‌ها، صفحات ثابت، وبلاگ سئو |
| **بک‌اند** | Laravel 11 + Filament 3.3 | API سرور، پنل ادمین، موتور قیمت‌گذاری، صدور PDF، کیف پول |
| **پل ارتباطی** | پلاگین اختصاصی IFNEX Bridge | ارسال درخواست‌های کاربر از وردپرس به لاراول |
| **دیتابیس** | MySQL 8 | ذخیره‌سازی داده‌ها با پشتیبانی از JSON columns |
| **زیرساخت رهگیری** | 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 و هزینه‌های اضافی
   - **تست‌های کامل:** Feature tests و Service tests با پوشش ۱۰۰٪

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

### فاز ۲ (در حال اجرا) 🚧

1. **سیستم کیف پول (Wallet)**
   - API شارژ اعتبار
   - API بررسی موجودی
   - API تاریخچه تراکنش‌ها
   - **وضعیت:** Controllers و APIها ساخته شده، نیاز به اتصال درگاه پرداخت

2. **سیستم تخفیف (Discount Codes)**
   - API لیست کدهای تخفیف فعال
   - API اعتبارسنجی کد تخفیف
   - پشتیبانی از تخفیف درصدی و ثابت
   - **وضعیت:** کامل شده

3. **به‌روزرسانی خودکار نرخ ارز**
   - Artisan Command برای به‌روزرسانی روزانه
   - پشتیبانی از ECB و FreeCurrencyAPI
   - **وضعیت:** کامل شده

4. **کارهای باقی‌مانده فاز ۲**
   - [ ] اتصال درگاه پرداخت (زرین‌پال)
   - [ ] شارژ آنلاین کامل با درگاه پرداخت
   - [ ] پنل مالی در Filament (داشبورد سود/زیان)
   - [ ] فرمول محاسبه قیمت رقبا

### فاز ۳ (در صف) ⏳

- [ ] راه‌اندازی VPS پل خارج (هلند/آلمان)
- [ ] اتصال به TrackingMore/17track API
- [ ] سیستم وب‌هوک
- [ ] مپ کردن کدهای رهگیری
- [ ] داشبورد مالی
- [ ] فرم نظرسنجی و رضایت مشتری
- [ ] پنل کاربری مشتریان در وردپرس

---

## 📁 ساختار پروژه

```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/                    # هسته مرکزی سیستم (بک‌اند)
│   └── README.md                  # راهنمای نصب و استفاده از لاراول
│
└── README.md                      # این فایل — نمای کلی پروژه

💡 برای جزئیات فنی، نصب و راه‌اندازی، فایل 04_Laravel/README.md را مطالعه کنید.

📚 مستندات بیشتر
برای مطالعه دقیق منطق‌های سیستم، حتماً فایل‌های داخل پوشه 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 است و کپی یا استفاده‌ی غیرمجاز از آن ممنوع است.