# Order Migration Guide

This guide details the steps to migrate orders from Magento to Shopify using the Zodiac Middleware.

## Prerequisites

1.  **Database Configuration**: Ensure your `.env` file has the correct credentials for the **Magento** database connection (`DB_CONNECTION=magento`).
2.  **Shopify Credentials**: Ensure your `.env` has the Shopify Store URL and Admin Access Token (`SHOPIFY_STORE_URL`, `SHOPIFY_ACCESS_TOKEN`).
3.  **Queue Worker**: You MUST run a queue worker to process the jobs dispatched by the migration command.
    ```bash
    # Process jobs efficiently (Production ready)
    # IMPORTANT: You MUST specify the queue name
    php artisan queue:work --queue=order-migrations

    # OR for development (reloads code changes automatically)
    php artisan queue:listen --queue=order-migrations
    ```

    > [!NOTE]
    > **Production Deployment (Supervisor)**:
    > In `/etc/supervisor/conf.d/laravel-worker.conf`, ensure you set the command properly:
    > `command=php /path/to/artisan queue:work --queue=order-migrations --tries=3`

## 1. Test Single Order Migration

Before running the full migration, test with a single order to verify data mapping (customers, addresses, discounts, metafields).

```bash
php artisan migration:test-order <magento_order_id>
```

**Example:**
```bash
php artisan migration:test-order 52146
```

-   This command will display a preview of the JSON payload.
-   Type `yes` to attempt sending it to Shopify immediately.
-   Check the output for success or validation errors (e.g., missing metafields).

## 2. Run Full Migration

To migrate multiple orders, use the `migrate:orders` command. This dispatches background jobs for processing.

```bash
php artisan migrate:orders {--limit=} {--chunk=}
```

-   `--limit`: (Optional) Limit the number of orders to process (e.g., test with the first 100).
-   `--chunk`: (Optional) Number of orders to process per database chunk (default 100).

**Example:**
```bash
# Migrate first 1000 orders
php artisan migrate:orders --limit=1000 --chunk=100

# Migrate ALL orders
php artisan migrate:orders
```

## 3. Monitoring & Logging

We use a hybrid logging strategy to ensure performance and debuggability.

### Database Logging (`migration_logs` table)
-   Tracks the **status** of each order (`processing`, `completed`, `failed`).
-   Maps `magento_order_id` to `shopify_order_id`.
-   **Note**: Large payloads are **NOT** stored here to prevent database bloating.

### File Logging
-   Detailed logs, including the full JSON payload for every order, are stored in:
    `storage/logs/migration/orders.log`
-   Errors and exceptions are also logged here and in `storage/logs/laravel.log`.

## 4. Troubleshooting

-   **"Metafields value can't be blank"**: The transformer automatically filters out empty metafields to prevent this. Ensure your data source has values if a field is critical.
-   **Rate Limiting**: The job includes a basic `sleep(1)` to respect Shopify API limits. If you hit `429 Too Many Requests`, the job will automatically release back to the queue to retry later.
-   **Timeouts**: Large orders (many line items) may take longer. Ensure your `queue:work` timeout is sufficient.