From 09c008396e3d804d82a69170d561870ddc0dd658 Mon Sep 17 00:00:00 2001
From: hossein taromi <hosseintaromii@gmail.com>
Date: Sun, 27 Jul 2025 14:46:25 +0330
Subject: [PATCH] docs: add comprehensive API field mapping documentation

- Document exact mapping between form fields and API structure
- Include complete examples of product and variant data
- Detail product types and their use cases
- List UI-specific fields vs API fields
- Provide migration notes for removed fields
- Include file change summary and implementation details
---
 Product-Fields-Mapping.md | 154 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 154 insertions(+)
 create mode 100644 Product-Fields-Mapping.md

diff --git a/Product-Fields-Mapping.md b/Product-Fields-Mapping.md
new file mode 100644
index 0000000..f2b0d4d
--- /dev/null
+++ b/Product-Fields-Mapping.md
@@ -0,0 +1,154 @@
+# 📋 مقایسه فیلدها - سیستم محصولات
+
+## 🔵 فیلدهای محصول (Product Fields)
+
+| فرم ما                 | API Field              | نوع        | توضیح                    |
+| ---------------------- | ---------------------- | ---------- | ------------------------ |
+| ✅ `name`              | ✅ `name`              | `string`   | نام محصول                |
+| ✅ `description`       | ✅ `description`       | `string`   | توضیحات محصول            |
+| ✅ `design_style`      | ✅ `design_style`      | `string`   | استایل طراحی             |
+| ✅ `enabled`           | ✅ `enabled`           | `boolean`  | فعال/غیرفعال             |
+| ✅ `category_ids`      | ✅ `category_ids`      | `number[]` | آرایه شناسه دسته‌بندی‌ها |
+| ✅ `product_option_id` | ✅ `product_option_id` | `number`   | شناسه گزینه محصول        |
+| ✅ `total_sold`        | ✅ `total_sold`        | `number`   | تعداد فروخته شده         |
+| ✅ `type`              | ✅ `type`              | `number`   | نوع محصول (0,1,2,3)      |
+| ✅ `attributes`        | ✅ `attributes`        | `object`   | ویژگی‌های سفارشی         |
+| ✅ `variants`          | ✅ `variants`          | `array`    | آرایه variants           |
+
+## 🔧 فیلدهای Variant
+
+| فرم ما                 | API Field              | نوع       | توضیح                      |
+| ---------------------- | ---------------------- | --------- | -------------------------- |
+| ✅ `enabled`           | ✅ `enabled`           | `boolean` | فعال/غیرفعال variant       |
+| ✅ `fee_percentage`    | ✅ `fee_percentage`    | `number`  | درصد کارمزد                |
+| ✅ `profit_percentage` | ✅ `profit_percentage` | `number`  | درصد سود                   |
+| ✅ `stock_limit`       | ✅ `stock_limit`       | `number`  | حد کمینه موجودی            |
+| ✅ `stock_managed`     | ✅ `stock_managed`     | `boolean` | مدیریت موجودی فعال/غیرفعال |
+| ✅ `stock_number`      | ✅ `stock_number`      | `number`  | تعداد موجودی               |
+| ✅ `weight`            | ✅ `weight`            | `number`  | وزن (گرم)                  |
+| ✅ `attributes`        | ✅ `attributes`        | `object`  | ویژگی‌های variant          |
+| ✅ `meta`              | ✅ `meta`              | `object`  | Meta data                  |
+
+## 📊 فیلدهای اضافی در فرم
+
+| فرم ما          | API     | دلیل                           |
+| --------------- | ------- | ------------------------------ |
+| 🆕 `images`     | ❌ نیست | برای آپلود و مدیریت تصاویر     |
+| 🆕 `id`         | ❌ نیست | برای ویرایش (از response میاد) |
+| 🆕 `created_at` | ❌ نیست | از response میاد               |
+| 🆕 `updated_at` | ❌ نیست | از response میاد               |
+
+## 🎯 مثال API Request کامل
+
+```json
+{
+  "name": "تیشرت مردانه",
+  "description": "تیشرت با کیفیت بالا",
+  "design_style": "مدرن",
+  "enabled": true,
+  "category_ids": [1, 3],
+  "product_option_id": 2,
+  "total_sold": 25,
+  "type": 1,
+  "attributes": {
+    "material": "پنبه",
+    "season": "تابستان"
+  },
+  "variants": [
+    {
+      "enabled": true,
+      "fee_percentage": 5.5,
+      "profit_percentage": 25,
+      "stock_managed": true,
+      "stock_number": 10,
+      "stock_limit": 2,
+      "weight": 200,
+      "attributes": {
+        "color": "قرمز",
+        "size": "بزرگ"
+      },
+      "meta": {
+        "supplier": "تامین‌کننده A",
+        "priority": "high"
+      }
+    }
+  ]
+}
+```
+
+## 🚀 نوع محصولات (Product Types)
+
+| مقدار | نام         | توضیح                   |
+| ----- | ----------- | ----------------------- |
+| `0`   | محصول ساده  | محصول بدون variant      |
+| `1`   | محصول متغیر | محصول با variants مختلف |
+| `2`   | محصول گروهی | مجموعه محصولات          |
+| `3`   | محصول خارجی | لینک به سایت خارجی      |
+
+## 🎨 فیلدهای UI (غیر API)
+
+### فیلدهای مدیریت تصاویر:
+
+- **`images`** - آرایه تصاویر محصول
+- **`images.id`** - شناسه فایل آپلود شده
+- **`images.url`** - آدرس تصویر
+- **`images.alt`** - متن جایگزین
+- **`images.order`** - ترتیب نمایش
+
+### فیلدهای مدیریت داخلی:
+
+- **`id`** - شناسه محصول (برای ویرایش)
+- **`created_at`** - تاریخ ایجاد
+- **`updated_at`** - تاریخ آخرین ویرایش
+
+## ✨ خلاصه مطابقت
+
+### ✅ کاملاً مطابق:
+
+- **100% فیلدهای API پیاده‌سازی شده**
+- **ساختار دقیقاً مشابه**
+- **نوع داده‌ها صحیح**
+- **Validation مناسب**
+
+### 🎯 ویژگی‌های اضافی:
+
+- **مدیریت تصاویر** با آپلود و پیش‌نمایش
+- **UI/UX بهتر** با validation و error handling
+- **Preview زنده** تغییرات
+- **Responsive design** برای موبایل
+
+## 📝 نتیجه‌گیری
+
+**✅ تمام فیلدهای API شما دقیقاً پیاده‌سازی شده است**
+
+**🎨 قابلیت‌های اضافی UI/UX برای تجربه بهتر کاربر اضافه شده**
+
+**🚀 سیستم آماده برای استفاده در production**
+
+---
+
+## 📋 فیلدهای حذف شده (که در API نبودند)
+
+### ❌ فیلدهایی که حذف کردیم:
+
+- **`price`** - نه در محصول و نه در variant
+- **`sku`** - نه در محصول و نه در variant
+- **`status`** - در API نبود
+- **`name`** برای variant - در API نبود
+
+### 🔄 تغییرات انجام شده:
+
+1. **Models** به‌روزرسانی شد طبق API دقیق
+2. **Product Form** فیلدهای اضافی حذف شد
+3. **Variant Manager** ساده‌سازی شد طبق API
+4. **Validation** تنظیم شد برای فیلدهای جدید
+
+## 🛠️ فایلهای تغییر یافته:
+
+- `src/pages/products/core/_models.ts`
+- `src/pages/products/product-form/ProductFormPage.tsx`
+- `src/components/ui/VariantManager.tsx`
+
+## 🎉 نتیجه نهایی:
+
+**سیستم کاملاً آماده و مطابق با API شماست! 🚀**