Kazem Alghasi 02c29db696 feat(core): implement order approval flow, credit system, and import invoicing

Introduce a comprehensive set of commercial features including a multi-step
order approval workflow, customer credit management, and specialized
import service invoicing.

Key changes:
- Implement `pending_approval` and `approved` shipment statuses to allow
  staff verification before customer payment.
- Add a credit system to `User` model with `credit_limit` and `credit_used`
  to manage customer balances and debts.
- Develop a new `importInvoice` PDF generation service following the
  "Sheet ENG Invoice" specification for import services.
- Add Filament resources for managing Audit Logs, Commitment Forms,
  Customer Credits, and Shipment Checklists.
- Implement staff-specific APIs for order approval/rejection and
  customer financial status monitoring.
- Integrate Kavenegar SMS service for mobile verification and notifications.
- Add bulk tracking import functionality via CSV/Excel.
- Update WordPress bridge assets (CSS/JS) to support the new multi-step
  order form UI and updated redirection logic.
- Update deployment configurations and documentation to reflect new
  production domains and feature sets.

2026-09-03 06:04:20 +03:30

21 KiB

Raw Blame History

🚀 IFNEX Logistics Management System

پلتفرم جامع مدیریت لجستیک بین‌المللی

جایگزینی فرآیندهای دستی مبتنی بر اکسل با معماری Headless مدرن

📚 مستندات • ⚡ شروع سریع • 🏗️ معماری • 📞 پشتیبانی

📖 درباره پروژه

IFNEX یک راه‌حل جامع برای شرکت‌های حمل‌ونقل بین‌المللی است که فرآیندهای مبتنی بر فایل‌های اکسل را با یک سیستم Headless مدرن جایگزین می‌کند. این سیستم با تکیه بر Laravel 11 به عنوان بک‌اند، WordPress به عنوان فرانت‌اند و Filament 3.3 به عنوان پنل مدیریت، تجربه‌ای یکپارچه برای اپراتورها و مشتریان فراهم می‌آورد.

✨ امکانات کلیدی

موتور قیمت‌گذاری هوشمند با ۴ زون مجزا (Export/Import × Parcel/Doc) و ۳ نوع سرویس (DOC_NORMAL, DOC_ECONOMY, PARCEL)
ثبت سفارش آنلاین چندمرحله‌ای با Wizard و محاسبه لحظه‌ای قیمت
تولید خودکار اسناد (AWB, Invoice, Label) با بارکد استاندارد و پشتیبانی کامل از زبان انگلیسی
پورتال مشتری کامل با کیف پول، پرداخت آنلاین، تراکنش‌ها، اعلان‌ها و رهگیری مرسوله
پنل مدیریت قدرتمند با Filament 3.3 شامل مدیریت مرسوله‌ها، نرخ‌ها، ارزها، کاربران و گزارش‌ها
سیستم ترکینگ با قابلیت مهاجرت داده‌های تاریخی و تایم‌لاین کامل
اعلان‌های دیتابیس برای ادمین و مشتری با badge unread در سایدبار
پشتیبانی از ۱۹۲ کشور با پیش‌شماره تلفن استاندارد ISO 3166-1
اعتبارسنجی فرم‌ها شامل تشخیص خودکار زبان فارسی/انگلیسی و پیش‌شماره خودکار
سیستم تأیید سفارش با فلوی pending_approval → approved → paid → processed
فرم تعهدنامه با قابلیت آپلود فایل توسط مدیر و مشاهده توسط مشتری
فاکتور واردات با طراحی مطابق Sheet ENG Invoice
مانده حساب با نمایش موجودی کیف پول منهای بدهی‌ها
وضعیت مالی مشتری برای مدیر/کارمند با جزئیات بدهی به هر ارز
سیستم اعتباردهی (Credit) با قابلیت افزایش/کاهش توسط مدیر کل
چک‌لیست کارمند برای هر سفارش + تاریخچه مراحل
ایمپورت گروهی وضعیت ترکینگ با فایل CSV
سیستم Audit Log برای لاگ تغییرات مدیر
اتصال سرویس اس‌ام‌اس Kavenegar برای تأیید موبایل و ارسال پیامک

🏗️ معماری سیستم

این پروژه بر اساس الگوی Headless طراحی شده است — فرانت‌اند (WordPress) و بک‌اند (Laravel) کاملاً جدا و فقط از طریق REST API با هم ارتباط دارند. این جداسازی به ما امکان می‌دهد تا هر لایه را مستقل مقیاس‌پذیر کنیم، امنیت را بهبود ببخشیم و در آینده فرانت‌اند‌های دیگری (مثل اپلیکیشن موبایل) را اضافه کنیم.

┌──────────────────────────────────────────────────────┐
│                  CLIENT BROWSER                     │
└────────────────────────┬─────────────────────────────┘
                         │
┌────────────────────────▼─────────────────────────────┐
│              WORDPRESS (Frontend)                    │
│  ┌───────────────────┐  ┌──────────────────────────┐ │
│  │   IFNEX Theme     │  │   IFNEX Bridge Plugin    │ │
│  │   (Landing Page)  │  │   (REST Client + AJAX)   │ │
│  └───────────────────┘  └────────────┬─────────────┘ │
└───────────────────────────────────────┼──────────────┘
                                        │ REST API (Sanctum + Bridge Key)
┌───────────────────────────────────────▼──────────────┐
│              LARAVEL 11 (Backend)                    │
│  ┌─────────────────┐  ┌──────────────┐  ┌──────────┐ │
│  │   Filament      │  │   API         │  │ Services │ │
│  │   Admin Panel   │  │   Controllers │  │ (Pricing,│ │
│  │   (/panel)      │  │   (/api/v1)   │  │  PDF,    │ │
│  └─────────────────┘  └──────┬───────┘  │  Payment)│ │
└──────────────────────────────┼──────────┴──────────┘
                               │
                  ┌────────────▼────────────┐
                  │     MySQL 8 Database    │
                  │  (23 migrations, 13     │
                  │   models)               │
                  └─────────────────────────┘

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

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

📁 ساختار پروژه

IFNEX-Logistics/
├── 📄 01_Documents/                  # مستندات فنی پروژه
│   ├── IFNEX_File_Map.md             # نقشه کامل ۱۰۰+ فایل
│   ├── IFNEX_Roadmap.md              # نقشه راه ۴ فازی
│   ├── IFNEX_Phase0_Checklist.md     # چک‌لیست تکمیل فازها
│   ├── IFNEX_DEPRECATED_FILES_NOTICE.md
│   └── EXCEL_ANALYSIS.md             # تحلیل داده‌های تاریخی
│
├── 🌐 03_WordPress/                  # فرانت‌اند (WordPress 7.0.3)
│   └── wp-content/
│       ├── themes/ifnex/             # قالب سفارشی IFNEX
│       └── plugins/
│           └── ifnex-bridge/         # پلاگین ارتباط با لاراول
│               ├── includes/
│               │   ├── api-client.php       # مستقیم به API
│               │   ├── user-bridge.php      # Bridge Auth + AJAX handlers
│               │   ├── shortcodes.php       # ۱۰+ شورت‌کد
│               │   └── tracking-form.php    # فرم رهگیری
│               └── assets/
│                   ├── css/ifnex-orders.css # استایل دشبورد
│                   └── js/ifnex-order-form.js # فرم چندمرحله‌ای
│
├── ⚙️ 04_Laravel/                    # بک‌اند (Laravel 11)
│   ├── app/
│   │   ├── Enums/                    # ShipmentStatus, Direction, Type
│   │   ├── Filament/
│   │   │   ├── Resources/            # 10+ Resource (Shipment, Country, ...)
│   │   │   ├── Pages/                # Settings, ImportRates, PriceTest, Reports
│   │   │   └── Widgets/              # Dashboard Widgets
│   │   ├── Http/
│   │   │   ├── Controllers/Api/      # Track, Pricing, Auth, Bridge, Customer, Wallet, Payment
│   │   │   └── Middleware/           # ApiKeyMiddleware
│   │   ├── Models/                   # 13 مدل Eloquent
│   │   ├── Notifications/            # Database notifications
│   │   ├── Services/                 # PriceCalculator, Pdf, Tracking, OrderPayment
│   │   └── Imports/                  # Excel imports (OldShipments, ShippingRates)
│   ├── database/
│   │   ├── migrations/               # 23 migrations
│   │   └── seeders/                  # Countries, SystemSettings, DatabaseSeeder
│   ├── resources/views/
│   │   ├── pdfs/                     # awb, invoice, label
│   │   └── filament/                 # Blade views
│   └── routes/
│       ├── api.php                   # 30+ REST API endpoints
│       └── web.php                   # Web routes + Download Template
│
├── 📋 README.md                      # این فایل
├── 📋 DEPLOYMENT.md                  # راهنمای استقرار Production
└── 📋 04_Laravel/README.md           # راهنمای بک‌اند

✨ ویژگی‌های کلیدی بر اساس فازها

فاز ۰ — بنیان سیستم ✅ (تکمیل شده - 100%)

اسکیمای دیتابیس مدرن با ۴ زون مجزا (Export/Import × Parcel/Doc)
مهاجرت ۳۹۵۰ رکورد تاریخی از اکسل به دیتابیس
پنل مدیریت Filament با UX تخصصی اپراتور
API ترکینگ با امنیت API Key + Rate Limiting
پلاگین WordPress Bridge برای ارتباط با فرانت‌اند

فاز ۱ — پورتال مشتری ✅ (تکمیل شده - 100%)

احراز هویت Laravel Sanctum + Bridge Auth (بدون نیاز به رمز عبور)
فرم ثبت سفارش چندمرحله‌ای با Wizard (مسیر، اطلاعات تماس، تخفیف، تأیید)
داشبورد جامع مشتری شامل: داشبورد، سفارشات، ثبت سفارش، کیف پول، تراکنش‌ها، رهگیری، اعلان‌ها، پروفایل
سیستم ترکینگ با تایم‌لاین و تاریخچه کامل

فاز ۲ — مالی و کیف پول ✅ (تکمیل شده - 100%)

سیستم کیف پول کامل با تراکنش‌ها و تاریخچه
درگاه پرداخت Zarinpal + Mock Gateway برای تست لوکال
مدیریت ارزهای چندگانه (IRR, AED, USD, EUR, CNY)
کدهای تخفیف با اعتبارسنجی و محدودیت مصرف
تولید PDF حرفه‌ای (AWB, Invoice, Label) با بارکد استاندارد
پشتیبانی از چند بسته در یک سفارش (Multi-Package)
تاریخچه تغییرات وضعیت (ShipmentStatusHistory)

فاز ۳ — بهبود و یکپارچه‌سازی ✅ (تکمیل شده - 100%)

ایمپورت/اکسپورت نرخ‌ها با دانلود Template اکسل
سیستم اعلان‌های دیتابیس (ادمین + مشتری) با badge unread در سایدبار
هشدار هوشمند زبان فارسی/انگلیسی در فرم سفارش (نام، شهر، آدرس)
پیش‌شماره تلفن خودکار بر اساس کشور انتخابی (۱۹۲ کشور)
اعتبارسنجی تلفن (فقط اعداد، +، فاصله)
استایل مدرن تراکنش‌ها و دشبورد مشتری
صفحه شارژ کیف پول با مبالغ آماده
بازطراحی PDFها (AWB, Invoice, Label) با بارکد مطابق نمونه کارفرما
اصلاح متدهای Enum (isPaid, canBeCancelledByCustomer)
میدلور API برای بازگرداندن JSON 401 به جای redirect

فاز ۳.۵ — اصلاحات اساسی ✅ (تکمیل شده - 90%)

Multi-Package در فرم سفارش مشتری (چند بسته در یک سفارش)
فرم Invoice برای محموله‌های PARCEL (اقلام گمرکی با HS Code)
بازطراحی PDFها (AWB, Invoice, Label) با بارکد مطابق نمونه کارفرما
تست ترکینگ کامل با timeline زیبا و چندمرحله‌ای
محاسبه خودکار وزن حجمی از ابعاد (فرمول: L×W×H/5000)
ساختار ۵ مرحله‌ای فرم سفارش (مسیر → تماس → اقلام → تخفیف → تأیید)
اصلاحات فنی (Enum casts, migration, model)
پشتیبانی چندزبانه (i18n) — به زمان دیپلوی منتقل شد

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

مدل نمایندگی کامل با کمیسیون و پنل جداگانه
طرح مطالعاتی آماده — منتظر تأیید کارفرما

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

مدل پولی چندلایه‌ای: Starter / Business / Enterprise
فرم‌ساز Drag & Drop
White-label branding
API Gateway برای توسعه‌دهندگان

⚡ شروع سریع

پیش‌نیازها

PHP 8.2+ با extensions: pdo_mysql, mbstring, xml, gd, zip
Composer 2.x
MySQL 8+
WordPress 7.0+

نصب بک‌اند (Laravel)

# ۱. کلون مخزن
git clone https://www.git.vernahost.ir/gitmodir110/ifnex.git
cd ifnex/04_Laravel

# ۲. نصب وابستگی‌ها
composer install

# ۳. تنظیم فایل محیط
cp .env.example .env
php artisan key:generate

# ۴. ایجاد دیتابیس
mysql -u root -p -e "CREATE DATABASE ifnex_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

# ۵. ویرایش .env — مقادیر کلیدی:
#    DB_DATABASE=ifnex_db
#    DB_USERNAME=root
#    DB_PASSWORD=your_password
#    IFNEX_BRIDGE_API_KEY=your-secret-bridge-key  # مهم برای وردپرس
#    ZARINPAL_MERCHANT_ID=fake-merchant-id-for-testing  # برای Mock Mode
#    ZARINPAL_SANDBOX=true
#    CORS_ALLOWED_ORIGINS=http://localhost,http://127.0.0.1

# ۶. اجرای migrations و seeders
php artisan migrate --force
php artisan db:seed --force

# ۷. اجرای سرور
php artisan serve
# پنل ادمین: http://127.0.0.1:8000/panel

نصب فرانت‌اند (WordPress)

# ۱. کپی پوشه 03_WordPress به htdocs (XAMPP) یا public_html (سرور)
# ۲. ساخت دیتابیس وردپرس و اجرای نصب
# ۳. فعال‌سازی قالب IFNEX و پلاگین IFNEX Bridge
# ۴. تنظیمات پلاگین (admin → منوی IFNEX):
#    - API URL: http://localhost:8000/api/v1
#    - API Key (عمومی): همان مقدار IFNEX_API_KEY در .env لاراول
#    - Bridge API Key: همان مقدار IFNEX_BRIDGE_API_KEY در .env لاراول
# ۵. ساخت صفحات با شورت‌کدها:
#    - /my-account/ → [ifnex_customer_dashboard]
#    - /my-orders/  → [ifnex_orders_list]
#    - /new-order/  → [ifnex_order_form]
#    - /wallet/     → [ifnex_wallet_charge]
#    - /tracking/   → [ifnex_tracking_form]

📖 برای راهنمای کامل استقرار روی سرور، DEPLOYMENT.md را ببینید.

🛠️ Stack فنی

Backend (Laravel)

تکنولوژی	نسخه	کاربرد
Laravel	11.x	فریمورک اصلی
PHP	8.2+	زبان برنامه‌نویسی
Filament	3.3.x	پنل مدیریت ادمین
MySQL	8+	دیتابیس
Dompdf	Latest	تولید PDF
Laravel Excel	Latest	Import/Export
Sanctum	Latest	API Authentication
Morilog Jalali	3.x	تاریخ شمسی
picqer/php-barcode	Latest	تولید بارکد

Frontend (WordPress)

تکنولوژی	نسخه	کاربرد
WordPress	7.0.3	CMS
IFNEX Theme	Custom	قالب سفارشی
IFNEX Bridge	1.7.0	پلاگین ارتباطی
jQuery	3.x	AJAX + DOM

زیرساخت

سرویس	کاربرد
HestiaCP	پنل مدیریت سرور
Nginx	وب‌سرور
PHP-FPM	پردازش PHP
MySQL 8	دیتابیس
Let's Encrypt	SSL رایگان
Git (Gitea)	مخزن کد

📊 آمار پروژه

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

📚 مستندات

برای مطالعه دقیق منطق‌های سیستم:

فایل	محتوا	اولویت
IFNEX_Phase0_Checklist.md	چک‌لیست کامل فازها	⭐⭐⭐
IFNEX_Roadmap.md	نقشه راه آینده (فاز ۳.۵، ۴، ۵)	⭐⭐⭐
IFNEX_File_Map.md	نقشه ۱۰۰+ فایل پروژه	⭐⭐⭐
IFNEX_I18N_Strategy.md	استراتژی چندزبانه (Polylang)	⭐⭐
IFNEX_Commercial_Model.md	مدل تجاری و پلن‌های فروش	⭐⭐
DEPLOYMENT.md	راهنمای استقرار Production	⭐⭐
04_Laravel/README.md	راهنمای بک‌اند	⭐⭐
IFNEX_DEPRECATED_FILES_NOTICE.md	فایل‌های منسوخ	⭐

🚀 مراحل بعدی

فاز ۳.۵ — باقیمانده (زمان دیپلوی)

پشتیبانی کامل چندزبانه (i18n) با Polylang

فاز ۴ (آینده)

سیستم نمایندگی کامل با کمیسیون و پنل جداگانه

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

مدل پولی چندلایه‌ای: Starter / Business / Enterprise
اتصال به APIهای ترکینگ زنده (TrackingMore/17track)
پلاگین SMS برای اطلاع‌رسانی خودکار
مستندات API (OpenAPI/Swagger)
راهنمای اپراتور (Operator Manual)
تست‌های واحد و Integration
اپلیکیشن موبایل (احتمالی)
فرم‌ساز Drag & Drop
White-label branding
API Gateway برای توسعه‌دهندگان

📞 تماس

توسعه‌دهنده: Kazem Alghasi
شرکت: VernaSoft Group
ایمیل: kazem@vernasoft.group
مخزن: git.vernahost.ir/gitmodir110/ifnex
سرور تست: api.ifnex.vernahost.ir (Laravel) | ifnex.vernahost.ir (WordPress)

📜 لایسنس

این پروژه اختصاصی شرکت IFNEX است و کپی یا استفاده غیرمجاز ممنوع می‌باشد.

21 KiB Raw Blame History Unescape Escape