monkeybrain-runtime 1.0.0__py3-none-any.whl

services/inventory/routers/warehouse_regulated_records.py

@@ -0,0 +1,273 @@
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+from motor.motor_asyncio import AsyncIOMotorDatabase
+from pydantic import BaseModel
+
+from services.common.auth import require_permission
+from services.common.db import get_database
+from services.inventory.helpers import warehouse_regulated_records as crud
+from services.inventory.models.warehouse_regulated_records import (
+    InventoryDispositionRecord,
+    InventoryDispositionRecordCreate,
+    InventoryDispositionRecordUpdate,
+    MaterialInwardLog,
+    MaterialInwardLogCreate,
+    MaterialInwardLogUpdate,
+    PaginatedInventoryDispositionRecordResponse,
+    PaginatedMaterialInwardLogResponse,
+    PaginatedSpecialStorageRequirementResponse,
+    PaginatedWarehouseDispensingRecordResponse,
+    PaginatedWarehouseStatusLabelResponse,
+    SpecialStorageRequirement,
+    SpecialStorageRequirementCreate,
+    SpecialStorageRequirementUpdate,
+    WarehouseDispensingRecord,
+    WarehouseDispensingRecordCreate,
+    WarehouseDispensingRecordUpdate,
+    WarehouseStatusLabel,
+    WarehouseStatusLabelCreate,
+    WarehouseStatusLabelUpdate,
+)
+
+router = APIRouter()
+
+
+def _query(**filters: str | None) -> dict[str, Any] | None:
+    query = {key: value for key, value in filters.items() if value not in (None, "")}
+    return query or None
+
+
+async def _list_records(record_type: str, response_cls, page: int, page_size: int, db: AsyncIOMotorDatabase, query: dict[str, Any] | None = None):
+    records, total = await crud.get_all(db, record_type, page=page, page_size=page_size, query=query)
+    return response_cls(total=total, page=page, page_size=page_size, results=records)
+
+
+async def _get_record(record_type: str, record_id: str, db: AsyncIOMotorDatabase, label: str):
+    record = await crud.get_by_id(db, record_type, record_id)
+    if not record:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"{label} '{record_id}' not found")
+    return record
+
+
+async def _create_record(record_type: str, data: BaseModel, db: AsyncIOMotorDatabase, record_id: str, label: str):
+    if await crud.get_by_id(db, record_type, record_id):
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=f"{label} '{record_id}' already exists")
+    return await crud.create(db, record_type, data)
+
+
+async def _update_record(record_type: str, record_id: str, data: BaseModel, db: AsyncIOMotorDatabase, label: str):
+    updated = await crud.update(db, record_type, record_id, data)
+    if not updated:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"{label} '{record_id}' not found")
+    return updated
+
+
+async def _delete_record(record_type: str, record_id: str, db: AsyncIOMotorDatabase, label: str):
+    if not await crud.delete(db, record_type, record_id):
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"{label} '{record_id}' not found")
+
+
+@router.get("/special-storage-requirements", response_model=PaginatedSpecialStorageRequirementResponse)
+async def list_special_storage_requirements(
+    page: int = Query(1, ge=1),
+    page_size: int = Query(20, ge=1, le=1000),
+    product_id: str | None = None,
+    component_id: str | None = None,
+    material_code: str | None = None,
+    status_value: str | None = Query(None, alias="status"),
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-inventory")),
+):
+    return await _list_records(
+        "special_storage_requirements",
+        PaginatedSpecialStorageRequirementResponse,
+        page,
+        page_size,
+        db,
+        _query(product_id=product_id, component_id=component_id, material_code=material_code, status=status_value),
+    )
+
+
+@router.post("/special-storage-requirements", response_model=SpecialStorageRequirement, status_code=status.HTTP_201_CREATED)
+async def create_special_storage_requirement(data: SpecialStorageRequirementCreate, db: AsyncIOMotorDatabase = Depends(get_database), _: dict = Depends(require_permission("perm-create-inventory"))):
+    return await _create_record("special_storage_requirements", data, db, data.requirement_id, "Special storage requirement")
+
+
+@router.get("/special-storage-requirements/{requirement_id}", response_model=SpecialStorageRequirement)
+async def get_special_storage_requirement(requirement_id: str, db: AsyncIOMotorDatabase = Depends(get_database), _: dict = Depends(require_permission("perm-view-inventory"))):
+    return await _get_record("special_storage_requirements", requirement_id, db, "Special storage requirement")
+
+
+@router.patch("/special-storage-requirements/{requirement_id}", response_model=SpecialStorageRequirement)
+async def update_special_storage_requirement(requirement_id: str, data: SpecialStorageRequirementUpdate, db: AsyncIOMotorDatabase = Depends(get_database), _: dict = Depends(require_permission("perm-update-inventory"))):
+    return await _update_record("special_storage_requirements", requirement_id, data, db, "Special storage requirement")
+
+
+@router.delete("/special-storage-requirements/{requirement_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_special_storage_requirement(requirement_id: str, db: AsyncIOMotorDatabase = Depends(get_database), _: dict = Depends(require_permission("perm-delete-inventory"))):
+    await _delete_record("special_storage_requirements", requirement_id, db, "Special storage requirement")
+
+
+@router.get("/material-inward-logs", response_model=PaginatedMaterialInwardLogResponse)
+async def list_material_inward_logs(
+    page: int = Query(1, ge=1),
+    page_size: int = Query(20, ge=1, le=1000),
+    gr_id: str | None = None,
+    gr_number: str | None = None,
+    grn_record_id: str | None = None,
+    material_code: str | None = None,
+    warehouse_location_id: str | None = None,
+    status_value: str | None = Query(None, alias="status"),
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-inventory")),
+):
+    return await _list_records(
+        "material_inward_logs",
+        PaginatedMaterialInwardLogResponse,
+        page,
+        page_size,
+        db,
+        _query(gr_id=gr_id, gr_number=gr_number, grn_record_id=grn_record_id, material_code=material_code, warehouse_location_id=warehouse_location_id, status=status_value),
+    )
+
+
+@router.post("/material-inward-logs", response_model=MaterialInwardLog, status_code=status.HTTP_201_CREATED)
+async def create_material_inward_log(data: MaterialInwardLogCreate, db: AsyncIOMotorDatabase = Depends(get_database), _: dict = Depends(require_permission("perm-create-inventory"))):
+    return await _create_record("material_inward_logs", data, db, data.inward_log_id, "Material inward log")
+
+
+@router.get("/material-inward-logs/{inward_log_id}", response_model=MaterialInwardLog)
+async def get_material_inward_log(inward_log_id: str, db: AsyncIOMotorDatabase = Depends(get_database), _: dict = Depends(require_permission("perm-view-inventory"))):
+    return await _get_record("material_inward_logs", inward_log_id, db, "Material inward log")
+
+
+@router.patch("/material-inward-logs/{inward_log_id}", response_model=MaterialInwardLog)
+async def update_material_inward_log(inward_log_id: str, data: MaterialInwardLogUpdate, db: AsyncIOMotorDatabase = Depends(get_database), _: dict = Depends(require_permission("perm-update-inventory"))):
+    return await _update_record("material_inward_logs", inward_log_id, data, db, "Material inward log")
+
+
+@router.delete("/material-inward-logs/{inward_log_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_material_inward_log(inward_log_id: str, db: AsyncIOMotorDatabase = Depends(get_database), _: dict = Depends(require_permission("perm-delete-inventory"))):
+    await _delete_record("material_inward_logs", inward_log_id, db, "Material inward log")
+
+
+@router.get("/status-labels", response_model=PaginatedWarehouseStatusLabelResponse)
+async def list_status_labels(
+    page: int = Query(1, ge=1),
+    page_size: int = Query(20, ge=1, le=1000),
+    entity_type: str | None = None,
+    entity_id: str | None = None,
+    label_type: str | None = None,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-inventory")),
+):
+    return await _list_records("warehouse_status_labels", PaginatedWarehouseStatusLabelResponse, page, page_size, db, _query(entity_type=entity_type, entity_id=entity_id, label_type=label_type))
+
+
+@router.post("/status-labels", response_model=WarehouseStatusLabel, status_code=status.HTTP_201_CREATED)
+async def create_status_label(data: WarehouseStatusLabelCreate, db: AsyncIOMotorDatabase = Depends(get_database), _: dict = Depends(require_permission("perm-create-inventory"))):
+    return await _create_record("warehouse_status_labels", data, db, data.label_id, "Warehouse status label")
+
+
+@router.get("/status-labels/{label_id}", response_model=WarehouseStatusLabel)
+async def get_status_label(label_id: str, db: AsyncIOMotorDatabase = Depends(get_database), _: dict = Depends(require_permission("perm-view-inventory"))):
+    return await _get_record("warehouse_status_labels", label_id, db, "Warehouse status label")
+
+
+@router.patch("/status-labels/{label_id}", response_model=WarehouseStatusLabel)
+async def update_status_label(label_id: str, data: WarehouseStatusLabelUpdate, db: AsyncIOMotorDatabase = Depends(get_database), _: dict = Depends(require_permission("perm-update-inventory"))):
+    return await _update_record("warehouse_status_labels", label_id, data, db, "Warehouse status label")
+
+
+@router.delete("/status-labels/{label_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_status_label(label_id: str, db: AsyncIOMotorDatabase = Depends(get_database), _: dict = Depends(require_permission("perm-delete-inventory"))):
+    await _delete_record("warehouse_status_labels", label_id, db, "Warehouse status label")
+
+
+@router.get("/dispensing-records", response_model=PaginatedWarehouseDispensingRecordResponse)
+async def list_dispensing_records(
+    page: int = Query(1, ge=1),
+    page_size: int = Query(20, ge=1, le=1000),
+    work_order_id: str | None = None,
+    batch_id: str | None = None,
+    bom_id: str | None = None,
+    component_id: str | None = None,
+    material_code: str | None = None,
+    status_value: str | None = Query(None, alias="status"),
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-inventory")),
+):
+    return await _list_records(
+        "warehouse_dispensing_records",
+        PaginatedWarehouseDispensingRecordResponse,
+        page,
+        page_size,
+        db,
+        _query(work_order_id=work_order_id, batch_id=batch_id, bom_id=bom_id, component_id=component_id, material_code=material_code, status=status_value),
+    )
+
+
+@router.post("/dispensing-records", response_model=WarehouseDispensingRecord, status_code=status.HTTP_201_CREATED)
+async def create_dispensing_record(data: WarehouseDispensingRecordCreate, db: AsyncIOMotorDatabase = Depends(get_database), _: dict = Depends(require_permission("perm-create-inventory"))):
+    return await _create_record("warehouse_dispensing_records", data, db, data.dispensing_record_id, "Warehouse dispensing record")
+
+
+@router.get("/dispensing-records/{dispensing_record_id}", response_model=WarehouseDispensingRecord)
+async def get_dispensing_record(dispensing_record_id: str, db: AsyncIOMotorDatabase = Depends(get_database), _: dict = Depends(require_permission("perm-view-inventory"))):
+    return await _get_record("warehouse_dispensing_records", dispensing_record_id, db, "Warehouse dispensing record")
+
+
+@router.patch("/dispensing-records/{dispensing_record_id}", response_model=WarehouseDispensingRecord)
+async def update_dispensing_record(dispensing_record_id: str, data: WarehouseDispensingRecordUpdate, db: AsyncIOMotorDatabase = Depends(get_database), _: dict = Depends(require_permission("perm-update-inventory"))):
+    return await _update_record("warehouse_dispensing_records", dispensing_record_id, data, db, "Warehouse dispensing record")
+
+
+@router.delete("/dispensing-records/{dispensing_record_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_dispensing_record(dispensing_record_id: str, db: AsyncIOMotorDatabase = Depends(get_database), _: dict = Depends(require_permission("perm-delete-inventory"))):
+    await _delete_record("warehouse_dispensing_records", dispensing_record_id, db, "Warehouse dispensing record")
+
+
+@router.get("/quarantine-release-rejection-records", response_model=PaginatedInventoryDispositionRecordResponse)
+async def list_quarantine_release_rejection_records(
+    page: int = Query(1, ge=1),
+    page_size: int = Query(20, ge=1, le=1000),
+    entity_type: str | None = None,
+    entity_id: str | None = None,
+    disposition: str | None = None,
+    gr_id: str | None = None,
+    inventory_id: str | None = None,
+    lot_id: str | None = None,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-inventory")),
+):
+    return await _list_records(
+        "inventory_disposition_records",
+        PaginatedInventoryDispositionRecordResponse,
+        page,
+        page_size,
+        db,
+        _query(entity_type=entity_type, entity_id=entity_id, disposition=disposition, gr_id=gr_id, inventory_id=inventory_id, lot_id=lot_id),
+    )
+
+
+@router.post("/quarantine-release-rejection-records", response_model=InventoryDispositionRecord, status_code=status.HTTP_201_CREATED)
+async def create_quarantine_release_rejection_record(data: InventoryDispositionRecordCreate, db: AsyncIOMotorDatabase = Depends(get_database), _: dict = Depends(require_permission("perm-create-inventory"))):
+    return await _create_record("inventory_disposition_records", data, db, data.disposition_id, "Inventory disposition record")
+
+
+@router.get("/quarantine-release-rejection-records/{disposition_id}", response_model=InventoryDispositionRecord)
+async def get_quarantine_release_rejection_record(disposition_id: str, db: AsyncIOMotorDatabase = Depends(get_database), _: dict = Depends(require_permission("perm-view-inventory"))):
+    return await _get_record("inventory_disposition_records", disposition_id, db, "Inventory disposition record")
+
+
+@router.patch("/quarantine-release-rejection-records/{disposition_id}", response_model=InventoryDispositionRecord)
+async def update_quarantine_release_rejection_record(disposition_id: str, data: InventoryDispositionRecordUpdate, db: AsyncIOMotorDatabase = Depends(get_database), _: dict = Depends(require_permission("perm-update-inventory"))):
+    return await _update_record("inventory_disposition_records", disposition_id, data, db, "Inventory disposition record")
+
+
+@router.delete("/quarantine-release-rejection-records/{disposition_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_quarantine_release_rejection_record(disposition_id: str, db: AsyncIOMotorDatabase = Depends(get_database), _: dict = Depends(require_permission("perm-delete-inventory"))):
+    await _delete_record("inventory_disposition_records", disposition_id, db, "Inventory disposition record")

services/iot/helpers/__init__.py

@@ -0,0 +1,8 @@
+"""iot service helpers package."""
+
+__all__ = [
+    "ble_device",
+    "sensors",
+    "servers",
+    "uwb_device",
+]

services/iot/helpers/ble_device.py

@@ -0,0 +1,87 @@
+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.iot.models.ble_device import BLEDeviceCreate, BLEDeviceUpdate
+
+
+COLLECTION = "ble_devices"
+
+
+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, 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, device_id: str) -> Optional[dict]:
+    return _serialize(await db[COLLECTION].find_one({"id": device_id}))
+
+
+async def get_by_mac_address(db: AsyncIOMotorDatabase, mac_address: str) -> Optional[dict]:
+    return _serialize(await db[COLLECTION].find_one({"mac_address": mac_address.strip().upper()}))
+
+
+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 get_by_tag(db: AsyncIOMotorDatabase, tag: str) -> list[dict]:
+    cursor = db[COLLECTION].find({"tags": tag})
+    return [_serialize(doc) async for doc in cursor]
+
+
+async def create(db: AsyncIOMotorDatabase, data: BLEDeviceCreate) -> dict:
+    doc = _prepare(data.model_dump(mode="python"))
+    await db[COLLECTION].insert_one(doc)
+    return _serialize(doc)
+
+
+async def update(db: AsyncIOMotorDatabase, device_id: str, data: BLEDeviceUpdate) -> Optional[dict]:
+    fields = _prepare(data.model_dump(mode="python", exclude_unset=True))
+    if not fields:
+        return await get_by_id(db, device_id)
+    result = await db[COLLECTION].find_one_and_update(
+        {"id": device_id},
+        {"$set": fields},
+        return_document=ReturnDocument.AFTER,
+    )
+    return _serialize(result)
+
+
+async def delete(db: AsyncIOMotorDatabase, device_id: str) -> bool:
+    result = await db[COLLECTION].delete_one({"id": device_id})
+    return result.deleted_count == 1

services/iot/helpers/mqtt_bridge.py

@@ -0,0 +1,115 @@
+import asyncio
+import json
+import logging
+from datetime import datetime, timezone
+from typing import Any
+from urllib.parse import urlparse
+
+from services.auth.helpers import nats_store
+from services.common.config import settings
+
+
+log = logging.getLogger("uvicorn.error")
+
+_client = None
+_loop: asyncio.AbstractEventLoop | None = None
+
+
+def _topic_list() -> list[str]:
+    return [topic.strip() for topic in str(settings.MQTT_TOPICS or "").split(",") if topic.strip()]
+
+
+def _sensor_id_from_topic(topic: str) -> str:
+    parts = [part for part in str(topic or "").split("/") if part and part != "#"]
+    return parts[-1] if parts else "unknown"
+
+
+def _reading_from_message(topic: str, payload: bytes) -> dict[str, Any]:
+    text = payload.decode("utf-8", errors="replace").strip()
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError:
+        data = {"value": text}
+    if not isinstance(data, dict):
+        data = {"value": data}
+
+    sensor_id = str(
+        data.get("sensor_id")
+        or data.get("sensorId")
+        or data.get("id")
+        or _sensor_id_from_topic(topic)
+    )
+    reading = {
+        **data,
+        "sensor_id": sensor_id,
+        "topic": topic,
+        "source": "mqtt",
+        "received_at": datetime.now(timezone.utc).isoformat(),
+    }
+    if "timestamp" not in reading:
+        reading["timestamp"] = reading["received_at"]
+    return reading
+
+
+async def _publish_reading(reading: dict[str, Any]) -> None:
+    subject = nats_store.sensor_subject(str(reading.get("sensor_id") or "unknown"))
+    await nats_store.publish_event(json.dumps(reading, default=str).encode("utf-8"), subject=subject)
+    log.info(
+        "MQTT sensor reading published to NATS subject=%s sensor_id=%s",
+        subject,
+        reading.get("sensor_id"),
+    )
+
+
+def _on_connect(client, _userdata, _flags, reason_code, _properties=None):
+    if reason_code != 0:
+        log.warning("MQTT bridge failed to connect reason_code=%s", reason_code)
+        return
+    for topic in _topic_list():
+        client.subscribe(topic)
+        log.info("MQTT bridge subscribed topic=%s", topic)
+
+
+def _on_message(_client, _userdata, message):
+    if _loop is None:
+        return
+    reading = _reading_from_message(message.topic, message.payload)
+    asyncio.run_coroutine_threadsafe(_publish_reading(reading), _loop)
+
+
+async def start_mqtt_bridge() -> None:
+    global _client, _loop
+    if not settings.MQTT_ENABLED:
+        log.info("MQTT bridge disabled")
+        return
+    if _client is not None:
+        return
+
+    try:
+        import paho.mqtt.client as mqtt
+    except ImportError:
+        log.warning("MQTT bridge disabled because paho-mqtt is not installed")
+        return
+
+    parsed = urlparse(settings.MQTT_BROKER_URL)
+    host = parsed.hostname or "localhost"
+    port = parsed.port or 1883
+    _loop = asyncio.get_running_loop()
+    _client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id=settings.MQTT_CLIENT_ID)
+    if settings.MQTT_USERNAME:
+        _client.username_pw_set(settings.MQTT_USERNAME, settings.MQTT_PASSWORD or None)
+    _client.on_connect = _on_connect
+    _client.on_message = _on_message
+    _client.connect(host, port, keepalive=60)
+    _client.loop_start()
+    log.info("MQTT bridge connecting broker=%s topics=%s", settings.MQTT_BROKER_URL, _topic_list())
+
+
+async def stop_mqtt_bridge() -> None:
+    global _client, _loop
+    if _client is None:
+        return
+    _client.loop_stop()
+    _client.disconnect()
+    _client = None
+    _loop = None

services/iot/helpers/sensor_readings.py

@@ -0,0 +1,63 @@
+import json
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlencode
+from urllib.request import Request, urlopen
+
+from services.auth.helpers import nats_store
+from services.common.config import settings
+
+
+def _is_missing_table(status_code: int, detail: str) -> bool:
+    normalized = detail.lower()
+    return status_code == 400 and "table" in normalized and "not found" in normalized
+
+
+def _query_sensor_table(sensor_id: str, limit: int) -> list[dict]:
+    table = nats_store.sensor_subject(sensor_id)
+    query = (
+        'SELECT time, reading_json '
+        f'FROM "{table}" '
+        "ORDER BY time DESC "
+        f"LIMIT {limit}"
+    )
+    params = urlencode({"db": settings.INFLUXDB_BUCKET, "q": query})
+    url = f"{settings.INFLUXDB_URL.rstrip('/')}/api/v3/query_sql?{params}"
+    headers = {}
+    if settings.INFLUXDB_TOKEN:
+        headers["Authorization"] = f"Bearer {settings.INFLUXDB_TOKEN}"
+
+    request = Request(url, headers=headers, method="GET")
+    try:
+        with urlopen(request, timeout=5) as response:
+            return json.loads(response.read().decode("utf-8"))
+    except HTTPError as exc:
+        detail = exc.read().decode("utf-8", errors="replace")
+        if _is_missing_table(exc.code, detail):
+            return []
+        raise RuntimeError(f"InfluxDB query failed with status {exc.code}: {detail}") from exc
+    except URLError as exc:
+        raise RuntimeError(f"Unable to connect to InfluxDB at {settings.INFLUXDB_URL}: {exc}") from exc
+
+
+def _reading_from_row(row: dict) -> dict:
+    reading_json = row.get("reading_json")
+    if isinstance(reading_json, str):
+        try:
+            reading = json.loads(reading_json)
+        except json.JSONDecodeError:
+            reading = {}
+    else:
+        reading = {}
+    if row.get("time") is not None:
+        reading["time"] = row["time"]
+    return reading
+
+
+async def get_sensor_readings(sensor_id: str, limit: int = 100) -> list[dict]:
+    rows = _query_sensor_table(sensor_id, limit)
+    return [_reading_from_row(row) for row in rows]
+
+
+async def get_latest_sensor_reading(sensor_id: str) -> dict | None:
+    readings = await get_sensor_readings(sensor_id, limit=1)
+    return readings[0] if readings else None

services/iot/helpers/sensors.py

@@ -0,0 +1,77 @@
+from datetime import date, datetime
+from typing import Optional
+from motor.motor_asyncio import AsyncIOMotorDatabase
+from services.iot.models.sensors import SensorCreate, SensorUpdate
+
+COLLECTION = "sensors"
+
+
+def _serialize(doc: dict) -> dict:
+    doc = dict(doc)
+    doc.pop("_id", None)
+    return doc
+
+
+def _prepare(doc: dict) -> dict:
+    """Convert date → datetime so BSON can encode them."""
+    return {
+        k: datetime(v.year, v.month, v.day) if isinstance(v, date) and not isinstance(v, datetime) else v
+        for k, v in doc.items()
+    }
+
+
+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)
+    results = [_serialize(d) async for d in cursor]
+    return results, total
+
+
+async def get_by_id(db: AsyncIOMotorDatabase, sensor_id: str) -> Optional[dict]:
+    doc = await db[COLLECTION].find_one({"sensor_id": sensor_id})
+    return _serialize(doc) if doc else None
+
+
+async def get_by_machine(db: AsyncIOMotorDatabase, machine_id: str) -> list[dict]:
+    cursor = db[COLLECTION].find({"machine_id": machine_id})
+    return [_serialize(d) async for d in cursor]
+
+async def get_by_equipment_id(db: AsyncIOMotorDatabase, equipment_id: str) -> list[dict]:
+    cursor = db[COLLECTION].find({"equipment_id": equipment_id})
+    return [_serialize(d) async for d in cursor]
+
+async def get_by_edge_server(db: AsyncIOMotorDatabase, edge_server_id: str) -> list[dict]:
+    cursor = db[COLLECTION].find({"edge_server_id": edge_server_id})
+    return [_serialize(d) async for d in cursor]
+
+async def get_by_facility(db: AsyncIOMotorDatabase, facility: str) -> list[dict]:
+    cursor = db[COLLECTION].find({"facility": facility})
+    return [_serialize(d) async for d in cursor]
+
+async def create(db: AsyncIOMotorDatabase, data: SensorCreate) -> dict:
+    doc = _prepare(data.model_dump())
+    await db[COLLECTION].insert_one(doc)
+    return _serialize(doc)
+
+async def update(
+    db: AsyncIOMotorDatabase, sensor_id: str, data: SensorUpdate
+) -> Optional[dict]:
+    fields = _prepare(data.model_dump(exclude_unset=True))
+    if not fields:
+        return await get_by_id(db, sensor_id)
+    result = await db[COLLECTION].find_one_and_update(
+        {"sensor_id": sensor_id},
+        {"$set": fields},
+        return_document=True,
+    )
+    return _serialize(result) if result else None
+
+
+async def delete(db: AsyncIOMotorDatabase, sensor_id: str) -> bool:
+    result = await db[COLLECTION].delete_one({"sensor_id": sensor_id})
+    return result.deleted_count == 1