# ProductVariant

## Description

ProductVariant represents a unique combination of attribute values generated from an ACTIVE product. Each variant links the product, the specific value combination, and the generated Item ID in item-management. Variants are created during the variant generation process and provide full traceability between the commercial product structure and operational SKUs.

Variant generation is idempotent -- existing combinations are skipped, and only new combinations create new variant records and corresponding Items.

## Domain Model Definitions

### Model type

Standard

### Command Definitions

- [generateVariants](../command/GenerateVariants.md) - Generate variants from attribute value combinations on an ACTIVE product

### Query Definitions

- GetProductVariant - Retrieve a single variant by id or by productId + axisValueKey
- ListProductVariants - Retrieve all variants for a given product

### Models

- ProductVariant

### Invariants

- Each variant represents a unique combination of attribute values within a product
- Each variant is associated with exactly one generated Item in item-management
- The value combination (`productId` + `axisValueKey`) must be unique
- `axisValueKey` is a canonical string key derived from sorted value IDs (e.g., `"value-1|value-3"`)
- Variants can only be created from ACTIVE products
- Once created, variant records are immutable (the link between product, values, and Item is permanent)

### Relationships

- **Belongs To Product**: Each variant is generated from exactly one product (`productId`)
- **References ProductAttributeValues**: Each variant stores the specific value combination via `axisValueKey`
- **References item-management::Item**: Each variant links to the Item created during generation (`itemId`)