ifnex/AGENT.md

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) هستند و محاسبه آنلاین ندارند.

---

⚙️ دستورات روزمره (برای ایجنت)

# نصب وابستگی‌ها
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)