From 1ea9486ca10a5f3d9f14548da05df0546c36f25d Mon Sep 17 00:00:00 2001
From: Kazem Alghasi <alghasi@live.com>
Date: Thu, 6 Aug 2026 01:39:26 +0330
Subject: [PATCH] docs(imports): add documentation comments to
 ShippingRatesImport

---
 .../app/Imports/ShippingRatesImport.php       | 41 ++++++++++++++++++-
 1 file changed, 40 insertions(+), 1 deletion(-)

diff --git a/04_Laravel/app/Imports/ShippingRatesImport.php b/04_Laravel/app/Imports/ShippingRatesImport.php
index f89e389..124d5ac 100644
--- a/04_Laravel/app/Imports/ShippingRatesImport.php
+++ b/04_Laravel/app/Imports/ShippingRatesImport.php
@@ -9,10 +9,12 @@ use Maatwebsite\Excel\Concerns\OnEachRow;
 use Maatwebsite\Excel\Concerns\WithMultipleSheets;
 use Maatwebsite\Excel\Concerns\WithStartRow;
 use Maatwebsite\Excel\Row;
-use Illuminate\Support\Collection;
 
 class ShippingRatesImport implements WithMultipleSheets
 {
+    /**
+     * تعریف شیت‌های مختلف فایل اکسل و کلاس‌های پردازش‌گر مربوطه
+     */
     public function sheets(): array
     {
         return [
@@ -23,6 +25,9 @@ class ShippingRatesImport implements WithMultipleSheets
     }
 }
 
+/**
+ * کلاس برای پردازش شیت‌های استاندارد نرخ‌ها (Export Rate و Import Rate)
+ */
 class RateSheetImport implements OnEachRow, WithStartRow
 {
     protected int $imported = 0;
@@ -31,30 +36,40 @@ class RateSheetImport implements OnEachRow, WithStartRow
 
     public function __construct(protected string $direction) {}
 
+    /**
+     * شروع خواندن از ردیف ۵ (۴ ردیف اول هدر هستند)
+     */
     public function startRow(): int
     {
         return 5;
     }
 
+    /**
+     * پردازش هر ردیف از شیت
+     */
     public function onRow(Row $row)
     {
         $rowIndex = $row->getIndex();
         $cells = $row->toArray();
 
+        // بررسی اعتبار ستون وزن (ستون اول)
         if (empty($cells[0]) || !is_numeric($cells[0])) {
             $this->skipped++;
             return;
         }
 
         try {
+            // تشخیص نوع سرویس (Doc یا Parcel)
             $type = $this->resolveType($rowIndex, $cells);
 
+            // استخراج و نرمال‌سازی قیمت‌های ۱۰ زون
             $zones = [];
             for ($i = 1; $i <= 10; $i++) {
                 $val = str_replace([',', ' '], '', (string) ($cells[$i] ?? 0));
                 $zones['zone_' . $i] = is_numeric($val) ? (float) $val : 0;
             }
 
+            // ثبت یا به‌روزرسانی نرخ در دیتابیس
             ShippingRate::updateOrCreate(
                 [
                     'direction' => $this->direction,
@@ -71,6 +86,9 @@ class RateSheetImport implements OnEachRow, WithStartRow
         }
     }
 
+    /**
+     * دریافت آمار عملیات ایمپورت
+     */
     public function getStats(): array
     {
         return [
@@ -80,6 +98,9 @@ class RateSheetImport implements OnEachRow, WithStartRow
         ];
     }
 
+    /**
+     * تشخیص نوع سرویس بر اساس محتوای ردیف
+     */
     private function resolveType(int $rowIndex, array $cells): ShipmentType
     {
         $header = strtoupper((string) ($cells[3] ?? ''));
@@ -92,10 +113,14 @@ class RateSheetImport implements OnEachRow, WithStartRow
             return ShipmentType::Parcel;
         }
 
+        // اگر نوع مشخص نبود، بر اساس شماره ردیف حدس می‌زنیم
         return $rowIndex < 10 ? ShipmentType::DocNormal : ShipmentType::Parcel;
     }
 }
 
+/**
+ * کلاس برای پردازش شیت ساده‌تر نرخ‌ها (DocEco)
+ */
 class SimpleRateSheetImport implements OnEachRow, WithStartRow
 {
     protected int $imported = 0;
@@ -107,15 +132,22 @@ class SimpleRateSheetImport implements OnEachRow, WithStartRow
         protected string $direction = 'export'
     ) {}
 
+    /**
+     * شروع خواندن از ردیف ۲ (۱ ردیف اول هدر است)
+     */
     public function startRow(): int
     {
         return 2;
     }
 
+    /**
+     * پردازش هر ردیف از شیت
+     */
     public function onRow(Row $row)
     {
         $cells = $row->toArray();
 
+        // بررسی اعتبار ستون وزن (ستون اول)
         if (empty($cells[0]) || !is_numeric($cells[0])) {
             $this->skipped++;
             return;
@@ -127,21 +159,25 @@ class SimpleRateSheetImport implements OnEachRow, WithStartRow
             $rawValue = str_replace([',', ' '], '', (string) ($cells[2] ?? 0));
             $rawValue = is_numeric($rawValue) ? (float) $rawValue : 0;
 
+            // بررسی اعتبار شماره زون و قیمت
             if ($zoneNumber < 1 || $zoneNumber > 10 || $rawValue <= 0) {
                 $this->skipped++;
                 return;
             }
 
+            // تبدیل قیمت از AED به IRR
             $aedToIrr = (float) SystemSetting::get('aed_to_irr', 455000);
             $value = $aedToIrr > 0 ? $rawValue / $aedToIrr : $rawValue;
 
             $zoneColumn = 'zone_' . $zoneNumber;
 
+            // ایجاد مقادیر پیش‌فرض برای زون‌ها
             $defaults = [];
             for ($i = 1; $i <= 10; $i++) {
                 $defaults['zone_' . $i] = 0;
             }
 
+            // یافتن یا ایجاد رکورد و به‌روزرسانی قیمت زون
             $record = ShippingRate::firstOrCreate(
                 [
                     'direction' => $this->direction,
@@ -161,6 +197,9 @@ class SimpleRateSheetImport implements OnEachRow, WithStartRow
         }
     }
 
+    /**
+     * دریافت آمار عملیات ایمپورت
+     */
     public function getStats(): array
     {
         return [