# 🚨 STATUS.md — این فایل را اول بخوانید

> ⚠️ **به‌روزرسانی 2026-09-10:** این سند تا **10 آگوست 2026** به‌روزرسانی شده و تاریخچه فازهای ۰ تا ۳ را پوشش می‌دهد. **وضعیت جاری پروژه (فاز ۳.۵ ✅ و فاز ۳.۶ — اصلاحات جلسه کارفرما 🟡 ۸۰٪) در [`AGENT.md`](../AGENT.md) و [`IFNEX_Roadmap.md`](IFNEX_Roadmap.md) نگهداری می‌شود** — برای وضعیت فعلی و کارهای باقی‌مانده آن دو سند را ببینید. بخش‌های پایین این فایل را به‌عنوان تاریخچه و مرجع خط قرمزها بخوانید.

> **آخرین به‌روزرسانی محتوا:** 2026-08-10 13:08 (Asia/Tehran)  
> **فاز در حال اجرا (فعلی):** فاز ۳.۶ — اصلاحات جلسه کارفرما (تاریخچه: این سند تا فاز ۳ را ثبت کرده است)  
> **توسعه‌دهنده:** VernaSoft Group — Kazem Alghasi  
> **وضعیت کلی پروژه:** فاز ۰ کامل — فاز ۱ کامل — فاز ۲ کامل — فاز ۳ کامل — فاز ۳.۵ کامل — فاز ۳.۶ در حال تکمیل (۸۰٪)

---

## ⚠️ هشدار حیاتی — قبل از هر کاری بخوانید

این پروژه دارای **سه سند تاریخی** است که با هم تناقض دارند. فقط یکی از آن‌ها معتبر است:

| فایل | وضعیت | اقدام |
|------|-------|-------|
| `01_Documents/Phase0_Proposal.md` | 🗄️ حذف شده از مخزن | محتوای معتبر آن در `AGENT.md` و `IFNEX_Roadmap.md` ادغام شده است |
| `01_Documents/PRD_v2.md` (در archives) | ❌ قدیمی و ناقص | فقط برای مرجع تاریخی — به اسکیمای دیتابیس آن اعتماد نکنید |
| `01_Documents/Project_Roadmap.md` (در archives) | ❌ قدیمی (۳ فازی) | فقط برای مرجع تاریخی — به فازبندی آن اعتماد نکنید |
| `01_Documents/EXCEL_ANALYSIS.md` | ✅ **مرجع تحلیل اکسل** | حتماً بخوانید قبل از کار با داده‌های تاریخی |
| `README.md` (ریشه) | ✅ به‌روز | برای نمای کلی بخوانید |
| `AGENT.md` (ریشه) | ✅ **مرجع اصلی وضعیت و قراردادها** | اول این را بخوانید |

> 🔴 **قانون طلایی:** هرجا بین اسناد تناقض دیدی، به `Phase0_Proposal.md` اعتماد کن. اسناد قدیمی فقط برای فهم تاریخچه‌ی تصمیمات نگه داشته شده‌اند.

---

## 📌 Quick Reference — نسخه‌ها و معماری

### تکنولوژی‌ها (قفل‌شده)
| مورد | نسخه/مقدار | دلیل |
|------|------------|------|
| Laravel | **11** (همه‌جا یکسان) | در PRD قدیمی ۱۰+ نوشته، در Roadmap قدیمی ۱۱، در README قدیمی ۱۲ — نسخه نهایی: **۱۱** |
| PHP | 8.2+ | الزام لاراول ۱۱ |
| MySQL | 8+ | برای پشتیبانی JSON columns |
| WordPress | ۷.۰.۳ | با پوسته سفامشی IFNEX + Polylang برای چندزبانه |
| پنل ادمین | Laravel Filament 3.3.x | رنگ Navy gradient، فونت Vazirmatn، RTL کامل |
| Frontend | وردپرس + پوسته IFNEX | **کپی نکنید** — فقط الهام |
| Authentication | Laravel Sanctum | توکن‌های Bearer برای API مشتری |
| Permissions | spatie/laravel-permission | RBAC برای پنل ادمین |
| Payment Gateway | زرین‌پال (Zarinpal) | با Mock Gateway برای تست |
| Design System | IFNEX Design System | رنگ‌های برند، فاصله‌گذاری، تایپوگرافی یکپارچه |

### معماری کلی
```
┌─────────────────┐         REST API         ┌─────────────────┐
│   WordPress     │  ←─────────────────────→  │   Laravel 11    │
│  (Frontend)     │   پلاگین IFNEX Bridge     │   (Backend)     │
│                 │                           │  + Filament     │
└─────────────────┘                           └────────┬────────┘
                                                        │
                                               ┌────────┴────────┐
                                               │     MySQL 8     │
                                               └─────────────────┘
                                                        │
                                               (فاز ۳)  │
                                               ┌────────┴────────┐
                                               │  VPS پل خارج    │
                                               │  (هلند/آلمان)   │
                                               └────────┬────────┘
                                                        │
                                               ┌────────┴────────┐
                                               │ TrackingMore /  │
                                               │ 17track API     │
                                               └─────────────────┘
```

---

## ✅ وضعیت فعلی کار

### کارهای انجام‌شده (تا تاریخ 2026-08-04)

#### ۱. اسکیمای دیتابیس فاز ۰ (کامل)
- [x] بازنویسی migration `countries` با ۴ زون مجزا + `iso_code` + `is_active`
- [x] بازنویسی migration `shipments` مطابق Phase 0 (فیلدهای مالی + ۴ زون + nullable حقایل)
- [x] بازنویسی migration `shipping_rates` با enum `direction` و `type` (DOC_NORMAL/DOC_ECONOMY/PARCEL)
- [x] ایجاد migration `shipment_carrier_mappings` (جدول جدید — نگاشت چند شرکت حمل)
- [x] ایجاد migration `shipment_tracking_events` (جدول جدید — تایم‌لاین رویدادها)
- [x] ایجاد migration `system_settings` (جدول جدید — key-value برای VAT، نرخ ارز و...)
- [x] ایجاد migration `update_users` (افزودن `phone`, `role`, `is_active`)
- [x] ایجاد migration `shipment_items` (جدول جدید — اقلام گمرکی)
- [x] حل مشکل `unsignedDecimal` در Laravel 11 (استفاده از `decimal()->unsigned()`)
- [x] حل مشکل FK constraints در migrations (استفاده از `disableForeignKeyConstraints()`)
- [x] اجرای همه migrations در MySQL بدون خطا

#### ۲. مدل‌ها و Enums (کامل)
- [x] بازنویسی `Country.php` + روابط `fromShipments()` / `toShipments()`
- [x] بازنویسی `Shipment.php` + روابط `fromCountry()`, `toCountry()`, `items()`, `carrierMappings()`, `trackingEvents()`
- [x] بازنویسی `ShippingRate.php` + cast برای enums
- [x] بازنویسی `User.php` + فیلدهای `phone`, `role`, `is_active` + helper methods
- [x] ایجاد مدل‌های جدید:
  - `ShipmentCarrierMapping.php`
  - `ShipmentTrackingEvent.php`
  - `SystemSetting.php`
  - `Wallet.php` + `WalletTransaction.php`
  - `DiscountCode.php`
  - `ExchangeRateHistory.php`
  - `Role.php` (spatie/laravel-permission)
- [x] ایجاد ۶ enum:
  - `ShipmentDirection` (import/export)
  - `ShipmentType` (DOC_NORMAL/DOC_ECONOMY/PARCEL)
  - `ShipmentStatus` (۹ وضعیت شامل pending_payment/cancelled)
  - `CarrierCode` (DHL/FEDEX/UPS/ARAMEX/NAGHEL/EMX/APSITEX/IMPEX/OTHER)
  - `TrackingSource` (۵ منبع: manual/api/import/system/customer)
  - `TransactionType` + `TransactionStatus`
  - `PaymentGateway` (zarinpal/wallet/manual/system)
  - `UserRole` (super_admin/tracking_operator/data_entry/customer)

#### ۳. Seeders (کامل)
- [x] بازنویسی `CountriesTableSeeder` با ۲۳۳ کشور + ۴ زون + iso_code تصحیح‌شده
  - تصحیح کدهای ISO نادرست (Bonaire BQ، Curacao CW، حذف Somaliland XS)
  - حذف کشورهای تکراری ("United Arab Emirates" و "Rest of Dubai" هر دو با zone 9 و 10)
- [x] ایجاد `SystemSettingSeeder` (VAT 9%، packing 100000 IRR، profit_margin 1.25، نرخ ارزهای اولیه)
- [x] بازنویسی `DatabaseSeeder` (countries + system_settings + super_admin user)
- [x] ایجاد `RoleAndPermissionSeeder` (نقش‌های اولیه + دسترسی‌های پایه)
- [x] ایجاد `SampleDataSeeder` (۵ مرسوله، ۴ تراکنش، ۳ کد تخفیف)
- [x] اجرای seeders — ۲۳۲ کشور + ۷ setting + ۱ کاربر ادمین

#### ۴. API ترکینگ (کامل)
- [x] ایجاد `TrackController` با JSON response کامل (shipment + carrier_mappings + timeline)
- [x] ایجاد `ApiKeyMiddleware` (Bearer token validation)
- [x] ثبت route `GET /api/v1/track/{awb_no}` با middleware API Key
- [x] تست‌های موفق:
  - `GET /api/v1/track/TEST123` با API Key صحیح → **200 OK**
  - بدون API Key → **401 Unauthorized**
  - با API Key نامعتبر → **403 Forbidden**

#### ۵. Filament Resources (کامل)
- [x] `CountryResource` — فرم ۴ زون + iso_code + is_active + فیلترها
- [x] `ShipmentResource` — فرم کامل با ۷ Section + RelationManagers
  - Section: Route & Status
  - Section: Weight & Dimensions
  - Section: Financial Info (۱۱ فیلد مالی)
  - Section: Sender Info
  - Section: Receiver Info
  - Section: Customs Items (Repeater ۹ ردیف)
- [x] `ShippingRateResource` — فرم ۱۰ zone + enum type/direction
- [x] `ShipmentItemResource` — CRUD کامل
- [x] `WalletResource` — مدیریت کیف پول
- [x] `WalletTransactionResource` — CRUD کامل با صفحات Create/Edit
- [x] `PaymentResource` — مشاهده تراکنش‌های درگاه
- [x] `DiscountCodeResource` — مدیریت کدهای تخفیف با form/table/filters
- [x] `ExchangeRateHistoryResource` — مشاهده تاریخچه نرخ ارز
- [x] `RoleResource` — مدیریت نقش‌ها (spatie/laravel-permission)
- [x] `UserResource` — مدیریت کاربران (spatie/laravel-permission)
- [x] RelationManagers:
  - `CarrierMappingsRelationManager` (برای Shipment)
  - `TrackingEventsRelationManager` (برای Shipment)
- [x] Pages:
  - `ListShipments`, `CreateShipment`, `EditShipment`, `ViewShipment`
  - `ListCountries`, `CreateCountry`, `EditCountry`
  - `ListShippingRates`, `CreateShippingRate`, `EditShippingRate`
  - `ListShipmentItems`, `CreateShipmentItem`, `EditShipmentItem`
  - `ListWalletTransactions`, `CreateWalletTransaction`, `EditWalletTransaction`
  - `ListPayments`, `ViewPayment`
  - `ListDiscountCodes`, `CreateDiscountCode`, `EditDiscountCode`
  - `ListExchangeRateHistories`, `ViewExchangeRateHistory`
  - `ListRoles`, `CreateRole`, `EditRole`
  - `ListUsers`, `CreateUser`, `EditUser`
- [x] `SettingsPage` (Page سفارشی برای System Settings)
- [x] `DashboardInfoWidget` — اطلاعات کلی داشبورد
- [x] `ExchangeRateWidget` — نرخ ارز زنده
- [x] `WalletStats` — آمار کیف پول
- [x] `TransactionChartWidget` — نمودار تراکنش‌ها
- [x] `RecentTransactionsWidget` — آخرین تراکنش‌ها
- [x] `FinancialReport` — گزارش مالی کامل

#### ۶. Services (کامل)
- [x] `TrackingService` — getTrackingTimeline, addTrackingEvent, getShipmentWithTracking
- [x] `PriceCalculatorService` — محاسبه قیمت کامل مطابق EXCEL_ANALYSIS.md
  - مرحله ۱: وزن حجمی
  - مرحله ۲: وزن قابل پرداخت
  - مرحله ۳: استخراج زون از ۴ زون مجزا
  - مرحله ۴: استخراج قیمت پایه از shipping_rates
  - مرحله ۵: اعمال ضریب سود
  - مرحله ۶: تبدیل درهم به ریال
  - مرحله ۷: اضافه هزینه‌های جانبی
  - مرحله ۸: اعمال VAT 9%
  - مرحله ۹: ذخیره خروجی‌ها
- [x] `ExchangeRateService` — مدیریت و ردیابی نرخ ارز
- [x] `ZarinpalService` — اتصال به درگاه پرداخت زرین‌پال
- [x] `MockZarinpalService` — شبیه‌سازی درگاه برای تست
- [x] `OrderPaymentService` — پرداخت سفارشات (کیف پول + درگاه)

#### ۷. Imports (Excel) (کامل)
- [x] `ShippingRatesImport` — import از ۵ شیت (Import Rate, Export Rate, DocNor, DocEco, Parcel)
  - ۴۰۴ رکورد import شد: DocNormal: ۷۴، DocEconomy: ۷۰، Parcel: ۲۶۰
- [x] `HistoricalShipmentsImport` — import از شیت List فایل اصلی
  - ⚠️ **مشکل:** فایل اکسل فقط ۲ ردیف داده واقعی دارد و بقیه فرمول‌های Excel هستند
  - ۱ رکورد (980100010) موفقیت‌آمیز import شد
- [x] Artisan Commands:
  - `ifnex:import:rates {path}`
  - `ifnex:import:shipments {path}`

#### ۸. سوییچ به Laravel 11 (کامل با نقص باقی‌مانده)
- [x] تغییر `composer.json`: `laravel/framework` از `^12.0` به `^11.0`
- [x] تغییر `morilog/jalali` از `^4.3` به `^3.0` (v4 وجود ندارد)
- [x] اجرای `composer update` — Laravel از v12.64.0 به v11.55.0 downgrade شد
- [x] رفع خطای PSR-4 در `SettingsPage.php`
- [x] رفع مشکل middleware در `bootstrap/app.php` برای Laravel 11
- [x] رفع خطای `MethodNotAllowedHttpException` برای POST `/admin/login`

#### ٩. پیکربندی (کامل)
- [x] اضافه کردن `IFNEX_API_KEY` به `.env.example`
- [x] اضافه کردن `CORS_ALLOWED_ORIGINS` به `.env.example`
- [x] اضافه کردن `IFNEX_TRACKING_RATE_LIMIT` به `.env.example`
- [x] ایجاد `config/ifnex.php` برای تنظیمات اختصاصی
- [x] تغییر `APP_LOCALE` به `fa` در `.env.example`
- [x] اضافه کردن `morilog/jalali` به `composer.json`
- [x] ایجاد `config/cors.php`

---

### 🔴 Code Review Findings — نیاز به رفع

| # | فایل | مشکل | وضعیت | راه‌حل |
|---|------|------|-------|-------|
| 1 | `bootstrap/app.php` | گروه `web` تعریف نشده | ✅ انجام شد | `$middleware->group('web', [...])` اضافه شد |
| 2 | `AdminPanelProvider.php` | Middlewareهای طولانی به صورت لیست دستی | ✅ انجام شد | استفاده از گروه `web` به جای لیست دستی |
| 3 | `bootstrap/app.php` | `statefulApi` تعریف نشده | 🟡 آینده | برای احراز هویت SPA در فاز بعد لازم است |

**توضیح مشکل #1:**
در Laravel 11، گروه `web` به‌صورت خودکار تعریف نمی‌شود. Filament برای لاگین نیاز به Session, Cookies, CSRF, ShareErrors دارد. فعلاً کار می‌کند چون در `AdminPanelProvider.php` همه Middlewareها به صورت لیست دستی نوشته شده‌اند، اما این روش **خوب نیست** و مطابق Laravel 11 conventions نیست. اگر جایی از `web` group استفاده شود، کار نمی‌کند.

**راه‌حل پیشنهادی برای `bootstrap/app.php`:**
```php
->withMiddleware(function (Middleware $middleware): void {
    $middleware->api(prepend: \Illuminate\Http\Middleware\HandleCors::class);

    $middleware->group('web', [
        \Illuminate\Cookie\Middleware\EncryptCookies::class,
        \Illuminate\Cookie\Middleware\AddQueuedCookiesToResponse::class,
        \Illuminate\Session\Middleware\StartSession::class,
        \Illuminate\View\Middleware\ShareErrorsFromSession::class,
        \Illuminate\Foundation\Http\Middleware\ValidateCsrfToken::class,
        \Illuminate\Routing\Middleware\SubstituteBindings::class,
    ]);
})
```

**راه‌حل پیشنهادی برای `AdminPanelProvider.php` بعد از تعریف گروه `web`:**
```php
->middleware([
    'web',
    \Filament\Http\Middleware\Authenticate::class,
])
```

---

### 🔴 مشکل — مهاجرت داده‌های تاریخی

**وضعیت:** فایل اکسل مرسولات فعلی فقط داده‌های نمونه/قدیمی دارد و برای import کامل مناسب نیست.
**راه‌حل:** هر فایل اکسل جدید که مشتری تحویل دهد، باید قابل import باشد. نیازی به مهاجرت همه داده‌های قدیمی نیست.
**فایل ترکینگ:** `01_Documents/Data entry 2026-06-28.xlsx` — شامل ۶ شیت: Sheet1, Refrence, Paste, copy, Delivered, test
**وضعیت:** **فایل موجود است** — مهاجrut داده‌های ترکینگ می‌تواند انجام شود.

---

### کارهای در دست اقدام (فاز ۰)

| اولویت | کار | وضعیت | توضیحات |
|--------|-----|-------|---------|
| 🔴 بالا | تست دستی کامل Filament (ورود + CRUD) | ✅ انجام شد | همه Resources + RelationManagers + Settings کار می‌کنند |
| 🟡 متوسط | مهاجرت داده‌های ترکینگ از `01_Documents/Data entry 2026-06-28.xlsx` | ✅ انجام شد | 98 رویداد import شد، 8 shipment |
| 🟡 متوسط | ساخت پلاگین وردپرس IFNEX Bridge | ✅ انجام شد | شورت‌کدهای [ifnex_tracking_form] و [ifnex_tracking_status] کار می‌کنند |
| 🟡 متوسط | تست API Track با نمونه‌های بیشتر | ✅ انجام شد | AWB 980100010 و 980103619 تست شدند |
| 🟢 پایین | تست نهایی فاز ۰ و تحویل به مشتری | ✅ انجام شد | همه موارد تست شدند |

---

### کارهای فاز ۱ (تکمیل شده)

- [x] موتور قیمت‌گذاری کامل (`PriceCalculatorService`) — نوشته شد، تست با داده‌های واقعی انجام شد
- [x] جدول `shipping_rates` — ۱۳۸ رکورد import شد با پشتیبانی از ۵ نوع سرویس/جهت
- [x] فرم ثبت سفارش آنلاین با ۹ ردیف کالای گمرکی
- [x] تولید PDF: AWB، INVOICE، Label — پیاده شد. قالب‌ها بر اساس ساختار شیت‌های اکسل و لوگوی استخراج‌شده طراحی شدند. استایل نهایی و تطبیق دقیق‌تر با قالب‌های اکسل در فاز بعدی انجام می‌شود.
- [x] ماژول ایمپورت اکسل تعرفه‌ها — command با قابلیت‌های --clear و --dry-run پیاده شد
- [x] صفحه استعلام قیمت واقعی — رابط کاربری عمومی + API محاسبه قیمت

---

### کارهای فاز ۲ (تکمیل شده)

- [x] ساخت `WalletController` با APIهای شارژ، بررسی موجودی و تاریخچه تراکنش‌ها
- [x] ساخت `DiscountCodeController` با APIهای لیست و اعتبارسنجی کده تخفیف
- [x] ساخت `UpdateExchangeRates` Artisan Command با پشتیبانی از ECB و FreeCurrencyAPI
- [x] ثبت routeهای کیف پول و تخفیف در `api.php`
- [x] اضافه کردن `CURRENCY_API_KEY` به `.env.example` و `config/ifnex.php`
- [x] پاک‌سازی فایل‌های تست و debug (`check_*.php`, `debug_*.php`, `test_*.php`, `inspect_*.php`)
- [x] رفع CORS — تغییر از `*` به دامنه مشخص از `.env`
- [x] حذف migration‌های قدیمی تکراری (`2023_10_27_*`, `2026_07_31_*`)
- [x] اتصال درگاه پرداخت (زرین‌پال) با Mock Gateway برای تست
- [x] ساخت `ZarinpalService` و `MockZarinpalService`
- [x] ساخت `OrderPaymentService` برای پرداخت سفارشات
- [x] ساخت `ExchangeRateService` و `ExchangeRateHistory` برای ردیابی نرخ ارز
- [x] پنل مالی در Filament (داشبورد سود/زیان)
- [x] تکمیل DiscountCodeResource با form/table/filters
- [x] ساخت PaymentResource در Filament
- [x] ساخت WalletTransactionResource با صفحات Create/Edit
- [x] ساخت ExchangeRateHistoryResource
- [x] تست‌های Unit/Feature برای Phase 2 (24 تست، 77 assertion)
- [x] رفع باگ WalletController::balance()
- [x] حذف PaymentGatewayService قدیمی (استفاده نمی‌شد)
- [x] زیباسازی داشبورد و صفحه لاگین Filament (رنگ Navy، Vazirmatn، RTL)
- [x] گسترش پلاگین IFNEX Bridge برای وردپرس:
  - [x] ساخت `IFNEX_User_Bridge` برای مدیریت توکن Sanctum کاربران وردپرس
  - [x] اضافه کردن شورت‌کد `[ifnex_wallet_balance]`
  - [x] اضافه کردن شورت‌کد `[ifnex_transactions]`
  - [x] اضافه کردن AJAX handlers برای کیف پول و تراکنش‌ها
  - [x] ساخت استایل‌های CSS کامل برای تمام کامپوننت‌های پلاگین
  - [x] ایجاد صفحه تست در وردپرس: http://localhost/ifnexwp/?page_id=18
- [x] یکپارچگی RBAC با spatie/laravel-permission
  - [x] نصب پکیج `spatie/laravel-permission`
  - [x] ساخت `RoleResource` و `UserResource` در Filament
  - [x] ساخت `RoleAndPermissionSeeder`
- [x] سینک کاربران وردپرس ↔ لاراول با دستور `ifnex:sync-wp-users`
- [x] طراحی سیستم یکپارچه IFNEX (DESIGN_SYSTEM.md)
- [x] گزارش‌گیری مالی در Filament (FinancialReport)
- [x] خروجی Excel برای ShipmentResource و WalletTransactionResource

### کارهای فاز ۳ (تکمیل شده)

- [x] ساخت `AuthController` برای ورود/خروج Sanctum مشتریان
- [x] ساخت `BridgeAuthController` برای لاگین مستقیم از وردپرس
- [x] ساخت `CustomerOrderController` با ۶ endpoint:
  - [x] `GET /api/v1/customer/profile` — پروفایل و آمار
  - [x] `GET /api/v1/customer/countries` — لیست کشورها
  - [x] `GET /api/v1/customer/orders` — لیست سفارشات
  - [x] `POST /api/v1/customer/orders` — ثبت سفارش جدید
  - [x] `GET /api/v1/customer/orders/{shipment}` — جزئیات سفارش
  - [x] `POST /api/v1/customer/orders/{shipment}/cancel` — لغو سفارش
- [x] ساخت `OrderPaymentService` برای پرداخت سفارشات
  - [x] پرداخت از کیف پول: `payFromWallet()`
  - [x] پرداخت از درگاه: `initiateGatewayPayment()`
  - [x] تکمیل پرداخت بعد از callback: `completeGatewayPayment()`
- [x] توسعه پلاگین IFNEX Bridge برای پورتال مشتری:
  - [x] شورت‌کد `[ifnex_order_form]` — فرم ثبت سفارش چندمرحله‌ای
  - [x] شورت‌کد `[ifnex_orders_list]` — لیست سفارشات
  - [x] شورت‌کد `[ifnex_order_payment]` — صفحه پرداخت سفارش
  - [x] شورت‌کد `[ifnex_order_detail]` — جزئیات سفارش
  - [x] شورت‌کد `[ifnex_user_profile]` — پروفایل کاربر
  - [x] استایل `ifnex-orders.css` برای تمام کامپوننت‌ها
  - [x] اسکریپت `ifnex-order-form.js` برای ناوبری مراحل و AJAX
  - [x] AJAX handlers: `ifnex_pay_order_wallet`, `ifnex_pay_order_gateway`, `ifnex_cancel_order`
- [x] توسعه پوسته سفامشی IFNEX برای وردپرس:
  - [x] پشتیبانی چندزبانه با Polylang
  - [x] مدیریت LTR/RTL خودکار
  - [x] Customizer برای لوگو و زبان
  - [x] قالب‌های archive, single, front-page
  - [x] ساختار تمیک شرکتی با لوگو IFNEX
- [x] به‌روزرسانی وردپرس به نسخه ۷.۰.۳ با بهبودهای امنیتی
- [x] یکپارچگی Design System در Filament و وردپرس
- [x] خروجی CSV برای ShipmentResource و WalletTransactionResource

---

## 🚫 خط قرمزها (DO NOT) — هرگز این کارها را نکن

### 🚫 اسکیمای دیتابیس
- **NEVER** جدول `countries` را به ۲ زون برگردانی — ۴ زون مجزا (export_parcel, export_doc, import_parcel, import_doc) الزامی است.
- **NEVER** فقط ۲ نوع سرویس پیاده کن — ۳ نوع الزامی است: `DOC_NORMAL`, `DOC_ECONOMY`, `PARCEL`.
- **NEVER** فیلد `forwarder_track_id` را به‌عنوان فیلد واحد در `shipments` نگه دار — باید `shipment_carrier_mappings` استفاده شود.
- **NEVER** فیلدهای مالی مهم (VAT، Domestic Pickup، Domestic Delivery، Warehousing Cost، Extra Service، Packing Cost) را حذف کن.
- **NEVER** فیلد `status` در `shipments` را به String تغییر دهی — Enum استفاده کن.

### 🚫 معماری
- **NEVER** ترکینگ را در وردپرس پیاده کن — همیشه در لاراول.
- **NEVER** در وردپرس پردازش داده‌ی سفارش انجام دهی — تمام فرم‌ها از طریق پلاگین IFNEX Bridge به لاراول ارسال می‌شوند.
- **NEVER** API لاراول را بدون API Key، Rate Limiting و CORS whitelist بگذاری.
- **NEVER** از CORS `*` استفاده کنی — فقط دامنه‌ی تولیدی وردپرس باید whitelist شود.
- **NEVER** تاریخ‌ها را به شمسی در دیتابیس ذخیره کنی — همیشه timestamp میلادی.

### 🚫 طراحی و کپی‌رایت
- **NEVER** از رنگ، لوگو یا عناصر هویت بصری DHL کپی کنی.
- **NEVER** خروجی PDF (AWB، Invoice، Label) را به فارسی بسازی — انگلیسی باشد.

### 🚫 فرآیند
- **NEVER** فایل `.env` را در Git کامیت کنی.
- **NEVER** `APP_DEBUG=true` را در محیط تولید بگذاری.
- **NEVER** اسکوپ فاز ۰ را بدون Change Request رسمی تغییر دهی.
- **NEVER** فاز ۱ را قبل از تأیید رسمی فاز ۰ توسط مشتری شروع کنی.

---

## ❓ سوالات متداول (FAQ)

### س: کدام نسخه لاراول استفاده کنم؟
**ج:** لاراول **۱۱**. این نسخه در `STATUS.md` قفل شده و در `composer.json` هم تنظیم شده است.

### س: مهاجرت داده‌هایHistorical چقدر مهم است؟
**ج:** هر فایل اکسل جدید که مشتری تحویل دهد، باید قابل import باشد. نیازی به مهاجرت همه داده‌های قدیمی نیست. فایل ترکینگ `Data entry 2026-06-28.xlsx` موجود است و قابل import است.

### س: چه کارهایی در این جلسه انجام شد؟
**ج:** 
1. تکمیل کامل سیستم سفارشات مشتری (CustomerOrderController با ۶ endpoint)
2. توسعه سرویس پرداخت سفارشات (OrderPaymentService) — کیف پول + درگاه
3. ساخت AuthController و BridgeAuthController برای احراز هویت
4. گسترش پلاگین IFNEX Bridge با شورت‌کدهای پرداخت و جزئیات سفارش
5. افزودن ۲ وضعیت جدید به ShipmentStatus: pending_payment و cancelled
6. توسعه پورتال مشتری در وردپرس (فرم سفارش، لیست، پرداخت، جزئیات)
7. یکپارچگی RBAC با spatie/laravel-permission
8. ردیابی تاریخچه نرخ ارز با ExchangeRateHistory
9. طراحی سیستم یکپارچه IFNEX (DESIGN_SYSTEM.md)
10. به‌روزرسانی وردپرس به ۷.۰.۳

### س: چه کارهایی باقی مانده؟
**ج:** 
- تست کامل APIهای سفارشات مشتری و پرداخت
- تست کامل پلاگین وردپرس با داده‌های واقعی مشتری
- راه‌اندازی VPS پل خارج برای API ترکینگ زنده (فاز ۴)
- اتصال به TrackingMore/17track API
- ~~فرمول محاسبه قیمت رقبا~~ (آرشیو شد)

---

## 🛠️ Quick Commands — دستورات پرکاربرد

### نصب و راه‌اندازی لاراول
```bash
cd 04_Laravel
composer install
cp .env.example .env
php artisan key:generate
php artisan migrate --force
php artisan db:seed --force
php artisan serve
```

### Artisan Commands سفارشی
```bash
# Import shipping rates
php artisan ifnex:import:rates storage/app/public/01KYWGVNKS5TNMN37RV77PCYNZ.xlsx

# Import historical shipments
php artisan ifnex:import:shipments storage/app/public/01KYWGVNKS5TNMN37RV77PCYNZ.xlsx

# Update exchange rates
php artisan ifnex:update-exchange-rates

# Sync WordPress users
php artisan ifnex:sync-wp-users
```

### تست API Track
```bash
# با API Key صحیح
curl -H "Authorization: Bearer ifnex-local-dev-key" http://localhost:8000/api/v1/track/TEST123

# بدون API Key
curl http://localhost:8000/api/v1/track/TEST123

# با API Key نامعتبر
curl -H "Authorization: Bearer wrong-key" http://localhost:8000/api/v1/track/TEST123
```

### تست API سفارشات مشتری
```bash
# ورود و دریافت توکن
curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@ifnex.local","password":"password"}'

# لیست سفارشات (با توکن)
curl -H "Authorization: Bearer {token}" \
  http://localhost:8000/api/v1/customer/orders

# ثبت سفارش جدید
curl -X POST http://localhost:8000/api/v1/customer/orders \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"direction":"export","type":"PARCEL","from_country_id":1,"to_country_id":2,"weight":2.5,...}'
```

### پشتیبان‌گیری از دیتابیس
```bash
mysqldump -u root -p ifnex_db > backups/ifnex_$(date +%Y%m%d).sql
```

---

## 📂 ساختار پوشه‌های پروژه (پس از تکمیل فاز ۰)

```
IFNEX-Logistics/
├── 01_Documents/
│   ├── STATUS.md                      ⭐ این فایل — اول بخوان
│   ├── Phase0_Proposal.md             ⭐ مرجع اصلی پروژه
│   ├── EXCEL_ANALYSIS.md              ⭐ تحلیل فایل‌های اکسل
│   ├── PRD_v2.md                      (قدیمی — مرجع تاریخی)
│   ├── Project_Roadmap.md             (قدیمی — مرجع تاریخی)
│   └── IFNEX_Phase0_Checklist.md      (چک‌لیست فاز ۰)
│
├── 02_Design/
│   └── Assets/                        (لوگوها، آیکون‌ها، فایل‌های فیگما)
│
├── 03_WordPress/
│   └── wp-content/plugins/
│       └── ifnex-bridge/              (پلاگین اختصاصی)
│           ├── ifnex-bridge.php
│           ├── includes/
│           │   ├── api-client.php
│           │   ├── shortcodes.php
│           │   └── tracking-form.php
│           └── assets/
│               ├── css/
│               └── js/
│
├── 04_Laravel/
│   ├── app/
│   │   ├── Models/
│   │   │   ├── Country.php
│   │   │   ├── Shipment.php
│   │   │   ├── ShipmentCarrierMapping.php
│   │   │   ├── ShipmentTrackingEvent.php
│   │   │   ├── SystemSetting.php
│   │   │   ├── ShippingRate.php
│   │   │   ├── ShipmentItem.php
│   │   │   └── User.php
│   │   ├── Enums/
│   │   │   ├── ShipmentDirection.php
│   │   │   ├── ShipmentType.php
│   │   │   ├── ShipmentStatus.php
│   │   │   ├── CarrierCode.php
│   │   │   ├── TrackingSource.php
│   │   │   └── UserRole.php
│   │   ├── Services/
│   │   │   ├── TrackingService.php
│   │   │   └── PriceCalculatorService.php
│   │   ├── Http/
│   │   │   ├── Controllers/
│   │   │   │   └── Api/
│   │   │   │       ├── TrackController.php
│   │   │   │       └── PricingController.php
│   │   │   └── Middleware/
│   │   │       └── ApiKeyMiddleware.php
│   │   ├── Imports/
│   │   │   ├── ShippingRatesImport.php
│   │   │   ├── HistoricalShipmentsImport.php
│   │   │   └── RateSheetImport.php
│   │   ├── Console/
│   │   │   └── Commands/
│   │   │       ├── ImportShippingRates.php
│   │   │       ├── ImportHistoricalData.php
│   │   │       └── DebugImportCommand.php
│   │   ├── Filament/
│   │   │   ├── Resources/
│   │   │   │   ├── CountryResource.php
│   │   │   │   ├── ShipmentResource.php
│   │   │   │   │   ├── Pages/
│   │   │   │   │   │   ├── CreateShipment.php
│   │   │   │   │   │   ├── EditShipment.php
│   │   │   │   │   │   ├── ViewShipment.php
│   │   │   │   │   │   └── ListShipments.php
│   │   │   │   │   └── RelationManagers/
│   │   │   │   │       ├── CarrierMappingsRelationManager.php
│   │   │   │   │       └── TrackingEventsRelationManager.php
│   │   │   │   ├── ShippingRateResource.php
│   │   │   │   └── ShipmentItemResource.php
│   │   │   └── Pages/
│   │   │       └── IfnexSettingsPage.php
│   │   └── Providers/
│   │       ├── AppServiceProvider.php
│   │       └── Filament/
│   │           └── AdminPanelProvider.php
│   ├── database/
│   │   ├── migrations/
│   │   │   ├── 2026_08_02_000001_create_countries_table.php
│   │   │   ├── 2026_08_02_000002_create_shipments_table.php
│   │   │   ├── 2026_08_02_000003_create_shipping_rates_table.php
│   │   │   ├── 2026_08_02_000004_create_shipment_carrier_mappings_table.php
│   │   │   ├── 2026_08_02_000005_create_shipment_tracking_events_table.php
│   │   │   ├── 2026_08_02_000006_create_system_settings_table.php
│   │   │   └── 2026_08_02_000007_update_users_table.php
│   │   └── seeders/
│   │       ├── CountriesTableSeeder.php
│   │       ├── SystemSettingSeeder.php
│   │       └── DatabaseSeeder.php
│   ├── routes/
│   │   ├── web.php
│   │   └── api.php
│   ├── config/
│   │   ├── ifnex.php
│   │   └── cors.php
│   ├── bootstrap/
│   │   └── app.php
│   └── .env.example
│
├── README.md
├── composer.json
└── .gitignore
```

---

## 🎯 گام بعدی برای ادامه‌ی کار

اگر نمونه‌ی جدیدی از AI Agent هستی که می‌خواهی کار را ادامه دهی، این مراحل را به ترتیب برو:

۱. **این فایل (`STATUS.md`)** را کامل بخوان — حالا خواندی ✅
۲. **`EXCEL_ANALYSIS.md`** را کامل بخوان — برای فهم داده‌های تاریخی ضروری است
۳. **`Phase0_Proposal.md`** را کامل بخون — مرجع اصلی پروژه
۴. **`README.md`** ریشه را بخوان — برای نمای کلی
۵. کد موجود در `04_Laravel` را بررسی کن — ببین چه چیزی نوشته شده
۶. **اولویت اول:** تست کامل APIهای جدید (customer orders, payments, auth)
۷. **اولویت دوم:** تست کامل پلاگین وردپرس با داده‌های واقعی
۸. با کاربر (Kazem) هماهنگ کن — بپرس کدام کار را باید ادامه دهی

**مهم‌ترین کار بعدی:** تست کامل APIهای سفارشات مشتری + پرداخت.

---

## 📞 تماس

- **توسعه‌دهنده اصلی:** Kazem Alghasi (VernaSoft Group)
- **مشتری:** شرکت IFNEX اصفهان
- **مخزن:** https://www.git.vernahost.ir/gitmodir110/ifnex

اگر سوالی داشتی که در این فایل یا `EXCEL_ANALYSIS.md` یا `Phase0_Proposal.md` پاسخ آن نبود، از کاربر بپرس — حدس نزن.

---

### کارهای انجام‌شده اخیر (آگوست ۲۰۲۶)

### 2026-08-10
- رفع باگ ExportAction در ShipmentResource و WalletTransactionResource
- جایگزینی ExportAction با Action ساده + CSV native (بدون نیاز به maatwebsite/excel)
- ساخت صفحات CreateWalletTransaction و EditWalletTransaction
- اصلاح match expression برای TransactionType enum
- سفارشی‌سازی تم Filament:
  * رنگ Primary = Amber (#f59e0b)
  * Sidebar = Dark Navy gradient (#1a1a2e → #16213e)
  * فونت Vazirmatn برای فارسی
  * RTL کامل
  * Scrollbar سفارشی
  * Login Page با گرادیان زیبا
- نصب جدول notifications برای database notifications
- بهینه‌سازی استفاده از متدهای color() و label() در Enumها
- تست کامل داشبورد مالی و منوهای مختلف
- **تکمیل کامل پورتال مشتری وردپرس:**
  - شورت‌کد `[ifnex_order_form]` — فرم ثبت سفارش چندمرحله‌ای
  - شورت‌کد `[ifnex_orders_list]` — لیست سفارشات با فیلتر وضعیت
  - شورت‌کد `[ifnex_order_payment]` — صفحه پرداخت سفارش (کیف پول + درگاه)
  - شورت‌کد `[ifnex_order_detail]` — جزئیات سفارش با timeline رهگیری
  - شورت‌کد `[ifnex_user_profile]` — پروفایل کاربر با آمار کیف پول
  - استایل `ifnex-orders.css` و اسکریپت `ifnex-order-form.js`
  - AJAX handlers برای پرداخت از کیف پول و درگاه
- **تکمیل سیستم پرداخت سفارشات:**
  - `CustomerOrderController` با ۶ endpoint
  - `OrderPaymentService` برای پرداخت از کیف پول و درگاه
  - `BridgeAuthController` برای لاگین از وردپرس
  - APIهای `/customer/orders/*` و `/customer/orders/{shipment}/pay-*`
  - وضعیت‌های جدید `pending_payment` و `cancelled` در ShipmentStatus
- **به‌روزرسانی Enums:**
  - `PaymentGateway` اضافه شدن case `WALLET`
  - `TrackingSource` اضافه شدن cases `SYSTEM` و `CUSTOMER`

#### ۲۰۲۶-۰۸-۰۸
- ساخت `WalletController` با APIهای شارچ، بررسی موجودی و تاریخچه تراکنش‌ها
- ساخت `DiscountCodeController` با APIهای لیست و اعتبارسنجی کده تخفیف
- ساخت `UpdateExchangeRates` Artisan Command
- ثبت routeهای کیف پول و تخفیف در `api.php`
- اضافه کردن `CURRENCY_API_KEY` به `.env.example` و `config/ifnex.php`
- پاک‌سازی فایل‌های تست و debug از پوشه `04_Laravel`
- رفع CORS — تغییر از `*` به دامنه مشخص از `.env`
- حذف migration‌های قدیمی تکراری
- نصب و پیکربندی Laravel Sanctum برای API authentication
- ساخت Artisan Command `ifnex:token` برای تولید توکن API
- تست کامل APIهای کیف پول با curl
- ساخت ZarinpalService برای اتصال به درگاه پرداخت واقعی
- ساخت MockZarinpalService برای تست بدون Merchant ID
- ساخت MockGatewayController با UI زیبا برای شبیه‌سازی درگاه
- تست کامل flow پرداخت آنلاین (redirect → verify → complete)
- رفع باگ double-click در PaymentController
- ساخت صفحه Payment Result با UI موفق/ناموفق
- رفع باگ WalletController::balance() — کیف پول خودکار ایجاد می‌شود
- حذف PaymentGatewayService قدیمی (استفاده نمی‌شد)
- ساخت پنل مالی Filament با ۳ Widget: FinanceOverviewWidget، TransactionChartWidget، RecentTransactionsWidget
- تکمیل DiscountCodeResource با form/table/filters کامل
- ساخت PaymentResource در Filament برای مشاهده تراکنش‌های درگاه
- نوشتن ۲۱ تست جدید Phase 2: WalletServiceTest (8)، PaymentControllerTest (5)، DiscountCodeControllerTest (6)
- رفع باگ CHECK constraint در migration discount_codes (enum type: percent → percentage)
- رفع باگ Wallet::isFrozen() — مدیریت null برای مقدار پیش‌فرض
- به‌روزرسانی STATUS.md با کارهای انجام‌شده Phase 2
- گسترش پلاگین IFNEX Bridge:
  - ساخت `IFNEX_User_Bridge` برای مدیریت توکن Sanctum کاربران وردپرس
  - اضافه کردن شورت‌کد `[ifnex_wallet_balance]` با نمایش موجودی کیف پول
  - اضافه کردن شورت‌کد `[ifnex_transactions]` با لیست تراکنش‌های کاربر
  - اضافه کردن AJAX handlers برای موجودی کیف پول و تراکنش‌ها
  - ساخت استایل‌های CSS کامل برای تمام کامپوننت‌های پلاگین
  - ایجاد صفحه تست در وردپرس: http://localhost/ifnexwp/?page_id=18
  - رفع باگ صفحه لاگین Filament (MethodNotAllowed)
  - حذف فایل‌های سفارشی لاگین و بازگشت به پیش‌فرض Filament
  - رفع باگ DiscountCode enum: تغییر از `percent` به `percentage`
  - ساخت `SampleDataSeeder` برای داده‌های نمونه (۵ مرسوله، ۴ تراکنش، ۳ کد تخفیف)
  - ساخت دستور Artisan `ifnex:sync-wp-users` برای یک‌سازی کاربران وردپرس ↔ لاراول
  - تست زنده پلاگین وردپرس — همه APIها با موفقیت تست شدند
  - پاک‌سازی فایل‌های تست و اضافی از ریشه پروژه
  - افزودن خروجی Excel برای تراکنش‌ها و مرسولات در Filament
  - ساخت صفحه گزارش‌گیری مالی در Filament: خلاصه مالی، تراکنش‌ها، مرسولات
  - ساخت Design System یکپارچه IFNEX برای استفاده در Filament و وردپرس
  - به‌روزرسانی استایل‌های Filament مطابق با Design System
  - به‌روزرسانی استایل‌های پلاگین وردپرس مطابق با Design System


#### ۲۰۲۶-۰۸-۰۷ 
[x] **refactor(api): improve pricing logic و add test coverage**
    - به‌روزرسانی `ShippingRatesImport` برای استفاده از 'outbound' و 'inbound'
    - Refactor `PriceCalculatorService` با ساختار ماژولارتر
    - به‌روزرسانی مدل `ShippingRate` با Property Casting برای zones
    - اضافه شدن `HasFactory` به مدل‌های `Country` و `ShippingRate`
    - اضافه شدن Factories جدید برای تست
    - پیاده‌سازی تست‌های Feature و Service برای `PriceCalculatorService`
    - ✅ تمام تست‌ها پاس شدند

#### ۲۰۲۶-۰۸-۰۵ 
[x] **refactor(api): expose wallet و discount endpoints**
    - ساخت `WalletController` با APIهای شارژ، بررسی موجودی و تاریخچه
    - ساخت `DiscountCodeController` با APIهای لیست و اعتبارسنجی
    - ساخت `UpdateExchangeRates` Artisan Command
    - ثبت routeهای کیف پول و تخفیف در `api.php`
    - پاک‌سازی فایل‌های تست و debug
    - رفع CORS - تغییر از `*` به دامنه مشخص


### کارهای بعدی

#### فاز ۲.۵ — تست و بهینه‌سازی
- [ ] **تست نهایی پلاگین وردپرس با داده‌های واقعی**
  - تست همه شورت‌کدها با داده‌های واقعی مشتری
  - تست CORS و Rate Limiting در محیط تولید
  - تست عملکرد offline/timeout
- [ ] **مستندسازی API**
  - مستند کامل APIهای لاراول برای فرانت‌اند developerها
  - مستند نحوه نصب و تنظیم پلاگین وردپرس
  - مستند نحوه sync کاربران
- [ ] **بهینه‌سازی عملکرد**
  - کش‌کردن نرخ ارز و تعرفه‌ها
  - بهینه‌سازی queryهای پرتکرار

#### فاز ۴ — VPS پل و ترکینگ زنده
- [ ] **راه‌اندازی VPS پل خارج (هلند/آلمان)**
- [ ] **اتصال به TrackingMore/17track API**
  - مپ کردن کدهای رهگیری
  - وب‌هوک برای به‌روزرسانی خودکار وضعیت
- [ ] **گزارش‌گیری پیشرفته**
  - خروجی Excel/PDF برای تراکنش‌ها، مرسولات، سود/زیان
  - داشبورد مدیریتی برای مدیرعامل
- [ ] **پلاگین SMS**
  - اطلاع‌رسانی وضعیت مرسوله به مشتری
  - اطلاع‌رسانی پرداخت‌های کیف پول
  - یادآوری انقضا کدهای تخفیف
- [ ] **ماژول CRM**
  - مدیریت مشتریان
  - تماس‌ها و یادآوری‌ها
  - تحلیل رفتار مشتریان
- [ ] **اپلیکیشن موبایل**
  - نسخه Android/iOS برای مشتریان
  - Push notification برای وضعیت مرسوله

---

## 🚫 خط قرمزها (DO NOT) — هرگز این کارها را نکن