# Configurable Product Migration Documentation (Magento to Shopify)

This document outlines the process of migrating **Configurable Products** from Magento to Shopify using the `migrate:configurable-products` artisan command.

## 1. Command Overview
**Command:** `php artisan migrate:configurable-products {--limit=} {--sku=} {--store=0} {--force}`

- **Purpose:** Identifies parent configurable products in Magento, fetches all associated simple child products, transforms the entire family into a Shopify product with multiple variants, and manages the sync state.
- **Workflow:** 
    1. Parent product identified.
    2. Children products identified via `catalog_product_super_link`.
    3. Transformation logic groups children by **Size**.
    4. Shopify product is created/updated with the "Size" option.
    5. Variants are synced individually or in bulk.

---

## 2. Data Sourcing & Relationship (Magento)

### A. Core Relationship
| Magento Table | Data Points | Usage |
| :--- | :--- | :--- |
| `catalog_product_entity` | `entity_id`, `sku`, `type_id` | Identifies parent (configurable) and children (simple). |
| `catalog_product_super_link` | `parent_id`, `product_id` | Defines the relationship between the parent and child SKUs. |

### B. Parent Data (The Shopify Product)
The Parent Magento product provides the base metadata for the Shopify Product:
- **Title:** Magento `name` or `pname`.
- **Description:** Magento `description`.
- **Vendor:** Magento `brands`.
- **Type:** Magento `attribute_set_name`.
- **Handle:** Magento `url_key`.

### C. Child Data (The Shopify Variants)
Each Simple product associated with the parent is converted into a Shopify Variant.
- **Deduplication Logic:** If multiple children have the same **Size**, the system prioritizes the one with **Status = 1 (Enabled)**.
- **Price:** Fetched from Child SKU (falls back to Parent Price if child price is null).
- **SKU:** Each variant maintains its original Magento SKU for tracking and inventory.

---

## 3. Transformation & Option Mapping

### A. Variant Options
- **Strict Requirement:** Only **"Size"** is used as a variant option in Shopify. Other attributes (Color, Fit) are moved to metafields.
- **Option Values:** Collected from all active child products to build the `productOptions` in Shopify.

### B. Parent-Level Metafields
Parent metafields follow the standard definitions but include **Fallback Inheritance**:
1. If a value is missing on the Parent, the system checks a "Representative Child" (the first child).
2. Category names and SKU-based links (Related, Cross-sell) are converted to JSON lists.

### C. Variant-Level Metafields (Children)
Variants use a separate namespace (`custom_variant`) to avoid key collisions.
- **Inheritance:** If a child is missing an attribute (e.g., Fabric), it inherits the value from the Parent.
- **Special Fields:** `magento_status` (1/2) and `migration_date` are added to every variant for tracking.

---

## 4. Technical Workflow

### Step 1: Identification & Mapping
The job checks the `product_mappings` table for the parent SKU.
- If it exists and `--force` is not used, it skips.
- If it exists but was previously a "Simple" product in Shopify (Default Title), the job **deletes** the product and recreates it as a Configurable product to fix the option structure.

### Step 2: Shopify Product Creation
The `productCreate` mutation is called with `productOptions` (Size) and the base parent metadata. Media is attached at the product level.

### Step 3: Variant Sync
- **Update Existing:** If a variant already exists for a specific size, it updates the SKU, Price, and Metafields.
- **Bulk Create:** If new sizes are found, they are created in bulk using `productVariantsBulkCreate`.
- **Metafield Retry:** An explicit second pass is made on the first variant's metafields because Shopify sometimes ignores them during the initial creation.

---

## 5. Summary Table (Mapping)

| Field | Source (Magento) | Target (Shopify) | Logic |
| :--- | :--- | :--- | :--- |
| **Product Title** | Parent `pname` / `name` | `title` | Parent Title |
| **Product Type** | Parent `attribute_set_name` | `productType` | e.g. "Formal Shirt" |
| **Options** | Children `size` values | `productOptions` | Only "Size" is allowed |
| **Variant SKU** | Child `sku` | `variants.sku` | 1:1 Mapping |
| **Variant Price** | Child `price` | `variants.price` | Fallback to Parent Price |
| **Metafields** | Parent/Child attributes | `custom` / `custom_variant` | Uses Definitions JSON |
| **Tags** | Unified Parent + Child attributes | `tags` | Combined pool of unique tags |

---

## 6. Technical Stack
- **Command:** `App\Console\Commands\MigrateConfigurableProducts`
- **Job:** `App\Jobs\ProcessConfigurableProductMigration`
- **Transformer:** `App\Services\ConfigurableProductTransformer`
- **Mapping Model:** `App\Models\ProductMapping`