monkeybrain-runtime 1.0.0__py3-none-any.whl

services/inventory/helpers/warehouse_regulated_records.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+from datetime import date, datetime, timezone
+from typing import Optional
+
+from motor.motor_asyncio import AsyncIOMotorDatabase
+from pydantic import BaseModel
+from pymongo import ReturnDocument
+
+from services.inventory.models.warehouse_regulated_records import (
+    InventoryDispositionRecord,
+    InventoryDispositionRecordCreate,
+    InventoryDispositionRecordUpdate,
+    MaterialInwardLog,
+    MaterialInwardLogCreate,
+    MaterialInwardLogUpdate,
+    SpecialStorageRequirement,
+    SpecialStorageRequirementCreate,
+    SpecialStorageRequirementUpdate,
+    WarehouseDispensingRecord,
+    WarehouseDispensingRecordCreate,
+    WarehouseDispensingRecordUpdate,
+    WarehouseStatusLabel,
+    WarehouseStatusLabelCreate,
+    WarehouseStatusLabelUpdate,
+)
+from services.products.models.product_common import utc_now
+
+
+RECORDS = {
+    "special_storage_requirements": ("special_storage_requirements", "requirement_id", SpecialStorageRequirement, SpecialStorageRequirementCreate, SpecialStorageRequirementUpdate),
+    "material_inward_logs": ("material_inward_logs", "inward_log_id", MaterialInwardLog, MaterialInwardLogCreate, MaterialInwardLogUpdate),
+    "warehouse_status_labels": ("warehouse_status_labels", "label_id", WarehouseStatusLabel, WarehouseStatusLabelCreate, WarehouseStatusLabelUpdate),
+    "warehouse_dispensing_records": ("warehouse_dispensing_records", "dispensing_record_id", WarehouseDispensingRecord, WarehouseDispensingRecordCreate, WarehouseDispensingRecordUpdate),
+    "inventory_disposition_records": ("inventory_disposition_records", "disposition_id", InventoryDispositionRecord, InventoryDispositionRecordCreate, InventoryDispositionRecordUpdate),
+}
+
+
+def _record_config(record_type: str):
+    try:
+        return RECORDS[record_type]
+    except KeyError as exc:
+        raise ValueError(f"Unknown warehouse regulated record type '{record_type}'") from exc
+
+
+def _serialize(doc: Optional[dict]) -> Optional[dict]:
+    if not doc:
+        return None
+    doc = dict(doc)
+    doc.pop("_id", None)
+    return doc
+
+
+def _prepare(value):
+    if isinstance(value, BaseModel):
+        return _prepare(value.model_dump())
+    if isinstance(value, datetime):
+        if value.tzinfo is None:
+            return value.replace(tzinfo=timezone.utc)
+        return value.astimezone(timezone.utc)
+    if isinstance(value, date):
+        return datetime(value.year, value.month, value.day, tzinfo=timezone.utc)
+    if isinstance(value, dict):
+        return {key: _prepare(item) for key, item in value.items()}
+    if isinstance(value, list):
+        return [_prepare(item) for item in value]
+    return value
+
+
+async def get_all(
+    db: AsyncIOMotorDatabase,
+    record_type: str,
+    *,
+    page: int = 1,
+    page_size: int = 20,
+    query: Optional[dict] = None,
+) -> tuple[list[dict], int]:
+    collection, _, _, _, _ = _record_config(record_type)
+    query = query or {}
+    total = await db[collection].count_documents(query)
+    cursor = db[collection].find(query).skip((page - 1) * page_size).limit(page_size)
+    return [_serialize(doc) async for doc in cursor], total
+
+
+async def get_by_id(db: AsyncIOMotorDatabase, record_type: str, record_id: str) -> Optional[dict]:
+    collection, id_field, _, _, _ = _record_config(record_type)
+    return _serialize(await db[collection].find_one({id_field: record_id}))
+
+
+async def create(db: AsyncIOMotorDatabase, record_type: str, data: BaseModel) -> dict:
+    collection, _, model_cls, _, _ = _record_config(record_type)
+    doc = _prepare(model_cls(**data.model_dump()))
+    await db[collection].insert_one(doc)
+    return _serialize(doc)
+
+
+async def update(
+    db: AsyncIOMotorDatabase,
+    record_type: str,
+    record_id: str,
+    data: BaseModel,
+) -> Optional[dict]:
+    collection, id_field, model_cls, _, _ = _record_config(record_type)
+    existing = await get_by_id(db, record_type, record_id)
+    if not existing:
+        return None
+    fields = _prepare(data.model_dump(exclude_unset=True))
+    if not fields:
+        return existing
+    merged = {**existing, **fields, id_field: record_id, "updated_at": utc_now()}
+    doc = _prepare(model_cls(**merged))
+    result = await db[collection].find_one_and_update(
+        {id_field: record_id},
+        {"$set": doc},
+        return_document=ReturnDocument.AFTER,
+    )
+    return _serialize(result)
+
+
+async def delete(db: AsyncIOMotorDatabase, record_type: str, record_id: str) -> bool:
+    collection, id_field, _, _, _ = _record_config(record_type)
+    result = await db[collection].delete_one({id_field: record_id})
+    return result.deleted_count == 1

services/inventory/main.py

@@ -0,0 +1,62 @@
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from services.common.logging import configure_service_logging, install_request_logging
+from services.common.tracing import install_route_tracing
+
+from services.common.db import close_db, connect_db
+from services.inventory.routers.inventory_allocations import router as inventory_allocations_router
+from services.inventory.routers.inventory_item_counts import router as inventory_item_counts_router
+from services.inventory.routers.inventory_item_quantities import router as inventory_item_quantities_router
+from services.inventory.routers.inventory_items import router as inventory_items_router
+from services.inventory.routers.inventory_stage_outputs import router as inventory_stage_outputs_router
+from services.inventory.routers.stock_adjustment_requests import router as stock_adjustment_requests_router
+from services.inventory.routers.inventory_transactions import router as inventory_transactions_router
+from services.inventory.routers.warehouse_regulated_records import router as warehouse_regulated_records_router
+from services.inventory.routers.warehouse_cycle_counts import router as warehouse_cycle_counts_router
+from services.inventory.routers.warehouse_locations import router as warehouse_locations_router
+
+
+logger = configure_service_logging("inventory")
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    await connect_db()
+    yield
+    await close_db()
+
+
+app = FastAPI(
+    title="Inventory Service",
+    description="Microservice for inventory service.",
+    version="1.0.0",
+    lifespan=lifespan,
+)
+install_request_logging(app, "inventory")
+install_route_tracing(app, "inventory")
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+app.include_router(inventory_allocations_router, prefix="/api/v1/inventory-allocations", tags=["Inventory Allocations"])
+app.include_router(inventory_items_router, prefix="/api/v1/inventory-items", tags=["Inventory Items"])
+app.include_router(inventory_item_counts_router, prefix="/api/v1/inventory-item-counts", tags=["Inventory Item Counts"])
+app.include_router(inventory_item_quantities_router, prefix="/api/v1/inventory-item-quantities", tags=["Inventory Item Quantities"])
+app.include_router(inventory_stage_outputs_router, prefix="/api/v1/inventory-stage-outputs", tags=["Inventory Stage Outputs"])
+app.include_router(stock_adjustment_requests_router, prefix="/api/v1/stock-adjustment-requests", tags=["Stock Adjustment Requests"])
+app.include_router(inventory_transactions_router, prefix="/api/v1/inventory-transactions", tags=["Inventory Transactions"])
+app.include_router(warehouse_cycle_counts_router, prefix="/api/v1/warehouse-cycle-counts", tags=["Warehouse Cycle Counts"])
+app.include_router(warehouse_locations_router, prefix="/api/v1/warehouse-locations", tags=["Warehouse Locations"])
+app.include_router(warehouse_regulated_records_router, prefix="/api/v1/warehouse", tags=["Warehouse Regulated Records"])
+
+
+@app.get("/health", tags=["Health"])
+async def health_check():
+    return {"status": "healthy"}

services/inventory/models/__init__.py

@@ -0,0 +1,17 @@
+"""inventory service models package."""
+
+__all__ = [
+    "inventory_common",
+    "inventory_allocations",
+    "inventory_item_count",
+    "inventory_item_quantity",
+    "inventory_enums",
+    "inventory_items",
+    "inventory_responses",
+    "inventory_state",
+    "inventory_stage_outputs",
+    "inventory_transactions",
+    "stock_adjustment_requests",
+    "warehouse_cycle_counts",
+    "warehouse_location_models",
+]

services/inventory/models/cycle_counts.py

@@ -0,0 +1,99 @@
+from datetime import date, datetime
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from services.products.models.product_common import utc_now
+
+
+class CycleCountStatus(str, Enum):
+    DRAFT = "Draft"
+    SCHEDULED = "Scheduled"
+    IN_PROGRESS = "In-Progress"
+    COMPLETED = "Completed"
+    CANCELLED = "Cancelled"
+
+
+class CycleCountScope(str, Enum):
+    WAREHOUSE = "Warehouse"
+    LOCATION = "Location"
+    SKU = "SKU"
+    BIN = "Bin"
+
+
+class CycleCountLine(BaseModel):
+    sku: str = Field(..., min_length=1)
+    inventory_id: str | None = None
+    location_id: str | None = None
+    bin_location: str | None = None
+    system_quantity: float = Field(default=0, ge=0)
+    counted_quantity: float | None = Field(default=None, ge=0)
+    unit_of_measure: str = Field(default="piece", min_length=1)
+    variance_quantity: float = 0
+    variance_reason: str | None = None
+    counted_by: str | None = None
+    counted_at: datetime | None = None
+    notes: str | None = None
+
+    @model_validator(mode="after")
+    def compute_variance(self):
+        if self.counted_quantity is not None:
+            self.variance_quantity = self.counted_quantity - self.system_quantity
+        return self
+
+
+class CycleCountBase(BaseModel):
+    warehouse_id: str = Field(..., min_length=1)
+    scope: CycleCountScope = CycleCountScope.WAREHOUSE
+    location_id: str | None = None
+    bin_location: str | None = None
+    sku: str | None = None
+    status: CycleCountStatus = CycleCountStatus.DRAFT
+    scheduled_date: date | None = None
+    started_at: datetime | None = None
+    completed_at: datetime | None = None
+    assigned_to: str | None = None
+    created_by: str | None = None
+    lines: list[CycleCountLine] = Field(default_factory=list)
+    notes: str | None = None
+    metadata: dict[str, Any] | None = None
+
+
+class CycleCountCreate(CycleCountBase):
+    """Schema for scheduling or creating a warehouse cycle count."""
+
+
+class CycleCountUpdate(BaseModel):
+    warehouse_id: str | None = None
+    scope: CycleCountScope | None = None
+    location_id: str | None = None
+    bin_location: str | None = None
+    sku: str | None = None
+    status: CycleCountStatus | None = None
+    scheduled_date: date | None = None
+    started_at: datetime | None = None
+    completed_at: datetime | None = None
+    assigned_to: str | None = None
+    created_by: str | None = None
+    lines: list[CycleCountLine] | None = None
+    notes: str | None = None
+    metadata: dict[str, Any] | None = None
+    updated_by: str | None = None
+
+
+class CycleCountResponse(CycleCountBase):
+    id: str
+    cycle_count_id: str
+    updated_by: str | None = None
+    created_at: datetime = Field(default_factory=utc_now)
+    updated_at: datetime = Field(default_factory=utc_now)
+
+    model_config = ConfigDict(from_attributes=True)
+
+
+class PaginatedCycleCountResponse(BaseModel):
+    total: int
+    page: int
+    page_size: int
+    results: list[CycleCountResponse]

services/inventory/models/inventory_allocations.py

@@ -0,0 +1,121 @@
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from services.products.models.product_common import utc_now
+
+
+class AllocationItemType(str, Enum):
+    COMPONENT = "component"
+    PRODUCT = "product"
+    SPARE_PART = "spare_part"
+    RAW_MATERIAL = "raw_material"
+
+
+class AllocationRequestType(str, Enum):
+    QUANTITY = "quantity"
+    COUNT = "count"
+
+
+class AllocationStatus(str, Enum):
+    PENDING = "pending"
+    APPROVED = "approved"
+    REJECTED = "rejected"
+    ALLOCATED = "allocated"
+    PICKED = "picked"
+    DELIVERED = "delivered"
+    CANCELLED = "cancelled"
+
+
+class AllocationUnitOfMeasure(str, Enum):
+    PIECE = "piece"
+    BOX = "box"
+    PALLET = "pallet"
+    KG = "kg"
+    LITER = "liter"
+    OTHER = "other"
+
+
+class InventoryAllocationBase(BaseModel):
+    workstation_id: str = Field(..., min_length=1)
+    warehouse_id: str = Field(..., min_length=1)
+    sku: str = Field(..., min_length=1, description="Stock Keeping Unit")
+    srn: str | None = Field(None, description="Serial Reference Number")
+    item_type: AllocationItemType
+    request_type: AllocationRequestType
+    requested_quantity: float | None = Field(default=None, gt=0)
+    requested_count: int | None = Field(default=None, gt=0)
+    unit_of_measure: AllocationUnitOfMeasure
+    status: AllocationStatus = AllocationStatus.PENDING
+    requested_by: str | None = None
+    approved_by: str | None = None
+    fulfilled_by: str | None = None
+    rejected_reason: str | None = None
+    due_at: datetime | None = None
+    requested_at: datetime = Field(default_factory=utc_now)
+    approved_at: datetime | None = None
+    allocated_at: datetime | None = None
+    delivered_at: datetime | None = None
+    notes: str | None = None
+    metadata: dict[str, Any] | None = None
+
+    @model_validator(mode="after")
+    def validate_request_amount(self):
+        if self.request_type == AllocationRequestType.QUANTITY:
+            if self.requested_quantity is None:
+                raise ValueError("requested_quantity is required for quantity requests")
+            if self.requested_count is not None:
+                raise ValueError("requested_count must not be set for quantity requests")
+
+        if self.request_type == AllocationRequestType.COUNT:
+            if self.requested_count is None:
+                raise ValueError("requested_count is required for count requests")
+            if self.requested_quantity is not None:
+                raise ValueError("requested_quantity must not be set for count requests")
+
+        return self
+
+
+class InventoryAllocationCreate(InventoryAllocationBase):
+    """Schema for workstation requests to allocate inventory from a warehouse."""
+
+
+class InventoryAllocationUpdate(BaseModel):
+    workstation_id: str | None = None
+    warehouse_id: str | None = None
+    sku: str | None = None
+    srn: str | None = None
+    item_type: AllocationItemType | None = None
+    request_type: AllocationRequestType | None = None
+    requested_quantity: float | None = Field(default=None, gt=0)
+    requested_count: int | None = Field(default=None, gt=0)
+    unit_of_measure: AllocationUnitOfMeasure | None = None
+    status: AllocationStatus | None = None
+    requested_by: str | None = None
+    approved_by: str | None = None
+    fulfilled_by: str | None = None
+    rejected_reason: str | None = None
+    due_at: datetime | None = None
+    requested_at: datetime | None = None
+    approved_at: datetime | None = None
+    allocated_at: datetime | None = None
+    delivered_at: datetime | None = None
+    notes: str | None = None
+    metadata: dict[str, Any] | None = None
+
+
+class InventoryAllocationResponse(InventoryAllocationBase):
+    id: str
+    allocation_id: str
+    updated_at: datetime
+
+    model_config = ConfigDict(from_attributes=True)
+
+
+class PaginatedInventoryAllocationResponse(BaseModel):
+    total: int
+    page: int
+    page_size: int
+    results: list[InventoryAllocationResponse]

services/inventory/models/inventory_common.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Literal, Optional
+
+
+InventoryStatus = Literal[
+    "In-Stock",
+    "Low-Stock",
+    "Out-of-Stock",
+    "Reserved",
+    "In-Transit",
+    "Quarantine",
+    "Damaged",
+    "Expired",
+]
+
+InventoryTransactionType = Literal[
+    "Receipt",
+    "Shipment",
+    "Adjustment",
+    "Transfer-In",
+    "Transfer-Out",
+    "Return",
+    "Write-Off",
+    "Cycle-Count",
+    "Reservation",
+    "Release",
+]
+
+StockMovementDirection = Literal["in", "out", "transfer", "adjustment"]
+
+InventoryValuationMethod = Literal[
+    "FIFO",
+    "LIFO",
+    "Weighted-Average",
+    "Specific-Identification",
+]
+
+InventoryLocationType = Literal["Warehouse", "Store", "Transit", "Virtual", "Production"]
+
+ReferenceType = Literal[
+    "PO",
+    "SO",
+    "Transfer",
+    "Adjustment",
+    "Production",
+    "Return",
+    "Work-Order",
+]
+
+AdjustmentType   = Literal["Add", "Remove", "Correction"]
+AdjustmentStatus = Literal["Pending", "Approved", "Rejected", "Completed"]
+
+
+def utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def ensure_utc(dt: Optional[datetime]) -> Optional[datetime]:
+    if dt is None:
+        return None
+    if dt.tzinfo is None:
+        return dt.replace(tzinfo=timezone.utc)
+    return dt.astimezone(timezone.utc)

services/inventory/models/inventory_enums.py

@@ -0,0 +1,21 @@
+from services.inventory.models.inventory_common import (
+    AdjustmentStatus,
+    AdjustmentType,
+    InventoryLocationType,
+    InventoryStatus,
+    InventoryTransactionType,
+    InventoryValuationMethod,
+    ReferenceType,
+    StockMovementDirection,
+)
+
+__all__ = [
+    "AdjustmentStatus",
+    "AdjustmentType",
+    "InventoryLocationType",
+    "InventoryStatus",
+    "InventoryTransactionType",
+    "InventoryValuationMethod",
+    "ReferenceType",
+    "StockMovementDirection",
+]

services/inventory/models/inventory_item_count.py

@@ -0,0 +1,65 @@
+from enum import Enum
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from services.products.models.product_common import utc_now
+
+
+class ItemType(str, Enum):
+    COMPONENT = "component"
+    PRODUCT = "product"
+    SPARE_PART = "spare_part"
+    RAW_MATERIAL = "raw_material"
+
+
+class UnitOfMeasure(str, Enum):
+    PIECE = "piece"
+    BOX = "box"
+    PALLET = "pallet"
+    OTHER = "other"
+
+
+class InventoryItemCountBase(BaseModel):
+    item_type: ItemType
+    sku: str = Field(..., min_length=1, description="Stock Keeping Unit")
+    srn: str | None = Field(None, description="Serial Reference Number")
+    count: int = Field(ge=0, description="Count of units on hand")
+    unit_of_measure: UnitOfMeasure = Field(
+        ...,
+        description="Unit of measure for the quantity (e.g., pieces, boxes, pallets)",
+    )
+    warehouse_id: str | None = None
+    bin_location: str | None = None
+    counted_by: str | None = None
+    counted_at: datetime = Field(default_factory=utc_now)
+
+
+class InventoryItemCountCreate(InventoryItemCountBase):
+    """Schema for creating an inventory item count."""
+
+
+class InventoryItemCountUpdate(BaseModel):
+    item_type: ItemType | None = None
+    sku: str | None = None
+    srn: str | None = None
+    count: int | None = Field(default=None, ge=0)
+    unit_of_measure: UnitOfMeasure | None = None
+    warehouse_id: str | None = None
+    bin_location: str | None = None
+    counted_by: str | None = None
+    counted_at: datetime | None = None
+
+
+class InventoryItemCountResponse(InventoryItemCountBase):
+    id: str
+    updated_at: datetime
+
+    model_config = ConfigDict(from_attributes=True)
+
+
+class PaginatedInventoryItemCountResponse(BaseModel):
+    total: int
+    page: int
+    page_size: int
+    results: list[InventoryItemCountResponse]

services/inventory/models/inventory_item_quantity.py

@@ -0,0 +1,82 @@
+from datetime import datetime
+from enum import Enum
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from services.products.models.product_common import utc_now
+
+
+class ItemType(str, Enum):
+    COMPONENT = "component"
+    PRODUCT = "product"
+    SPARE_PART = "spare_part"
+    RAW_MATERIAL = "raw_material"
+
+
+class UnitOfMeasure(str, Enum):
+    PIECE = "piece"
+    BOX = "box"
+    PALLET = "pallet"
+    KG = "kg"
+    LITER = "liter"
+    OTHER = "other"
+
+
+class InventoryItemQuantityBase(BaseModel):
+    item_type: ItemType = ItemType.RAW_MATERIAL
+    sku: str = Field(..., min_length=1, description="Stock Keeping Unit")
+    srn: str | None = Field(None, description="Serial Reference Number")
+    warehouse_id: str | None = None
+    bin_location: str | None = None
+    quantity: float = Field(default=0, ge=0, description="Quantity of units on hand")
+    quantity_allocated: float = Field(default=0, ge=0)
+    quantity_reserved: float = Field(default=0, ge=0)
+    quantity_available: float | None = Field(default=None, ge=0)
+    unit_of_measure: UnitOfMeasure = Field(..., description="Unit of measure for the quantity")
+    updated_by: str | None = None
+    measured_at: datetime = Field(default_factory=utc_now)
+
+    @model_validator(mode="after")
+    def validate_quantity_state(self):
+        expected = max(self.quantity - self.quantity_allocated - self.quantity_reserved, 0)
+        if self.quantity_available is None:
+            self.quantity_available = expected
+        elif self.quantity_available != expected:
+            raise ValueError(
+                "quantity_available must equal "
+                "quantity - quantity_allocated - quantity_reserved"
+            )
+        return self
+
+
+class InventoryItemQuantityCreate(InventoryItemQuantityBase):
+    """Schema for creating an inventory item quantity snapshot."""
+
+
+class InventoryItemQuantityUpdate(BaseModel):
+    item_type: ItemType | None = None
+    sku: str | None = None
+    srn: str | None = None
+    warehouse_id: str | None = None
+    bin_location: str | None = None
+    quantity: float | None = Field(default=None, ge=0)
+    quantity_allocated: float | None = Field(default=None, ge=0)
+    quantity_reserved: float | None = Field(default=None, ge=0)
+    quantity_available: float | None = Field(default=None, ge=0)
+    unit_of_measure: UnitOfMeasure | None = None
+    updated_by: str | None = None
+    measured_at: datetime | None = None
+
+
+class InventoryItemQuantityResponse(InventoryItemQuantityBase):
+    id: str
+    updated_at: datetime
+
+    model_config = ConfigDict(from_attributes=True)
+
+
+class PaginatedInventoryItemQuantityResponse(BaseModel):
+    total: int
+    page: int
+    page_size: int
+    results: list[InventoryItemQuantityResponse]