@tailor-platform/erp-kit 0.2.0 → 0.2.2

package/src/modules/product-management/docs/commands/CreateProductCategory.md

@@ -0,0 +1,54 @@
+# CreateProductCategory
+
+## Overview
+
+createProductCategory creates a new category node in the hierarchical product category tree. Categories can be root nodes (no parent) or child nodes referencing an existing parent. The category tree is used to classify products for commercial and marketing purposes.
+
+## Business Rules
+
+- Category code is required, must be globally unique, and is immutable after creation
+- Category name is required and must be non-empty
+- Parent ID is optional — omitting it creates a root category
+- If parent ID is provided, the parent category must exist
+- Creating a child category must not exceed the configurable maximum tree depth
+- Categories are created without any product assignments
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create request] --> B{Code provided and unique?}
+    B -->|No| C[Return error: DUPLICATE_CODE or MISSING_REQUIRED_FIELD]
+    B -->|Yes| D{Name provided?}
+    D -->|No| E[Return error: MISSING_REQUIRED_FIELD]
+    D -->|Yes| F{Parent ID provided?}
+    F -->|No| G[Create as root category]
+    F -->|Yes| H{Parent exists?}
+    H -->|No| I[Return error: PARENT_NOT_FOUND]
+    H -->|Yes| J{Depth within limit?}
+    J -->|No| K[Return error: MAX_DEPTH_EXCEEDED]
+    J -->|Yes| L[Create as child category]
+    G --> M[Return created category]
+    L --> M
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **DUPLICATE_CODE**: A category with the same code already exists
+- **MISSING_REQUIRED_FIELD**: Code or name not provided
+- **PARENT_NOT_FOUND**: Specified parent category ID does not exist
+- **MAX_DEPTH_EXCEEDED**: Adding this child would exceed the configurable maximum tree depth
+
+## Test Cases
+
+- should return MissingRequiredFieldError when code is empty
+- should return MissingRequiredFieldError when name is empty
+- should return DuplicateCodeError when code already exists
+- should return ParentNotFoundError when parent does not exist
+- should return MaxDepthExceededError when depth exceeds maxDepth
+- should create a root category when no parentId is provided
+- should create a child category when parentId is provided

package/src/modules/product-management/docs/commands/DeactivateProduct.md

@@ -0,0 +1,39 @@
+# DeactivateProduct
+
+## Overview
+
+deactivateProduct transitions a product from ACTIVE to ARCHIVED status, preventing new variant generation. Existing Items generated from this product's variants remain unaffected and continue to operate independently in item-management.
+
+## Business Rules
+
+- Target product must exist
+- Target product must be in ACTIVE status
+- Deactivating does not delete or deactivate existing generated Items
+- Deactivated products can be reactivated via reactivateProduct
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive deactivate request] --> B{Product exists?}
+    B -->|No| C[Return error: PRODUCT_NOT_FOUND]
+    B -->|Yes| D{Status is ACTIVE?}
+    D -->|No| E[Return error: INVALID_STATE_TRANSITION]
+    D -->|Yes| F[Update status to ARCHIVED]
+    F --> G[Return deactivated product]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PRODUCT_NOT_FOUND**: Specified product ID does not exist
+- **INVALID_STATE_TRANSITION**: Product is not in ACTIVE status
+
+## Test Cases
+
+- returns error when product not found
+- returns error when not in ACTIVE status
+- deactivates ACTIVE product to ARCHIVED

package/src/modules/product-management/docs/commands/DeleteProduct.md

@@ -0,0 +1,42 @@
+# DeleteProduct
+
+## Overview
+
+deleteProduct permanently removes a product from the system. Only products in DRAFT status can be deleted, as ACTIVE and ARCHIVED products may have generated variants and associated Items that must be preserved for traceability and audit purposes.
+
+## Business Rules
+
+- Target product must exist
+- Target product must be in DRAFT status
+- ACTIVE and ARCHIVED products cannot be deleted
+- Deleting a product removes all associated attribute value assignments (ProductAttributeAssignments)
+- Deleting a product removes all associated category assignments (ProductCategoryAssignments)
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive delete request] --> B{Product exists?}
+    B -->|No| C[Return error: PRODUCT_NOT_FOUND]
+    B -->|Yes| D{Status is DRAFT?}
+    D -->|No| E[Return error: DELETE_NOT_ALLOWED]
+    D -->|Yes| F[Remove attribute value assignments]
+    F --> G[Remove category assignments]
+    G --> H[Delete product record]
+    H --> I[Return success]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PRODUCT_NOT_FOUND**: Specified product ID does not exist
+- **DELETE_NOT_ALLOWED**: Product is not in DRAFT status and cannot be deleted
+
+## Test Cases
+
+- returns error when product not found
+- returns error when not DRAFT
+- deletes DRAFT product and associated records

package/src/modules/product-management/docs/commands/DeleteProductAttribute.md

@@ -0,0 +1,39 @@
+# DeleteProductAttribute
+
+## Overview
+
+deleteProductAttribute permanently removes a product attribute from the system. An attribute can only be deleted if it is not currently assigned to any product. This prevents orphaning attribute references on existing products.
+
+## Business Rules
+
+- Target attribute must exist
+- Attribute deletion is blocked if the attribute is assigned to any product (has any ProductAttributeAssignment records)
+- Deleting an attribute also removes all associated ProductAttributeValues
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive delete request] --> B{Attribute exists?}
+    B -->|No| C[Return error: ATTRIBUTE_NOT_FOUND]
+    B -->|Yes| D{Assigned to any product?}
+    D -->|Yes| E[Return error: ATTRIBUTE_IN_USE]
+    D -->|No| F[Remove attribute values]
+    F --> G[Delete attribute record]
+    G --> H[Return success]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **ATTRIBUTE_NOT_FOUND**: Specified attribute ID does not exist
+- **ATTRIBUTE_IN_USE**: Attribute is assigned to one or more products and cannot be deleted
+
+## Test Cases
+
+- returns error when attribute not found
+- returns error when attribute is in use
+- deletes attribute and values successfully

package/src/modules/product-management/docs/commands/DeleteProductAttributeValue.md

@@ -0,0 +1,42 @@
+# DeleteProductAttributeValue
+
+## Overview
+
+deleteProductAttributeValue deletes a predefined value from an existing attribute. Deletion is blocked if the value is currently in use on any ACTIVE product, preventing the invalidation of existing variant configurations.
+
+## Business Rules
+
+- Target attribute value must exist
+- Value deletion is blocked if the value is in use on any ACTIVE product
+- Values used only on DRAFT products can be deleted
+- Deleting a value also removes any ProductAttributeAssignment records referencing it on DRAFT products
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive delete value request] --> B{Attribute value exists?}
+    B -->|No| C[Return error: VALUE_NOT_FOUND]
+    B -->|Yes| D{Value in use on ACTIVE product?}
+    D -->|Yes| E[Return error: VALUE_IN_USE]
+    D -->|No| F[Delete product attribute assignment references on DRAFT products]
+    F --> G[Delete attribute value record]
+    G --> H[Return success]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **VALUE_NOT_FOUND**: Specified attribute value ID does not exist
+- **ATTRIBUTE_NOT_FOUND**: Parent attribute of the value does not exist (data integrity check)
+- **VALUE_IN_USE**: Value is in use on one or more ACTIVE products
+
+## Test Cases
+
+- returns error when value not found
+- returns error when parent attribute does not exist
+- returns error when value is in use on ACTIVE product
+- deletes value and cleans up DRAFT product assignments

package/src/modules/product-management/docs/commands/DeleteProductCategory.md

@@ -0,0 +1,43 @@
+# DeleteProductCategory
+
+## Overview
+
+deleteProductCategory permanently removes a category from the tree. Only leaf categories (no children) with no product assignments can be deleted. This prevents orphaning child categories or breaking product classification.
+
+## Business Rules
+
+- Target category must exist
+- Category must have no child categories
+- Category must have no product assignments (no ProductCategoryAssignment records)
+- Deletion is permanent and cannot be undone
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive delete request] --> B{Category exists?}
+    B -->|No| C[Return error: CATEGORY_NOT_FOUND]
+    B -->|Yes| D{Has child categories?}
+    D -->|Yes| E[Return error: HAS_CHILDREN]
+    D -->|No| F{Has product assignments?}
+    F -->|Yes| G[Return error: HAS_ASSIGNMENTS]
+    F -->|No| H[Delete category record]
+    H --> I[Return success]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **CATEGORY_NOT_FOUND**: Specified category ID does not exist
+- **HAS_CHILDREN**: Category has child categories and cannot be deleted
+- **HAS_ASSIGNMENTS**: Category has product assignments and cannot be deleted
+
+## Test Cases
+
+- should return CategoryNotFoundError when category does not exist
+- should return HasChildrenError when category has children
+- should return HasAssignmentsError when category has assignments
+- should delete leaf category successfully

package/src/modules/product-management/docs/commands/GenerateVariants.md

@@ -0,0 +1,68 @@
+# GenerateVariants
+
+## Overview
+
+generateVariants creates product variants from the cartesian product of attribute values assigned to an ACTIVE product. Each new variant creates a corresponding Item in item-management with a SKU produced by the injectable SKU generation strategy (default: sequential numbering based on product code). Generation is idempotent — existing axis value combinations are skipped.
+
+The SKU generation strategy is injectable at module configuration time. The default strategy produces SKUs like `CLASSIC-TSHIRT-001`, `CLASSIC-TSHIRT-002` using sequential numbering per product. This avoids coupling SKUs to attribute value labels, ensuring label changes do not create inconsistencies. Custom strategies can implement any pattern (attribute-value slug, brand prefix, hash-based, etc.).
+
+## Business Rules
+
+- Target product must exist and be in ACTIVE status
+- Product must have at least one attribute with assigned values
+- Each unique combination of attribute values produces one variant
+- Existing combinations are skipped (idempotent generation)
+- Each new variant creates exactly one Item in item-management via createItem
+- Generated Items are created in DRAFT status
+- Generated Items inherit the product's configured UoM
+- SKU is produced by the configured SKU generation strategy (receives product code, axis values, and current variant count for sequential numbering)
+- ProductVariant records store productId, axis value combination, and generated itemId
+- Generation fails atomically if any Item creation fails (no partial generation)
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive generate request] --> B{Product exists?}
+    B -->|No| C[Return error: PRODUCT_NOT_FOUND]
+    B -->|Yes| D{Status is ACTIVE?}
+    D -->|No| E[Return error: INVALID_PRODUCT_STATUS]
+    D -->|Yes| F[Collect all attribute assignments and values]
+    F --> G{Any attributes assigned?}
+    G -->|No| H[Return error: NO_VARIANT_AXES]
+    G -->|Yes| I[Compute cartesian product of attribute values]
+    I --> J{For each combination}
+    J --> K{Variant already exists?}
+    K -->|Yes| L[Skip]
+    K -->|No| M[Generate SKU via strategy]
+    M --> N[Create Item in item-management]
+    N --> O[Create ProductVariant record]
+    O --> J
+    J -->|All done| P[Return generated variants]
+```
+
+## External Dependencies
+
+- [item-management::createItem](../../../item-management/docs/commands/CreateItem.md) - Creates an Item for each new variant with generated SKU and inherited UoM
+
+## Error Scenarios
+
+- **PRODUCT_NOT_FOUND**: Specified product ID does not exist
+- **INVALID_PRODUCT_STATUS**: Product is not in ACTIVE status (DRAFT or ARCHIVED)
+- **NO_VARIANT_AXES**: Product has no attributes with assigned values
+- **ATTRIBUTE_NOT_FOUND**: Referenced attribute no longer exists (data integrity check)
+- **ATTRIBUTE_VALUE_NOT_FOUND**: Referenced attribute value no longer exists (data integrity check)
+- **ITEM_CREATION_FAILED**: Item creation in item-management failed (e.g., duplicate SKU) — entire generation is rolled back
+
+## Test Cases
+
+- should return ProductNotFoundError when product does not exist
+- should return InvalidProductStatusError when product is not ACTIVE
+- should return NoVariantAxesError when no attribute assignments exist
+- should return AttributeNotFoundError when referenced attribute no longer exists
+- should return AttributeValueNotFoundError when referenced value no longer exists
+- should skip existing variant combinations (idempotency)
+- should return ItemCreationFailedError when item creation fails
+- should generate multi-axis cartesian product variants
+- should only generate new combinations when some already exist
+- should generate variants successfully

package/src/modules/product-management/docs/commands/MoveProductCategory.md

@@ -0,0 +1,54 @@
+# MoveProductCategory
+
+## Overview
+
+moveProductCategory reparents a category node within the hierarchical tree. The category and all its descendants move to the new location. Moving to null parent promotes the category to a root node. Circular references are prevented — a category cannot be moved under one of its own descendants.
+
+## Business Rules
+
+- Target category must exist
+- If new parent ID is provided, the new parent must exist
+- A category cannot be moved under itself or any of its descendants (circular reference prevention)
+- Moving must not cause any descendant to exceed the configurable maximum tree depth
+- Moving a category preserves all product assignments and child categories
+- Moving a category updates the paths of all descendant categories to reflect the new hierarchy
+- Moving to null parent makes the category a root node
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive move request] --> B{Category exists?}
+    B -->|No| C[Return error: CATEGORY_NOT_FOUND]
+    B -->|Yes| D{New parent provided?}
+    D -->|Yes| E{New parent exists?}
+    E -->|No| F[Return error: PARENT_NOT_FOUND]
+    E -->|Yes| G{Circular reference?}
+    G -->|Yes| H[Return error: CIRCULAR_REFERENCE]
+    G -->|No| I{Depth within limit?}
+    I -->|No| J[Return error: MAX_DEPTH_EXCEEDED]
+    I -->|Yes| K[Update parent reference]
+    D -->|No| K
+    K --> K2[Update descendant paths]
+    K2 --> L[Return moved category]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **CATEGORY_NOT_FOUND**: Specified category ID does not exist
+- **PARENT_NOT_FOUND**: Specified new parent category ID does not exist
+- **CIRCULAR_REFERENCE**: Moving the category would create a circular reference (new parent is a descendant)
+- **MAX_DEPTH_EXCEEDED**: Moving would cause descendants to exceed the maximum tree depth
+
+## Test Cases
+
+- should return CategoryNotFoundError when category does not exist
+- should return ParentNotFoundError when new parent does not exist
+- should return CircularReferenceError when move would create a cycle
+- should return MaxDepthExceededError when move would exceed max depth
+- should move category to new parent successfully
+- should promote category to root when newParentId is null

package/src/modules/product-management/docs/commands/ReactivateProduct.md

@@ -0,0 +1,38 @@
+# ReactivateProduct
+
+## Overview
+
+reactivateProduct transitions a product from ARCHIVED back to ACTIVE status, allowing new variant generation with updated attribute values. This supports product relaunch scenarios where a previously discontinued product line is brought back.
+
+## Business Rules
+
+- Target product must exist
+- Target product must be in ARCHIVED status
+- After reactivation, the product behaves as any other ACTIVE product (variant generation is permitted)
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive reactivate request] --> B{Product exists?}
+    B -->|No| C[Return error: PRODUCT_NOT_FOUND]
+    B -->|Yes| D{Status is ARCHIVED?}
+    D -->|No| E[Return error: INVALID_STATE_TRANSITION]
+    D -->|Yes| F[Update status to ACTIVE]
+    F --> G[Return reactivated product]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PRODUCT_NOT_FOUND**: Specified product ID does not exist
+- **INVALID_STATE_TRANSITION**: Product is not in ARCHIVED status
+
+## Test Cases
+
+- returns error when product not found
+- returns error when not in ARCHIVED status
+- reactivates ARCHIVED product to ACTIVE

package/src/modules/product-management/docs/commands/RemoveProductFromCategory.md

@@ -0,0 +1,34 @@
+# RemoveProductFromCategory
+
+## Overview
+
+removeProductFromCategory removes the many-to-many link between a product and a product category. This does not delete either the product or the category — it only removes the classification relationship.
+
+## Business Rules
+
+- The assignment (productId, categoryId) must exist
+- Removal only affects the assignment record, not the product or category themselves
+- Products in any status (DRAFT, ACTIVE, ARCHIVED) can have category assignments removed
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive remove request] --> B{Assignment exists?}
+    B -->|No| C[Return error: ASSIGNMENT_NOT_FOUND]
+    B -->|Yes| D[Delete assignment record]
+    D --> E[Return success]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **ASSIGNMENT_NOT_FOUND**: No assignment exists for the specified product and category combination
+
+## Test Cases
+
+- should return AssignmentNotFoundError when assignment does not exist
+- should remove assignment successfully

package/src/modules/product-management/docs/commands/SetProductAttributeAssignment.md

@@ -0,0 +1,62 @@
+# SetProductAttributeAssignment
+
+## Overview
+
+setProductAttributeAssignment adds an attribute value assignment to a product. A product can have multiple values per attribute (e.g., Color=Red, Color=Blue). Each record is uniquely identified by (productId, attributeId, valueId). If the exact triple already exists, the operation is a no-op (idempotent).
+
+Since all attributes are variant axes, an additive-only policy applies for non-DRAFT products.
+
+## Business Rules
+
+- Target product must exist
+- Target attribute must exist
+- The value must reference a valid ProductAttributeValue belonging to the attribute
+- On DRAFT products: all operations are allowed (add values, add new attributes)
+- On ACTIVE products: adding new values to an already-assigned attribute is allowed (additive-only); assigning a new attribute (one not yet assigned to the product) is blocked — the attribute structure is locked once activated
+- On ARCHIVED products: all assignment changes are blocked
+- If the exact (productId, attributeId, valueId) assignment already exists, the command returns success without changes (idempotent)
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive set value request] --> B{Product exists?}
+    B -->|No| C[Return error: PRODUCT_NOT_FOUND]
+    B -->|Yes| D{Attribute exists?}
+    D -->|No| E[Return error: ATTRIBUTE_NOT_FOUND]
+    D -->|Yes| F{Value valid?}
+    F -->|No| M[Return error: INVALID_VALUE]
+    F -->|Yes| G{Already assigned?}
+    G -->|Yes| O[Return existing assignment - no-op]
+    G -->|No| H{Product in DRAFT?}
+    H -->|Yes| N[Create assignment record]
+    H -->|No| H2{Product ARCHIVED?}
+    H2 -->|Yes| P[Return error: PRODUCT_ARCHIVED]
+    H2 -->|No| I{New attribute for this product?}
+    I -->|Yes| J[Return error: AXIS_STRUCTURE_LOCKED]
+    I -->|No| N
+    N --> O2[Return assignment]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PRODUCT_NOT_FOUND**: Specified product ID does not exist
+- **ATTRIBUTE_NOT_FOUND**: Specified attribute ID does not exist
+- **PRODUCT_ARCHIVED**: Archived products do not allow any assignment changes
+- **AXIS_STRUCTURE_LOCKED**: A new attribute cannot be assigned to an ACTIVE product — the set of attributes is fixed once activated
+- **INVALID_VALUE**: Value does not reference a valid ProductAttributeValue for the attribute
+
+## Test Cases
+
+- returns error when product not found
+- returns error when attribute not found
+- returns error when value not found for attribute
+- returns error when product is ARCHIVED
+- returns existing assignment when exact triple already exists (idempotent no-op)
+- returns error when adding new attribute to ACTIVE product
+- creates new assignment on DRAFT product
+- adds new value to existing attribute on ACTIVE product (additive-only)

package/src/modules/product-management/docs/commands/UpdateProduct.md

@@ -0,0 +1,61 @@
+# UpdateProduct
+
+## Overview
+
+updateProduct modifies mutable fields of an existing product — name, description, and UoM. Product code is immutable and cannot be changed. The set of updatable fields may depend on the product's lifecycle status: UoM can only be updated in DRAFT status, while name and description can be updated in any status.
+
+## Business Rules
+
+- Target product must exist
+- Product code is immutable — any attempt to change code returns an error
+- Name can be updated in any status (DRAFT, ACTIVE, ARCHIVED); must remain non-empty
+- Description can be updated in any status
+- UoM can be updated only in DRAFT status — once activated, UoM is locked to preserve variant consistency
+- UoM must reference an existing active Unit from the primitives module
+- At least one field must be provided for update
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update request] --> B{Product exists?}
+    B -->|No| C[Return error: PRODUCT_NOT_FOUND]
+    B -->|Yes| D{Code change attempted?}
+    D -->|Yes| E[Return error: CODE_IMMUTABLE]
+    D -->|No| F{Any field provided?}
+    F -->|No| G[Return error: NO_FIELDS_TO_UPDATE]
+    F -->|Yes| H{UoM change requested?}
+    H -->|Yes| I{Status is DRAFT?}
+    I -->|No| J[Return error: UOM_LOCKED]
+    I -->|Yes| K{UoM valid and active?}
+    K -->|No| L[Return error: INVALID_UOM]
+    K -->|Yes| M[Apply updates]
+    H -->|No| M
+    M --> N[Return updated product]
+```
+
+## External Dependencies
+
+- [primitives::Unit](../../../primitives/docs/models/Unit.md) - Validates that the referenced UoM exists and is active (when UoM is being updated)
+
+## Error Scenarios
+
+- **PRODUCT_NOT_FOUND**: Specified product ID does not exist
+- **CODE_IMMUTABLE**: Attempt to change the product code
+- **MISSING_REQUIRED_FIELD**: Name is empty or blank when provided
+- **NO_FIELDS_TO_UPDATE**: No updatable fields were provided in the request
+- **UOM_LOCKED**: UoM cannot be changed after product has been activated
+- **INVALID_UOM**: Referenced unit does not exist or is inactive
+
+## Test Cases
+
+- returns error when product not found
+- returns error when code change attempted
+- returns error when no fields provided
+- returns error when name is empty
+- returns error when UoM locked on non-DRAFT
+- returns error when UoM is invalid
+- updates description successfully
+- updates UoM successfully on DRAFT product
+- updates name successfully
+- passes custom fields through

package/src/modules/product-management/docs/commands/UpdateProductAttribute.md

@@ -0,0 +1,46 @@
+# UpdateProductAttribute
+
+## Overview
+
+updateProductAttribute modifies the display name of an existing product attribute. In extensible module configurations, consumer-defined custom fields may also be updated through this command. Attribute code is immutable through this command.
+
+## Business Rules
+
+- Target attribute must exist
+- Attribute code is immutable — cannot be changed
+- At least one updatable field must be provided
+- Name must remain non-empty when provided
+- Consumer-defined custom fields may be updated
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update request] --> B{Attribute exists?}
+    B -->|No| C[Return error: ATTRIBUTE_NOT_FOUND]
+    B -->|Yes| D{Code change attempted?}
+    D -->|Yes| E[Return error: CODE_IMMUTABLE]
+    D -->|No| F{Any updatable fields provided?}
+    F -->|No| G[Return error: MISSING_REQUIRED_FIELD]
+    F -->|Yes| H[Apply name and/or custom field updates]
+    H --> I[Return updated attribute]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **ATTRIBUTE_NOT_FOUND**: Specified attribute ID does not exist
+- **CODE_IMMUTABLE**: Attempt to change the attribute code
+- **MISSING_REQUIRED_FIELD**: No updatable fields were provided, or name is empty when provided without any custom field updates
+
+## Test Cases
+
+- returns error when attribute not found
+- returns error when trying to change code
+- returns error when no fields provided
+- returns error when name is empty string
+- passes custom fields through to update
+- updates name successfully

package/src/modules/product-management/docs/commands/UpdateProductAttributeValue.md

@@ -0,0 +1,47 @@
+# UpdateProductAttributeValue
+
+## 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