# 🚀 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 اطلاعاتی

---

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

```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/
│   │   ├── 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 است و کپی یا استفاده‌ی غیرمجاز از آن ممنوع است.