monkeybrain-runtime 1.0.0__py3-none-any.whl

services/shipping/helpers/vehicle.py

@@ -0,0 +1,85 @@
+from datetime import date, datetime, timezone
+from typing import Optional
+from uuid import UUID
+
+from motor.motor_asyncio import AsyncIOMotorDatabase
+from pymongo import ReturnDocument
+
+from services.shipping.models.vehicle import VehicleCreate, VehicleUpdate, utc_now
+
+COLLECTION = "vehicles"
+
+
+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, UUID):
+        return str(value)
+    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, tuple):
+        return [_prepare(item) for item in value]
+    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, page: int = 1, page_size: int = 20) -> tuple[list[dict], int]:
+    query: dict = {}
+    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, vehicle_id: str) -> Optional[dict]:
+    return _serialize(await db[COLLECTION].find_one({"id": vehicle_id}))
+
+
+async def get_by_carrier(db: AsyncIOMotorDatabase, carrier_id: str) -> list[dict]:
+    cursor = db[COLLECTION].find({"carrier_id": carrier_id})
+    return [_serialize(doc) async for doc in cursor]
+
+
+async def get_by_registration_plate(db: AsyncIOMotorDatabase, registration_plate: str) -> Optional[dict]:
+    return _serialize(await db[COLLECTION].find_one({"registration_plate": registration_plate}))
+
+
+async def get_by_active(db: AsyncIOMotorDatabase, active: bool) -> list[dict]:
+    cursor = db[COLLECTION].find({"active": active})
+    return [_serialize(doc) async for doc in cursor]
+
+
+async def create(db: AsyncIOMotorDatabase, data: VehicleCreate) -> dict:
+    doc = _prepare(data.model_dump(mode="python"))
+    await db[COLLECTION].insert_one(doc)
+    return _serialize(doc)
+
+
+async def update(db: AsyncIOMotorDatabase, vehicle_id: str, data: VehicleUpdate) -> Optional[dict]:
+    fields = _prepare(data.model_dump(mode="python", exclude_unset=True))
+    if not fields:
+        return await get_by_id(db, vehicle_id)
+    fields["updated_at"] = utc_now()
+    result = await db[COLLECTION].find_one_and_update(
+        {"id": vehicle_id},
+        {"$set": fields},
+        return_document=ReturnDocument.AFTER,
+    )
+    return _serialize(result)
+
+
+async def delete(db: AsyncIOMotorDatabase, vehicle_id: str) -> bool:
+    result = await db[COLLECTION].delete_one({"id": vehicle_id})
+    return result.deleted_count == 1

services/shipping/helpers/waybill.py

@@ -0,0 +1,86 @@
+from datetime import date, datetime, timezone
+from decimal import Decimal
+from typing import Optional
+from uuid import UUID
+
+from motor.motor_asyncio import AsyncIOMotorDatabase
+from pymongo import ReturnDocument
+
+from services.shipping.models.waybill import WaybillCreate, WaybillUpdate, utc_now
+
+
+COLLECTION = "waybills"
+
+
+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, UUID):
+        return str(value)
+    if isinstance(value, Decimal):
+        return str(value)
+    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, page: int = 1, page_size: int = 20) -> tuple[list[dict], int]:
+    query: dict = {}
+    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, waybill_id: str) -> Optional[dict]:
+    return _serialize(await db[COLLECTION].find_one({"id": waybill_id}))
+
+
+async def get_by_number(db: AsyncIOMotorDatabase, waybill_number: str) -> Optional[dict]:
+    return _serialize(await db[COLLECTION].find_one({"waybill_number": waybill_number}))
+
+
+async def get_by_status(db: AsyncIOMotorDatabase, status: str) -> list[dict]:
+    cursor = db[COLLECTION].find({"status": status})
+    return [_serialize(doc) async for doc in cursor]
+
+
+async def get_by_barcode(db: AsyncIOMotorDatabase, barcode: str) -> Optional[dict]:
+    return _serialize(await db[COLLECTION].find_one({"barcode": barcode}))
+
+
+async def create(db: AsyncIOMotorDatabase, data: WaybillCreate) -> dict:
+    doc = _prepare(data.model_dump(mode="python"))
+    await db[COLLECTION].insert_one(doc)
+    return _serialize(doc)
+
+
+async def update(db: AsyncIOMotorDatabase, waybill_id: str, data: WaybillUpdate) -> Optional[dict]:
+    fields = _prepare(data.model_dump(mode="python", exclude_unset=True))
+    if not fields:
+        return await get_by_id(db, waybill_id)
+    fields["updated_at"] = utc_now()
+    result = await db[COLLECTION].find_one_and_update(
+        {"id": waybill_id},
+        {"$set": fields},
+        return_document=ReturnDocument.AFTER,
+    )
+    return _serialize(result)
+
+
+async def delete(db: AsyncIOMotorDatabase, waybill_id: str) -> bool:
+    result = await db[COLLECTION].delete_one({"id": waybill_id})
+    return result.deleted_count == 1

services/shipping/main.py

@@ -0,0 +1,64 @@
+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.shipping.routers.carrier import router as carrier_router
+from services.shipping.routers.customs_declaration import router as customs_declaration_router
+from services.shipping.routers.delivery_note import router as delivery_note_router
+from services.shipping.routers.package import router as package_router
+from services.shipping.routers.pallet import router as pallet_router
+from services.shipping.routers.route import router as route_router
+from services.shipping.routers.shipping_information import router as shipping_information_router
+from services.shipping.routers.shipping_provider_details import router as shipping_provider_details_router
+from services.shipping.routers.shipping_provider_metadata import router as shipping_provider_metadata_router
+from services.shipping.routers.vehicle import router as vehicle_router
+from services.shipping.routers.waybill import router as waybill_router
+
+
+logger = configure_service_logging("shipping")
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    await connect_db()
+    yield
+    await close_db()
+
+
+app = FastAPI(
+    title="Shipping Service",
+    description="Microservice for shipping service.",
+    version="1.0.0",
+    lifespan=lifespan,
+)
+install_request_logging(app, "shipping")
+install_route_tracing(app, "shipping")
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+app.include_router(shipping_information_router, prefix="/api/v1/shipping-information", tags=["Shipping Information"])
+app.include_router(carrier_router, prefix="/api/v1/carriers", tags=["Carriers"])
+app.include_router(vehicle_router, prefix="/api/v1/vehicles", tags=["Vehicles"])
+app.include_router(pallet_router, prefix="/api/v1/pallets", tags=["Pallets"])
+app.include_router(package_router, prefix="/api/v1/packages", tags=["Packages"])
+app.include_router(delivery_note_router, prefix="/api/v1/delivery-notes", tags=["Delivery Notes"])
+app.include_router(route_router, prefix="/api/v1/routes", tags=["Routes"])
+app.include_router(customs_declaration_router, prefix="/api/v1/customs-declarations", tags=["Customs Declarations"])
+app.include_router(shipping_provider_details_router, prefix="/api/v1/shipping-providers", tags=["Shipping Providers"])
+app.include_router(shipping_provider_metadata_router, prefix="/api/v1/shipping-provider-metadata", tags=["Shipping Provider Metadata"])
+app.include_router(waybill_router, prefix="/api/v1/waybills", tags=["Waybills"])
+
+
+@app.get("/health", tags=["Health"])
+async def health_check():
+    return {"status": "healthy"}

services/shipping/models/__init__.py

@@ -0,0 +1,15 @@
+"""shipping service models package."""
+
+__all__ = [
+    "carrier",
+    "customs_declaration",
+    "delivery_note",
+    "package",
+    "pallet",
+    "route",
+    "shipping_information",
+    "shipping_provider_details",
+    "shipping_provider_metadata",
+    "vehicle",
+    "waybill",
+]

services/shipping/models/carrier.py

@@ -0,0 +1,97 @@
+from datetime import date, datetime, timezone
+from enum import Enum
+from typing import Optional
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, EmailStr, Field
+
+
+def utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+class CarrierMode(str, Enum):
+    ROAD = "road"
+    RAIL = "rail"
+    AIR = "air"
+    OCEAN = "ocean"
+    PARCEL = "parcel"
+    INTERMODAL = "intermodal"
+
+
+class Address(BaseModel):
+    line1: str = Field(..., min_length=1, max_length=200)
+    line2: Optional[str] = Field(None, max_length=200)
+    city: str = Field(..., min_length=1, max_length=100)
+    state: Optional[str] = Field(None, max_length=100)
+    postal_code: Optional[str] = Field(None, max_length=30)
+    country: str = Field(..., min_length=1, max_length=100)
+
+    model_config = {"str_strip_whitespace": True}
+
+
+class CarrierContact(BaseModel):
+    name: str = Field(..., min_length=1, max_length=150)
+    role: Optional[str] = Field(None, max_length=100, examples=["Dispatcher", "Account Manager"])
+    phone: str = Field(..., max_length=30)
+    email: Optional[EmailStr] = None
+
+    model_config = {"str_strip_whitespace": True}
+
+
+class Carrier(BaseModel):
+    """Freight / logistics carrier (third-party or in-house)."""
+
+    id: UUID = Field(default_factory=uuid4)
+    name: str = Field(..., min_length=1, max_length=200)
+    code: str = Field(..., min_length=1, max_length=20, description="Internal carrier code")
+    transport_mode: CarrierMode = CarrierMode.ROAD
+    scac_code: Optional[str] = Field(
+        None, max_length=4, description="Standard Carrier Alpha Code (SCAC) - North America"
+    )
+    tax_id: Optional[str] = Field(None, max_length=50)
+    address: Address
+    contacts: list[CarrierContact] = Field(default_factory=list)
+    insurance_policy_number: Optional[str] = Field(None, max_length=100)
+    insurance_expiry: Optional[date] = None
+    contract_reference: Optional[str] = Field(None, max_length=100)
+    active: bool = True
+    notes: Optional[str] = None
+    created_at: datetime = Field(default_factory=utc_now)
+    updated_at: Optional[datetime] = None
+
+    model_config = {"str_strip_whitespace": True}
+
+
+class CarrierCreate(Carrier):
+    pass
+
+
+class CarrierUpdate(BaseModel):
+    name: Optional[str] = Field(None, min_length=1, max_length=200)
+    code: Optional[str] = Field(None, min_length=1, max_length=20)
+    transport_mode: Optional[CarrierMode] = None
+    scac_code: Optional[str] = Field(None, max_length=4)
+    tax_id: Optional[str] = Field(None, max_length=50)
+    address: Optional[Address] = None
+    contacts: Optional[list[CarrierContact]] = None
+    insurance_policy_number: Optional[str] = Field(None, max_length=100)
+    insurance_expiry: Optional[date] = None
+    contract_reference: Optional[str] = Field(None, max_length=100)
+    active: Optional[bool] = None
+    notes: Optional[str] = None
+    updated_at: Optional[datetime] = None
+
+    model_config = {"str_strip_whitespace": True}
+
+
+class CarrierResponse(Carrier):
+    class Config:
+        from_attributes = True
+
+
+class PaginatedCarrierResponse(BaseModel):
+    total: int
+    page: int
+    page_size: int
+    results: list[CarrierResponse]

services/shipping/models/customs_declaration.py

@@ -0,0 +1,138 @@
+from datetime import date, datetime, timezone
+from decimal import Decimal
+from enum import Enum
+from typing import Annotated, Optional
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, Field, computed_field
+
+from services.shipping.models.carrier import Address, CarrierMode
+
+
+def utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+class CustomsDeclarationType(str, Enum):
+    IMPORT = "import"
+    EXPORT = "export"
+    TRANSIT = "transit"
+    RE_EXPORT = "re_export"
+    TEMPORARY_IMPORT = "temporary_import"
+
+
+class MoneyAmount(BaseModel):
+    amount: Annotated[Decimal, Field(ge=0)]
+    currency: str = Field(default="USD", min_length=3, max_length=3, description="ISO 4217")
+
+    model_config = {"str_strip_whitespace": True}
+
+
+class CustomsLineItem(BaseModel):
+    line_number: int = Field(..., ge=1)
+    commodity_code: str = Field(..., max_length=20, description="HS / tariff code")
+    description: str = Field(..., max_length=500)
+    country_of_origin: str = Field(..., min_length=2, max_length=2)
+    quantity: Annotated[Decimal, Field(gt=0)]
+    unit_of_measure: str = Field(..., max_length=20)
+    gross_weight_kg: Annotated[float, Field(gt=0)]
+    net_weight_kg: Optional[Annotated[float, Field(gt=0)]] = None
+    customs_value: MoneyAmount
+    duty_rate_pct: Optional[Annotated[float, Field(ge=0, le=100)]] = None
+    duty_amount: Optional[MoneyAmount] = None
+    vat_rate_pct: Optional[Annotated[float, Field(ge=0, le=100)]] = None
+    licence_number: Optional[str] = Field(None, max_length=100)
+
+    model_config = {"str_strip_whitespace": True}
+
+
+class CustomsDeclaration(BaseModel):
+    """Import / export customs declaration linked to a shipment."""
+
+    id: UUID = Field(default_factory=uuid4)
+    declaration_reference: str = Field(..., min_length=1, max_length=80)
+    declaration_type: CustomsDeclarationType
+    declaration_date: date = Field(default_factory=date.today)
+    shipment_id: Optional[str] = Field(None, max_length=100)
+    delivery_note_id: Optional[str] = Field(None, max_length=100)
+    exporter_name: str = Field(..., max_length=200)
+    exporter_address: Address
+    exporter_eori: Optional[str] = Field(None, max_length=50, description="EORI number")
+    importer_name: str = Field(..., max_length=200)
+    importer_address: Address
+    importer_eori: Optional[str] = Field(None, max_length=50)
+    country_of_export: str = Field(..., min_length=2, max_length=2)
+    country_of_import: str = Field(..., min_length=2, max_length=2)
+    port_of_loading: Optional[str] = Field(None, max_length=100)
+    port_of_discharge: Optional[str] = Field(None, max_length=100)
+    transport_mode: CarrierMode
+    incoterms: Optional[str] = Field(None, max_length=10)
+    currency: str = Field(default="USD", min_length=3, max_length=3)
+    lines: list[CustomsLineItem] = Field(default_factory=list, min_length=1)
+    mrn: Optional[str] = Field(None, max_length=50, description="Movement Reference Number")
+    customs_cleared: bool = False
+    clearance_date: Optional[date] = None
+    broker_name: Optional[str] = Field(None, max_length=200)
+    broker_reference: Optional[str] = Field(None, max_length=80)
+    notes: Optional[str] = None
+    created_at: datetime = Field(default_factory=utc_now)
+    updated_at: Optional[datetime] = None
+
+    model_config = {"str_strip_whitespace": True}
+
+    @computed_field  # type: ignore[misc]
+    @property
+    def total_customs_value(self) -> Decimal:
+        return sum(line.customs_value.amount for line in self.lines)
+
+    @computed_field  # type: ignore[misc]
+    @property
+    def total_duty(self) -> Decimal:
+        return sum(line.duty_amount.amount for line in self.lines if line.duty_amount)
+
+
+class CustomsDeclarationCreate(CustomsDeclaration):
+    pass
+
+
+class CustomsDeclarationUpdate(BaseModel):
+    declaration_reference: Optional[str] = Field(None, min_length=1, max_length=80)
+    declaration_type: Optional[CustomsDeclarationType] = None
+    declaration_date: Optional[date] = None
+    shipment_id: Optional[str] = Field(None, max_length=100)
+    delivery_note_id: Optional[str] = Field(None, max_length=100)
+    exporter_name: Optional[str] = Field(None, max_length=200)
+    exporter_address: Optional[Address] = None
+    exporter_eori: Optional[str] = Field(None, max_length=50)
+    importer_name: Optional[str] = Field(None, max_length=200)
+    importer_address: Optional[Address] = None
+    importer_eori: Optional[str] = Field(None, max_length=50)
+    country_of_export: Optional[str] = Field(None, min_length=2, max_length=2)
+    country_of_import: Optional[str] = Field(None, min_length=2, max_length=2)
+    port_of_loading: Optional[str] = Field(None, max_length=100)
+    port_of_discharge: Optional[str] = Field(None, max_length=100)
+    transport_mode: Optional[CarrierMode] = None
+    incoterms: Optional[str] = Field(None, max_length=10)
+    currency: Optional[str] = Field(None, min_length=3, max_length=3)
+    lines: Optional[list[CustomsLineItem]] = Field(None, min_length=1)
+    mrn: Optional[str] = Field(None, max_length=50)
+    customs_cleared: Optional[bool] = None
+    clearance_date: Optional[date] = None
+    broker_name: Optional[str] = Field(None, max_length=200)
+    broker_reference: Optional[str] = Field(None, max_length=80)
+    notes: Optional[str] = None
+    updated_at: Optional[datetime] = None
+
+    model_config = {"str_strip_whitespace": True}
+
+
+class CustomsDeclarationResponse(CustomsDeclaration):
+    class Config:
+        from_attributes = True
+
+
+class PaginatedCustomsDeclarationResponse(BaseModel):
+    total: int
+    page: int
+    page_size: int
+    results: list[CustomsDeclarationResponse]

services/shipping/models/delivery_note.py

@@ -0,0 +1,163 @@
+from datetime import date, datetime, timezone
+from decimal import Decimal
+from enum import Enum
+from typing import Annotated, Optional
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, Field, computed_field, field_validator, model_validator
+
+from services.shipping.models.carrier import Address
+
+
+def utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+class DeliveryStatus(str, Enum):
+    PENDING = "pending"
+    DISPATCHED = "dispatched"
+    IN_TRANSIT = "in_transit"
+    DELIVERED = "delivered"
+    PARTIALLY_DELIVERED = "partially_delivered"
+    CANCELLED = "cancelled"
+    RETURNED = "returned"
+
+
+class DeliveryNoteItem(BaseModel):
+    """A single line item on the delivery note."""
+
+    line_number: int = Field(..., ge=1)
+    product_code: str = Field(..., min_length=1, max_length=50)
+    product_description: str = Field(..., max_length=255)
+    purchase_order_number: Optional[str] = Field(None, max_length=50)
+    sales_order_number: Optional[str] = Field(None, max_length=50)
+    invoice_number: Optional[str] = Field(None, max_length=50)
+    waybill_id: Optional[str] = Field(None, max_length=100)
+    batch_number: Optional[str] = Field(None, max_length=50)
+    serial_number: Optional[str] = Field(None, max_length=100)
+    quantity_ordered: Annotated[Decimal, Field(gt=0)]
+    quantity_delivered: Annotated[Decimal, Field(ge=0)]
+    unit_of_measure: str = Field(..., max_length=20)
+    unit_weight_kg: Optional[Annotated[float, Field(ge=0)]] = None
+    pallet_label: Optional[str] = Field(None, max_length=50, description="Reference to Pallet.pallet_label")
+    notes: Optional[str] = None
+
+    @computed_field  # type: ignore[misc]
+    @property
+    def quantity_outstanding(self) -> Decimal:
+        return max(Decimal(0), self.quantity_ordered - self.quantity_delivered)
+
+
+class DeliveryNote(BaseModel):
+    """Delivery Note (also called Dispatch Note / Consignment Note)."""
+
+    id: UUID = Field(default_factory=uuid4)
+    delivery_note_number: str = Field(..., min_length=1, max_length=50, description="Unique DN reference")
+    issue_date: date = Field(default_factory=date.today)
+    expected_delivery_date: Optional[date] = None
+    actual_delivery_date: Optional[date] = None
+    status: DeliveryStatus = DeliveryStatus.PENDING
+    manufacturer_name: str = Field(..., max_length=200)
+    manufacturer_address: Address
+    ship_from_address: Optional[Address] = None
+    customer_name: str = Field(..., max_length=200)
+    customer_code: Optional[str] = Field(None, max_length=50)
+    delivery_address: Address
+    billing_address: Optional[Address] = None
+    purchase_order_numbers: list[str] = Field(default_factory=list)
+    sales_order_numbers: list[str] = Field(default_factory=list)
+    invoice_number: Optional[str] = Field(None, max_length=50)
+    carrier_id: Optional[UUID] = None
+    vehicle_id: Optional[UUID] = None
+    tracking_number: Optional[str] = Field(None, max_length=100)
+    pro_number: Optional[str] = Field(None, max_length=50, description="PRO / waybill number")
+    items: list[DeliveryNoteItem] = Field(default_factory=list, min_length=1)
+    pallet_ids: list[UUID] = Field(default_factory=list)
+    total_pallets: Optional[int] = Field(None, ge=0)
+    total_gross_weight_kg: Optional[float] = Field(None, ge=0)
+    total_net_weight_kg: Optional[float] = Field(None, ge=0)
+    total_volume_m3: Optional[float] = Field(None, ge=0)
+    requires_signature: bool = True
+    hazardous_goods: bool = False
+    special_instructions: Optional[str] = None
+    received_by: Optional[str] = Field(None, max_length=150)
+    signature_reference: Optional[str] = Field(None, max_length=255, description="URL or document ref")
+    pod_timestamp: Optional[datetime] = None
+    discrepancy_notes: Optional[str] = None
+    created_by: Optional[str] = Field(None, max_length=100)
+    created_at: datetime = Field(default_factory=utc_now)
+    updated_at: Optional[datetime] = None
+
+    model_config = {"str_strip_whitespace": True}
+
+    @field_validator("expected_delivery_date")
+    @classmethod
+    def delivery_date_not_in_past(cls, value: Optional[date]) -> Optional[date]:
+        return value
+
+    @model_validator(mode="after")
+    def pod_requires_receiver(self) -> "DeliveryNote":
+        if self.status == DeliveryStatus.DELIVERED and self.received_by is None:
+            raise ValueError("received_by is required when status is DELIVERED")
+        return self
+
+
+class DeliveryNoteCreate(DeliveryNote):
+    pass
+
+
+class DeliveryNoteUpdate(BaseModel):
+    delivery_note_number: Optional[str] = Field(None, min_length=1, max_length=50)
+    issue_date: Optional[date] = None
+    expected_delivery_date: Optional[date] = None
+    actual_delivery_date: Optional[date] = None
+    status: Optional[DeliveryStatus] = None
+    manufacturer_name: Optional[str] = Field(None, max_length=200)
+    manufacturer_address: Optional[Address] = None
+    ship_from_address: Optional[Address] = None
+    customer_name: Optional[str] = Field(None, max_length=200)
+    customer_code: Optional[str] = Field(None, max_length=50)
+    delivery_address: Optional[Address] = None
+    billing_address: Optional[Address] = None
+    purchase_order_numbers: Optional[list[str]] = None
+    sales_order_numbers: Optional[list[str]] = None
+    invoice_number: Optional[str] = Field(None, max_length=50)
+    carrier_id: Optional[UUID] = None
+    vehicle_id: Optional[UUID] = None
+    tracking_number: Optional[str] = Field(None, max_length=100)
+    pro_number: Optional[str] = Field(None, max_length=50)
+    items: Optional[list[DeliveryNoteItem]] = Field(None, min_length=1)
+    pallet_ids: Optional[list[UUID]] = None
+    total_pallets: Optional[int] = Field(None, ge=0)
+    total_gross_weight_kg: Optional[float] = Field(None, ge=0)
+    total_net_weight_kg: Optional[float] = Field(None, ge=0)
+    total_volume_m3: Optional[float] = Field(None, ge=0)
+    requires_signature: Optional[bool] = None
+    hazardous_goods: Optional[bool] = None
+    special_instructions: Optional[str] = None
+    received_by: Optional[str] = Field(None, max_length=150)
+    signature_reference: Optional[str] = Field(None, max_length=255)
+    pod_timestamp: Optional[datetime] = None
+    discrepancy_notes: Optional[str] = None
+    created_by: Optional[str] = Field(None, max_length=100)
+    updated_at: Optional[datetime] = None
+
+    model_config = {"str_strip_whitespace": True}
+
+    @model_validator(mode="after")
+    def pod_requires_receiver(self) -> "DeliveryNoteUpdate":
+        if self.status == DeliveryStatus.DELIVERED and self.received_by is None:
+            raise ValueError("received_by is required when status is DELIVERED")
+        return self
+
+
+class DeliveryNoteResponse(DeliveryNote):
+    class Config:
+        from_attributes = True
+
+
+class PaginatedDeliveryNoteResponse(BaseModel):
+    total: int
+    page: int
+    page_size: int
+    results: list[DeliveryNoteResponse]