# نقشه راه پروژه 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.