02c29db696
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.
260 lines
13 KiB
Markdown
260 lines
13 KiB
Markdown
# IFNEX Logistics Management System — Agent Guide
|
||
|
||
> **هدف:** راهنمای جامع برای دستیار هوش مصنوعی (OpenCode + DeepSeek Flash) جهت درک سریع پروژه، معماری، قراردادها و نکات کلیدی.
|
||
>
|
||
> **نسخه:** 1.0
|
||
> **تاریخ:** 2026-09-02
|
||
> **مدل پیشنهادی:** DeepSeek Flash (تنظیم شده با API)
|
||
|
||
---
|
||
|
||
## 🎯 خلاصه پروژه
|
||
|
||
سیستم مدیریت لجستیک بینالمللی با معماری Headless (Laravel 11 بهعنوان بکاند، WordPress بهعنوان فرانتاند، Filament 3.3 بهعنوان پنل مدیریت). جایگزین فرآیندهای دستی مبتنی بر اکسل شده و از Multi-Package، فاکتور گمرکی (Invoice)، کیف پول دیجیتال، درگاه پرداخت Zarinpal، تولید PDF با بارکد، و سیستم رهگیری پیشرفته پشتیبانی میکند.
|
||
|
||
**وضعیت فعلی:** فازهای ۰، ۱، ۲، ۳ و ۳.۵ (۹۰٪) تکمیل شدهاند. تنها مورد باقیمانده از فاز ۳.۵، پشتیبانی کامل چندزبانه (i18n) است که به زمان دیپلوی موکول شده است.
|
||
|
||
---
|
||
|
||
## 🧰 تکنولوژیها و نسخهها
|
||
|
||
| لایه | تکنولوژی | نسخه / توضیح |
|
||
|------|-----------|--------------|
|
||
| **Backend** | Laravel | 11.x |
|
||
| **PHP** | PHP | ^8.2 (۸.۳ نیز پشتیبانی میشود) |
|
||
| **Admin Panel** | Filament | 3.3.x |
|
||
| **Frontend** | WordPress | 7.0.3 + قالب سفارشی IFNEX |
|
||
| **Authentication** | Laravel Sanctum + Bridge Auth | بدون رمز عبور (API Key مشترک) |
|
||
| **Payment** | Zarinpal + Mock Gateway (تست) | کلید sandbox برای تست لوکال |
|
||
| **PDF & Barcode** | Dompdf + picqer/php-barcode-generator | تولید AWB، Invoice، Label |
|
||
| **Excel** | maatwebsite/excel | Import/Export نرخها و دادههای تاریخی |
|
||
| **Date/Time** | morilog/jalali + Carbon | تاریخ شمسی در نمایش، میلادی در DB |
|
||
| **Database** | MySQL | 8.0+ |
|
||
| **Queue** | Redis (ترجیح) / Database | برای پردازشهای سنگین |
|
||
| **Server** | HestiaCP + Nginx + PHP-FPM | تولید (api.ifnex.vernahost.ir) |
|
||
|
||
---
|
||
|
||
## 📂 ساختار دایرکتوری (کلیدی)
|
||
|
||
IFNEX-Logistics/
|
||
├── 01_Documents/ # مستندات فنی (تحلیل اکسل، نقشه راه، چکلیست، ...)
|
||
│ ├── EXCEL_ANALYSIS.md # تحلیل کامل فایلهای اکسل (۳۹۵۰ رکورد)
|
||
│ ├── IFNEX_Phase0_Checklist.md # چکلیست کامل فازها
|
||
│ ├── IFNEX_Roadmap.md # نقشه راه ۵ فازی
|
||
│ ├── IFNEX_File_Map.md # نقشه ۱۰۰+ فایل پروژه
|
||
│ ├── IFNEX_I18N_Strategy.md # استراتژی چندزبانه
|
||
│ ├── IFNEX_Commercial_Model.md # مدل تجاری و پلنهای فروش
|
||
│ └── DESIGN_SYSTEM.md # رنگها، تایپوگرافی، فاصلهگذاری
|
||
│
|
||
├── 03_WordPress/ # فرانتاند وردپرس
|
||
│ ├── wp-content/themes/ifnex/ # قالب سفارشی
|
||
│ └── wp-content/plugins/ifnex-bridge/ # پلاگین ارتباط با لاراول
|
||
│
|
||
├── 04_Laravel/ # بکاند لاراول (هسته اصلی)
|
||
│ ├── app/
|
||
│ │ ├── Enums/ # ShipmentStatus, ShipmentDirection, ShipmentType, PaymentGateway, TransactionStatus
|
||
│ │ ├── Filament/
|
||
│ │ │ ├── Resources/ # ۱۰+ Resource (Shipment, Country, ShippingRate, Currency, ...)
|
||
│ │ │ ├── Pages/ # Settings, PriceTest, ImportRates, FinancialReport
|
||
│ │ │ └── Widgets/ # داشبورد
|
||
│ │ ├── Http/
|
||
│ │ │ ├── Controllers/Api/ # Track, Pricing, Auth, Bridge, Customer, Wallet, Payment, MockGateway
|
||
│ │ │ └── Middleware/ # ApiKeyMiddleware
|
||
│ │ ├── Models/ # ۱۷ مدل (Shipment, Package, Invoice, Wallet, ...)
|
||
│ │ ├── Notifications/ # ShipmentUpdatedNotification
|
||
│ │ ├── Services/ # PriceCalculator, Pdf, Tracking, OrderPayment, Zarinpal, MockZarinpal
|
||
│ │ ├── Imports/ # OldShipmentsImport, ShippingRatesImport
|
||
│ │ └── Exports/ # ShippingRatesTemplateExport
|
||
│ ├── database/
|
||
│ │ ├── migrations/ # ۲۸+ migration
|
||
│ │ └── seeders/ # Countries, SystemSettings, DatabaseSeeder
|
||
│ ├── resources/views/
|
||
│ │ ├── pdfs/ # awb, invoice, label (با بارکد)
|
||
│ │ └── filament/ # صفحات سفارشی
|
||
│ └── routes/
|
||
│ ├── api.php # ۳۰+ endpoint
|
||
│ └── web.php # روتهای عمومی (دانلود template، Mock Gateway)
|
||
│
|
||
├── DEPLOYMENT.md # راهنمای استقرار در سرور
|
||
└── README.md # معرفی کلی پروژه
|
||
|
||
|
||
---
|
||
|
||
## 🔑 مفاهیم کلیدی بیزینس
|
||
|
||
### ۱. مرسوله (Shipment)
|
||
- **انواع (Type):** `DOC_NORMAL`، `DOC_ECONOMY`، `PARCEL`
|
||
- **جهت (Direction):** `export` (صادرات) و `import` (واردات)
|
||
- **وضعیت (Status):** `pending` → `confirmed` → `picked_up` → `in_transit` → `out_for_delivery` → `delivered` / `failed` / `returned` / `cancelled`
|
||
- **ویژگیها:** دارای چند بسته (`packages`)، اقلام گمرکی (`items` - فقط برای PARCEL)، تاریخچه تغییرات وضعیت (`statusHistories`)، شرکتهای حمل (`carrierMappings`)، رویدادهای رهگیری (`trackingEvents`).
|
||
|
||
### ۲. بسته (Package)
|
||
- هر مرسوله میتواند چندین بسته داشته باشد.
|
||
- وزن حجمی = `(Length × Width × Height) / 5000` (استاندارد IATA).
|
||
- وزن قابل پرداخت = `max(وزن واقعی, وزن حجمی)`.
|
||
|
||
### ۳. فاکتور گمرکی (Invoice)
|
||
- فقط برای مرسولههای نوع `PARCEL` صادر میشود.
|
||
- حداکثر ۹ قلم کالا (شرح، HS Code، تعداد، قیمت واحد، مجموع به USD).
|
||
- مجموع کل فاکتور در `shipments.invoice_total_usd` ذخیره میشود.
|
||
|
||
### ۴. کیف پول (Wallet)
|
||
- هر کاربر یک کیف پول دارد.
|
||
- تراکنشها (`WalletTransaction`) با نوع `deposit`، `payment`، `refund`، `adjustment`.
|
||
- پرداخت از کیف پول یا درگاه Zarinpal (با Mock برای تست).
|
||
|
||
### ۵. احراز هویت Bridge
|
||
- کاربران وردپرس بدون نیاز به رمز عبور، از طریق `POST /api/v1/bridge/login` با ارسال `bridge_api_key` و `wp_user_id` وارد لاراول میشوند.
|
||
- پاسخ شامل `token` Sanctum (معتبر ۳۰ روز) و اطلاعات کاربر است.
|
||
- کلید `IFNEX_BRIDGE_API_KEY` باید در هر دو طرف (`.env` لاراول و تنظیمات پلاگین وردپرس) یکسان باشد.
|
||
|
||
### ۶. رهگیری (Tracking)
|
||
- کاربر با شماره AWB جستجو میکند.
|
||
- سیستم رویدادهای رهگیری را از جدول `shipment_tracking_events` با `source` (manual, api, system) نمایش میدهد.
|
||
- در فاز ۳.۵، صفحه رهگیری با تایملاین زیبا و badge رنگی بازطراحی شده است.
|
||
|
||
### ۷. قیمتگذاری (Pricing)
|
||
- بر اساس ۴ زون مجزا (Export/Import × Parcel/Doc) و ۳ نوع سرویس.
|
||
- فرمول: قیمت پایه (AED) × ضریب سود × نرخ تبدیل به ریال + هزینههای جانبی (Packing, Domestic Pickup, ...) + VAT (۹٪).
|
||
- محمولههای بالای ۳۰ کیلوگرم مشمول نرخ ویژه (Spot Rate) هستند و محاسبه آنلاین ندارند.
|
||
|
||
---
|
||
|
||
## ⚙️ دستورات روزمره (برای ایجنت)
|
||
|
||
```bash
|
||
# نصب وابستگیها
|
||
composer install
|
||
|
||
# تنظیم محیط
|
||
cp .env.example .env
|
||
php artisan key:generate
|
||
|
||
# دیتابیس (ابتدا باید ایجاد شود)
|
||
php artisan migrate --force
|
||
php artisan db:seed --force
|
||
|
||
# اجرای سرور توسعه
|
||
php artisan serve
|
||
|
||
# اجرای Queue (برای پردازشهای سنگین)
|
||
php artisan queue:work
|
||
|
||
# تستها
|
||
php artisan test
|
||
|
||
# پاکسازی کش
|
||
php artisan optimize:clear
|
||
php artisan config:cache
|
||
php artisan route:cache
|
||
php artisan view:cache
|
||
php artisan filament:clear-cached-components
|
||
|
||
# ایمپورت/اکسپورت نرخها
|
||
php artisan ifnex:import-rates
|
||
php artisan ifnex:export-rates-template
|
||
|
||
# بروزرسانی نرخ ارز (کرون)
|
||
php artisan ifnex:update-exchange-rates
|
||
|
||
# تولید API Token برای ادمین
|
||
php artisan ifnex:generate-api-token
|
||
|
||
|
||
🧪 متغیرهای محیطی کلیدی (.env)
|
||
APP_ENV=local
|
||
APP_DEBUG=true
|
||
APP_URL=http://localhost:8000
|
||
|
||
DB_CONNECTION=mysql
|
||
DB_HOST=127.0.0.1
|
||
DB_PORT=3306
|
||
DB_DATABASE=ifnex_db
|
||
DB_USERNAME=root
|
||
DB_PASSWORD=
|
||
|
||
# IFNEX اختصاصی
|
||
IFNEX_API_KEY=ifnex-local-dev-key
|
||
IFNEX_BRIDGE_API_KEY=ifnex-bridge-secret-key-2026-vernasoft # باید با وردپرس یکی باشد
|
||
IFNEX_TRACKING_RATE_LIMIT=60
|
||
|
||
# CORS (فقط دامنههای مجاز وردپرس)
|
||
CORS_ALLOWED_ORIGINS=http://localhost,http://127.0.0.1
|
||
|
||
# Zarinpal (برای تست از Mock استفاده کن)
|
||
ZARINPAL_MERCHANT_ID=fake-merchant-id-for-testing # اگر fake باشد، MockGateway فعال میشود
|
||
ZARINPAL_SANDBOX=true
|
||
ZARINPAL_CALLBACK_URL=http://localhost:8000/api/v1/payment/callback
|
||
ZARINPAL_FRONTEND_SUCCESS_URL=http://localhost/IFNEX-Logistics/03_WordPress/wallet
|
||
ZARINPAL_FRONTEND_FAILURE_URL=http://localhost/IFNEX-Logistics/03_WordPress/wallet
|
||
|
||
# Wallet
|
||
WALLET_MIN_DEPOSIT=10000
|
||
WALLET_MAX_DEPOSIT=500000000
|
||
WALLET_AUTO_CREATE=true
|
||
|
||
|
||
⚠️ خط قرمزها (ممنوعیتهای مطلق)
|
||
|
||
❌ هرگز ✅ همیشه
|
||
برگرداندن کشورها به ۲ زون ۴ زون مجزا (Export/Import × Parcel/Doc)
|
||
استفاده از ۲ نوع سرویس ۳ نوع (DOC_NORMAL, DOC_ECONOMY, PARCEL)
|
||
ذخیره تاریخ شمسی در DB ذخیره timestamp میلادی + تبدیل در نمایش
|
||
CORS * در Production CORS محدود به دامنه وردپرس
|
||
کامیت .env در Git در .gitignore باشد
|
||
APP_DEBUG=true در Production APP_DEBUG=false
|
||
PDF فارسی (AWB/Invoice/Label) همیشه انگلیسی (برای حمل بینالمللی)
|
||
کپی از DHL طراحی منحصر به فرد IFNEX
|
||
استفاده از wire:click برای دانلود استفاده از <a href> با روت مستقیم
|
||
getFormActions() در Custom Pages استفاده از wire:click در Blade
|
||
هدایت AJAX به redirect() استفاده از payment_url در response JSON
|
||
متدهای نوتیفیکیشن بیرون از کلاس داخل کلاس IFNEX_User_Bridge
|
||
📌 نکات ویژه برای ایجنت (DeepSeek Flash)
|
||
هنگام تولید کد جدید، حتماً از Enumها به جای رشتههای سختکد شده استفاده کن.
|
||
|
||
برای هر مدل جدید، migration، مدل، و در صورت نیاز کنترلر/ریسورس Filament بساز.
|
||
|
||
خطاهای رایج:
|
||
|
||
عدم وجود فیلد deleted_at در کوئریها (از SoftDeletes استفاده کن).
|
||
|
||
فراموشی fillable یا casts در مدلها.
|
||
|
||
فراموشی $with برای بارگذاری روابط در Resourceها.
|
||
|
||
استفاده از redirect() در کنترلرهای API (باید JSON برگردانند).
|
||
|
||
برای تغییر وضعیت مرسوله، حتماً تایملاین را بهروز کن (مدل ShipmentStatusHistory).
|
||
|
||
در فرم سفارش مشتری، مرحله Invoice فقط برای نوع PARCEL نمایش داده شود.
|
||
|
||
تولید PDF با بارکد بهصورت base64 embed انجام شود.
|
||
|
||
Bridge Auth نیازی به رمز عبور ندارد؛ فقط از IFNEX_BRIDGE_API_KEY استفاده میکند.
|
||
|
||
تست لوکال پرداخت: از ZARINPAL_MERCHANT_ID=fake-merchant-id-for-testing برای فعالسازی Mock Gateway استفاده کن.
|
||
|
||
مدیریت تاریخ: همیشه از Carbon استفاده کن و تاریخ را بهصورت Y-m-d H:i:s در DB ذخیره کن.
|
||
|
||
برای کوئریهای سنگین، از chunk() یا cursor() استفاده کن تا حافظه مصرف نشود.
|
||
|
||
|
||
📚 مستندات مرجع (برای مطالعه بیشتر)
|
||
فایل محتوا
|
||
01_Documents/EXCEL_ANALYSIS.md تحلیل کامل فایلهای اکسل (۳۹۵۰ رکورد، فرمولها، زونها)
|
||
01_Documents/IFNEX_Phase0_Checklist.md چکلیست کامل فازها (۰ تا ۳.۵)
|
||
01_Documents/IFNEX_Roadmap.md نقشه راه ۵ فازی
|
||
01_Documents/IFNEX_File_Map.md نقشه ۱۰۰+ فایل پروژه
|
||
01_Documents/IFNEX_I18N_Strategy.md استراتژی چندزبانه (برای زمان دیپلوی)
|
||
01_Documents/IFNEX_Commercial_Model.md مدل تجاری و پلنهای فروش
|
||
01_Documents/DESIGN_SYSTEM.md رنگها، تایپوگرافی، فاصلهگذاری
|
||
DEPLOYMENT.md راهنمای کامل استقرار روی سرور
|
||
04_Laravel/README.md راهنمای بکاند
|
||
تاریخ: 2026-09-02
|
||
نسخه: 1.0
|
||
تهیهکننده: VernaSoft Group — Kazem Alghasi
|
||
مدل هدف: DeepSeek Flash (API)
|
||
|