# UpdateProductAttributeValue

## Permission Scope

productCatalog

## Overview

updateProductAttributeValue updates the display label of an existing attribute value. Only the label (display name) can be changed; the value's identity (ID) remains immutable, preserving all existing references from ProductVariant records, ProductAttributeAssignment records, and generated Items.

This command enables corrections (e.g., fixing a typo "Rd" to "Red") and localization changes (e.g., renaming a value from one language to another) without disrupting variant structure or SKU integrity.

## Business Rules

- Target attribute value must exist
- New label is required and must be non-empty
- New label must be unique within the parent attribute (no duplicate labels)
- The value's ID and parent attribute reference are immutable
- Updating the label does not affect any existing ProductVariant records or generated Item SKUs

## Process Flow

```mermaid
flowchart TD
    A[Receive update value request] --> B{Attribute value exists?}
    B -->|No| C[Return error: VALUE_NOT_FOUND]
    B -->|Yes| D{New label non-empty?}
    D -->|No| E[Return error: INVALID_LABEL]
    D -->|Yes| F{Label unique within attribute?}
    F -->|No| G[Return error: DUPLICATE_VALUE]
    F -->|Yes| H[Update attribute value label]
    H --> I[Return updated value]
```

## External Dependencies

- None

## Error Scenarios

- **VALUE_NOT_FOUND**: Specified attribute value ID does not exist
- **INVALID_LABEL**: Label is empty or blank
- **DUPLICATE_VALUE**: A value with the same label already exists for this attribute

## Test Cases

- returns error when value not found
- returns error when label is empty
- returns error when label already exists on same attribute
- returns error when label is whitespace only
- updates label successfully