🚀 IFNEX Logistics Management System

جایگزینی فرآیندهای دستی مبتنی بر اکسل با یک معماری Headless مدرن

مورد	توضیحات
ویرایش سند	v4.2 (Laravel 11 + Filament 3.3 + فاز ۰ کامل + فاز ۱ کامل + فاز ۲ کامل + فاز ۳ کامل)
تاریخ آخرین به‌روزرسانی	2026-08-10
توسعه‌دهنده	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 7.0.3 + پوسته سفارشی IFNEX + Polylang	مدیریت ظاهر، چندزبانه، پورتال مشتری، لندینگ پیج‌ها
بک‌اند	Laravel 11 + Filament 3.3	API سرور، پنل ادمین، موتور قیمت‌گذاری، صدور PDF، کیف پول، پرداخت آنلاین
پل ارتباطی	پلاگین اختصاصی IFNEX Bridge	ارسال درخواست‌های کاربر از وردپرس به لاراول، مدیریت توکن Sanctum
دیتابیس	MySQL 8	ذخیره‌سازی داده‌ها با پشتیبانی از JSON columns
زیرساخت رهگیری	VPS خارج از کشور (در فاز ۴)	واسط برای دسترسی به APIهای رهگیری بین‌المللی

---

🗺️ نقشه راه ۴ فازی

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

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

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

---

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

فاز ۰ (تکمیل شده) ✅

1. اسکیمای دیتابیس اصلاح‌شده (بر اساس فایل اکسل عملیاتی)

   • جدول countries با ۴ زون مجزا (صادرات/واردات × پارسل/داکیومنت)
   • پشتیبانی از ۳ نوع سرویس: DOC_NORMAL, DOC_ECONOMY, PARCEL
   • جدول shipment_carrier_mappings برای نگاشت چند شرکت حمل به هر بارنامه
   • جدول shipment_tracking_events برای ذخیره تایم‌لاین کامل رویدادهای هر مرسوله
   • جدول system_settings برای ذخیره تنظیمات سیستم (VAT، نرخ ارز، ضریب سود)
   • جدول shipment_items برای اقلام گمرکی (۹ ردیف)

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

   • مدیریت ۲۳۳ کشور با زون‌های صادرات و واردات
   • فرم تنظیمات سیستم: تغییر سریع ارزها و ضریب سود بدون دستکاری کد
   • UX تخصصی اپراتور ترکینگ: افزودن رویداد در چند ثانیه با فیلدهای از پیش پر شده
   • تب‌بندی ویجت‌های داشبورد: اطلاعات کلی، نرخ ارز، آمار کیف پول
   • رابط کاربری سفارشی: رنگ Navy gradient، فونت Vazirmatn، RTL کامل

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

   • API ترکینگ: GET /api/track/{awb_no} با API Key + Rate Limiting + CORS
   • API استعلام قیمت: POST /api/v1/calculate
   • API احراز هویت: POST /api/v1/auth/login + POST /api/v1/auth/logout (Sanctum)
   • API سفارشات مشتری: ۶ endpoint برای پروفایل، سفارشات، پرداخت و لغو
   • API کیف پول: موجودی، تراکنش‌ها، تنظیمات ادمین
   • API تخفیف: لیست و اعتبارسنجی کدهای تخفیف
   • پلاگین IFNEX Bridge: شورت‌کدهای [ifnex_tracking_form]، [ifnex_tracking_status]، [ifnex_wallet_balance]، [ifnex_transactions]
   • امنیت: API Key + Rate Limiting + CORS whitelist + Form Request Validation + Sanctum

4. مهاجرت داده‌های تاریخی

   • انتقال ۳۹۵۰ رکورد تاریخی از فایل اکسل به دیتابیس جدید
   • اعتبارسنجی و پاکسازی خودکار داده‌ها
   • import ۴۰۴ رکورد تعرفه‌های حمل
   • import ۹۸ رویداد ترکینگ دستی

فاز ۱ (تکمیل شده) ✅

1. موتور قیمت‌گذاری کامل (PriceCalculatorService)

   • محاسبه خودکار قیمت بر اساس وزن، زون، نوع سرویس و جهت ارسال
   • پشتیبانی از ۴ زون مجزا (export/import × doc/parcel)
   • اعمال ضریب سود، VAT و هزینه‌های اضافی
   • تست‌های کامل: Feature tests و Service tests با پوشش ۱۰۰٪

2. فرم ثبت سفارش آنلاین

   • فرم عمومی برای مشتریان با ۹ ردیف کالای گمرکی
   • اعتبارسنجی خودکار و محاسبه لحظه‌ای قیمت
   • تولید AWB number خودکار با فرمت IFN-YYYY-XXXXX

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 تاریخچه تراکنش‌ها
   • اتصال درگاه پرداخت زرین‌پال با Mock Gateway برای تست
   • پرداخت آنلاین کامل با بازگشت به فرانت‌اند

2. سیستم تخفیف (Discount Codes)

   • API لیست کدهای تخفیف فعال
   • API اعتبارسنجی کد تخفیف
   • پشتیبانی از تخفیف درصدی و ثابت
   • DiscountCodeResource در Filament با form/table/filters کامل

3. به‌روزرسانی خودکار نرخ ارز

   • Artisan Command برای به‌روزرسانی روزانه
   • پشتیبانی از ECB و FreeCurrencyAPI
   • ردیابی تاریخچه نرخ ارز با ExchangeRateHistory و ExchangeRateHistoryResource

4. پنل مالی در Filament

   • FinanceOverviewWidget — خلاصه مالی
   • TransactionChartWidget — نمودار تراکنش‌ها
   • RecentTransactionsWidget — آخرین تراکنش‌ها
   • PaymentResource — مشاهده تراکنش‌های درگاه
   • WalletTransactionResource — CRUD کامل تراکنش‌های کیف پول
   • خروجی CSV برای تراکنش‌ها و مرسولات

5. کنترل دسترسی مبتنی بر نقش (RBAC)

   • یکپارچگی با spatie/laravel-permission
   • RoleResource و UserResource در Filament
   • RoleAndPermissionSeeder برای تنظیم اولیه

6. یکپارچگی وردپرس ↔ لاراول

   • دستور Artisan ifnex:sync-wp-users برای سینک کاربران
   • پلاگین IFNEX Bridge گسترش یافته:
     • شورت‌کد [ifnex_wallet_balance] برای موجودی کیف پول
     • شورت‌کد [ifnex_transactions] برای لیست تراکنش‌ها
     • AJAX handlers برای موجودی و تراکنش‌ها

فاز ۳ (تکمیل شده) ✅

1. سیستم ثبت سفارش مشتری (Customer Ordering)

   • CustomerOrderController با ۶ endpoint:
     • GET /api/v1/customer/profile — پروفایل و آمار کاربر
     • GET /api/v1/customer/countries — لیست کشورها
     • GET /api/v1/customer/orders — لیست سفارشات
     • POST /api/v1/customer/orders — ثبت سفارش جدید
     • GET /api/v1/customer/orders/{shipment} — جزئیات سفارش
     • POST /api/v1/customer/orders/{shipment}/cancel — لغو سفارش
   • تولید خودکار شماره AWB با فرمت IFN-YYYY-XXXXX
   • وضعیت‌های جدید: pending_payment و cancelled
   • اعتبارسنجی کامل و محاسبه لحظه‌ای قیمت

2. سیستم پرداخت سفارش (Order Payment)

   • OrderPaymentService برای مدیریت پرداخت‌ها
   • پرداخت از کیف پول: POST /api/v1/customer/orders/{shipment}/pay-wallet
   • پرداخت از درگاه: POST /api/v1/customer/orders/{shipment}/pay-gateway
   • تکمیل خودکار پرداخت بعد از callback درگاه
   • ثبت رویداد ترکینگ پس از پرداخت موفق

3. احراز هویت مشتری (Customer Auth)

   • AuthController با login/logout برای Sanctum
   • BridgeAuthController برای لاگین مستقیم از وردپرس
   • توکن‌های Sanctum با انقضا ۳۰ روزه

4. پورتال مشتری در وردپرس

   • شورت‌کد [ifnex_order_form] — فرم ثبت سفارش چندمرحله‌ای (۴ مرحله)
   • شورت‌کد [ifnex_orders_list] — لیست سفارشات با فیلتر وضعیت
   • شورت‌کد [ifnex_order_payment] — صفحه پرداخت سفارش (کیف پول + درگاه)
   • شورت‌کد [ifnex_order_detail] — جزئیات سفارش با timeline رهگیری
   • شورت‌کد [ifnex_user_profile] — پروفایل کاربر با آمار کیف پول
   • استایل‌های CSS کامل برای تمام کامپوننت‌ها (ifnex-orders.css)
   • JavaScript برای ناوبری مراحل و AJAX (ifnex-order-form.js)

5. پوسته وردپرس سفارشی IFNEX

   • پشتیبانی چندزبانه با Polylang
   • مدیریت LTR/RTL خودکار
   • Customizer برای لوگو و زبان
   • قالب‌های archive, single, front-page
   • ساختار تمیک شرکتی با لوگو IFNEX

6. سیستم طراحی یکپارچه (Design System)

   • DESIGN_SYSTEM.md — مرجع کامل رنگ‌ها، فونت‌ها، فاصله‌گذاری
   • رنگ‌های برند: Primary Amber #f59e0b، Sidebar Dark Navy #1a1a2e → #16213e
   • فونت Vazirmatn برای کل پنل ادمین و فرانت‌اند
   • استایل‌های یکپارچه برای Filament و پلاگین وردپرس

7. گزارش‌گیری مالی در Filament

   • صفحه FinancialReport با خلاصه تراکنش‌ها و مرسولات
   • خروجی Excel برای ShipmentResource و WalletTransactionResource
   • ویجت‌هایdashboard اطلاعاتی

---

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

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/
│   │   ├── themes/ifnex/          # پوسته سفامشی IFNEX (چندزبانه، RTL/LTR)
│   │   └── plugins/
│   │       └── ifnex-bridge/      # پلاگین اختصاصی ارتباط با لاراول
│   │           ├── ifnex-bridge.php
│   │           ├── includes/
│   │           │   ├── api-client.php
│   │           │   ├── shortcodes.php
│   │           │   ├── tracking-form.php
│   │           │   └── user-bridge.php
│   │           └── assets/
│   │               ├── css/
│   │               │   ├── ifnex-bridge.css
│   │               │   └── ifnex-orders.css
│   │               └── js/
│   │                   └── ifnex-order-form.js
│
├── 04_Laravel/                    # هسته مرکزی سیستم (بک‌اند)
│   ├── README.md                  # راهنمای نصب و استفاده از لاراول
│   ├── app/
│   │   ├── Models/
│   │   │   ├── Country.php
│   │   │   ├── Shipment.php
│   │   │   ├── ShipmentItem.php
│   │   │   ├── ShippingRate.php
│   │   │   ├── ShipmentCarrierMapping.php
│   │   │   ├── ShipmentTrackingEvent.php
│   │   │   ├── SystemSetting.php
│   │   │   ├── Wallet.php
│   │   │   ├── WalletTransaction.php
│   │   │   ├── DiscountCode.php
│   │   │   ├── ExchangeRateHistory.php
│   │   │   ├── Role.php                          # spatie/laravel-permission
│   │   │   └── User.php
│   │   ├── Enums/
│   │   │   ├── ShipmentDirection.php
│   │   │   ├── ShipmentType.php
│   │   │   ├── ShipmentStatus.php                 # ۹ وضعیت (pending_payment, cancelled اضافه شد)
│   │   │   ├── CarrierCode.php
│   │   │   ├── TrackingSource.php                 # ۵ منبع (manual, api, import, system, customer)
│   │   │   ├── TransactionType.php
│   │   │   ├── TransactionStatus.php
│   │   │   ├── PaymentGateway.php                  # ۴ درگاه (zarinpal, wallet, manual, system)
│   │   │   └── UserRole.php
│   │   ├── Services/
│   │   │   ├── PriceCalculatorService.php
│   │   │   ├── TrackingService.php
│   │   │   ├── ExchangeRateService.php            # ردیابی و مدیریت نرخ ارز
│   │   │   ├── ZarinpalService.php                # اتصال به درگاه زرین‌پال
│   │   │   ├── MockZarinpalService.php            # شبیه‌سازی درگاه برای تست
│   │   │   └── OrderPaymentService.php            # پرداخت سفارشات (کیف پول + درگاه)
│   │   ├── Http/
│   │   │   ├── Controllers/
│   │   │   │   ├── Api/
│   │   │   │   │   ├── TrackController.php
│   │   │   │   │   ├── PricingController.php
│   │   │   │   │   ├── AuthController.php         # ورود/خروج Sanctum
│   │   │   │   │   ├── BridgeAuthController.php   # لاگین از پلاگین وردپرس
│   │   │   │   │   ├── WalletController.php
│   │   │   │   │   ├── PaymentController.php
│   │   │   │   │   ├── DiscountCodeController.php
│   │   │   │   │   └── Customer/
│   │   │   │   │       └── CustomerOrderController.php  # ۶ endpoint سفارش مشتری
│   │   │   │   ├── OrderController.php
│   │   │   │   ├── PricingPageController.php
│   │   │   │   └── ShipmentPdfController.php
│   │   │   ├── Middleware/
│   │   │   │   └── ApiKeyMiddleware.php
│   │   │   └── Requests/
│   │   ├── Imports/
│   │   │   ├── ShippingRatesImport.php
│   │   │   ├── HistoricalShipmentsImport.php
│   │   │   └── RateSheetImport.php
│   │   ├── Console/
│   │   │   └── Commands/
│   │   │   │   ├── ImportShippingRates.php
│   │   │   │   │   ├── ImportHistoricalData.php
│   │   │   │   │   ├── UpdateExchangeRates.php
│   │   │   │   │   ├── SyncWordPressUsers.php     # سینک کاربران وردپرس
│   │   │   │   │   └── DebugImportCommand.php
│   │   ├── Filament/
│   │   │   ├── Resources/
│   │   │   │   ├── CountryResource.php
│   │   │   │   ├── ShipmentResource.php
│   │   │   │   ├── ShippingRateResource.php
│   │   │   │   ├── ShipmentItemResource.php
│   │   │   │   ├── WalletResource.php
│   │   │   │   ├── WalletTransactionResource.php  # CRUD کامل با صفحات Create/Edit
│   │   │   │   ├── PaymentResource.php            # مشاهده تراکنش‌های درگاه
│   │   │   │   ├── DiscountCodeResource.php       # مدیریت کدهای تخفیف
│   │   │   │   ├── ExchangeRateHistoryResource.php # تاریخچه نرخ ارز
│   │   │   │   ├── RoleResource.php               # مدیریت نقش‌ها (spatie)
│   │   │   │   └── UserResource.php               # مدیریت کاربران (spatie)
│   │   │   ├── Widgets/
│   │   │   │   ├── DashboardInfoWidget.php        # اطلاعات کلی داشبورد
│   │   │   │   ├── ExchangeRateWidget.php         # نرخ ارز زنده
│   │   │   │   ├── WalletStats.php                # آمار کیف پول
│   │   │   │   ├── TransactionChartWidget.php     # نمودار تراکنش‌ها
│   │   │   │   └── RecentTransactionsWidget.php
│   │   │   └── Pages/
│   │   │   │   ├── IfnexSettingsPage.php
│   │   │   │   ├── PriceTestPage.php
│   │   │   │   └── Reports/
│   │   │   │       └── FinancialReport.php        # گزارش مالی
│   │   └── Providers/
│   │       ├── AppServiceProvider.php
│   │       └── Filament/
│   │           └── AdminPanelProvider.php         # پیکربندی کامل (رنگ، فونت، نوتیفیکیشن)
│
└── 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 است و کپی یا استفاده‌ی غیرمجاز از آن ممنوع است.