ifnex/01_Documents/IFNEX_Roadmap.md
Kazem Alghasi b5e136a76d docs(roadmap): introduce phase 3.5 and future commercialization plans
Update project documentation to reflect the transition from Phase 3 to
a new critical refinement phase (Phase 3.5) and outline long-term
strategic goals.

Key documentation updates:
- Added Phase 3.5 (Essential Refinements) to the roadmap and checklist,
  focusing on multi-package support, parcel invoice forms, and
  internationalization (i18n).
- Defined Phase 5 (Commercialization) including tiered subscription
  models (Starter, Business, Enterprise) and premium features.
- Created `IFNEX_Commercial_Model.md` to detail monetization strategies.
- Created `IFNEX_I18N_Strategy.md` to outline the multi-language
  implementation approach using Polylang.
- Updated `README.md` with the revised project lifecycle and new
  documentation references.
2026-08-29 05:19:54 +03:30

444 lines
22 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# نقشه راه پروژه IFNEX
> **آخرین بروزرسانی:** 2026-08-29
> **توسعه‌دهنده:** VernaSoft Group — Kazem Alghasi
> **وضعیت کلی:** فاز ۰، ۱، ۲، ۳ تکمیل شد ✅ — فاز ۳.۵ در دست اقدام 🔄
---
## خلاصه وضعیت
| فاز | عنوان | وضعیت | درصد |
|------|-------|--------|------|
| فاز ۰ | پایه و زیرساخت | ✅ تکمیل شده | 100% |
| فاز ۱ | پنل مشتری وردپرس | ✅ تکمیل شده | 100% |
| فاز ۲ | پرداخت و کیف پول | ✅ تکمیل شده | 100% |
| فاز ۳ | یکپارچه‌سازی و بهبود | ✅ تکمیل شده | 100% |
| **فاز ۳.۵** | **اصلاحات اساسی** | 🔄 در دست اقدام | 0% |
| فاز ۴ | سیستم نمایندگی | 📋 مطالعاتی | 0% |
| فاز ۵ | تجاری‌سازی و Premium | 📋 مطالعاتی | 0% |
---
## فاز ۰ — پایه و زیرساخت ✅
**هدف:** ساخت زیرساخت 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 در فرم سفارش مشتری 🔴 ضروری
**مشکل:** در حال حاضر، مشتری می‌تونه فقط یه بسته ثبت کنه. در صورتی که:
- بک‌اند پشتیبانی از چند بسته (ShipmentPackage) رو داره ✅
- پنل ادمین Filament هم Repeater برای بسته‌ها داره ✅
- ولی فرم سفارش مشتری (وردپرس) فقط یه بسته می‌گیره ❌
**راه حل:**
- اضافه‌کردن قابلیت "افزودن بسته دیگر" در مرحله ۱ فرم سفارش
- هر بسته شامل: وزن واقعی، وزن حجمی، ابعاد، تعداد
- محاسبه مجموع وزن‌ها و قیمت نهایی
- نمایش لیست بسته‌های اضافه‌شده قبل از تأیید نهایی
**تأثیرات:**
- اصلاح `ifnex-order-form.js` (افزودن Repeater UI)
- اصلاح `buildOrderData()` (ارسال آرایه packages)
- اصلاح API `POST /customer/orders` (پذیرش packages[])
- اصلاح مدل Shipment (ایجاد خودکار ShipmentPackage)
### ۳.۵.۲ — فرم Invoice برای محموله‌های PARCEL 🔴 ضروری
**مشکل:** وقتی مشتری نوع محموله رو PARCEL انتخاب می‌کنه، باید فرم Invoice (اقلام گمرکی) رو پر کنه. در حال حاضر این فرم وجود نداره.
**راه حل:**
- اضافه‌کردن مرحله جدید به فرم سفارش (مرحله ۲.۵)
- نمایش این مرحله فقط وقتی نوع = PARCEL
- فیلدهای هر آیتم: Description, HS Code, Quantity, Unit Price (USD), Total (USD)
- امکان افزودن چندین آیتم (تا ۹ ردیف)
- محاسبه خودکار Total و نمایش مجموع
- ارسال items[] به API
**تأثیرات:**
- اصلاح `ifnex-order-form.js` (مرحله ۲.۵ با Repeater)
- اصلاح `ifnex-order-form.blade.php` (HTML مرحله جدید)
- اصلاح API `POST /customer/orders` (پذیرش items[])
### ۳.۵.۳ — پشتیبانی چندزبانه (i18n) 🟡 مهم
**مشکل:** سایت ۲ زبانه (فارسی + انگلیسی) هست با Polylang، ولی:
- تمام شورت‌کدها و فرم‌ها فقط فارسی هستن
- پیام‌های خطا و موفقیت فقط فارسی هستن
- فایل‌های JS پیام‌های hard-coded فارسی دارن
- فایل‌های PHP رشته‌های hard-coded فارسی دارن
**راه حل:**
- استخراج تمام رشته‌های متنی به فایل‌های ترجمه
- استفاده از `__()` و `_e()` در وردپرس
- استفاده از `__('text', 'ifnex-bridge')` در فایل‌های PHP پلاگین
- استفاده از `wp_localize_script` برای ارسال ترجمه‌ها به JS
- افزودن فایل‌های `.po/.mo` برای زبان‌های فارسی و انگلیسی
- پشتیبانی از RTL/LTR به‌صورت خودکار بر اساس زبان فعال
**تأثیرات:**
- اصلاح تمام فایل‌های `ifnex-bridge/includes/*.php`
- اصلاح `ifnex-order-form.js` (استفاده از متغیرهای ترجمه)
- ساخت فایل‌های ترجمه در `ifnex-bridge/languages/`
- اصلاح CSS برای پشتیبانی RTL/LTR
### ۳.۵.۴ — تست و نهایی‌سازی 🟡 مهم
- [ ] تست تولید 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.