# IFNEX Logistics — Backend (Laravel 11)

> بخش بک‌اند سیستم لجستیک ایف‌نکس. این پوشه به تنهایی یک اپلیکیشن لاراول ۱۱ کامل است.

---

## 🚀 راه‌اندازی سریع

```bash
composer install
cp .env.example .env
php artisan key:generate
php artisan migrate --force
php artisan db:seed --force
php artisan serve
```

---

## 📦 پکیج‌های اصلی

| پکیج | نسخه | نقش |
|------|------|-----|
| `laravel/framework` | ^11.0 | هسته فریم‌ورک |
| `filament/filament` | 3.3.* | پنل مدیریت ادمین |
| `maatwebsite/excel` | ^3.1 | ایمپورت اکسل |
| `barryvdh/laravel-dompdf` | ^3.1 | تولید PDF |
| `dompdf/dompdf` | ^3.0 | موتور تولید PDF |
| `morilog/jalali` | ^3.0 | تبدیل تاریخ شمسی/میلادی |

---

## 📁 ساختار کد

```
04_Laravel/
├── app/
│   ├── Models/              # مدل‌های Eloquent
│   ├── Enums/               # Enumهای سفارشی
│   ├── Services/            # PriceCalculatorService, PdfService, ...
│   ├── Http/
│   │   ├── Controllers/
│   │   │   ├── Api/         # PricingController, TrackController
│   │   │   ├── OrderController.php
│   │   │   ├── PricingPageController.php
│   │   │   └── ShipmentPdfController.php
│   │   ├── Middleware/       # ApiKeyMiddleware
│   │   └── Requests/        # Form Request Validation
│   ├── Imports/             # ShippingRatesImport
│   ├── Console/Commands/    # ImportShippingRates
│   └── Filament/            # پنل مدیریت
│       ├── Resources/       # Country, Shipment, ShippingRate, ShipmentItem
│       └── Pages/           # Settings, Dashboard
├── database/
│   ├── migrations/          # ۷ migration فاز ۰
│   └── seeders/             # seeders داده اولیه
├── routes/
│   ├── web.php              # /order, /pricing, PDF downloads
│   └── api.php              # /api/v1/calculate, /api/v1/track/{awb}
└── config/
    ├── ifnex.php            # تنظیمات اختصاصی
    └── cors.php             # تنظیمات CORS
```

---

## 🔌 API Endpoints

| روش | مسیر | توضیحات |
|------|------|---------|
| POST | `/api/v1/calculate` | محاسبه قیمت حمل (بدون احراز هویت) |
| GET | `/api/v1/track/{awb_no}` | استعلام وضعیت مرسوله با API Key |

**درخواست نمونه محاسبه قیمت:**
```bash
curl -X POST http://localhost:8000/api/v1/calculate \
  -H "Content-Type: application/json" \
  -d '{
    "direction": "Outbound",
    "type": "DOC_NORMAL",
    "country_iso": "AE",
    "weight": 1,
    "volumetric_weight": 1
  }'
```

---

## 🛠️ دستورات Artisan سفارشی

```bash
# ایمپورت نرخ‌های حمل از اکسل
php artisan ifnex:import:rates {path} [--clear] [--dry-run]

# ایمپورت داده‌های ترکینگ
php artisan ifnex:import:tracking {path}
```

---

## 🌐 صفحات عمومی

| مسیر | توضیحات |
|------|---------|
| `/` | صفحه اصلی |
| `/order` | فرم ثبت سفارش آنلاین |
| `/order/success/{shipment}` | صفحه تایید سفارش |
| `/pricing` | صفحه استعلام قیمت |
| `/shipments/{id}/pdf/awb` | دانلود AWB (نیاز به لاگین) |
| `/shipments/{id}/pdf/invoice` | دانلود INVOICE (نیاز به لاگین) |
| `/shipments/{id}/pdf/label` | دانلود LABEL (نیاز به لاگین) |

---

## 🔐 احراز هویت و دسترسی

| نقش | دسترسی |
|------|--------|
| `super_admin` | دسترسی کامل به همه بخش‌های Filament |
| `tracking_operator` | مدیریت ترکینگ و رویدادها |
| `data_entry` | وارد کردن داده‌های مرسوله |
| `customer` | دسترسی محدود (در فاز بعدی) |

---

## ⚠️ نکات مهم

- **Laravel 11** — با سوییچ از v12 انجام شد
- **Livewire 3.8.3** — فرم‌ها با AJAX کار می‌کنند، POST مستقیم به `/admin/login` ثبت نمی‌شود
- **Filament 3.3.x** — پنل مدیریت در مسیر `/admin`
- **MySQL 8+** — الزام migrations با JSON columns
- **DomPDF** — برای تولید PDFهای AWB, INVOICE, LABEL استفاده می‌شود

---

## 📚 مستندات بیشتر

برای اطلاعات کامل‌تر به پوشه `01_Documents` در ریشه پروژه مراجعه کنید:
- `STATUS.md` — وضعیت فعلی و گزارش پیشرفت
- `IFNEX_Phase0_Checklist.md` — چک‌لیست دقیق فاز ۰
- `Phase0_Proposal.md` — مرجع اصلی پروژه
- `EXCEL_ANALYSIS.md` — تحلیل کامل فایل‌های اکسل عملیاتی

---

## 📜 لایسنس

© 2026 VernaSoft Group (Kazem Alghasi). All rights reserved.

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