# GetProductVariant

## Overview

GetProductVariant retrieves a single product variant record by id or by the combination of productId and axisValueKey. This serves as the core variant lookup for traceability — linking a product's attribute value combination to the generated Item in item-management.

## Business Rules

- Accepts one of two lookup variants:
  - `{ id }` — retrieves by unique variant identifier
  - `{ productId, axisValueKey }` — retrieves by the product and canonical axis value combination key (e.g., `"value-1|value-3"`)
- Returns the full variant record including all fields (id, productId, axisValueKey, itemId, timestamps)
- Returns null if no matching variant is found
- The axisValueKey comparison is exact (canonical sorted format)

## Process Flow

```mermaid
flowchart TD
    A[Receive input] --> B{Which lookup?}
    B -->|id| C[SELECT from ProductVariant where id = input.id]
    B -->|productId + axisValueKey| D[SELECT from ProductVariant where productId = input.productId AND axisValueKey = input.axisValueKey]
    C --> E{Variant found?}
    D --> E
    E -->|Yes| F[Return variant record]
    E -->|No| G[Return null]
```

## External Dependencies

- None

## Error Scenarios

- **VARIANT_NOT_FOUND**: No variant matches the given criteria — caller receives null

## Test Cases

- returns variant by id
- returns variant by productId and axisValueKey
- returns null when not found