ifnex/01_Documents/IFNEX_Roadmap.md

نقشه راه پروژه IFNEX

آخرین بروزرسانی: 2026-08-29
توسعه‌دهنده: VernaSoft Group — Kazem Alghasi
وضعیت کلی: فاز ۰، ۱، ۲، ۳ و ۳.۵ تکمیل شد ✅

---

خلاصه وضعیت

فاز	عنوان	وضعیت	درصد
فاز ۰	پایه و زیرساخت	✅ تکمیل شده	100%
فاز ۱	پنل مشتری وردپرس	✅ تکمیل شده	100%
فاز ۲	پرداخت و کیف پول	✅ تکمیل شده	100%
فاز ۳	یکپارچه‌سازی و بهبود	✅ تکمیل شده	100%
فاز ۳.۵	اصلاحات اساسی	✅ تکمیل شده (۹۰%)	90%
فاز ۴	سیستم نمایندگی	📋 مطالعاتی	0%
فاز ۵	تجاری‌سازی و Premium	📋 مطالعاتی	0%

نکته: فاز ۳.۵ شامل Multi-Package، فرم Invoice و تست ترکینگ است. تنها مورد باقیمانده (پشتیبانی چندزبانه i18n) به زمان دیپلوی منتقل شد.

---

فاز ۰ — پایه و زیرساخت ✅

هدف: ساخت زیرساخت API لاراول + پنل ادمین Filament + ترکینگ دستی

انجام شده:

• دیتابیس کامل با ۴ زون مجزا (Export/Import × Parcel/Doc) + ۳ نوع سرویس
• ۱۷ مدل Eloquent با Enum casts و روابط کامل
• Seeders کشورها (۲۳۳ کشور) و تنظیمات سیستم
• API ترکینگ (GET /api/v1/track/{awb}) با API Key + Rate Limiting
• API قیمت‌گذاری (POST /api/v1/calculate)
• پنل Filament: Country, Shipment, ShippingRate Resources
• RelationManagers: TrackingEvents, CarrierMappings, Items
• صفحات سفارشی: Settings, PriceTest, ImportRates
• مهاجرت ۳۹۵۰ رکورد تاریخی از اکسل
• ایمپورت/اکسپورت نرخ‌ها (Excel)

---

فاز ۱ — پنل مشتری وردپرس ✅

هدف: ثبت سفارش، لیست سفارشات، جزئیات و رهگیری در سایت وردپرس

انجام شده:

• Bridge Auth (وردپرس → لاراول بدون رمز عبور) با API Key مشترک
• شورت‌کدهای وردپرس: ۱۰+ شورت‌کد برای تمام صفحات
• دشبورد جامع مشتری شامل ۸ تب
• API مشتری: پروفایل، کشورها، سفارشات، لغو، نوتیفیکیشن
• قالب سفارشی IFNEX برای وردپرس

---

فاز ۲ — پرداخت و کیف پول ✅

هدف: سیستم پرداخت آنلاین و کیف پول دیجیتال

انجام شده:

• جدول کیف پول و تراکنش‌ها با audit log کامل
• API کیف پول (موجودی، تراکنش‌ها، فعالیت‌ها)
• پرداخت از کیف پول و درگاه بانکی (Zarinpal)
• Mock Gateway (شبیه‌سازی درگاه برای تست لوکال)
• سیستم ارز (Currency CRUD + بروزرسانی خودکار نرخ از API)
• Multi-package (بسته‌های چندگانه مرسوله — در پنل ادمین)
• تاریخچه تغییرات وضعیت (ShipmentStatusHistory)
• نوتیفیکیشن دیتابیس (ادمین و مشتری)
• تولید PDF حرفه‌ای (AWB, Invoice, Label) با بارکد
• کدهای تخفیف با اعتبارسنجی و محدودیت مصرف

---

فاز ۳ — یکپارچه‌سازی و بهبود ✅

هدف: اصلاحات کارفرما، بهبود UI/UX، استانداردسازی

انجام شده (۱۸ مورد کارفرما + تست لوکال):

اصلاحات کارفرما (۱۸ مورد):

1. ✅ رفع اکشن‌های PDF در ViewShipment
2. ✅ رفع ShippingRatesImport
3. ✅ رفع تصاویر PDF (asset بجای public_path)
4. ✅ ستون‌های جدید جدول Shipment
5. ✅ Packages Repeater در فرم
6. ✅ changeStatus به عنوان bulkAction
7. ✅ afterSave hook نوتیفیکیشن
8. ✅ Currency CRUD
9. ✅ فیلد source در TrackingEvents
10. ✅ ImportRatesPage (دکمه‌ها + دانلود template)
11. ✅ استایل تراکنش‌های وردپرس
12. ✅ هشدار آدرس انگلیسی
13. ✅ نوتیفیکیشن پنل کاربری وردپرس (با badge unread)
14. ✅ API نوتیفیکیشن (لیست + علامت‌گذاری خوانده‌شده)
15. ✅ متدهای ifnex-bridge برای نوتیفیکیشن
16. ✅ رفع مشکلات Filament Custom Page (wire:click بجای getFormActions)
17. ✅ رفع دانلود template (روت مستقیم بجای AJAX)
18. ✅ دیپلوی روی سرور تست (api.ifnex.vernahost.ir + ifnex.vernahost.ir)

اصلاحات تست لوکال (فاز ۳ نهایی):

• ✅ اضافه شدن متدهای isPaid() و canBeCancelledByCustomer() به Enum ShipmentStatus
• ✅ اضافه شدن ستون calling_code به جدول countries
• ✅ آپدیت ۱۹۲ کشور با پیش‌شماره استاندارد ISO 3166-1
• ✅ اضافه شدن IFNEX_BRIDGE_API_KEY به .env و کانفیگ
• ✅ اصلاح میدلور auth:sanctum برای بازگرداندن JSON 401 به جای redirect
• ✅ اضافه شدن شورت‌کد [ifnex_wallet_charge] برای شارژ کیف پول
• ✅ اضافه شدن AJAX handler ifnex_wallet_charge
• ✅ رفع مشکل use App\Models\WalletTransaction در CustomerOrderController
• ✅ هشدار هوشمند زبان فارسی/انگلیسی برای نام، شهر و آدرس
• ✅ پیش‌شماره تلفن خودکار بر اساس کشور انتخابی
• ✅ اعتبارسنجی تلفن (فقط اعداد، +، فاصله)
• ✅ اصلاح ارور "[object Object]" در پاسخ‌های AJAX
• ✅ اصلاح ifnex_enqueue_order_assets برای لود صحیح JS

بازطراحی PDFها (فاز ۳ نهایی):

• ✅ نصب picqer/php-barcode-generator
• ✅ بازطراحی AWB با بارکد، From/To کامل، Value، Service، Type
• ✅ بازطراحی Invoice با جدول ۹ ردیفه، اعلان قانونی، بارکد پایین
• ✅ بازطراحی Label با اندازه ۱۰۰×۱۵۰mm و بارکد بزرگ
• ✅ اضافه‌شدن شرط DOC/PARCEL برای Invoice (فقط PARCEL فاکتور داره)

مورد ۱۹ (نمایندگی) به فاز ۴ منتقل شد:

• طرح مطالعاتی آماده است
• منتظر تأیید و تسویه کارفرما برای فاز ۳

---

فاز ۳.۵ — اصلاحات اساسی ✅

هدف: رفع نواقص شناسایی‌شده پس از تست لوکال + افزودن قابلیت‌های ضروری

✅ این فاز قبل از ارائه نهایی به کارفرما تکمیل شد.

۳.۵.۱ — Multi-Package در فرم سفارش مشتری ✅

مشکل: بک‌اند و پنل ادمین از چند بسته پشتیبانی می‌کردند، ولی فرم سفارش مشتری فقط یه بسته می‌گرفت.

انجام شده:

• ✅ ساخت migration shipment_packages (جدول جدید)
• ✅ ساخت مدل ShipmentPackage با متد calculateVolumetricWeight()
• ✅ اضافه‌شدن رابطه packages() به مدل Shipment
• ✅ اصلاح API POST /customer/orders برای پذیرش packages[]
• ✅ محاسبه خودکار وزن حجمی از ابعاد (فرمول: L×W×H/5000)
• ✅ بازطراحی فرم سفارش با Repeater UI (افزودن/حذف بسته)
• ✅ اعتبارسنجی اجباری وزن واقعی و ابعاد
• ✅ خلاصه وزن‌ها (مجموع واقعی، حجمی، قابل محاسبه)
• ✅ نرمال‌سازی ابعاد به فرمت * (مثلاً 5*6*9)

۳.۵.۲ — فرم Invoice برای محموله‌های PARCEL ✅

مشکل: وقتی مشتری نوع PARCEL رو انتخاب می‌کرد، باید فرم اقلام گمرکی (Invoice) رو پر می‌کرد.

انجام شده:

• ✅ اضافه‌شدن مرحله جدید به فرم سفارش (مرحله ۳ - اقلام گمرکی)
• ✅ نمایش این مرحله فقط وقتی نوع = PARCEL
• ✅ فیلدهای هر آیتم: شرح کالا، HS Code، تعداد، قیمت واحد (USD)
• ✅ محاسبه خودکار مجموع هر قلم
• ✅ خلاصه فاکتور (تعداد اقلام + مجموع USD)
• ✅ حداکثر ۹ قلم
• ✅ اعتبارسنجی کامل (همه فیلدها اجباری)
• ✅ نمایش اقلام در خلاصه قیمت نهایی
• ✅ ساختار ۵ مرحله‌ای فرم (۱: مسیر، ۲: تماس، ۳: اقلام، ۴: تخفیف، ۵: تأیید)

۳.۵.۳ — پشتیبانی چندزبانه (i18n) 📋

وضعیت: به زمان دیپلوی منتقل شد

این مورد به زمان دیپلوی منتقل شد تا همراه با تنظیمات Polylang روی سرور انجام بشه. سند کامل استراتژی در IFNEX_I18N_Strategy.md موجود است.

۳.۵.۴ — بازطراحی PDFها ✅

• ✅ نصب picqer/php-barcode-generator
• ✅ بازطراحی AWB با بارکد، From/To کامل، Value، Service، Type
• ✅ بازطراحی Invoice با جدول ۹ ردیفه، اعلان قانونی، بارکد پایین
• ✅ بازطراحی Label با اندازه A5 افقی و بارکد بزرگ
• ✅ اضافه‌شدن شرط DOC/PARCEL برای Invoice (فقط PARCEL فاکتور داره)
• ✅ بارکد به‌صورت base64 embed (مطمئن‌ترین روش)

۳.۵.۵ — اصلاحات فنی ✅

• ✅ اضافه‌شدن Enum casts به مدل Shipment (status, direction, type)
• ✅ اصلاح متد deselectAfterCompletion → deselectRecordsAfterCompletion
• ✅ Migration برای ستون‌های row_number و unit_price در shipment_items
• ✅ Migration برای nullable کردن name
• ✅ اصلاح متدهای Enum (DocNormal/DocEconomy به‌جای DOC_NORMAL/DOC_ECONOMY)

۳.۵.۶ — تست ترکینگ ✅

• ✅ اصلاح API لاراول (TrackController) با status_label
• ✅ بازطراحی صفحه رهگیری وردپرس با timeline زیبا
• ✅ باکس وضعیت با badge رنگی بر اساس status
• ✅ grid اطلاعات کامل (۸ فیلد)
• ✅ timeline با تاریخ، توضیحات، لوکیشن و منبع
• ✅ بخش شرکت‌های حمل
• ✅ تست موفق با محموله چندمرحله‌ای

۳.۵.۷ — تست و نهایی‌سازی ✅

• ✅ تست تولید PDF با بارکد
• ✅ تست Multi-Package
• ✅ تست Invoice Form برای PARCEL
• ✅ تست ترکینگ چندمرحله‌ای
• ⏳ دیپلوی نهایی روی سرور (بعد از جلسه)

---

فاز ۴ (آینده) — سیستم نمایندگی 📋

وضعیت: طرح مطالعاتی آماده — منتظر تصمیم کارفرما

مدل‌های پیشنهادی:

مدل	توضیح	پیچیدگی
A) کد معرف ساده	هر کاربر یه کد معرف داره، درصدی از سود به معرف میرسه	کم
B) نمایندگی کامل	پنل جداگانه، گزارش فروش، کمیسیون	متوسط
C) زیرعامل‌دهی	نماینده زیرمجموعه تعریف می‌کنه (چند سطحی)	زیاد

پیشنهاد: شروع با مدل B و امکان ارتقا به C

جداول دیتابیس پیشنهادی:

• agents — اطلاعات نماینده (agent_code, commission_rate, parent_agent_id)
• agent_customers — تخصیص مشتریان به نماینده
• agent_commissions — محاسبه و پرداخت کمیسیون‌ها

فازهای پیاده‌سازی:

1. جداول + مدل + ثبت‌نام با کد معرف
2. محاسبه خودکار کمیسیون هنگام ثبت سفارش
3. پنل نماینده در Filament (گزارش‌ها + تسویه)
4. لینک معرف اختصاصی + صفحه لندینگ ثبت‌نام

---

فاز ۵ (آینده) — تجاری‌سازی و Premium 📋

وضعیت: طرح مطالعاتی آماده

🎯 مدل تجاری پیشنهادی

به‌جای نسخه رایگان، یه مدل پولی چندلایه‌ای پیشنهاد می‌شه (چون بازار هدف محدود هست):

┌─────────────────────────────────────────┐
│  IFNEX Starter (پرداخت یک‌بار/ماهانه)   │
│  ├── پنل مشتری پایه                     │
│  ├── فرم سفارش ساده                     │
│  ├── PDF استاندارد (AWB/Invoice/Label) │
│  ├── اکسپورت اکسل پایه                  │
│  └── پشتیبانی ایمیل                     │
└─────────────────────────────────────────┘
              ↓ (ارتقا)
┌─────────────────────────────────────────┐
│  IFNEX Business                         │
│  ├── تمام امکانات Starter               │
│  ├── Multi-Package                      │
│  ├── سیستم نمایندگی (فاز ۴)             │
│  ├── گزارش‌های مالی پیشرفته             │
│  ├── اکسپورت اکسل کامل                  │
│  ├── API ترکینگ زنده (TrackingMore)    │
│  └── پشتیبانی اولویت‌دار                │
└─────────────────────────────────────────┘
              ↓ (ارتقا)
┌─────────────────────────────────────────┐
│  IFNEX Enterprise                       │
│  ├── تمام امکانات Business              │
│  ├── فرم‌ساز Drag & Drop                │
│  ├── White-label branding               │
│  ├── API Gateway برای توسعه‌دهندگان     │
│  ├── پلاگین SMS                        │
│  ├── Multi-language                     │
│  ├── پشتیبانی اختصاصی ۲۴/۷              │
│  └── آموزش تیمی                         │
└─────────────────────────────────────────┘

قابلیت‌های Premium برای فاز ۵:

فیچر	Starter	Business	Enterprise
پنل مشتری	✅	✅	✅
فرم سفارش ساده	✅	✅	✅
PDF استاندارد	✅	✅	✅
اکسپورت اکسل پایه	✅	✅	✅
Multi-Package	❌	✅	✅
سیستم نمایندگی	❌	✅	✅
گزارش‌های پیشرفته	❌	✅	✅
API ترکینگ زنده	❌	✅	✅
فرم‌ساز Drag & Drop	❌	❌	✅
White-label	❌	❌	✅
API Gateway	❌	❌	✅
پشتیبانی ۲۴/۷	❌	❌	✅

سایر موارد فاز ۵:

• اتصال به APIهای ترکینگ زنده (TrackingMore/17track)
• پلاگین SMS برای اطلاع‌رسانی خودکار
• مستندات API (OpenAPI/Swagger)
• راهنمای اپراتور (Operator Manual)
• تست‌های واحد و Integration
• اپلیکیشن موبایل (احتمالی)
• بهبود سئو وب‌سایت وردپرس
• ویرایش پروفایل مشتری
• استان/شهر بر اساس کشور

---

معماری پروژه

┌─────────────────────────────────────────────────┐
│               کاربر نهایی                       │
│          (مرورگر وب / موبایل)                    │
│  ─ زبان فارسی (پیش‌فرض)                         │
│  ─ زبان انگلیسی (Polylang)                      │
└──────────────────┬──────────────────────────────┘
                   │
        ┌──────────▼──────────┐
        │   وب‌سایت وردپرس    │
        │  (ifnex.vernahost.ir) │
        │                     │
        │  ─ قالب IFNEX       │
        │  ─ پلاگین IFNEX     │
        │    Bridge           │
        │  ─ Polylang (i18n)  │
        │  ─ دشبورد مشتری     │
        │  ─ فرم سفارش        │
        │    (Multi-Package)  │
        │  ─ صفحه پرداخت      │
        └──────────┬──────────┘
                   │ API (Sanctum/Bridge)
        ┌──────────▼──────────┐
        │   API لاراول        │
        │ (api.ifnex.vernahost) │
        │                     │
        │  ─ قیمت‌گذاری       │
        │  ─ سفارشات مشتری   │
        │  ─ کیف پول          │
        │  ─ پرداخت           │
        │  ─ نوتیفیکیشن        │
        │  ─ PDF با بارکد     │
        └──────────┬──────────┘
                   │
        ┌──────────▼──────────┐
        │   پنل ادمین Filament │
        │ (api.ifnex.vernahost) │
        │      /panel          │
        │                     │
        │  ─ مرسولات          │
        │  ─ نرخ‌ها           │
        │  ─ کشورها           │
        │  ─ ارزها            │
        │  ─ ترکینگ           │
        │  ─ تنظیمات          │
        └─────────────────────┘

---

جریان احراز هویت Bridge

┌──────────┐   POST /bridge/login   ┌─────────────┐  ┌──────────────┐
│ WordPress│ ─────────────────────> │ Bridge      │─>│ Sanctum Token│
│  Plugin  │ <──── token + user ─── │ Controller  │<─│ (30 days)    │
└──────────┘                        └─────────────┘  └──────────────┘
     │                                                                  │
     │ ───── All API calls with Bearer Token ──────────────────────────>│
     │                                                                  │
     │ <──── JSON responses ────────────────────────────────────────────│
└────────────────────────────────────────────────────────────────────────┘

نکته: Bridge Auth نیازی به رمز عبور ندارد — از API Key مشترک بین لاراول و وردپرس استفاده می‌کند.

---

تکنولوژی‌ها

لایه	تکنولوژی
بک‌اند	Laravel 11 + PHP 8.2
پنل ادمین	Filament 3.3.x
فرانت‌اند	WordPress 7.0.3 + قالب سفارشی
چندزبانه	Polylang (وردپرس)
پرداخت	Zarinpal + Mock Gateway (تست)
PDF	Dompdf + picqer/php-barcode
Excel	maatwebsite/excel
تاریخ	morilog/jalali
احراز هویت	Laravel Sanctum + Bridge Auth
دیتابیس	MySQL 8
سرور	HestiaCP + Nginx + PHP-FPM
SSL	Let's Encrypt
مخزن	Gitea (git.vernahost.ir)

---

محیط‌ها

محیط	دامنه	وضعیت
تست/تولید	api.ifnex.vernahost.ir	✅ فعال (Laravel)
تست/تولید	ifnex.vernahost.ir	✅ فعال (WordPress)
لوکال	localhost:8000	✅ توسعه
لوکال	localhost/IFNEX-Logistics/03_WordPress	✅ توسعه

---

آمار کلی پروژه

معیار	مقدار
تعداد مایگریشن‌ها	۲۸
تعداد API endpoints	۳۰+
تعداد Filament Resources	۱۰+
تعداد مدل‌ها	۱۷
تعداد شورت‌کدهای وردپرس	۱۰+
تعداد کشورها با پیش‌شماره	۱۹۲
رکوردهای تاریخی مهاجرت‌شده	۳۹۵۰
تعداد موارد کارفرما (فاز ۳)	۱۸ مورد ✅
زبان‌های پشتیبانی‌شده	۲ (فارسی، انگلیسی)
خطوط کد (تخمینی)	۱۵۰۰۰+

---

نکات کلیدی

✅ نقاط قوت

• معماری Headless مقیاس‌پذیر
• امنیت چندلایه (API Key + Sanctum + Bridge Key)
• پشتیبانی از ۱۹۲ کشور با پیش‌شماره استاندارد
• تولید PDF حرفه‌ای با بارکد (مطابق نمونه کارفرما)
• Mock Gateway برای تست بدون درگاه واقعی
• سیستم نوتیفیکیشن دیتابیس برای ادمین و مشتری
• رابط کاربری مدرن و واکنش‌گرا

⚠️ نواقص باقیمانده (فاز ۳.۵)

• Multi-Package در فرم سفارش مشتری
• فرم Invoice برای محموله‌های PARCEL
• پشتیبانی کامل چندزبانه (i18n)
• تست نهایی روی سرور

📋 برای آینده

• تجاری‌سازی با مدل پولی چندلایه‌ای
• سیستم نمایندگی کامل
• فرم‌ساز پیشرفته
• API Gateway برای توسعه‌دهندگان

---

2026 VernaSoft Group. Internal use only.