Kazem Alghasi a1a6dbdd8a feat(core): complete phase 3 integration and enhance country/phone features

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.

2026-08-29 04:38:28 +03:30

14 KiB

Raw Blame History

نقشه راه پروژه 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، استانداردسازی

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

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

✅ رفع اکشن‌های PDF در ViewShipment
✅ رفع ShippingRatesImport
✅ رفع تصاویر PDF (asset بجای public_path)
✅ ستون‌های جدید جدول Shipment
✅ Packages Repeater در فرم
✅ changeStatus به عنوان bulkAction
✅ afterSave hook نوتیفیکیشن
✅ Currency CRUD
✅ فیلد source در TrackingEvents
✅ ImportRatesPage (دکمه‌ها + دانلود template)
✅ استایل تراکنش‌های وردپرس
✅ هشدار آدرس انگلیسی
✅ نوتیفیکیشن پنل کاربری وردپرس (با badge unread)
✅ API نوتیفیکیشن (لیست + علامت‌گذاری خوانده‌شده)
✅ متدهای ifnex-bridge برای نوتیفیکیشن
✅ رفع مشکلات Filament Custom Page (wire:click بجای getFormActions)
✅ رفع دانلود template (روت مستقیم بجای AJAX)
✅ دیپلوی روی سرور تست (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 — محاسبه و پرداخت کمیسیون‌ها

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

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

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

ویرایش پروفایل مشتری (نام، تلفن، آدرس)
استان/شهر بر اساس کشور (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.

14 KiB Raw Blame History Unescape Escape

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

خلاصه وضعیت

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

انجام شده:

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

انجام شده:

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

انجام شده:

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

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

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

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

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

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

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

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

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

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

معماری پروژه

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

تکنولوژی‌ها

محیط‌ها

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

نکات کلیدی

✅ نقاط قوت

⚠️ نکات قابل توجه

14 KiB

Raw Blame History