ifnex/AGENT.md

# IFNEX Logistics Management System — Agent Guide

> **هدف:** راهنمای جامع برای دستیار هوش مصنوعی جهت درک سریع پروژه، معماری، قراردادها و نکات کلیدی.
>
> **نسخه:** 1.1  
> **تاریخ:** 2026-09-10  

---

## 🎯 خلاصه پروژه

سیستم مدیریت لجستیک بین‌المللی با معماری Headless (Laravel 11 به‌عنوان بک‌اند، WordPress به‌عنوان فرانت‌اند، Filament 3.3 به‌عنوان پنل مدیریت). جایگزین فرآیندهای دستی مبتنی بر اکسل شده و از Multi-Package، فاکتور گمرکی (Invoice)، کیف پول دیجیتال، درگاه پرداخت Zarinpal، تولید PDF با بارکد، فلوی تأیید سفارش، تعهدنامه، SMS کاوه‌نگار و سیستم رهگیری پیشرفته پشتیبانی می‌کند.

**وضعیت فعلی:** فازهای ۰، ۱، ۲، ۳ و ۳.۵ تکمیل شده‌اند. **فاز ۳.۶ (اصلاحات جلسه کارفرما — فلوی تأیید سفارش، تعهدنامه و دانلود اسناد، SMS کاوه‌نگار، Audit Log، وضعیت مالی مشتری)** حدود ۸۰٪ انجام شده است؛ فهرست دقیق باقی‌مانده در بخش «کارهای باقی‌مانده» همین سند و سکشن فاز ۳.۶ در `01_Documents/IFNEX_Roadmap.md` آمده است. چندزبانه (i18n) همچنان به زمان دیپلوی موکول است.

---

## 🧰 تکنولوژی‌ها و نسخه‌ها

| لایه | تکنولوژی | نسخه / توضیح |
|------|-----------|--------------|
| **Backend** | Laravel | 11.x |
| **PHP** | PHP | ^8.2 (۸.۳ نیز پشتیبانی می‌شود) |
| **Admin Panel** | Filament | 3.3.x |
| **Frontend** | WordPress | 7.x + قالب سفارشی IFNEX |
| **Authentication** | Laravel Sanctum + Bridge Auth | بدون رمز عبور (API Key مشترک) |
| **Payment** | Zarinpal + Mock Gateway (تست) | کلید sandbox برای تست لوکال |
| **PDF & Barcode** | Dompdf + picqer/php-barcode-generator | تولید AWB، Invoice، Label، فاکتور واردات |
| **SMS** | Kavenegar | تأیید موبایل + اعلان وضعیت سفارش |
| **Excel** | maatwebsite/excel | Import/Export نرخ‌ها و داده‌های تاریخی |
| **Date/Time** | morilog/jalali + Carbon | تاریخ شمسی در نمایش، میلادی در DB |
| **Database** | MySQL | 8.0+ (تست‌ها با SQLite) |
| **Queue** | Redis (ترجیح) / Database | برای پردازش‌های سنگین |
| **Server** | HestiaCP + Nginx + PHP-FPM | تولید (api.ifnex.vernahost.ir) |

---

## 📂 ساختار دایرکتوری (کلیدی)

```
IFNEX-Logistics/
├── 01_Documents/          # مستندات فنی (تحلیل اکسل، نقشه راه، چک‌لیست، ...)
├── 03_WordPress/          # فرانت‌اند وردپرس
│   ├── wp-content/themes/ifnex/       # قالب سفارشی
│   └── wp-content/plugins/ifnex-bridge/  # پلاگین ارتباط با لاراول
├── 04_Laravel/            # بک‌اند لاراول (هسته اصلی)
│   ├── app/
│   │   ├── Enums/         # ShipmentStatus, ShipmentDirection, ShipmentType, PaymentGateway, TransactionStatus
│   │   ├── Filament/      # ۱۷ Resource + Pages (Settings, ImportRates, BulkTrackingImport, FinancialReport) + Widgets
│   │   ├── Http/Controllers/Api/  # Track, Pricing, Auth, Bridge, Customer, Wallet, Payment, Staff, CommitmentForm, ...
│   │   ├── Http/Middleware/       # ApiKeyMiddleware
│   │   ├── Models/        # ۲۲ مدل (Shipment, ShipmentPackage, CommitmentForm, Wallet, ...)
│   │   ├── Notifications/ # DB notifications + SMS (ShipmentApprovedSms, PaymentSuccessSms, SmsChannel, ...)
│   │   ├── Observers/     # ShipmentObserver (تریگر نوتیفیکیشن/SMS روی تغییر وضعیت)
│   │   ├── Services/      # PriceCalculator, Pdf, Tracking, OrderPayment, Wallet, Zarinpal, KavenegarSms
│   │   ├── Traits/        # Auditable
│   │   ├── Imports/       # OldShipmentsImport, ShippingRatesImport
│   │   └── Exports/       # ShippingRatesTemplateExport
│   ├── database/migrations/   # ۳۸+ migration
│   ├── resources/views/pdfs/  # awb, invoice, label, import-invoice (با بارکد)
│   └── routes/api.php         # ۴۰+ endpoint
├── AGENT.md               # همین سند
├── DEPLOYMENT.md          # راهنمای استقرار در سرور
└── README.md              # معرفی کلی پروژه
```

---

## 🔑 مفاهیم کلیدی بیزینس

### ۱. مرسوله (Shipment)
- **انواع (Type):** `DOC_NORMAL`، `DOC_ECONOMY`، `PARCEL`
- **جهت (Direction):** `export` (صادرات) و `import` (واردات)
- **وضعیت (Status):** `pending_approval` → `approved` → `processed` → `picked_up` → `in_transit` → `out_for_delivery` → `delivered` / `failed` / `returned` / `cancelled` (+ `pending_payment` legacy و `archived`)
- **ویژگی‌ها:** دارای چند بسته (`packages`)، اقلام گمرکی (`items` - فقط برای PARCEL)، تاریخچه تغییرات وضعیت (`statusHistories`)، شرکت‌های حمل (`carrierMappings`)، رویدادهای رهگیری (`trackingEvents`)، تعهدنامه‌ها (`commitmentForms`).

### ۲. بسته (Package)
- هر مرسوله می‌تواند چندین بسته داشته باشد (جدول `shipment_packages`).
- وزن حجمی = `(Length × Width × Height) / 5000` (استاندارد IATA).
- وزن قابل پرداخت = `max(وزن واقعی, وزن حجمی)`.

### ۳. فاکتور گمرکی (Invoice)
- فقط برای مرسوله‌های نوع `PARCEL` صادر می‌شود.
- حداکثر ۹ قلم کالا (شرح، HS Code، تعداد، قیمت واحد، مجموع به USD).
- مجموع کل فاکتور در `shipments.invoice_total_usd` ذخیره می‌شود.
- **فاکتور واردات (Import Invoice):** فیلدهای brand_fee, report_fee, customs_clearance_cost, order_registration_fee و... + قالب PDF مطابق شیت ENG Invoice.

### ۴. کیف پول (Wallet)
- هر کاربر یک کیف پول دارد.
- تراکنش‌ها (`WalletTransaction`) با نوع `deposit`، `order_payment`، `refund`، `withdrawal` — به‌صورت polymorphic به Payment/سفارش متصل است.
- پرداخت از کیف پول یا درگاه Zarinpal (با Mock برای تست). freeze/unfreeze + activity log کامل.

### ۵. احراز هویت Bridge
- کاربران وردپرس بدون نیاز به رمز عبور، از طریق `POST /api/v1/bridge/login` با ارسال `bridge_api_key` و `wp_user_id` وارد لاراول می‌شوند.
- پاسخ شامل `token` Sanctum (معتبر ۳۰ روز) و اطلاعات کاربر است.
- کلید `IFNEX_BRIDGE_API_KEY` باید در هر دو طرف (`.env` لاراول و تنظیمات پلاگین وردپرس) یکسان باشد.
- توکن در usermeta کاربر وردپرس (`ifnex_laravel_token`) ذخیره می‌شود و روی 401 خودکار باطل/تجدید می‌شود.

### ۶. رهگیری (Tracking)
- کاربر با شماره AWB جستجو می‌کند.
- سیستم رویدادهای رهگیری را از جدول `shipment_tracking_events` با `source` (manual, api, import, system, customer) نمایش می‌دهد.
- ایمپورت گروهی وضعیت ترکینگ با CSV از پنل (صفحه BulkTrackingImport).

### ۷. قیمت‌گذاری (Pricing)
- بر اساس ۴ زون مجزا (Export/Import × Parcel/Doc) و ۳ نوع سرویس.
- فرمول: قیمت پایه (AED) × ضریب سود × نرخ تبدیل به ریال + هزینه‌های جانبی (Packing, Domestic Pickup, ...) + VAT (۹٪).
- محموله‌های بالای ۳۰ کیلوگرم مشمول نرخ ویژه (Spot Rate) هستند و محاسبه آنلاین ندارند.

### ۸. فلوی تأیید سفارش (Approval Flow)
- مشتری بعد از ثبت سفارش، **مستقیم به درگاه نمی‌رود**؛ سفارش با وضعیت `pending_approval` ثبت می‌شود.
- کارمند/مدیر از پنل فیلمنت (اکشن تأیید در ShipmentResource) یا API (`/staff/orders/{id}/approve|reject`) تأیید می‌کند.
- فقط بعد از `approved`، گزینه‌های پرداخت (کیف پول / درگاه) در وردپرس باز می‌شود؛ پرداخت موفق سفارش را `processed` می‌کند (PaymentController در callback با `is_order_payment` در metadata).
- سفارش‌های `approved` (پرداخت‌نشده) روی مانده حساب کاربر (account_balance در profile) اثر می‌گذارند.

### ۹. تعهدنامه و اسناد سفارش (Commitment Forms)
- مدیر فرم‌های تعهدنامه را در فیلمنت (`CommitmentFormResource`) آپلود می‌کند (با direction: export/import/both).
- مشتری در جزئیات سفارش وردپرس، لیست تعهدنامه‌ها را می‌بیند → دانلود/پرینت/امضا → آپلود فایل امضاشده (`POST /orders/{shipment}/commitment-forms/{form}/upload`)؛ ثبت در جدول `shipment_commitment_forms`.
- دانلود AWB / Invoice / Label هم از همین بخش (`/orders/{shipment}/pdf/*`) انجام می‌شود.
- ⚠️ هنوز چک مالکیت (ownership) در کنترلر PDF/تعهدنامه اضافه نشده — کار باقی‌مانده.

### ۱۰. اعلان‌ها و SMS کاوه‌نگار
- تنظیمات از `SystemSetting` خوانده می‌شود (`kavenegar_api_key` + سوییچ هر نوع پیام مثل `kavenegar_send_shipment_approved`).
- نوتیفیکیشن‌ها: `ShipmentApprovedSms`، `ShipmentRejectedSms`، `PaymentSuccessSms`، `TrackingUpdatedSms` + کانال `SmsChannel`.
- تریگر اصلی: `ShipmentObserver` (روی تغییر وضعیت Shipment) و PaymentController (پرداخت موفق). تأیید موبایل: `MobileVerificationController`.
- در `.env` لوکال کلید کاوه‌نگار خالی است؛ تا وقتی تنظیم نشود SMS ارسال نمی‌شود (فقط DB notification).

### ۱۱. اعتبار مشتری (Credit) — نیمه‌کاره
- فعلاً فقط دو ستون `credit_limit/credit_used` روی جدول users + `CustomerCreditResource` در فیلمنت.
- ⚠️ اکشن‌های افزایش/کاهش اعتبار هنوز روی ستون‌های ناموجود `wallet_transactions.user_id` و تایپ‌های `credit_add/credit_reduce` می‌نویسند (خراب) و اعتبار در فلوی سفارش/پرداخت هم استفاده نشده.
- نیاز کارفرما: بدهی به **ارز سفارش** (مثلاً ۵۰ یورو بدهکار) + تسویه ریالی با نرخ روز → نیاز به بازطراحی دارد.

### ۱۲. Audit Log
- trait `App\Traits\Auditable` روی مدل‌های اصلی (User, Shipment, Wallet, ...) اعمال شده و در `AuditLogResource` قابل مشاهده است.
- `ShipmentStatusHistory` با ستون‌های `from_status/to_status/reason` + ثبت نام کاربر تغییردهنده.

---

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

```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 {path}
php artisan ifnex:import:shipments {path}
php artisan ifnex:import:tracking {path}

# بروزرسانی نرخ ارز (کرون)
php artisan ifnex:update-rates --source=ecb

# تولید API Token برای ادمین
php artisan ifnex:token
```

## 🧪 متغیرهای محیطی کلیدی (.env)

```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

# Kavenegar SMS (خالی = فقط DB notification)
KAVENEGAR_API_KEY=
KAVENEGAR_SENDER=10008566

# 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 |
| روت staff/admin بدون چک نقش | چک نقش/مالکیت در middleware یا ابتدای کنترلر |
| سفارش مستقیم به درگاه بعد از ثبت | فلوی pending_approval → approved → پرداخت |

## 📌 نکات ویژه برای ایجنت

- هنگام تولید کد جدید، حتماً از Enum‌ها به جای رشته‌های سخت‌کد شده استفاده کن.
- برای هر مدل جدید، migration، مدل، و در صورت نیاز کنترلر/ریسورس Filament بساز.
- خطاهای رایج:
  - عدم وجود فیلد deleted_at در کوئری‌ها (از SoftDeletes استفاده کن).
  - فراموشی fillable یا casts در مدل‌ها.
  - فراموشی $with برای بارگذاری روابط در Resourceها.
  - استفاده از redirect() در کنترلرهای API (باید JSON برگردانند).
- برای تغییر وضعیت مرسوله، حتماً تاریخچه را به‌روز کن (مدل ShipmentStatusHistory با from_status/to_status/reason).
- در فرم سفارش مشتری، مرحله 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() استفاده کن تا حافظه مصرف نشود.
- **هنگام استفاده از هر Model در فایل جدید، حتماً `use App\Models\...` را import کن** — باگ اخیر `SystemSetting` در PaymentController/ShipmentObserver/TrackingService فلوی تأیید/پرداخت را می‌شکست (در کامیت `2737e26` رفع شد).
- **در مارک‌آپ شورت‌کدهای وردپرس، باز/بسته بودن div ها را متوازن نگه دار** — باگ «مرحله ۲ فرم سفارش لود نمی‌شود» ریشه‌اش یک div بسته‌نشده در shortcodes.php بود که مراحل را داخل هم nest می‌کرد؛ هک‌های MutationObserver/setInterval هیچ‌کدام مشکل را حل نمی‌کردند و حذف شدند.
- **هک‌های موقت دیباگ** (`opcache_reset()` و `header()` بالای فایل‌های پلاگین، cache-buster با `time()`) فقط برای کار لوکال هستند و قبل از دیپلوی باید حذف شوند.

## 🧭 کارهای باقی‌مانده (فاز ۳.۶ — به‌روزرسانی 2026-09-10)

| # | کار | وضعیت |
|---|-----|-------|
| 1 | تست انتهای فلوی سفارش: آپلود تعهدنامه → تأیید کارمند → پرداخت کیف پول/درگاه | ⏳ اولویت اول |
| 2 | امنیت: چک نقش روی `/staff/*`، چک مالکیت PDF/تعهدنامه، ثبت شورت‌کد `[ifnex_wallet_charge]` (صفحه /wallet/ خراب است)، محدودسازی `GET /discount-codes`، rate limiting | ⏳ |
| 3 | بازطراحی سیستم اعتبار (بدهی چندارزی مطابق نیاز کارفرما) + رفع اکشن‌های `CustomerCreditResource` | ⏳ |
| 4 | چک‌لیست خودکار کارمند بعد از تأیید سفارش + نمایش در صفحه سفارش (فعلاً فقط CRUD دستی) | ⏳ |
| 5 | سند پیشنهادی سیستم مالی (درخواست ۱۳ کارفرما) | ⏳ |
| 6 | پاک‌سازی: opcache_reset/header ها، cache-buster `time()`، هک‌های `!important` CSS، صفحات تستی منتشرشده، پلاگین ifnex-bridge-test، فایل‌های آشغال ریشه | ⏳ |
| 7 | نمایش وزن واقعی/حجمی در خلاصه قیمت وردپرس (API فیلد `weight` را برنمی‌گرداند) | ⏳ |
| 8 | چندزبانه (i18n) — به زمان دیپلوی موکول شده | ⏳ |

---

## 📚 مستندات مرجع (برای مطالعه بیشتر)

| فایل | محتوا |
|------|-------|
| 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-10
نسخه: 1.1
تهیه‌کننده: VernaSoft Group — Kazem Alghasi