ifnex/01_Documents/IFNEX_Phase0_Checklist.md

# چک‌لیست فاز ۰ — IFNEX Phase 0 Checklist

> **مرجع:** Phase0_Proposal.docx + EXCEL_ANALYSIS.md + STATUS.md  
> **تاریخ:** August 2026  
> **وضعیت:** فاز ۰ تکمیل شده + فاز ۱/۲ بخشی انجام شده  
> **توسعه‌دهنده:** VernaSoft Group — Kazem Alghasi  
> **آخرین بروزرسانی:** 2026-08-29

---

## وضعیت کلی

| فاز | وضعیت | درصد |
|------|-------|------|
| فاز ۰ (پایه) | ✅ تکمیل شده | 100% |
| فاز ۱ (پنل مشتری) | ✅ تکمیل شده | 100% |
| فاز ۲ (پرداخت و کیف پول) | ✅ تکمیل شده | 100% |
| فاز ۳ (یکپارچه‌سازی) | ✅ تکمیل شده | 100% |
| **فاز ۳.۵ (اصلاحات اساسی)** | 🔄 در دست اقدام | 0% |
| فاز ۴ (سیستم نمایندگی) | 📋 مطالعاتی | 0% |
| فاز ۵ (تجاری‌سازی) | 📋 مطالعاتی | 0% |

> **نکته:** فاز ۳.۵ شامل اصلاحات اساسی است که پس از تست لوکال شناسایی شد. این فاز قبل از ارائه نهایی به کارفرما باید تکمیل شود.

---

## بخش ۱: اصلاح اسکیمای دیتابیس

### 1.1 بازنویسی Migration `countries`
- [x] حذف `export_zone` و `import_zone` (۲ زون قدیمی)
- [x] اضافه کردن `export_zone_parcel` (TINYINT 1-10)
- [x] اضافه کردن `export_zone_doc` (TINYINT 1-10)
- [x] اضافه کردن `import_zone_parcel` (TINYINT 1-10)
- [x] اضافه کردن `import_zone_doc` (TINYINT 1-10)
- [x] اضافه کردن `iso_code` (CHAR(2) UNIQUE)
- [x] اضافه کردن `is_active` (BOOLEAN default true)
- [x] اضافه کردن `calling_code` (VARCHAR 10 NULL) — فاز ۲
- [x] اصلاح `name` — بدون کد ISO در پرانتز

### 1.2 بازنویسی Migration `shipments`
- [x] حذف `forwarder_track_id` (جایگزین با جدول مجزا)
- [x] تغییر `type` از STRING به ENUM: `DOC_NORMAL`, `DOC_ECONOMY`, `PARCEL`
- [x] تغییر `direction` از STRING به ENUM: `import`, `export`
- [x] تغییر `status` از STRING به ENUM (وضعیت‌های استاندارد)
- [x] اضافه کردن `from_country_id` (FK → countries.id)
- [x] اضافه کردن `to_country_id` (FK → countries.id)
- [x] اضافه کردن فیلدهای مالی: `domestic_pickup`, `domestic_delivery`, `warehousing_cost`, `vat_amount`
- [x] تبدیل فیلدهای غیرضروری به `nullable`
- [x] اضافه کردن `state_notes` (فیلد وضعیت و یادداشت مشتری) — فاز ۲
- [x] اضافه کردن `cod_amount` (مبلغ COD) — فاز ۲
- [x] رابطه `packages()` و `statusHistories()` — فاز ۲

### 1.3 ایجاد Migration `shipment_carrier_mappings`
- [x] تمام فیلدها طبق طرح اولیه
- [x] RelationManager در Filament با CRUD کامل

### 1.4 ایجاد Migration `shipment_tracking_events`
- [x] تمام فیلدها طبق طرح اولیه
- [x] اضافه کردن فیلد `source` (manual/api/system) — فاز ۲
- [x] RelationManager در Filament با CRUD کامل

### 1.5 بازنویسی Migration `system_settings`
- [x] تغییر به ساختار key-value

### 1.6 بازنویسی Migration `users`
- [x] اضافه کردن `phone`, `role`, `is_active`

### 1.7 اصلاح Migration `shipping_rates`
- [x] تغییر `type` و `direction` به ENUM

### 1.8 جداول جدید فاز ۱/۲
- [x] `currencies` — جدول ارزها (code, name, symbol, rate_to_rial, rate_to_aed, is_active)
- [x] `shipment_packages` — بسته‌های چندگانه هر مرسوله (package_no, weight, dimensions)
- [x] `shipment_status_histories` — تاریخچه تغییرات وضعیت (from_status, to_status, reason, changed_by)
- [x] `wallets` — کیف پول کاربران
- [x] `wallet_transactions` — تراکنش‌های کیف پول
- [x] `notifications` — نوتیفیکیشن‌های دیتابیس (Laravel default)

---

## بخش ۲: Model ها

- [x] `Country.php` — با ۴ زون + iso_code + calling_code + is_active
- [x] `Shipment.php` — با enum casts + روابط کامل + packages + statusHistories
- [x] `ShipmentCarrierMapping.php` — با relation + enum casts
- [x] `ShipmentTrackingEvent.php` — با relation + enum casts + source
- [x] `ShipmentItem.php` — با relation
- [x] `ShipmentPackage.php` — با belongsTo(Shipment) — فاز ۲
- [x] `ShipmentStatusHistory.php` — با booted auto-fill changed_by — فاز ۲
- [x] `ShippingRate.php` — با enum casts
- [x] `SystemSetting.php` — با get/set متدها
- [x] `User.php` — با role + is_active + wallet relation
- [x] `Currency.php` — با fillable + casts — فاز ۲
- [x] `Wallet.php` — فاز ۲
- [x] `WalletTransaction.php` — فاز ۲

---

## بخش ۳: Seeders

- [x] `CountriesTableSeeder.php` — با ۴ زون مجزا
- [x] `SystemSettingSeeder.php` — با ساختار key-value
- [x] `DatabaseSeeder.php` — با User اولیه super_admin

---

## بخش ۴: API و Controller ها

### ۴.۱ API ترکینگ
- [x] `GET /api/v1/track/{awb_no}` — تایم‌لاین کامل
- [x] `TrackController.php` — با timeline + carrier mappings

### ۴.۲ API قیمت‌گذاری
- [x] `POST /api/v1/calculate` — با ۳ نوع سرویس + VAT + هزینه‌های جانبی
- [x] `PricingController.php` — با API Key + Rate Limiting

### ۴.۳ API احراز هویت
- [x] `POST /api/v1/auth/login` — ورود با email + password
- [x] `POST /api/v1/auth/logout` — خروج ( Sanctum)
- [x] `POST /api/v1/bridge/login` — Bridge Auth (WordPress → Laravel)

### ۴.۴ API پنل مشتری (فاز ۱/۲)
- [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] `POST /api/v1/customer/orders/{shipment}/pay-wallet` — پرداخت از کیف پول
- [x] `POST /api/v1/customer/orders/{shipment}/pay-gateway` — پرداخت از درگاه
- [x] `GET /api/v1/customer/notifications` — نوتیفیکیشن‌ها — فاز ۲
- [x] `POST /api/v1/customer/notifications/{id}/read` — خواندن نوتیفیکیشن — فاز ۲

### ۴.۵ API کیف پول (فاز ۲)
- [x] `GET /api/v1/wallet/balance` — موجودی
- [x] `GET /api/v1/wallet/transactions` — تراکنش‌ها

### ۴.۶ API پرداخت (فاز ۲)
- [x] `POST /api/v1/payment/redirect` — انتقال به درگاه
- [x] `GET /api/v1/payment/check/{transaction}` — بررسی وضعیت
- [x] Mock Gateway (شبیه‌سازی درگاه پرداخت)

---

## بخش ۵: Filament Admin Panel

### ۵.۱ منابع (Resources)
- [x] `CountryResource` — با ۴ زون + iso_code + calling_code + is_active
- [x] `ShipmentResource` — با ستون‌های جدید + CSV export +Packages Repeater + changeStatus bulkAction
- [x] `ShippingRateResource` — با ۳ نوع سرویس
- [x] `CurrencyResource` — CRUD ارزها — فاز ۲

### ۵.۲ RelationManagers
- [x] `TrackingEventsRelationManager` — با فیلد `source` — فاز ۲
- [x] `CarrierMappingsRelationManager` — با CRUD کامل
- [x] `ItemsRelationManager` — اقلام مرسوله

### ۵.۳ صفحات سفارشی
- [x] `SettingsPage` — تنظیمات key-value
- [x] `PriceTestPage` — تست قیمت‌گذاری
- [x] `ImportRatesPage` — آپلود اکسل نرخ‌ها + دانلود template — فاز ۲

### ۵.۴ PDF
- [x] `PdfService` — با loadMissing (packages, fromCountry, toCountry, items)
- [x] `awb.blade.php` — با asset() برای تصاویر + جدول بسته‌ها
- [x] `label.blade.php` — با asset() برای تصاویر
- [x] `invoice.blade.php` — فاکتور

### ۵.۵ نوتیفیکیشن ادمین
- [x] `ShipmentUpdatedNotification` — با لیست فیلدهای تغییر کرده
- [x] `afterSave` hook در ShipmentResource — ارسال نوتیفیکیشن

---

## بخش ۶: Services

- [x] `PriceCalculatorService.php` — با ۴ زون + ۳ نوع + VAT + هزینه‌های جانبی
- [x] `TrackingService.php` — تایم‌لاین + افزودن رویداد
- [x] `PdfService.php` — تولید PDF (AWB, Label, Invoice)
- [x] `OrderPaymentService.php` — پرداخت از کیف پول و درگاه — فاز ۲

---

## بخش ۷: Import و مهاجرت داده

- [x] `OldShipmentsImport.php` — مهاجرت ۳۹۵۰ رکورد تاریخی
- [x] `ShippingRatesImport.php` — ایمپورت نرخ‌ها (بدون SystemSetting)
- [x] `ShippingRatesTemplateExport.php` — دانلود template اکسل (FromArray)

---

## بخش ۸: پلاگین وردپرس IFNEX Bridge

### ۸.۱ ساختار پلاگین
- [x] `ifnex-bridge.php` — فایل اصلی پلاگین
- [x] `includes/api-client.php` — ارتباط با API (قدیمی)
- [x] `includes/user-bridge.php` — Bridge Auth + API احراز‌شده
- [x] `includes/shortcodes.php` — تمام شورت‌کدها
- [x] `includes/tracking-form.php` — فرم رهگیری (قدیمی)
- [x] `assets/css/ifnex-orders.css` — استایل کامل (v1.6.0)
- [x] `assets/css/ifnex-bridge.css` — استایل ترکینگ
- [x] `assets/js/ifnex-order-form.js` — فرم سفارش + هشدار آدرس انگلیسی

### ۸.۲ شورت‌کدها
- [x] `[ifnex_tracking_form]` — فرم رهگیری مرسوله
- [x] `[ifnex_tracking_status]` — نمایش مستقیم وضعیت
- [x] `[ifnex_wallet_balance]` — موجودی کیف پول
- [x] `[ifnex_transactions]` — تاریخچه تراکنش‌ها (با استایل جدید)
- [x] `[ifnex_user_profile]` — پروفایل مشتری
- [x] `[ifnex_orders_list]` — لیست سفارشات
- [x] `[ifnex_order_form]` — فرم ثبت سفارش چند مرحله‌ای
- [x] `[ifnex_order_payment]` — صفحه پرداخت
- [x] `[ifnex_order_detail]` — جزئیات سفارش
- [x] `[ifnex_customer_dashboard]` — پنل جامع مشتری (داشبورد + سفارشات + کیف پول + تراکنش‌ها + اعلان‌ها + رهگیری + پروفایل)

### ۸.۳ استایل تراکنش‌ها — فاز ۲
- [x] استایل کامل برای `.ifnex-transactions-*` — مطابق دشبورد مدرن

### ۸.۴ هشدار آدرس انگلیسی — فاز ۲
- [x] تشخیص متن انگلیسی در آدرس (sender + receiver)
- [x] نمایش هشدار اسلایدی با انیمیشن

### ۸.۵ نوتیفیکیشن پنل کاربری — فاز ۲
- [x] تب اعلان‌ها در دشبورد
- [x] بج تعداد خوانده‌نشده در سایدبار
- [x] لیست نوتیفیکیشن‌ها با استایل مدرن
- [x] لینک به سفارش مرتبط
- [x] API لاراول برای دریافت/خواندن نوتیفیکیشن

---

## بخش ۹: وب‌سایت وردپرس

### ۹.۱ قالب IFNEX
- [x] نصب و تنظیم قالب سفارشی
- [x] front-page.php — لندینگ پیج
- [x] header.php / footer.php
- [x] template-parts (hero, services, how-it-works, stats, testimonials, cta)
- [x] template-login.php — صفحه ورود

### ۹.۲ صفحات
- [x] لندینگ پیج
- [x] صفحه رهگیری
- [x] صفحه استعلام قیمت (PricingPageController)

---

## بخش ۱۰: موارد اخیر فاز ۳ (۱۷ مورد کارفرما)

- [x] ۱. رفع `openUrlInNewTab()` روی اکشن‌های PDF در ViewShipment
- [x] ۲. رفع `ShippingRatesImport` (حذف SystemSetting + تبدیل ارز)
- [x] ۳. رفع تصاویر PDF (asset() بجای public_path())
- [x] ۴. رفع label.blade.php تصاویر
- [x] ۵. ستون‌های جدید ShipmentResource (fromCountry, toCountry, route, phones, cod_amount)
- [x] ۶. حذف reason_for_export تکراری
- [x] ۷. رفع CSV label ($status?->label())
- [x] ۸. Packages Repeater (collapsible)
- [x] ۹. changeStatus به عنوان bulkAction
- [x] ۱۰. afterSave hook برای ShipmentUpdatedNotification
- [x] ۱۱. Currency CRUD (Resource + Pages + Migration + Model)
- [x] ۱۲. RelationManagers (Create/Edit/Delete) + فیلد source
- [x] ۱۳. سیستم نوتیفیکیشن دیتابیس
- [x] ۱۴. Multi-package (migration + model + PDF)
- [x] ۱۵. ImportRatesPage (دکمه‌ها + دانلود template + ایمپورت)
- [x] ۱۶. استایل تراکنش‌های وردپرس
- [x] ۱۷. هشدار انگلیسی بودن آدرس
- [x] ۱۸. نوتیفیکیشن پنل کاربری وردپرس (تب + API + CSS)
- [~] ۱۹. سیستم نمایندگی (طرح مطالعاتی آماده — به فاز ۴ منتقل شد)

---

## بخش ۱۰.۱: تست لوکال و اصلاحات نهایی فاز ۳

- [x] اضافه شدن متدهای `isPaid()` و `canBeCancelledByCustomer()` به Enum ShipmentStatus
- [x] اضافه شدن ستون `calling_code` به جدول countries (migration جدید)
- [x] آپدیت ۱۹۲ کشور با پیش‌شماره استاندارد ISO 3166-1
- [x] اضافه شدن `IFNEX_BRIDGE_API_KEY` به `.env` و `config/ifnex.php`
- [x] اصلاح میدلور `auth:sanctum` در `bootstrap/app.php` برای بازگرداندن JSON 401
- [x] اضافه شدن شورت‌کد `[ifnex_wallet_charge]` برای شارژ کیف پول
- [x] اضافه شدن AJAX handler `ifnex_wallet_charge`
- [x] رفع مشکل `use App\Models\WalletTransaction` در CustomerOrderController
- [x] هشدار هوشمند زبان فارسی/انگلیسی برای نام، شهر و آدرس
- [x] پیش‌شماره تلفن خودکار بر اساس کشور انتخابی
- [x] اعتبارسنجی تلفن (فقط اعداد، +، فاصله)
- [x] اصلاح ارور "[object Object]" در پاسخ‌های AJAX
- [x] اصلاح `ifnex_enqueue_order_assets` برای لود صحیح JS
- [x] اصلاح `.env` و `ZARINPAL_FRONTEND_SUCCESS_URL` / `FAILURE_URL`
- [x] تست موفق تمام جریان‌ها: لاگین → سفارش → پرداخت → شارژ کیف پول → نوتیفیکیشن

### بازطراحی PDFها:
- [x] نصب `picqer/php-barcode-generator`
- [x] بازطراحی AWB با بارکد، From/To کامل، Value، Service، Type
- [x] بازطراحی Invoice با جدول ۹ ردیفه، اعلان قانونی، بارکد پایین
- [x] بازطراحی Label با اندازه ۱۰۰×۱۵۰mm و بارکد بزرگ
- [x] اضافه‌شدن شرط DOC/PARCEL برای Invoice (فقط PARCEL فاکتور داره)

---

## بخش ۱۱: فاز ۳.۵ — اصلاحات اساسی 🔄

> ⚠️ **این بخش قبل از ارائه نهایی به کارفرما باید تکمیل شود.**

### ۱۱.۱ — Multi-Package در فرم سفارش مشتری 🔴 ضروری

**مشکل:** بک‌اند و پنل ادمین از چند بسته پشتیبانی می‌کنند، ولی فرم سفارش مشتری فقط یه بسته می‌گیره.

- [ ] اصلاح `ifnex-order-form.js` — افزودن قابلیت "افزودن بسته دیگر"
- [ ] اصلاح HTML فرم — نمایش لیست بسته‌های اضافه‌شده
- [ ] محاسبه مجموع وزن‌ها و قیمت نهایی
- [ ] اصلاح `buildOrderData()` — ارسال آرایه `packages[]`
- [ ] اصلاح API `POST /customer/orders` — پذیرش `packages[]`
- [ ] ایجاد خودکار `ShipmentPackage` هنگام ثبت سفارش
- [ ] تست با چند بسته

### ۱۱.۲ — فرم Invoice برای محموله‌های PARCEL 🔴 ضروری

**مشکل:** وقتی مشتری نوع PARCEL رو انتخاب می‌کنه، باید فرم اقلام گمرکی (Invoice) رو پر کنه.

- [ ] اضافه‌کردن مرحله جدید به فرم سفارش (مرحله ۲.۵)
- [ ] نمایش این مرحله فقط وقتی نوع = PARCEL
- [ ] فیلدهای هر آیتم: Description, HS Code, Quantity, Unit Price, Total
- [ ] امکان افزودن چندین آیتم (تا ۹ ردیف)
- [ ] محاسبه خودکار Total و نمایش مجموع
- [ ] ارسال `items[]` به API
- [ ] ایجاد خودکار `ShipmentItem` هنگام ثبت سفارش
- [ ] تست با چند آیتم

### ۱۱.۳ — پشتیبانی چندزبانه (i18n) 🟡 مهم

**مشکل:** سایت ۲ زبانه (فارسی + انگلیسی) هست با Polylang، ولی:
- تمام شورت‌کدها و فرم‌ها فقط فارسی هستن
- پیام‌های خطا و موفقیت فقط فارسی هستن

- [ ] استخراج تمام رشته‌های متنی به فایل‌های ترجمه
- [ ] استفاده از `__()` و `_e()` در وردپرس
- [ ] استفاده از `wp_localize_script` برای ارسال ترجمه‌ها به JS
- [ ] افزودن فایل‌های `.po/.mo` برای زبان‌های فارسی و انگلیسی
- [ ] اصلاح تمام فایل‌های `ifnex-bridge/includes/*.php`
- [ ] اصلاح `ifnex-order-form.js` (استفاده از متغیرهای ترجمه)
- [ ] اصلاح CSS برای پشتیبانی RTL/LTR
- [ ] تست زبان انگلیسی

### ۱۱.۴ — تست و نهایی‌سازی 🟡 مهم

- [ ] تست تولید PDF با بارکد روی سرور
- [ ] تست Multi-Package
- [ ] تست Invoice Form برای PARCEL
- [ ] تست زبان انگلیسی
- [ ] دیپلوی نهایی روی سرور
- [ ] تست نهایی روی سرور

---

## بخش ۱۲: فاز ۵ — تجاری‌سازی 📋

> طرح مطالعاتی — مدل پولی چندلایه‌ای

### پلن‌های پیشنهادی:
- [ ] **IFNEX Starter** — پلن پایه پرداخت‌شده
- [ ] **IFNEX Business** — پلن متوسط
- [ ] **IFNEX Enterprise** — پلن کامل

### فیچرهای Premium:
- [ ] فرم‌ساز Drag & Drop
- [ ] White-label branding
- [ ] API Gateway برای توسعه‌دهندگان
- [ ] اکسپورت اکسل کامل (تمام فیلدها)
- [ ] API ترکینگ زنده (TrackingMore/17track)
- [ ] پلاگین SMS
- [ ] گزارش‌های مالی پیشرفته

- [x] IFNEX_Phase0_Checklist.md (همین فایل)
- [x] IFNEX_File_Map.md — نقشه فایل‌های پروژه
- [x] IFNEX_Roadmap.md — نقشه راه جامع ۴ فازی
- [ ] راهنمای اپراتور (Operator Manual) با اسکرین‌شات
- [ ] مستندات API (OpenAPI/Swagger)

---

## خط قرمزها — هرگز این کارها را نکن

- هرگز جدول countries را به ۲ زون برگردانی
- هرگز فقط ۲ نوع سرویس پیاده کن (۳ نوع الزامی است)
- هرگز ترکینگ را در وردپرس پیاده کن
- هرگز فیلدهای مالی (VAT, Packing, Warehousing) را حذف کن
- هرگز از رنگ/لوگو DHL کپی کن
- هرگز PDF را به فارسی بسازی
- هرگز تاریخ را شمسی در DB ذخیره کنی
- هرگز از CORS `*` استفاده کنی
- هرگز فایل .env را در Git کامیت کنی

---

> 2026 VernaSoft Group. Internal use only.