# Test Scenario Guide: Supply Order Item Product Matching

### 2. Scenario Introduction 💡
In the supply chain workflow, specifically within the **Awaiting Approval** stage for supply order items, users often encounter items with incomplete or unverified product data. To maintain a clean and standardized product catalog, it is critical to identify if an item already exists in the system before creating a new one or approving temporary data.

This feature introduces a **fuzzy matching endpoint** that analyzes a supply order item's name, brand, and part number against the existing product catalog. By showing products with a **80% or higher similarity**, supervisors can quickly identify duplicates and use the existing **Merge Product** functionality to link the item to the correct catalog entry.

---

### 3. Technical Schema Changes (Detailed) 🔍
This update introduces a new API endpoint and service logic without modifying the database schema.

*   **Endpoint:** `GET /api/v1/supply/order-items/{item}/matching-products`
*   **Request Params:**
    *   `item`: The ID of the `SupplyOrderItem` to analyze.
*   **Validation Rules:**
    *   Standard Laravel route binding ensures the `SupplyOrderItem` exists.
*   **Response Changes:**
    *   Returns a collection of match objects, each containing:
        *   `product_id`: ID of the matching catalog product.
        *   `name`: Product name.
        *   `brand`: Product brand.
        *   `part_number`: Product part number/SKU.
        *   `model`: Product model.
        *   `similarity_score`: A float (0.80 to 1.00) indicating match strength.
        *   `match_detail`: JSON object explaining which fields triggered the match (e.g., `name_similarity`, `normalized_part_number_exact`).
        *   `pricing_count`: Number of existing price quotes for this product.

---

### 4. Why the Update? (Change Log) 🔄

| Feature | Previous Behavior | New Behavior | Benefit |
| :--- | :--- | :--- | :--- |
| **Product Discovery** | Users had to manually search the catalog to check for duplicates. | System automatically suggests matches with $\ge 80\%$ similarity. | Reduced manual effort & data duplication. |
| **Data Integrity** | High risk of creating duplicate products for the same item. | Encourages merging items with existing catalog products. | Standardized product catalog. |
| **Decision Support** | Supervisors lacked immediate context on similar products. | Direct endpoint provides match scores and reasons. | Faster approval workflow. |

---

### 5. API Endpoints Table 📊

| Process | Endpoint | Method | Description |
| :--- | :--- | :--- | :--- |
| **Identify Matches** | `/api/v1/supply/order-items/{item}/matching-products` | `GET` | Retrieve catalog products with $\ge 80\%$ similarity to the item. |
| **Standardize Data** | `/api/v1/supply/order-items/{item}/merge-product` | `POST` | (Existing) Links the item to a selected catalog product. |

---

### 6. Test Cases 🧪

*   **[Case 1] The Happy Path:**
    1.  Select a `SupplyOrderItem` in `PENDING_DATA` status.
    2.  Call the `matching-products` endpoint.
    3.  Verify that products with similar names or part numbers are returned with correct `similarity_score` ($\ge 0.8$).
    4.  Verify `match_detail` accurately reflects why the product matched.

*   **[Case 2] Exact Match (Part Number):**
    1.  Ensure a product exists in the catalog with Part Number `ABC-123`.
    2.  Create a supply order item with Part Number `abc 123`.
    3.  Call the endpoint; it should return the catalog product with a score of `1.0` (Normalized Exact Match).

*   **[Case 3] Low Similarity (Below Threshold):**
    1.  Request matches for an item with a unique name and no part number.
    2.  If no catalog products have $\ge 80\%$ similarity, the response should be an empty successful collection `[]`.

*   **[Case 4] Unauthorized Access:**
    1.  Attempt to access the endpoint without a valid authentication token.
    2.  Expected result: `401 Unauthorized`.