Domain Model: Item Catalog¶

class ItemType(str, Enum):
    INGREDIENT = "ingredient"
    PRODUCT = "product"
    INTERMEDIATE = "intermediate"
    PACKAGING = "packaging"
    CONSUMABLE = "consumable"
    SERVICE = "service"
    RESALE = "resale"

class StorageUnit(str, Enum):
    KG = "kg"
    G = "g"
    L = "l"
    ML = "ml"
    PIECE = "piece"

class ItemStatus(str, Enum):
    ACTIVE = "active"
    INACTIVE = "inactive"

@dataclass(frozen=True)
class Tags:
    values: tuple[str, ...]  # deduplicated, case-insensitive, max 20 items

@dataclass(frozen=True)
class EAN:
    value: str  # max 20 chars, non-empty

@dataclass(frozen=True)
class ItemCreated:
    event_id: UUID
    event_type: str = "ItemCreated"
    aggregate_id: UUID          # item_id
    aggregate_type: str = "Item"
    tenant_id: UUID
    timestamp: datetime
    version: int = 1
    # payload
    code: str
    name: str
    item_type: ItemType
    storage_unit: StorageUnit
    shelf_life_days: int | None
    ean: str | None
    is_system: bool
    tags: tuple[str, ...]
    group_id: UUID | None
    created_by: UUID

@dataclass(frozen=True)
class ItemUpdated:
    event_id: UUID
    event_type: str = "ItemUpdated"
    aggregate_id: UUID          # item_id
    aggregate_type: str = "Item"
    tenant_id: UUID
    timestamp: datetime
    version: int = 1
    # payload — always full current values of all editable fields
    name: str
    description: str | None
    tags: tuple[str, ...]
    shelf_life_days: int | None
    old_ean: str | None
    new_ean: str | None
    updated_by: UUID

@dataclass(frozen=True)
class ItemDeactivated:
    event_id: UUID
    event_type: str = "ItemDeactivated"
    aggregate_id: UUID          # item_id
    aggregate_type: str = "Item"
    tenant_id: UUID
    timestamp: datetime
    version: int = 1
    # payload
    code: str
    item_type: ItemType
    deactivated_by: UUID

@dataclass(frozen=True)
class ItemReactivated:
    event_id: UUID
    event_type: str = "ItemReactivated"
    aggregate_id: UUID          # item_id
    aggregate_type: str = "Item"
    tenant_id: UUID
    timestamp: datetime
    version: int = 1
    # payload
    code: str
    item_type: ItemType
    reactivated_by: UUID

class ItemRepository(ABC):

    @abstractmethod
    async def get_by_id(self, item_id: UUID, tenant_id: UUID) -> Item:
        """Raises: ItemNotFound"""

    @abstractmethod
    async def get_by_code(self, code: str, tenant_id: UUID) -> Item | None:
        """Case-insensitive lookup. Returns None if not found."""

    @abstractmethod
    async def get_by_ean(self, ean: str, tenant_id: UUID) -> Item | None:
        """Returns None if not found."""

    @abstractmethod
    async def save(self, item: Item) -> None:
        """Insert or update."""

    @abstractmethod
    async def list_items(
        self,
        tenant_id: UUID,
        q: str | None,
        item_types: list[ItemType] | None,
        active: bool | None,
        group_id: UUID | None,
        page: int,
        page_size: int,
    ) -> tuple[list[Item], int]:
        """Full-text, diacritic-insensitive search across name/code/description/group_name/tags.
        Returns (items_on_page, total_count)."""

    @abstractmethod
    async def list_by_group(
        self,
        tenant_id: UUID,
        group_id: UUID,
        page: int,
        page_size: int,
    ) -> tuple[list[Item], int]:
        """Returns (items_on_page, total_count)."""

    @abstractmethod
    async def count_by_group(self, tenant_id: UUID, group_id: UUID) -> int:
        """Used by DeleteItemGroup handler to verify zero members."""

class ItemGroupRepository(ABC):

    @abstractmethod
    async def get_by_id(self, group_id: UUID, tenant_id: UUID) -> ItemGroup:
        """Raises: ItemGroupNotFound"""

    @abstractmethod
    async def get_by_name_and_type(
        self,
        name: str,
        item_type: ItemType,
        tenant_id: UUID,
    ) -> ItemGroup | None:
        """Case-insensitive name lookup within (tenant, item_type). Returns None if not found."""

    @abstractmethod
    async def save(self, group: ItemGroup) -> None:
        """Insert or update."""

    @abstractmethod
    async def delete(self, group_id: UUID, tenant_id: UUID) -> None:
        """Hard delete. Handler must confirm zero members before calling."""

    @abstractmethod
    async def list_groups(
        self,
        tenant_id: UUID,
        item_type: ItemType | None,
        page: int,
        page_size: int,
    ) -> tuple[list[ItemGroup], int]:
        """Returns (groups_on_page, total_count). Each result includes member count from repo query."""

class WarehouseItemQueryPort(ABC):
    @abstractmethod
    async def get_stock_quantity(self, item_id: UUID, tenant_id: UUID) -> Decimal:
        """Returns current total stock. Zero means safe to deactivate."""


class ManufacturingItemQueryPort(ABC):
    @abstractmethod
    async def count_open_production_orders(self, item_id: UUID, tenant_id: UUID) -> int:
        """Returns number of open ZPs referencing this item."""

    @abstractmethod
    async def count_published_bom_appearances(self, item_id: UUID, tenant_id: UUID) -> int:
        """Returns number of published recipe BOMs containing this item."""


class CRMItemQueryPort(ABC):
    @abstractmethod
    async def count_open_sales_orders(self, item_id: UUID, tenant_id: UUID) -> int:
        """Returns number of open ZSs referencing this item."""