a1a6dbdd8a
This commit marks the completion of Phase 3 (Integration and Improvements) and updates the project status to reflect that Phases 0 through 3 are finished. Key changes include: - **Laravel (Backend):** - Added `calling_code` column to `countries` table via new migration. - Added scripts to update calling codes for all countries. - Updated `CustomerOrderController` to include `calling_code` in country data. - Registered `api_key` middleware alias in `bootstrap/app.php`. - Improved error handling to return JSON 401 for API authentication failures. - Updated `README.md` with detailed architecture and feature descriptions. - **WordPress (Frontend/Bridge):** - Added `ifnex_wallet_charge` shortcode and AJAX handler for wallet top-ups. - Implemented auto-fill for calling codes in the order form based on selected country. - Added real-time phone number validation (digits, +, spaces only). - Added English-only validation for name, city, and address fields with UI warnings. - Updated asset enqueuing logic and versioning for CSS/JS. - **Documentation:** - Updated `IFNEX_File_Map.md`, `IFNEX_Phase0_Checklist.md`, and `IFNEX_Roadmap.md` to reflect completed phases and new features. - Updated `DEPLOYMENT.md` with new environment variables (`IFNEX_BRIDGE_API_KEY`) and required WordPress pages. - Updated project `README.md` with comprehensive feature list and system architecture.
295 lines
14 KiB
Markdown
295 lines
14 KiB
Markdown
# نقشه راه پروژه IFNEX
|
||
|
||
> **آخرین بروزرسانی:** 2026-08-29
|
||
> **توسعه‌دهنده:** VernaSoft Group — Kazem Alghasi
|
||
> **وضعیت کلی:** فاز ۰، ۱، ۲ و ۳ تکمیل شد ✅
|
||
|
||
---
|
||
|
||
## خلاصه وضعیت
|
||
|
||
| فاز | عنوان | وضعیت | درصد |
|
||
|------|-------|--------|------|
|
||
| فاز ۰ | پایه و زیرساخت | ✅ تکمیل شده | 100% |
|
||
| فاز ۱ | پنل مشتری وردپرس | ✅ تکمیل شده | 100% |
|
||
| فاز ۲ | پرداخت و کیف پول | ✅ تکمیل شده | 100% |
|
||
| فاز ۳ | یکپارچه‌سازی و بهبود | ✅ تکمیل شده | 100% |
|
||
| فاز ۴ (آینده) | سیستم نمایندگی | 📋 مطالعاتی | 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 مشترک
|
||
- شورت‌کدهای وردپرس: فرم سفارش چند مرحله‌ای، لیست سفارشات، جزئیات، پرداخت
|
||
- دشبورد جامع مشتری شامل ۸ تب:
|
||
- 📊 داشبورد (آمار + موجودی)
|
||
- 📦 سفارشات من (با فیلتر وضعیت)
|
||
- ➕ ثبت سفارش جدید (Wizard ۴ مرحله‌ای)
|
||
- 💰 کیف پول + شارژ آنلاین
|
||
- 📊 تراکنش‌ها
|
||
- 🚚 رهگیری مرسوله
|
||
- 🔔 اعلان‌ها (با badge unread)
|
||
- 👤 پروفایل
|
||
- 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
|
||
|
||
### مورد ۱۹ (نمایندگی) به فاز ۴ منتقل شد:
|
||
- طرح مطالعاتی آماده است
|
||
- منتظر تأیید و تسویه کارفرما برای فاز ۳
|
||
- فاز ۴ جداگانه اجرا خواهد شد
|
||
|
||
---
|
||
|
||
## فاز ۴ (آینده) — سیستم نمایندگی 📋
|
||
|
||
**وضعیت:** طرح مطالعاتی آماده — منتظر تصمیم کارفرما
|
||
|
||
### مدل‌های پیشنهادی:
|
||
|
||
| مدل | توضیح | پیچیدگی |
|
||
|-----|-------|---------|
|
||
| A) کد معرف ساده | هر کاربر یه کد معرف داره، درصدی از سود به معرف میرسه | کم |
|
||
| B) نمایندگی کامل | پنل جداگانه، گزارش فروش، کمیسیون | متوسط |
|
||
| C) زیرعامل‌دهی | نماینده زیرمجموعه تعریف می‌کنه (چند سطحی) | زیاد |
|
||
|
||
**پیشنهاد:** شروع با مدل B و امکان ارتقا به C
|
||
|
||
### جداول دیتابیس پیشنهادی:
|
||
- `agents` — اطلاعات نماینده (agent_code, commission_rate, parent_agent_id)
|
||
- `agent_customers` — تخصیص مشتریان به نماینده
|
||
- `agent_commissions` — محاسبه و پرداخت کمیسیون‌ها
|
||
|
||
### فازهای پیاده‌سازی:
|
||
1. جداول + مدل + ثبت‌نام با کد معرف
|
||
2. محاسبه خودکار کمیسیون هنگام ثبت سفارش
|
||
3. پنل نماینده در Filament (گزارش‌ها + تسویه)
|
||
4. لینک معرف اختصاصی + صفحه لندینگ ثبت‌نام
|
||
|
||
### سایر موارد فاز ۴:
|
||
- [ ] ویرایش پروفایل مشتری (نام، تلفن، آدرس)
|
||
- [ ] استان/شهر بر اساس کشور (Dynamic dropdowns)
|
||
- [ ] اتصال به APIهای ترکینگ زنده (TrackingMore/17track)
|
||
- [ ] پلاگین SMS برای اطلاع‌رسانی خودکار
|
||
- [ ] مستندات API (OpenAPI/Swagger)
|
||
- [ ] راهنمای اپراتور (Operator Manual)
|
||
- [ ] تست‌های واحد و Integration
|
||
- [ ] اپلیکیشن موبایل (احتمالی)
|
||
- [ ] بهبود سئو وب‌سایت وردپرس
|
||
|
||
---
|
||
|
||
## معماری پروژه
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────┐
|
||
│ کاربر نهایی │
|
||
│ (مرورگر وب / موبایل) │
|
||
└──────────────────┬──────────────────────────────┘
|
||
│
|
||
┌──────────▼──────────┐
|
||
│ وب‌سایت وردپرس │
|
||
│ (ifnex.vernahost.ir) │
|
||
│ │
|
||
│ ─ قالب IFNEX │
|
||
│ ─ پلاگین IFNEX │
|
||
│ Bridge │
|
||
│ ─ دشبورد مشتری │
|
||
│ ─ فرم سفارش │
|
||
│ ─ صفحه پرداخت │
|
||
└──────────┬──────────┘
|
||
│ API (Sanctum/Bridge)
|
||
┌──────────▼──────────┐
|
||
│ API لاراول │
|
||
│ (api.ifnex.vernahost) │
|
||
│ │
|
||
│ ─ قیمت‌گذاری │
|
||
│ ─ سفارشات مشتری │
|
||
│ ─ کیف پول │
|
||
│ ─ پرداخت │
|
||
│ ─ نوتیفیکیشن │
|
||
└──────────┬──────────┘
|
||
│
|
||
┌──────────▼──────────┐
|
||
│ پنل ادمین 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 + قالب سفارشی |
|
||
| پرداخت | 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 برای تست بدون درگاه واقعی
|
||
- سیستم نوتیفیکیشن دیتابیس برای ادمین و مشتری
|
||
- رابط کاربری مدرن و واکنش‌گرا
|
||
|
||
### ⚠️ نکات قابل توجه
|
||
- تست لوکال نیازمند XAMPP و فعال‌سازی Bridge API Key
|
||
- Mock Gateway فقط زمانی فعال میشه که `ZARINPAL_MERCHANT_ID=fake-merchant-id-for-testing`
|
||
- توکن Bridge ۳۰ روز اعتبار دارد و سپس باید تمدید شود
|
||
- فایل‌های PDF باید انگلیسی باشند (برای حمل بین‌المللی)
|
||
|
||
---
|
||
|
||
> 2026 VernaSoft Group. Internal use only.
|