@tailor-platform/erp-kit 0.1.1 → 0.2.0

package/src/modules/item-management/command/updateItem.test.ts

@@ -0,0 +1,178 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../testing/index";
+import { type CommandContext } from "../../shared/internal";
+import { DB } from "../generated/kysely-tailordb";
+import {
+  DuplicateBarcodeError,
+  UnitNotFoundError,
+  ItemNotFoundError,
+  NoFieldsToUpdateError,
+  SkuImmutableError,
+  UomLockedError,
+} from "../lib/errors.generated";
+import { baseActiveItem, baseDraftItem, baseInactiveItem } from "../testing/fixtures";
+import { getUnit } from "../../primitives";
+import { run } from "./updateItem";
+
+describe("updateItem", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["item-management:updateItem"],
+  };
+
+  it("returns error when item does not exist", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue(undefined);
+
+    const result = await run(db, { id: "nonexistent", name: "New Name" }, ctx, { getUnit });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ItemNotFoundError);
+    }
+  });
+
+  it("returns error when attempting to change SKU", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseDraftItem);
+
+    const result = await run(db, { id: baseDraftItem.id, sku: "NEW-SKU" }, ctx, { getUnit });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(SkuImmutableError);
+    }
+  });
+
+  it("returns error when no fields to update", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseDraftItem);
+
+    const result = await run(db, { id: baseDraftItem.id }, ctx, { getUnit });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(NoFieldsToUpdateError);
+    }
+  });
+
+  it("returns error when barcode is duplicate", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select
+      .mockReturnValueOnce(baseDraftItem) // Item lookup
+      .mockReturnValueOnce(baseActiveItem); // Barcode already taken
+
+    const result = await run(db, { id: baseDraftItem.id, barcode: "BAR-002" }, ctx, { getUnit });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(DuplicateBarcodeError);
+    }
+  });
+
+  it("returns error when changing UoM on non-DRAFT item", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseActiveItem);
+
+    const result = await run(db, { id: baseActiveItem.id, unitId: "unit-g" }, ctx, { getUnit });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(UomLockedError);
+    }
+  });
+
+  it("returns error when changing UoM on INACTIVE item", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseInactiveItem);
+
+    const result = await run(db, { id: baseInactiveItem.id, unitId: "unit-g" }, ctx, { getUnit });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(UomLockedError);
+    }
+  });
+
+  it("returns error when new UoM does not exist", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select
+      .mockReturnValueOnce(baseDraftItem) // Item lookup
+      .mockReturnValueOnce(undefined); // UoM not found
+
+    const result = await run(db, { id: baseDraftItem.id, unitId: "nonexistent-unit" }, ctx, {
+      getUnit,
+    });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(UnitNotFoundError);
+    }
+  });
+
+  it("updates name in any status", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const updatedItem = { ...baseActiveItem, name: "Updated Name" };
+    spies.select.mockReturnValueOnce(baseActiveItem);
+    spies.update.mockReturnValue(updatedItem);
+
+    const result = await run(db, { id: baseActiveItem.id, name: "Updated Name" }, ctx, { getUnit });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.item.name).toBe("Updated Name");
+    }
+    expect(spies.update).toHaveBeenCalled();
+  });
+
+  it("updates barcode in any status", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const updatedItem = { ...baseActiveItem, barcode: "NEW-BAR" };
+    spies.select
+      .mockReturnValueOnce(baseActiveItem) // Item lookup
+      .mockReturnValueOnce(undefined); // Barcode unique
+    spies.update.mockReturnValue(updatedItem);
+
+    const result = await run(db, { id: baseActiveItem.id, barcode: "NEW-BAR" }, ctx, { getUnit });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.item.barcode).toBe("NEW-BAR");
+    }
+  });
+
+  it("clears barcode by setting to null", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const updatedItem = { ...baseActiveItem, barcode: null };
+    spies.select.mockReturnValueOnce(baseActiveItem);
+    spies.update.mockReturnValue(updatedItem);
+
+    const result = await run(db, { id: baseActiveItem.id, barcode: null }, ctx, { getUnit });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.item.barcode).toBeNull();
+    }
+  });
+
+  it("updates UoM in DRAFT status", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const activeUnit = { id: "unit-g", isActive: true };
+    const updatedItem = { ...baseDraftItem, unitId: "unit-g" };
+    spies.select
+      .mockReturnValueOnce(baseDraftItem) // Item lookup
+      .mockReturnValueOnce(activeUnit); // UoM valid
+    spies.update.mockReturnValue(updatedItem);
+
+    const result = await run(db, { id: baseDraftItem.id, unitId: "unit-g" }, ctx, { getUnit });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.item.unitId).toBe("unit-g");
+    }
+  });
+
+  it("passes custom fields through to set", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const updatedItem = { ...baseDraftItem, priority: 10 };
+    spies.select.mockReturnValueOnce(baseDraftItem);
+    spies.update.mockReturnValue(updatedItem);
+
+    await run(db, { id: baseDraftItem.id, priority: 10 }, ctx, { getUnit });
+
+    expect(spies.set).toHaveBeenNthCalledWith(1, expect.objectContaining({ priority: 10 }));
+  });
+});

package/src/modules/item-management/command/updateItem.ts

@@ -0,0 +1,103 @@
+import { ok, err, type CommandContext } from "../../shared/internal";
+import { DB } from "../generated/kysely-tailordb";
+import {
+  DuplicateBarcodeError,
+  UnitNotFoundError,
+  ItemNotFoundError,
+  NoFieldsToUpdateError,
+  SkuImmutableError,
+  UomLockedError,
+} from "../lib/errors.generated";
+import { getItem } from "../query/getItem.generated";
+import { type PrimitivesQueries } from "../module";
+
+export interface UpdateItemInput {
+  id: string;
+  sku?: string;
+  name?: string;
+  barcode?: string | null;
+  unitId?: string;
+}
+
+/**
+ * Function: updateItem
+ *
+ * Updates mutable fields of an existing item. SKU is immutable.
+ * UoM can only be changed in DRAFT status.
+ */
+export async function run<CF extends Record<string, unknown>>(
+  db: DB,
+  input: UpdateItemInput & Partial<CF>,
+  ctx: CommandContext,
+  primitivesQueries?: Pick<PrimitivesQueries, "getUnit">,
+) {
+  const { id, sku, name, barcode, unitId, ...customFields } = input;
+
+  // 1. Check item exists
+  const { item } = await getItem(db, { id }, ctx);
+
+  if (!item) {
+    return err(new ItemNotFoundError(id));
+  }
+
+  // 2. SKU is immutable
+  if (sku !== undefined) {
+    return err(new SkuImmutableError(id));
+  }
+
+  // 3. Check at least one field provided
+  const hasName = name !== undefined;
+  const hasBarcode = barcode !== undefined;
+  const hasUnitId = unitId !== undefined;
+  const hasCustomFields = Object.keys(customFields).length > 0;
+
+  if (!hasName && !hasBarcode && !hasUnitId && !hasCustomFields) {
+    return err(new NoFieldsToUpdateError(id));
+  }
+
+  // 4. Check barcode uniqueness when provided (non-null)
+  if (hasBarcode && barcode !== null) {
+    const existingBarcode = await db
+      .selectFrom("Item")
+      .selectAll()
+      .where("barcode", "=", barcode)
+      .where("id", "!=", id)
+      .executeTakeFirst();
+
+    if (existingBarcode) {
+      return err(new DuplicateBarcodeError(barcode));
+    }
+  }
+
+  // 5. UoM can only be changed in DRAFT status
+  if (hasUnitId) {
+    if (item.status !== "DRAFT") {
+      return err(new UomLockedError(id));
+    }
+
+    // Validate UoM exists and is active
+    const { unit } = await primitivesQueries!.getUnit(db, { id: unitId }, ctx);
+
+    if (!unit?.isActive) {
+      return err(new UnitNotFoundError(unitId));
+    }
+  }
+
+  // 6. Apply updates
+  const updates: Record<string, unknown> = {
+    ...(customFields as Record<string, unknown>),
+    updatedAt: new Date(),
+  };
+  if (hasName) updates.name = name;
+  if (hasBarcode) updates.barcode = barcode;
+  if (hasUnitId) updates.unitId = unitId;
+
+  const updatedItem = await db
+    .updateTable("Item")
+    .set(updates)
+    .where("id", "=", id)
+    .returningAll()
+    .executeTakeFirstOrThrow();
+
+  return ok({ item: updatedItem });
+}

package/src/modules/item-management/command/updateTaxonomyNode.generated.ts

@@ -0,0 +1,6 @@
+// @generated — do not edit
+import { defineCommand } from "../../shared/internal";
+import { permissions } from "../lib/permissions.generated";
+import { run } from "./updateTaxonomyNode";
+
+export const updateTaxonomyNode = defineCommand(permissions.updateTaxonomyNode, run);

package/src/modules/item-management/command/updateTaxonomyNode.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../testing/index";
+import { type CommandContext } from "../../shared/internal";
+import { DB } from "../generated/kysely-tailordb";
+import {
+  CodeImmutableError,
+  MissingRequiredFieldsError,
+  NodeNotFoundError,
+} from "../lib/errors.generated";
+import { baseRootNode } from "../testing/fixtures";
+import { run } from "./updateTaxonomyNode";
+
+describe("updateTaxonomyNode", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["item-management:updateTaxonomyNode"],
+  };
+
+  it("returns error when node does not exist", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue(undefined);
+
+    const result = await run(db, { id: "nonexistent", name: "New Name" }, ctx);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(NodeNotFoundError);
+    }
+  });
+
+  it("returns error when attempting to change code", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseRootNode);
+
+    const result = await run(db, { id: baseRootNode.id, code: "NEW-CODE" }, ctx);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(CodeImmutableError);
+    }
+  });
+
+  it("returns error when name is empty", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseRootNode);
+
+    const result = await run(db, { id: baseRootNode.id, name: "" }, ctx);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(MissingRequiredFieldsError);
+    }
+  });
+
+  it("returns error when name is not provided", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValueOnce(baseRootNode);
+
+    const result = await run(db, { id: baseRootNode.id }, ctx);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(MissingRequiredFieldsError);
+    }
+  });
+
+  it("updates node name", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const updatedNode = { ...baseRootNode, name: "Consumer Electronics" };
+    spies.select.mockReturnValueOnce(baseRootNode);
+    spies.update.mockReturnValue(updatedNode);
+
+    const result = await run(db, { id: baseRootNode.id, name: "Consumer Electronics" }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.node.name).toBe("Consumer Electronics");
+    }
+    expect(spies.update).toHaveBeenCalled();
+  });
+
+  it("passes custom fields through to set", async () => {
+    const { db, spies } = createMockDb<DB>();
+    const updatedNode = { ...baseRootNode, sortOrder: 5 };
+    spies.select.mockReturnValueOnce(baseRootNode);
+    spies.update.mockReturnValue(updatedNode);
+
+    await run(db, { id: baseRootNode.id, name: "Electronics", sortOrder: 5 }, ctx);
+
+    expect(spies.set).toHaveBeenNthCalledWith(1, expect.objectContaining({ sortOrder: 5 }));
+  });
+});

package/src/modules/item-management/command/updateTaxonomyNode.ts

@@ -0,0 +1,62 @@
+import { ok, err, type CommandContext } from "../../shared/internal";
+import { DB } from "../generated/kysely-tailordb";
+import {
+  CodeImmutableError,
+  MissingRequiredFieldsError,
+  NodeNotFoundError,
+} from "../lib/errors.generated";
+import { getTaxonomyNode } from "../query/getTaxonomyNode.generated";
+
+export interface UpdateTaxonomyNodeInput {
+  id: string;
+  code?: string;
+  name?: string;
+}
+
+/**
+ * Function: updateTaxonomyNode
+ *
+ * Updates the display name of an existing taxonomy node.
+ * Node code is immutable.
+ */
+export async function run<CF extends Record<string, unknown>>(
+  db: DB,
+  input: UpdateTaxonomyNodeInput & Partial<CF>,
+  ctx: CommandContext,
+) {
+  const { id, code, name, ...customFields } = input;
+
+  // 1. Check node exists
+  const { node } = await getTaxonomyNode(db, { id }, ctx);
+
+  if (!node) {
+    return err(new NodeNotFoundError(id));
+  }
+
+  // 2. Code is immutable
+  if (code !== undefined) {
+    return err(new CodeImmutableError(id));
+  }
+
+  // 3. Name must be provided and non-empty (unless custom fields provided)
+  const hasCustomFields = Object.keys(customFields).length > 0;
+  if (!name && !hasCustomFields) {
+    return err(new MissingRequiredFieldsError("name"));
+  }
+
+  // 4. Update fields
+  const updates: Record<string, unknown> = {
+    ...(customFields as Record<string, unknown>),
+    updatedAt: new Date(),
+  };
+  if (name) updates.name = name;
+
+  const updatedNode = await db
+    .updateTable("TaxonomyNode")
+    .set(updates)
+    .where("id", "=", id)
+    .returningAll()
+    .executeTakeFirstOrThrow();
+
+  return ok({ node: updatedNode });
+}

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