@tailor-platform/erp-kit 0.2.0 → 0.2.2

package/src/modules/product-management/docs/queries/CalculateCategoryDepth.md

@@ -0,0 +1,47 @@
+# CalculateCategoryDepth
+
+## Overview
+
+CalculateCategoryDepth determines the depth of a product category in the tree hierarchy by walking up the ancestor chain from a given category to the root. Depth is defined as the number of nodes in the path from root to the target category (root = depth 1). This is essential for enforcing maximum depth constraints when creating or moving categories.
+
+## Business Rules
+
+- Depth is calculated by traversing parentId references from the target category up to the root
+- Root categories (parentId = null) have depth 1
+- Each additional ancestor increments the depth by 1
+- The traversal stops when a category with parentId = null is reached or a parent is not found
+- Used together with maxDepth parameter to enforce tree depth limits
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive categoryId] --> B[SELECT category where id = categoryId]
+    B --> C{Category found?}
+    C -->|No| D[Return error: CATEGORY_NOT_FOUND]
+    C -->|Yes| E[Initialize depth = 1, currentId = parentId]
+    E --> F{currentId is null?}
+    F -->|Yes| G[Return current depth]
+    F -->|No| H[SELECT ancestor where id = currentId]
+    H --> I{Ancestor found?}
+    I -->|No| G
+    I -->|Yes| J[Increment depth]
+    J --> K[Set currentId = ancestor.parentId]
+    K --> F
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **CATEGORY_NOT_FOUND**: The starting category or an ancestor in the chain is not found — traversal stops and returns partial depth
+
+## Test Cases
+
+- returns depth 1 for root category
+- returns depth 2 for child of root
+- returns depth 3 for grandchild of root
+- returns CategoryNotFoundError when category does not exist
+- returns partial depth when ancestor in chain is not found

package/src/modules/product-management/docs/queries/DetectCategoryCircularReference.md

@@ -0,0 +1,51 @@
+# DetectCategoryCircularReference
+
+## Overview
+
+DetectCategoryCircularReference validates that reparenting a product category would not create a circular reference in the tree hierarchy. It walks up the ancestor chain from the proposed new parent, checking whether the category being moved appears as an ancestor. If the moved category is found in the ancestor chain, the move would create a cycle.
+
+## Business Rules
+
+- A category cannot be moved to become a descendant of itself
+- Self-referencing is explicitly rejected: newParentId === categoryId
+- Ancestor chain is traversed from the new parent upward to the root
+- If the moved category's ID is found in the ancestor chain, the move is circular
+- Traversal stops at root (parentId = null) or broken chain (parent not found)
+- Only relevant when newParentId is non-null (promoting to root cannot create a cycle)
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive categoryId + newParentId] --> B[SELECT category where id = categoryId]
+    B --> C{Category found?}
+    C -->|No| D[Return error: CATEGORY_NOT_FOUND]
+    C -->|Yes| E{newParentId === categoryId?}
+    E -->|Yes| F[Return isCircular: true]
+    E -->|No| G[Set ancestorId = newParentId]
+    G --> H[SELECT ancestor where id = ancestorId]
+    H --> I{Ancestor found?}
+    I -->|No| J[Return isCircular: false]
+    I -->|Yes| K[Set ancestorId = ancestor.parentId]
+    K --> L{ancestorId === categoryId?}
+    L -->|Yes| F
+    L -->|No| M{ancestorId is null?}
+    M -->|Yes| J
+    M -->|No| H
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **CATEGORY_NOT_FOUND**: The specified categoryId does not exist
+
+## Test Cases
+
+- returns CategoryNotFoundError when category does not exist
+- detects self-reference as circular
+- detects circular reference when moving node under its descendant
+- returns not circular for valid move
+- returns not circular when ancestor chain is broken

package/src/modules/product-management/docs/queries/GetProduct.md

@@ -0,0 +1,42 @@
+# GetProduct
+
+## Overview
+
+GetProduct retrieves a single product record by id or code. The input is a union type — callers specify exactly one lookup field. This serves as the core product lookup for existence checks, status validation, and all product lifecycle commands.
+
+## Business Rules
+
+- Accepts one of two lookup variants:
+  - `{ id }` — retrieves by unique identifier (used for existence/state checks in lifecycle commands)
+  - `{ code }` — retrieves by product code (used for uniqueness validation during creation; code is immutable after creation)
+- Returns the full product record including all fields (id, code, name, description, unitId, status, timestamps)
+- Returns null if no matching product is found
+- All comparisons are exact (case-sensitive)
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input] --> B{Which field?}
+    B -->|id| C[SELECT from Product where id = input.id]
+    B -->|code| D[SELECT from Product where code = input.code]
+    C --> E{Product found?}
+    D --> E
+    E -->|Yes| F[Return product record]
+    E -->|No| G[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PRODUCT_NOT_FOUND**: No product matches the given criteria — caller receives null
+
+## Test Cases
+
+- returns product when found
+- returns null when not found
+- returns product when found
+- returns null when not found

package/src/modules/product-management/docs/queries/GetProductAttribute.md

@@ -0,0 +1,42 @@
+# GetProductAttribute
+
+## Overview
+
+GetProductAttribute retrieves a single product attribute record by id or code. The input is a union type — callers specify exactly one lookup field. This serves as the core attribute lookup for existence checks, type validation, and attribute management commands.
+
+## Business Rules
+
+- Accepts one of two lookup variants:
+  - `{ id }` — retrieves by unique identifier (used for existence checks and attribute operations)
+  - `{ code }` — retrieves by attribute code (used for uniqueness validation during creation; code is immutable after creation)
+- Returns the full attribute record including all fields (id, code, name, timestamps)
+- Returns null if no matching attribute is found
+- All comparisons are exact (case-sensitive)
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input] --> B{Which field?}
+    B -->|id| C[SELECT from ProductAttribute where id = input.id]
+    B -->|code| D[SELECT from ProductAttribute where code = input.code]
+    C --> E{Attribute found?}
+    D --> E
+    E -->|Yes| F[Return attribute record]
+    E -->|No| G[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **ATTRIBUTE_NOT_FOUND**: No attribute matches the given criteria — caller receives null
+
+## Test Cases
+
+- returns attribute when found
+- returns null when not found
+- returns attribute when found
+- returns null when not found

package/src/modules/product-management/docs/queries/GetProductAttributeAssignment.md

@@ -0,0 +1,34 @@
+# GetProductAttributeAssignment
+
+## Overview
+
+GetProductAttributeAssignment retrieves a specific product-to-attribute assignment by the composite key of productId and attributeId. Used for upsert detection in SetProductAttributeAssignment and for validating attribute-product relationships.
+
+## Business Rules
+
+- Searches ProductAttributeAssignment table using both productId AND attributeId as a composite filter
+- Returns the full assignment record if found (id, productId, attributeId, value, timestamps)
+- Returns null if no assignment exists for the given pair
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive productId + attributeId] --> B[SELECT from ProductAttributeAssignment where productId = input AND attributeId = input]
+    B --> C{Assignment found?}
+    C -->|Yes| D[Return assignment record]
+    C -->|No| E[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **ASSIGNMENT_NOT_FOUND**: No assignment exists for the product-attribute pair — caller receives null
+
+## Test Cases
+
+- returns assignments when found by productId and attributeId
+- returns empty array when not found

package/src/modules/product-management/docs/queries/GetProductAttributeValue.md

@@ -0,0 +1,40 @@
+# GetProductAttributeValue
+
+## Overview
+
+GetProductAttributeValue retrieves a single product attribute value record by id or by the combination of attributeId and label. Used for existence checks before updating or removing attribute values, validating attribute value references in attribute assignment commands, and enforcing label uniqueness within an attribute.
+
+## Business Rules
+
+- Accepts one of two lookup variants:
+  - `{ id }` — retrieves by unique identifier (used for existence/state checks in lifecycle commands)
+  - `{ attributeId, label }` — retrieves by attribute and label combination (used for uniqueness validation during creation; label must be unique within an attribute)
+- Returns the full attribute value record including all fields (id, attributeId, label, timestamps)
+- Returns null if no matching attribute value is found
+- Label comparison is exact (case-sensitive)
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input] --> B{Which lookup?}
+    B -->|id| C[SELECT from ProductAttributeValue where id = input.id]
+    B -->|attributeId + label| D[SELECT from ProductAttributeValue where attributeId = input.attributeId AND label = input.label]
+    C --> E{Value found?}
+    D --> E
+    E -->|Yes| F[Return value record]
+    E -->|No| G[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **VALUE_NOT_FOUND**: No attribute value matches the given id — caller receives null
+
+## Test Cases
+
+- returns value when found
+- returns null when not found

package/src/modules/product-management/docs/queries/GetProductCategory.md

@@ -0,0 +1,42 @@
+# GetProductCategory
+
+## Overview
+
+GetProductCategory retrieves a single product category record by id or code. The input is a union type — callers specify exactly one lookup field. This serves as the core category lookup for existence checks, parent validation, and category management commands.
+
+## Business Rules
+
+- Accepts one of two lookup variants:
+  - `{ id }` — retrieves by unique identifier (used for existence checks and tree operations)
+  - `{ code }` — retrieves by category code (used for uniqueness validation during creation; code is immutable after creation)
+- Returns the full category record including all fields (id, code, name, parentId, timestamps)
+- Returns null if no matching category is found
+- All comparisons are exact (case-sensitive)
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input] --> B{Which field?}
+    B -->|id| C[SELECT from ProductCategory where id = input.id]
+    B -->|code| D[SELECT from ProductCategory where code = input.code]
+    C --> E{Category found?}
+    D --> E
+    E -->|Yes| F[Return category record]
+    E -->|No| G[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **CATEGORY_NOT_FOUND**: No category matches the given criteria — caller receives null
+
+## Test Cases
+
+- returns category when found
+- returns null when not found
+- returns category when found
+- returns null when not found

package/src/modules/product-management/docs/queries/GetProductCategoryAssignment.md

@@ -0,0 +1,34 @@
+# GetProductCategoryAssignment
+
+## Overview
+
+GetProductCategoryAssignment retrieves a specific product-to-category assignment by the composite key of productId and categoryId. Used for duplicate detection during assignment creation and existence verification before removal.
+
+## Business Rules
+
+- Searches ProductCategoryAssignment table using both productId AND categoryId as a composite filter
+- Returns the full assignment record if found (id, productId, categoryId, timestamps)
+- Returns null if no assignment exists for the given pair
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive productId + categoryId] --> B[SELECT from ProductCategoryAssignment where productId = input AND categoryId = input]
+    B --> C{Assignment found?}
+    C -->|Yes| D[Return assignment record]
+    C -->|No| E[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **ASSIGNMENT_NOT_FOUND**: No assignment exists for the product-category pair — caller receives null
+
+## Test Cases
+
+- returns assignment when found
+- returns null when not found

package/src/modules/product-management/docs/queries/GetProductVariant.md

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

package/src/modules/product-management/docs/queries/ListAttributeAssignmentsByAttribute.md

@@ -0,0 +1,34 @@
+# ListAttributeAssignmentsByAttribute
+
+## Overview
+
+ListAttributeAssignmentsByAttribute retrieves all product assignments for a given attribute. Used as a guard check before attribute deletion to enforce the constraint that attributes assigned to any product cannot be deleted. Also used to check attribute value usage on ACTIVE products before removing values.
+
+## Business Rules
+
+- Searches ProductAttributeAssignment table for all records matching the given attributeId
+- Returns all matching assignment records as an array
+- Returns an empty array if the attribute is not assigned to any product
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive attributeId] --> B[SELECT from ProductAttributeAssignment where attributeId = input]
+    B --> C{Assignments found?}
+    C -->|Yes| D[Return assignment records]
+    C -->|No| E[Return empty array]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+None
+
+## Test Cases
+
+- returns assignments when found
+- returns empty array when no assignments

package/src/modules/product-management/docs/queries/ListCategoryAssignmentsByProduct.md

@@ -0,0 +1,35 @@
+# ListCategoryAssignmentsByProduct
+
+## Overview
+
+ListCategoryAssignmentsByProduct retrieves all category assignments for a given product. This is the inverse lookup of ListProductCategoryAssignments (which queries by categoryId). Used for displaying which categories a product belongs to and for validating multi-category assignment constraints.
+
+## Business Rules
+
+- Accepts `{ productId }` as the required input
+- Returns all ProductCategoryAssignment records for the specified product as an array
+- Returns an empty array if the product has no category assignments
+- Each returned record includes full fields (id, productId, categoryId, timestamps)
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive productId] --> B[SELECT from ProductCategoryAssignment where productId = input.productId]
+    B --> C{Results found?}
+    C -->|Yes| D[Return array of assignment records]
+    C -->|No| E[Return empty array]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PRODUCT_NOT_FOUND**: The specified productId does not reference an existing Product — caller receives an empty array
+
+## Test Cases
+
+- returns assignments when found
+- returns empty array when no assignments

package/src/modules/product-management/docs/queries/ListProductAttributeAssignments.md

@@ -0,0 +1,34 @@
+# ListProductAttributeAssignments
+
+## Overview
+
+ListProductAttributeAssignments retrieves all attribute assignments for a given product. Used by variant generation to collect all attribute values and compute combinations, and by product deletion to clean up assignments.
+
+## Business Rules
+
+- Searches ProductAttributeAssignment table for all records matching the given productId
+- Returns all matching assignment records as an array
+- Returns an empty array if the product has no attribute assignments
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive productId] --> B[SELECT from ProductAttributeAssignment where productId = input]
+    B --> C{Assignments found?}
+    C -->|Yes| D[Return assignment records]
+    C -->|No| E[Return empty array]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+None
+
+## Test Cases
+
+- returns assignments when found
+- returns empty array when no assignments

package/src/modules/product-management/docs/queries/ListProductAttributeValues.md

@@ -0,0 +1,36 @@
+# ListProductAttributeValues
+
+## Overview
+
+ListProductAttributeValues retrieves all attribute value records for a given attribute. Used for enumerating available options during attribute assignment, uniqueness validation when creating new values, and providing input choices for variant generation.
+
+## Business Rules
+
+- Accepts `{ attributeId }` as the required input
+- Returns all ProductAttributeValue records belonging to the specified attribute as an array
+- Returns an empty array if the attribute has no values
+- Results are ordered by creation timestamp (ascending) for consistent enumeration
+- All returned records include full fields (id, attributeId, label, timestamps)
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive attributeId] --> B[SELECT from ProductAttributeValue where attributeId = input.attributeId]
+    B --> C{Results found?}
+    C -->|Yes| D[Return array of attribute value records]
+    C -->|No| E[Return empty array]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **ATTRIBUTE_NOT_FOUND**: The specified attributeId does not reference an existing ProductAttribute — caller receives an empty array
+
+## Test Cases
+
+- returns values when found
+- returns empty array when no values

package/src/modules/product-management/docs/queries/ListProductCategoryAssignments.md

@@ -0,0 +1,34 @@
+# ListProductCategoryAssignments
+
+## Overview
+
+ListProductCategoryAssignments retrieves all product assignments for a given category. Used as a guard check before category deletion to enforce the constraint that categories with product assignments cannot be deleted.
+
+## Business Rules
+
+- Searches ProductCategoryAssignment table for all records matching the given categoryId
+- Returns all matching assignment records as an array
+- Returns an empty array if the category has no product assignments
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive categoryId] --> B[SELECT from ProductCategoryAssignment where categoryId = input]
+    B --> C{Assignments found?}
+    C -->|Yes| D[Return assignment records]
+    C -->|No| E[Return empty array]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+None
+
+## Test Cases
+
+- returns assignments when found
+- returns empty array when no assignments

package/src/modules/product-management/docs/queries/ListProductCategoryChildren.md

@@ -0,0 +1,34 @@
+# ListProductCategoryChildren
+
+## Overview
+
+ListProductCategoryChildren retrieves the direct child categories of a given product category. Used as a guard check before category deletion to enforce the constraint that only leaf categories (with no children) can be deleted.
+
+## Business Rules
+
+- Searches ProductCategory table for records with parentId matching the given category ID
+- Returns all matching child category records as an array
+- Returns an empty array if the category has no children (is a leaf category)
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive parentId] --> B[SELECT from ProductCategory where parentId = input]
+    B --> C{Children found?}
+    C -->|Yes| D[Return child records]
+    C -->|No| E[Return empty array]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+None
+
+## Test Cases
+
+- returns children when found
+- returns empty array when no children

package/src/modules/product-management/docs/queries/ListProductVariants.md

@@ -0,0 +1,34 @@
+# ListProductVariants
+
+## Overview
+
+ListProductVariants retrieves all variant records for a given product. Used during variant generation to detect existing combinations and skip duplicates, ensuring idempotent generation.
+
+## Business Rules
+
+- Searches ProductVariant table for all records matching the given productId
+- Returns all matching variant records as an array, including axis value combination and linked Item ID
+- Returns an empty array if the product has no variants
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive productId] --> B[SELECT from ProductVariant where productId = input]
+    B --> C{Variants found?}
+    C -->|Yes| D[Return variant records]
+    C -->|No| E[Return empty array]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+None
+
+## Test Cases
+
+- returns variants when found
+- returns empty array when no variants

package/src/modules/product-management/generated/enums.ts

@@ -0,0 +1,9 @@
+/**
+ * Lifecycle status: DRAFT, ACTIVE, ARCHIVED
+ */
+export const ProductStatus = {
+  "DRAFT": "DRAFT",
+  "ACTIVE": "ACTIVE",
+  "ARCHIVED": "ARCHIVED"
+} as const;
+export type ProductStatus = (typeof ProductStatus)[keyof typeof ProductStatus];