@tailor-platform/erp-kit 0.1.2 → 0.2.0

package/src/modules/item-management/db/item.ts

@@ -0,0 +1,47 @@
+import {
+  db,
+  type TailorAnyDBField,
+  type TailorAnyDBType,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { unit as unitStub } from "../lib/_db_deps";
+
+export const BASE_ITEM_STATUSES = ["DRAFT", "ACTIVE", "INACTIVE"] as const;
+
+export interface CreateItemTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+  additionalStatuses?: string[];
+  unitType: TailorAnyDBType;
+}
+
+export function createItemType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreateItemTypeParams<F>,
+) {
+  const statuses = [...BASE_ITEM_STATUSES, ...(params.additionalStatuses ?? [])] as [
+    string,
+    ...string[],
+  ];
+
+  return db
+    .type("Item", {
+      sku: db.string().unique().description("Globally unique, immutable SKU identifier"),
+      name: db.string().description("Item display name"),
+      barcode: db.string({ optional: true }).unique().description("Optional unique barcode"),
+      unitId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.unitType },
+          backward: "items",
+        })
+        .description("Foreign key to Unit"),
+      status: db.enum(statuses).description("Lifecycle status: DRAFT, ACTIVE, INACTIVE"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const item = createItemType({ unitType: unitStub });

package/src/modules/item-management/db/itemTaxonomyAssignment.ts

@@ -0,0 +1,49 @@
+import {
+  db,
+  type TailorAnyDBField,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { item } from "./item";
+import { taxonomyNode } from "./taxonomyNode";
+
+export interface CreateItemTaxonomyAssignmentTypeParams<
+  F extends Record<string, TailorAnyDBField>,
+> {
+  fields?: F;
+}
+
+export function createItemTaxonomyAssignmentType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreateItemTaxonomyAssignmentTypeParams<F>,
+) {
+  return db
+    .type("ItemTaxonomyAssignment", {
+      itemId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: item },
+          backward: "itemTaxonomyAssignments",
+        })
+        .description("Foreign key to Item"),
+      taxonomyNodeId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: taxonomyNode },
+          backward: "itemTaxonomyAssignments",
+        })
+        .description("Foreign key to TaxonomyNode"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .indexes({
+      fields: ["itemId", "taxonomyNodeId"],
+      unique: true,
+      name: "item_taxonomy_assignment_unique_idx",
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const itemTaxonomyAssignment = createItemTaxonomyAssignmentType({});

package/src/modules/item-management/db/taxonomyNode.ts

@@ -0,0 +1,34 @@
+import {
+  db,
+  type TailorAnyDBField,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+
+export interface CreateTaxonomyNodeTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+}
+
+export function createTaxonomyNodeType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreateTaxonomyNodeTypeParams<F>,
+) {
+  return db
+    .type("TaxonomyNode", {
+      code: db.string().unique().description("Globally unique, immutable node code"),
+      name: db.string().description("Display name for the taxonomy node"),
+      parentId: db
+        .uuid({ optional: true })
+        .relation({
+          type: "n-1",
+          toward: { type: "self" },
+          backward: "children",
+        })
+        .description("Parent node ID (null for root nodes)"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const taxonomyNode = createTaxonomyNodeType({});

package/src/modules/item-management/docs/commands/ActivateItem.md

@@ -0,0 +1,32 @@
+# ActivateItem
+
+## Overview
+
+activateItem transitions an item from DRAFT to ACTIVE status, making it available for use in transactions across downstream modules (Sales, Purchasing, Inventory). Since name, SKU, and UoM are required at creation time, no completeness validation is needed at activation.
+
+## Business Rules
+
+- Target item must exist in the system
+- Target item must be in DRAFT status
+- After activation, the item can participate in new transactions
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive activate request] --> B{Item exists?}
+    B -->|No| C[Return error: not found]
+    B -->|Yes| D{Status is DRAFT?}
+    D -->|No| E[Return error: invalid state transition]
+    D -->|Yes| F[Update status to ACTIVE]
+    F --> G[Return activated item]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **ITEM_NOT_FOUND**: Specified item ID does not exist
+- **INVALID_STATE_TRANSITION**: Item is not in DRAFT status

package/src/modules/item-management/docs/commands/AssignItemToTaxonomy.md

@@ -0,0 +1,38 @@
+# AssignItemToTaxonomy
+
+## Overview
+
+assignItemToTaxonomy creates a link between an item and a taxonomy node, enabling many-to-many classification. A single item can be assigned to multiple taxonomy nodes simultaneously (e.g., both "Electronics > Smartphones" and "Gift Ideas > Tech Gifts"), allowing flexible multi-dimensional classification.
+
+## Business Rules
+
+- The referenced item must exist in the system
+- The referenced taxonomy node must exist in the system
+- The combination of item and taxonomy node must be unique — duplicate assignments are rejected
+- An item can be assigned to any number of taxonomy nodes
+- A taxonomy node can have any number of items assigned
+- Assignment does not change the item's status or the node's position in the tree
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive assign request] --> B{Item exists?}
+    B -->|No| C[Return error: item not found]
+    B -->|Yes| D{Node exists?}
+    D -->|No| E[Return error: node not found]
+    D -->|Yes| F{Assignment already exists?}
+    F -->|Yes| G[Return error: duplicate assignment]
+    F -->|No| H[Create assignment record]
+    H --> I[Return created assignment]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **ITEM_NOT_FOUND**: Specified item ID does not exist
+- **NODE_NOT_FOUND**: Specified taxonomy node ID does not exist
+- **DUPLICATE_ASSIGNMENT**: Item is already assigned to this taxonomy node

package/src/modules/item-management/docs/commands/CreateItem.md

@@ -0,0 +1,44 @@
+# CreateItem
+
+## Overview
+
+createItem establishes a new item in the system with a unique SKU, name, unit of measure, and optional barcode. Items can be created in either DRAFT or ACTIVE status. DRAFT items allow review and correction before activation, while ACTIVE items are immediately available for transactions.
+
+This command supports both careful item onboarding workflows (create as DRAFT, review, then activate) and rapid setup scenarios (create directly as ACTIVE).
+
+## Business Rules
+
+- SKU is required, must be globally unique across all items (active, inactive, and draft)
+- SKU is immutable after creation — it cannot be changed once assigned
+- Name is required
+- Barcode must be unique across all items when provided
+- UoM (unit of measure) is required and must reference an existing active Unit from the primitives module
+- Default status is DRAFT if not specified
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create request] --> B{Validate SKU format}
+    B -->|Invalid| C[Return error: invalid SKU]
+    B -->|Valid| D{SKU unique?}
+    D -->|No| E[Return error: duplicate SKU]
+    D -->|Yes| F{Barcode provided?}
+    F -->|Yes| G{Barcode unique?}
+    G -->|No| H[Return error: duplicate barcode]
+    G -->|Yes| I{Validate UoM}
+    F -->|No| I
+    I -->|Invalid| J[Return error: invalid UoM]
+    I -->|Valid| K[Create item record]
+    K --> L[Return created item]
+```
+
+## External Dependencies
+
+- [primitives::Unit](../../../primitives/docs/models/Unit.md) - Validates that the referenced UoM exists and is active
+
+## Error Scenarios
+
+- **DUPLICATE_SKU**: An item with the same SKU already exists
+- **DUPLICATE_BARCODE**: An item with the same barcode already exists
+- **UNIT_NOT_FOUND**: Referenced unit does not exist or is inactive

package/src/modules/item-management/docs/commands/CreateTaxonomyNode.md

@@ -0,0 +1,44 @@
+# CreateTaxonomyNode
+
+## Overview
+
+createTaxonomyNode establishes a new node in the taxonomy hierarchy. A node can be a root node (no parent) or a child node positioned under an existing parent. Each node has a globally unique code for stable API references and integrations, and a display name.
+
+This command supports both initial taxonomy setup and incremental expansion of the classification tree.
+
+## Business Rules
+
+- Node code is required and must be globally unique across all taxonomy nodes
+- Node name is required
+- Parent node ID is optional — omitting it creates a root node
+- When parent is specified, the parent node must exist
+- Creating a child node must not cause the tree to exceed the configurable maximum depth (default 10)
+- Root nodes have a null parent reference
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create request] --> B{Validate code format}
+    B -->|Invalid| C[Return error: invalid code]
+    B -->|Valid| D{Code unique?}
+    D -->|No| E[Return error: duplicate code]
+    D -->|Yes| F{Parent specified?}
+    F -->|Yes| G{Parent exists?}
+    G -->|No| H[Return error: parent not found]
+    G -->|Yes| I{Depth limit exceeded?}
+    I -->|Yes| J[Return error: max depth exceeded]
+    I -->|No| K[Create node with parent]
+    F -->|No| K[Create root node]
+    K --> L[Return created node]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **DUPLICATE_NODE_CODE**: A node with the same code already exists
+- **PARENT_NODE_NOT_FOUND**: Specified parent node ID does not exist
+- **MAX_DEPTH_EXCEEDED**: Adding this child would exceed the configurable tree depth limit

package/src/modules/item-management/docs/commands/DeactivateItem.md

@@ -0,0 +1,34 @@
+# DeactivateItem
+
+## Overview
+
+deactivateItem transitions an item from ACTIVE to INACTIVE status, removing it from availability for new transactions while preserving it for historical reference and audit trails. This supports scenarios such as discontinuing a product line or seasonal item removal.
+
+## Business Rules
+
+- Target item must exist in the system
+- Target item must be in ACTIVE status
+- Deactivated items remain in the system for reporting and audit purposes
+- Deactivation prevents the item from being used in new transactions
+- Existing transactions referencing this item are not affected
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive deactivate request] --> B{Item exists?}
+    B -->|No| C[Return error: not found]
+    B -->|Yes| D{Status is ACTIVE?}
+    D -->|No| E[Return error: invalid state transition]
+    D -->|Yes| F[Update status to INACTIVE]
+    F --> G[Return deactivated item]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **ITEM_NOT_FOUND**: Specified item ID does not exist
+- **INVALID_STATE_TRANSITION**: Item is not in ACTIVE status

package/src/modules/item-management/docs/commands/DeleteItem.md

@@ -0,0 +1,35 @@
+# DeleteItem
+
+## Overview
+
+deleteItem permanently removes a DRAFT item from the system. Only items in DRAFT status can be deleted — ACTIVE and INACTIVE items are preserved for audit trails and historical reference. This supports draft cleanup workflows where unwanted items are removed before activation.
+
+## Business Rules
+
+- Target item must exist in the system
+- Target item must be in DRAFT status
+- ACTIVE and INACTIVE items cannot be deleted — they must be preserved for audit trails
+- Deletion is permanent and cannot be undone
+- Any taxonomy assignments for the item should be removed before or as part of deletion
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive delete request] --> B{Item exists?}
+    B -->|No| C[Return error: not found]
+    B -->|Yes| D{Status is DRAFT?}
+    D -->|No| E[Return error: cannot delete non-draft item]
+    D -->|Yes| F[Remove taxonomy assignments]
+    F --> G[Delete item record]
+    G --> H[Return success]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **ITEM_NOT_FOUND**: Specified item ID does not exist
+- **DELETE_NON_DRAFT**: Item is in ACTIVE or INACTIVE status — only DRAFT items can be deleted

package/src/modules/item-management/docs/commands/DeleteTaxonomyNode.md

@@ -0,0 +1,39 @@
+# DeleteTaxonomyNode
+
+## Overview
+
+deleteTaxonomyNode permanently removes a taxonomy node from the hierarchy. Deletion is only allowed for leaf nodes (no children) with no item assignments. This ensures the classification tree remains consistent and no item classifications are silently lost.
+
+For node consolidation scenarios, item assignments should first be moved to another node using assignItemToTaxonomy and removeItemFromTaxonomy before deleting the empty node.
+
+## Business Rules
+
+- Target node must exist in the system
+- Node must have no child nodes — a node with children cannot be deleted
+- Node must have no item assignments — a node with assigned items cannot be deleted
+- Deletion is permanent and cannot be undone
+- The node's code becomes available for reuse after deletion
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive delete request] --> B{Node exists?}
+    B -->|No| C[Return error: not found]
+    B -->|Yes| D{Has child nodes?}
+    D -->|Yes| E[Return error: has children]
+    D -->|No| F{Has item assignments?}
+    F -->|Yes| G[Return error: has assignments]
+    F -->|No| H[Delete node record]
+    H --> I[Return success]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **NODE_NOT_FOUND**: Specified node ID does not exist
+- **NODE_HAS_CHILDREN**: Node has one or more child nodes — children must be moved or deleted first
+- **NODE_HAS_ASSIGNMENTS**: Node has one or more item assignments — assignments must be removed first

package/src/modules/item-management/docs/commands/MoveTaxonomyNode.md

@@ -0,0 +1,45 @@
+# MoveTaxonomyNode
+
+## Overview
+
+moveTaxonomyNode reparents a taxonomy node by changing its parent reference. The node and all its descendants move together, preserving the subtree structure and all item assignments. This supports taxonomy restructuring scenarios such as promoting a branch to root level or reorganizing classification hierarchies.
+
+Moving to a null parent promotes the node to a root node.
+
+## Business Rules
+
+- Target node must exist in the system
+- New parent node must exist when specified (null for root promotion)
+- A node cannot be moved under itself or any of its descendants (circular reference prevention)
+- All child nodes and their item assignments are preserved during the move
+- The move must not cause the tree to exceed the configurable maximum depth
+- Node code and item assignments are unchanged by the move
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive move request] --> B{Node exists?}
+    B -->|No| C[Return error: not found]
+    B -->|Yes| D{New parent specified?}
+    D -->|Yes| E{New parent exists?}
+    E -->|No| F[Return error: parent not found]
+    E -->|Yes| G{New parent is descendant of node?}
+    G -->|Yes| H[Return error: circular reference]
+    G -->|No| I{Depth limit exceeded?}
+    I -->|Yes| J[Return error: max depth exceeded]
+    I -->|No| K[Update parent reference]
+    D -->|No/null| K[Promote to root]
+    K --> L[Return moved node]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **NODE_NOT_FOUND**: Specified node ID does not exist
+- **PARENT_NODE_NOT_FOUND**: Specified new parent node ID does not exist
+- **CIRCULAR_REFERENCE**: New parent is the node itself or one of its descendants
+- **MAX_DEPTH_EXCEEDED**: Moving this subtree would exceed the configurable tree depth limit

package/src/modules/item-management/docs/commands/ReactivateItem.md

@@ -0,0 +1,34 @@
+# ReactivateItem
+
+## Overview
+
+reactivateItem transitions an item from INACTIVE back to ACTIVE status, making a previously discontinued SKU available for transactions again. This supports scenarios such as bringing back seasonal products or restoring items after a temporary suspension.
+
+## Business Rules
+
+- Target item must exist in the system
+- Target item must be in INACTIVE status
+- After reactivation, the item can participate in new transactions
+- All item data (SKU, barcode, UoM, name) is preserved from before deactivation
+- Bulk reactivation is not supported — reactivation is expected to be a targeted, individual operation since bringing back discontinued items requires deliberate per-item review
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive reactivate request] --> B{Item exists?}
+    B -->|No| C[Return error: not found]
+    B -->|Yes| D{Status is INACTIVE?}
+    D -->|No| E[Return error: invalid state transition]
+    D -->|Yes| F[Update status to ACTIVE]
+    F --> G[Return reactivated item]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **ITEM_NOT_FOUND**: Specified item ID does not exist
+- **INVALID_STATE_TRANSITION**: Item is not in INACTIVE status

package/src/modules/item-management/docs/commands/RemoveItemFromTaxonomy.md

@@ -0,0 +1,30 @@
+# RemoveItemFromTaxonomy
+
+## Overview
+
+removeItemFromTaxonomy deletes the link between an item and a taxonomy node. Removing an assignment does not affect the item itself, the taxonomy node, or any other assignments the item may have. This supports scenarios such as reclassification, node consolidation, and cleanup of incorrect assignments.
+
+## Business Rules
+
+- The assignment (item + taxonomy node link) must exist in the system
+- Removing an assignment does not affect the item or its other taxonomy assignments
+- Removing an assignment does not affect the taxonomy node or its other item assignments
+- Removal is permanent and cannot be undone
+
+## 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 item and taxonomy node combination

package/src/modules/item-management/docs/commands/UpdateItem.md

@@ -0,0 +1,55 @@
+# UpdateItem
+
+## Overview
+
+updateItem modifies mutable fields of an existing item — name, barcode, and unit of measure (UoM). SKU is immutable and cannot be changed after creation. The set of updatable fields depends on the item's current lifecycle status.
+
+This command supports the DRAFT review workflow (correcting barcodes, setting names before activation) as well as post-activation updates to non-transactional fields.
+
+## Business Rules
+
+- Target item must exist in the system
+- SKU is immutable — any attempt to change SKU returns an error
+- Name can be updated in any status (DRAFT, ACTIVE, INACTIVE)
+- Barcode can be updated in any status; must remain unique across all items when provided
+- Barcode can be cleared (set to null) to remove it from the item
+- UoM can be updated only when the item is in DRAFT status — once activated, UoM is locked to preserve transaction consistency
+- UoM must reference an existing active Unit from the primitives module
+- At least one field must be provided for update (no-op updates are rejected)
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update request] --> B{Item exists?}
+    B -->|No| C[Return error: not found]
+    B -->|Yes| D{SKU change attempted?}
+    D -->|Yes| E[Return error: SKU immutable]
+    D -->|No| F{Any field provided?}
+    F -->|No| G[Return error: no fields to update]
+    F -->|Yes| H{Barcode provided?}
+    H -->|Yes| I{Barcode unique?}
+    I -->|No| J[Return error: duplicate barcode]
+    I -->|Yes| K{UoM change requested?}
+    H -->|No| K
+    K -->|Yes| L{Status is DRAFT?}
+    L -->|No| M[Return error: UoM locked after activation]
+    L -->|Yes| N{UoM valid and active?}
+    N -->|No| O[Return error: invalid UoM]
+    N -->|Yes| P[Apply updates]
+    K -->|No| P
+    P --> Q[Return updated item]
+```
+
+## 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
+
+- **ITEM_NOT_FOUND**: Specified item ID does not exist
+- **SKU_IMMUTABLE**: Attempt to change the SKU field
+- **DUPLICATE_BARCODE**: An item with the same barcode already exists
+- **UNIT_NOT_FOUND**: Referenced unit does not exist or is inactive
+- **UOM_LOCKED**: UoM cannot be changed after item has been activated (status is ACTIVE or INACTIVE)
+- **NO_FIELDS_TO_UPDATE**: No updatable fields were provided in the request

package/src/modules/item-management/docs/commands/UpdateTaxonomyNode.md

@@ -0,0 +1,36 @@
+# UpdateTaxonomyNode
+
+## Overview
+
+updateTaxonomyNode modifies the display name of an existing taxonomy node. The node code is immutable and cannot be changed after creation — only the name (display label) can be updated. This supports scenarios such as renaming a classification branch to better reflect its contents or aligning terminology across the organization.
+
+## Business Rules
+
+- Target node must exist in the system
+- Node code is immutable — any attempt to change the code returns an error
+- Name is required and must not be empty
+- Name update does not affect the node's position in the tree, child nodes, or item assignments
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update request] --> B{Node exists?}
+    B -->|No| C[Return error: not found]
+    B -->|Yes| D{Code change attempted?}
+    D -->|Yes| E[Return error: code immutable]
+    D -->|No| F{Name provided and non-empty?}
+    F -->|No| G[Return error: name required]
+    F -->|Yes| H[Update node name]
+    H --> I[Return updated node]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **NODE_NOT_FOUND**: Specified node ID does not exist
+- **CODE_IMMUTABLE**: Attempt to change the node code
+- **MISSING_REQUIRED_FIELDS**: Name not provided or empty

package/src/modules/item-management/docs/features/item-lifecycle.md

@@ -0,0 +1,60 @@
+# Item Lifecycle
+
+## Overview
+
+Items are the fundamental SKU-level entity in the ERP system — the sellable, purchasable, and trackable unit. Each item has its own lifecycle state machine, unique SKU identifier, and optional barcode. Items manage their unit of measure independently.
+
+Items can be created in DRAFT or ACTIVE status. DRAFT items require explicit activation before they can participate in transactions.
+
+## Business Purpose
+
+Items serve as the universal SKU entity across the ERP system. Downstream domains reference items as the fundamental tradeable/trackable unit:
+
+- Sales module creates order lines linked to Items
+- Inventory module tracks stock quantities per Item
+- Purchasing module creates purchase order lines linked to Items
+- Manufacturing module references Items in Bill of Materials
+
+The lifecycle state machine ensures:
+
+- Items are reviewed before becoming transactionally available (DRAFT → ACTIVE)
+- Discontinued items are preserved for historical reference (ACTIVE → INACTIVE)
+- Previously discontinued items can return to active use (INACTIVE → ACTIVE)
+- Only DRAFT items can be permanently deleted; ACTIVE/INACTIVE items are preserved for audit trails
+
+## Process Flow
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: createItem (draft)
+    [*] --> Active: createItem (active)
+    Draft --> Active: activateItem
+    Active --> Inactive: deactivateItem
+    Inactive --> Active: reactivateItem
+    Draft --> [*]: deleteItem
+```
+
+## Scenario Patterns
+
+- **New Item**: An item is created with a unique SKU, name, UoM, and optional barcode
+- **Draft Item Review**: Items created in DRAFT status are reviewed, barcodes corrected, and activated
+- **Item Deactivation**: A specific SKU is discontinued while other items remain active
+- **Item Reactivation**: A previously discontinued SKU is brought back into active use (INACTIVE → ACTIVE)
+- **Draft Item Cleanup**: Unwanted items in DRAFT status are deleted before activation
+- **SKU Assignment**: Each item receives a globally unique SKU that is immutable once assigned
+
+## Test Cases
+
+- Item lifecycle follows DRAFT → ACTIVE ↔ INACTIVE state machine
+- Items can be created in either DRAFT or ACTIVE status
+- SKU is required, globally unique, and immutable after assignment
+- Barcode must be unique when provided, can be updated
+- Only DRAFT items can be deleted; ACTIVE and INACTIVE items cannot
+- Only ACTIVE items can be referenced in new transactions (sales orders, purchase orders)
+- Items can be activated, deactivated, and reactivated individually
+- Item UoM can be updated in DRAFT status; once activated, UoM is locked to preserve transaction consistency
+
+## Reference Links
+
+- [Oracle Item Master](https://docs.oracle.com/en/cloud/saas/supply-chain-and-manufacturing/25a/fammi/define-items-and-item-structures.html)
+- [NetSuite Item Master Data](https://www.netsuite.com/portal/resource/articles/inventory-management/item-master-data.shtml)