bambuddy/backend/app/api/routes/spoolbuddy.py

"""SpoolBuddy device management API routes."""

import asyncio
import contextlib
import json
import logging
import re
import time
from datetime import datetime, timedelta, timezone
from urllib.parse import urlparse

import httpx
from fastapi import APIRouter, Depends, HTTPException
from sqlalchemy import func, select
from sqlalchemy.ext.asyncio import AsyncSession

from backend.app.core.auth import RequirePermissionIfAuthEnabled
from backend.app.core.database import get_db
from backend.app.core.permissions import Permission
from backend.app.core.websocket import ws_manager
from backend.app.models.spool import Spool
from backend.app.models.spoolbuddy_device import SpoolBuddyDevice
from backend.app.models.user import User
from backend.app.schemas.spoolbuddy import (
    CalibrationResponse,
    DeviceRegisterRequest,
    DeviceResponse,
    DiagnosticResultRequest,
    DisplaySettingsRequest,
    HeartbeatRequest,
    HeartbeatResponse,
    ScaleReadingRequest,
    SetCalibrationFactorRequest,
    SetTareRequest,
    SystemCommandRequest,
    SystemCommandResultRequest,
    SystemConfigRequest,
    TagRemovedRequest,
    TagScannedRequest,
    UpdateSpoolWeightRequest,
    WriteTagRequest,
    WriteTagResultRequest,
)
from backend.app.services.spool_tag_matcher import get_spool_by_tag
from backend.app.services.spoolman import SpoolmanClientError, SpoolmanNotFoundError, SpoolmanUnavailableError
from backend.app.utils.tag_normalization import is_bambu_tray_uuid, normalize_tag_uid, normalize_tray_uuid

logger = logging.getLogger(__name__)

router = APIRouter(prefix="/spoolbuddy", tags=["spoolbuddy"])

OFFLINE_THRESHOLD_SECONDS = 30
ONLINE_BROADCAST_INTERVAL_SECONDS = 10
_SSRF_WARN_THROTTLE_SECONDS = 60
_spoolbuddy_online_last_broadcast: dict[str, float] = {}
_ssrf_warn_last_broadcast: dict[str, float] = {}
_diagnostic_results: dict[tuple[str, str], dict] = {}


@contextlib.asynccontextmanager
async def _translate_spoolbuddy_errors():
    """Translate Spoolman typed exceptions to HTTP for SpoolBuddy endpoints."""
    try:
        yield
    except SpoolmanNotFoundError as exc:
        raise HTTPException(status_code=404, detail="Spool not found in Spoolman") from exc
    except SpoolmanClientError as exc:
        raise HTTPException(status_code=502, detail="Spoolman rejected the request") from exc
    except SpoolmanUnavailableError as exc:
        raise HTTPException(status_code=503, detail="Spoolman server is not reachable") from exc


async def _spoolman_mode(db: AsyncSession) -> bool:
    """Spoolman mode as every SpoolBuddy screen reads it: switched on, with a URL.

    Distinct from having a usable client: a URL the SSRF guard refuses leaves the
    mode on but no client, and the spools are still Spoolman's.
    """
    from backend.app.api.routes.settings import get_setting

    enabled = await get_setting(db, "spoolman_enabled")
    url = await get_setting(db, "spoolman_url")
    return bool(enabled) and enabled.lower() == "true" and bool((url or "").strip())


async def _get_spoolman_client_or_none(db: AsyncSession):
    """Return a SpoolmanClient if Spoolman is enabled with a safe URL, else None."""
    from backend.app.api.routes._spoolman_helpers import assert_safe_spoolman_url
    from backend.app.models.settings import Settings
    from backend.app.services.spoolman import get_spoolman_client, init_spoolman_client

    settings_result = await db.execute(select(Settings))
    settings_dict = {s.key: s.value for s in settings_result.scalars().all()}
    spoolman_url = settings_dict.get("spoolman_url", "").strip()
    spoolman_enabled = settings_dict.get("spoolman_enabled", "false").lower() == "true" and bool(spoolman_url)

    if not spoolman_enabled:
        return None

    # SSRF guard: reject dangerous schemes, cloud-metadata IPs (169.254.169.254, 100.100.100.200,
    # fd00:ec2::254), multicast and unspecified addresses — loopback and RFC-1918 ranges are
    # intentionally permitted (Spoolman commonly runs on the same host or home LAN).
    try:
        assert_safe_spoolman_url(spoolman_url)
    except ValueError as exc:
        logger.warning(
            "Spoolman integration disabled: URL %r rejected by SSRF guard: %s",
            spoolman_url,
            exc,
        )
        now = time.monotonic()
        if now - _ssrf_warn_last_broadcast.get(spoolman_url, 0) > _SSRF_WARN_THROTTLE_SECONDS:
            _ssrf_warn_last_broadcast[spoolman_url] = now
            await ws_manager.broadcast(
                {
                    "type": "spoolman_ssrf_blocked",
                    "detail": "Spoolman URL was rejected by the SSRF guard",
                }
            )
        return None

    client = await get_spoolman_client()
    if not client or client.base_url != spoolman_url.rstrip("/"):
        try:
            client = await init_spoolman_client(spoolman_url)
        except ValueError as exc:
            logger.warning(
                "Spoolman integration disabled: URL %r rejected on re-initialisation: %s",
                spoolman_url,
                exc,
            )
            return None
    return client


def _is_online(device: SpoolBuddyDevice) -> bool:
    if not device.last_seen:
        return False
    return (
        datetime.now(timezone.utc) - device.last_seen.replace(tzinfo=timezone.utc)
    ).total_seconds() < OFFLINE_THRESHOLD_SECONDS


def _device_to_response(device: SpoolBuddyDevice) -> DeviceResponse:
    return DeviceResponse(
        id=device.id,
        device_id=device.device_id,
        hostname=device.hostname,
        ip_address=device.ip_address,
        firmware_version=device.firmware_version,
        has_nfc=device.has_nfc,
        has_scale=device.has_scale,
        tare_offset=device.tare_offset,
        calibration_factor=device.calibration_factor,
        nfc_reader_type=device.nfc_reader_type,
        nfc_connection=device.nfc_connection,
        backend_url=device.backend_url,
        display_brightness=device.display_brightness,
        display_blank_timeout=device.display_blank_timeout,
        has_backlight=device.has_backlight,
        last_calibrated_at=device.last_calibrated_at,
        last_seen=device.last_seen,
        pending_command=device.pending_command,
        nfc_ok=device.nfc_ok,
        scale_ok=device.scale_ok,
        uptime_s=device.uptime_s,
        update_status=device.update_status,
        update_message=device.update_message,
        system_stats=json.loads(device.system_stats) if device.system_stats else None,
        online=_is_online(device),
        created_at=device.created_at,
        updated_at=device.updated_at,
    )


def _should_broadcast_online(device_id: str, force: bool = False) -> bool:
    if force:
        _spoolbuddy_online_last_broadcast[device_id] = time.time()
        return True

    now_ts = time.time()
    last_ts = _spoolbuddy_online_last_broadcast.get(device_id, 0.0)
    if now_ts - last_ts >= ONLINE_BROADCAST_INTERVAL_SECONDS:
        _spoolbuddy_online_last_broadcast[device_id] = now_ts
        return True
    return False


# --- Device endpoints ---


@router.post("/devices/register", response_model=DeviceResponse)
async def register_device(
    req: DeviceRegisterRequest,
    db: AsyncSession = Depends(get_db),
    _: User | None = RequirePermissionIfAuthEnabled(Permission.INVENTORY_UPDATE),
):
    """Register or re-register a SpoolBuddy device."""
    result = await db.execute(select(SpoolBuddyDevice).where(SpoolBuddyDevice.device_id == req.device_id))
    device = result.scalar_one_or_none()

    now = datetime.now(timezone.utc)
    if device:
        device.hostname = req.hostname
        device.ip_address = req.ip_address
        device.firmware_version = req.firmware_version
        device.has_nfc = req.has_nfc
        device.has_scale = req.has_scale
        device.nfc_reader_type = req.nfc_reader_type
        device.nfc_connection = req.nfc_connection
        if req.backend_url:
            device.backend_url = req.backend_url
        device.has_backlight = req.has_backlight
        device.last_seen = now
        # Clear stale update status on re-registration (daemon restarted after update)
        if device.update_status in ("pending", "updating", "complete", "error"):
            device.update_status = None
            device.update_message = None
        logger.info("SpoolBuddy device re-registered: %s (%s)", req.device_id, req.hostname)
    else:
        device = SpoolBuddyDevice(
            device_id=req.device_id,
            hostname=req.hostname,
            ip_address=req.ip_address,
            firmware_version=req.firmware_version,
            has_nfc=req.has_nfc,
            has_scale=req.has_scale,
            tare_offset=req.tare_offset,
            calibration_factor=req.calibration_factor,
            nfc_reader_type=req.nfc_reader_type,
            nfc_connection=req.nfc_connection,
            has_backlight=req.has_backlight,
            backend_url=req.backend_url,
            last_seen=now,
        )
        db.add(device)
        logger.info("SpoolBuddy device registered: %s (%s)", req.device_id, req.hostname)

    await db.commit()
    await db.refresh(device)

    _spoolbuddy_online_last_broadcast[device.device_id] = time.time()
    await ws_manager.broadcast(
        {
            "type": "spoolbuddy_online",
            "device_id": device.device_id,
            "hostname": device.hostname,
        }
    )

    response = _device_to_response(device)

    # Include SSH public key so the daemon can auto-deploy it
    try:
        from backend.app.services.spoolbuddy_ssh import get_public_key

        response.ssh_public_key = await get_public_key()
    except Exception as exc:
        logger.warning("Could not attach SSH public key to heartbeat response: %s", exc)

    return response


@router.get("/devices", response_model=list[DeviceResponse])
async def list_devices(
    db: AsyncSession = Depends(get_db),
    _: User | None = RequirePermissionIfAuthEnabled(Permission.INVENTORY_READ),
):
    """List all registered SpoolBuddy devices."""
    result = await db.execute(select(SpoolBuddyDevice).order_by(SpoolBuddyDevice.hostname))
    devices = list(result.scalars().all())
    return [_device_to_response(d) for d in devices]


@router.delete("/devices/{device_id}")
async def unregister_device(
    device_id: str,
    db: AsyncSession = Depends(get_db),
    _: User | None = RequirePermissionIfAuthEnabled(Permission.INVENTORY_DELETE),
):
    """Unregister a SpoolBuddy device. The daemon can re-register via heartbeat later."""
    result = await db.execute(select(SpoolBuddyDevice).where(SpoolBuddyDevice.device_id == device_id))
    device = result.scalar_one_or_none()
    if not device:
        raise HTTPException(status_code=404, detail="Device not registered")

    await db.delete(device)
    await db.commit()
    _spoolbuddy_online_last_broadcast.pop(device_id, None)
    logger.info("SpoolBuddy device unregistered: %s (%s)", device_id, device.hostname)
    await ws_manager.broadcast({"type": "spoolbuddy_unregistered", "device_id": device_id})
    return {"status": "deleted", "device_id": device_id}


@router.post("/devices/{device_id}/heartbeat", response_model=HeartbeatResponse)
async def device_heartbeat(
    device_id: str,
    req: HeartbeatRequest,
    db: AsyncSession = Depends(get_db),
    _: User | None = RequirePermissionIfAuthEnabled(Permission.INVENTORY_UPDATE),
):
    """Daemon heartbeat — updates status and returns pending commands."""
    result = await db.execute(select(SpoolBuddyDevice).where(SpoolBuddyDevice.device_id == device_id))
    device = result.scalar_one_or_none()
    if not device:
        raise HTTPException(status_code=404, detail="Device not registered")

    was_offline = not _is_online(device)
    now = datetime.now(timezone.utc)

    device.last_seen = now
    device.nfc_ok = req.nfc_ok
    device.scale_ok = req.scale_ok
    device.uptime_s = req.uptime_s
    if req.firmware_version:
        device.firmware_version = req.firmware_version
    if req.ip_address:
        device.ip_address = req.ip_address
    if req.nfc_reader_type:
        device.nfc_reader_type = req.nfc_reader_type
    if req.nfc_connection:
        device.nfc_connection = req.nfc_connection
    if req.backend_url:
        device.backend_url = req.backend_url
    if req.system_stats is not None:
        device.system_stats = json.dumps(req.system_stats)

    # Return and clear pending command
    pending = device.pending_command
    pending_write = None
    pending_system = None
    if pending == "write_tag" and device.pending_write_payload:
        # Parse the stored JSON payload to include in response
        try:
            pending_write = json.loads(device.pending_write_payload)
        except (json.JSONDecodeError, TypeError):
            pending_write = None
        # Don't clear write_tag command — it gets cleared by write-result
    elif pending == "apply_system_config" and device.pending_system_payload:
        try:
            pending_system = json.loads(device.pending_system_payload)
        except (json.JSONDecodeError, TypeError):
            pending_system = None
        # Don't clear config command — it gets cleared by daemon command-result callback
    elif pending and pending.startswith("run_") and pending.endswith("_diag"):
        # Don't clear diagnostic commands — they get cleared by the device reporting results
        pass
    else:
        device.pending_command = None

    await db.commit()

    # Emit online presence on offline->online transitions immediately, and
    # periodically while online so newly connected UIs can bootstrap state.
    if _should_broadcast_online(device.device_id, force=was_offline):
        await ws_manager.broadcast(
            {
                "type": "spoolbuddy_online",
                "device_id": device.device_id,
                "hostname": device.hostname,
            }
        )
    if was_offline:
        logger.info("SpoolBuddy device back online: %s", device.device_id)

    # Include current SSH public key so the daemon can re-deploy it whenever
    # Bambuddy's keypair rotates (data dir wiped, container recreated, etc.) —
    # otherwise SSH updates fail until the daemon restarts.
    ssh_public_key: str | None = None
    try:
        from backend.app.services.spoolbuddy_ssh import get_public_key

        ssh_public_key = await get_public_key()
    except Exception:
        pass

    return HeartbeatResponse(
        pending_command=pending,
        pending_write_payload=pending_write,
        pending_system_payload=pending_system,
        tare_offset=device.tare_offset,
        calibration_factor=device.calibration_factor,
        display_brightness=device.display_brightness,
        display_blank_timeout=device.display_blank_timeout,
        ssh_public_key=ssh_public_key,
    )


# --- NFC endpoints ---


async def _backfill_local_tray_uuid(db: AsyncSession, spool: Spool, tag_uid: str, tray_uuid: str) -> None:
    """Give a spool matched by its exact tag UID the tray UUID read from that tag.

    Spools added on the kiosk before #984 carry only the UID of the tag that was
    scanned then, so the spool's other tag and the AMS never found them. The scan
    read block 9 of this very tag, so the UUID belongs to this spool. Only an
    exact UID match counts: a fuzzy (suffix or first-byte) match may be another
    spool's tag and must never write anything. A UUID any other spool carries,
    archived ones included, is left alone.
    """
    if spool.tray_uuid or normalize_tag_uid(spool.tag_uid) != normalize_tag_uid(tag_uid):
        return
    try:
        holder = await db.execute(
            select(Spool.id).where(func.upper(Spool.tray_uuid) == tray_uuid, Spool.id != spool.id).limit(1)
        )
        if holder.scalar_one_or_none() is not None:
            return
        spool.tray_uuid = tray_uuid
        await db.commit()
        logger.info("SpoolBuddy: saved tray_uuid %s on spool %d, matched by tag %s", tray_uuid, spool.id, tag_uid)
    except Exception:
        await db.rollback()
        logger.exception("SpoolBuddy: could not save tray_uuid %s on spool %d", tray_uuid, spool.id)


async def _backfill_spoolman_tray_uuid(client, sm_spool: dict, tag_uid: str, tray_uuid: str) -> None:
    """Store the tray UUID as the tag of a Spoolman spool matched by its exact tag UID.

    Spoolman has one extra.tag per spool, and the AMS sync keys Bambu spools by
    the tray UUID there, so the UUID replaces the tag UID. The caller already
    looked the UUID up among the active spools and found none, the same check
    the link route makes. See _backfill_local_tray_uuid for why only an exact
    UID match counts.
    """
    extra = sm_spool.get("extra")
    raw_tag = extra.get("tag") if isinstance(extra, dict) else None
    stored = raw_tag.strip('"').upper() if isinstance(raw_tag, str) else ""
    spool_id = sm_spool.get("id")
    if not isinstance(spool_id, int) or not stored or stored != tag_uid.strip('"').upper():
        return
    try:
        await client.merge_spool_extra(spool_id, {"tag": json.dumps(tray_uuid)})
        logger.info("SpoolBuddy: stored tray_uuid %s as the tag of Spoolman spool %d", tray_uuid, spool_id)
        await ws_manager.broadcast({"type": "inventory_changed"})
    except Exception:
        logger.exception("SpoolBuddy: could not store tray_uuid %s on Spoolman spool %d", tray_uuid, spool_id)


@router.post("/nfc/tag-scanned")
async def nfc_tag_scanned(
    req: TagScannedRequest,
    db: AsyncSession = Depends(get_db),
    _: User | None = RequirePermissionIfAuthEnabled(Permission.INVENTORY_UPDATE),
):
    """RPi reports NFC tag detected — lookup spool and broadcast.

    Routes the lookup to the inventory backend Bambuddy is configured for:
    Spoolman exclusively when ``spoolman_enabled`` is true, local DB
    exclusively otherwise. The previous implementation always tried local
    first and only consulted Spoolman as a fallback on local-DB miss, which
    meant a stale local copy of a tag would silently win over the
    authoritative Spoolman row, and deleting the local copy was the only way
    to surface the Spoolman match. Operators expect the SpoolBuddy lookup to
    follow the inventory mode they selected in Bambuddy settings.
    """
    from backend.app.api.routes._spoolman_helpers import _map_spoolman_spool

    # Daemons before #984 read the filament type from blocks 4-5 and sent it as
    # tray_uuid. Drop anything that is not a real tray UUID, so an old daemon
    # falls back to tag_uid matching and its value is never offered for saving.
    tray_uuid: str | None = normalize_tray_uuid(req.tray_uuid) or None
    if tray_uuid and not is_bambu_tray_uuid(tray_uuid):
        logger.info(
            "SpoolBuddy %s sent tray_uuid %s for tag %s, which is not a Bambu tray UUID; ignoring it. "
            "Update the SpoolBuddy daemon.",
            req.device_id,
            tray_uuid,
            req.tag_uid,
        )
        tray_uuid = None

    # A usable client when Spoolman is on and its URL passes the SSRF guard.
    # With the mode on but no usable client the spools are still Spoolman's,
    # and the built-in table must not answer.
    client = await _get_spoolman_client_or_none(db)
    if client is None and await _spoolman_mode(db):
        await ws_manager.broadcast(
            {
                "type": "spoolman_unavailable",
                "device_id": req.device_id,
                "context": "nfc_tag_scanned",
            }
        )
        return {"status": "ok", "matched": False, "spool_id": None}

    if client is not None:
        # Spoolman mode — exclusive lookup, no local-DB fallback.
        try:
            sm_spool: dict | None = None
            native = await client.has_tag_api()
            cached_spools: list[dict] | None = None
            # The tray UUID is settled before the tag UID, as it always was: a spool
            # that carries the UUID only in extra.tag still wins over one holding the
            # chip UID natively. Spoolman 0.27+ answers each identifier with one exact
            # query; the whole inventory is loaded only when that misses.
            for uid in (tray_uuid, req.tag_uid):
                if not uid or sm_spool is not None:
                    continue
                if native:
                    try:
                        sm_spool = await client.find_spool_by_native_tag(uid.upper())
                    except SpoolmanClientError as exc:
                        logger.warning("Native tag lookup refused for %s, using extra.tag: %s", uid, exc)
                if sm_spool is None:
                    if cached_spools is None:
                        cached_spools = await client.get_spools()
                    sm_spool = await client.find_spool_by_tag(uid, cached_spools=cached_spools)

            if sm_spool is not None:
                # What this scan read becomes a native tag of the spool: a spool found
                # through extra.tag moves over on its first scan, and a Bambu spool
                # collects the chip UID of each side as it is read.
                await client.add_native_tags(
                    sm_spool, [tray_uuid, req.tag_uid], "bambu" if tray_uuid else None, retry_refused=True
                )
                mapped = _map_spoolman_spool(sm_spool)
                await ws_manager.broadcast(
                    {
                        "type": "spoolbuddy_tag_matched",
                        "device_id": req.device_id,
                        "tag_uid": req.tag_uid,
                        "tray_uuid": tray_uuid,
                        "spool": {
                            "id": mapped["id"],
                            "material": mapped["material"],
                            "subtype": mapped["subtype"],
                            "color_name": mapped["color_name"],
                            # Spoolman stores no colour name, so `color_name`
                            # here is usually the spool's subtype standing in
                            # for one. The kiosk needs to know that to prefer
                            # the colour catalog over "Silk+" (#3090).
                            "color_name_is_synthesized": mapped["color_name_is_synthesized"],
                            "rgba": mapped["rgba"],
                            # The kiosk paints the disc from these, as the
                            # Filament page does (#3033).
                            "extra_colors": mapped["extra_colors"],
                            "effect_type": mapped["effect_type"],
                            "brand": mapped["brand"],
                            "label_weight": mapped["label_weight"],
                            "core_weight": mapped["core_weight"],
                            "weight_used": mapped["weight_used"],
                        },
                    }
                )
                logger.info("SpoolBuddy tag matched (Spoolman): %s -> spool %d", req.tag_uid, mapped["id"])
                if tray_uuid:
                    await _backfill_spoolman_tray_uuid(client, sm_spool, req.tag_uid, tray_uuid)
                return {"status": "ok", "matched": True, "spool_id": mapped["id"]}
        except ValueError as exc:
            logger.error(
                "Spoolman returned malformed spool data during tag lookup for %s: %s",
                req.tag_uid,
                exc,
            )
            return {"status": "ok", "matched": False, "spool_id": None}
        except (httpx.RequestError, httpx.HTTPStatusError, SpoolmanUnavailableError):
            logger.warning(
                "Spoolman unreachable during tag lookup for %s",
                req.tag_uid,
            )
            # Broadcast a diagnostic event so the UI can surface "Spoolman down" to the user.
            # Use a distinct type from spoolbuddy_unknown_tag — Spoolman outage != unregistered spool.
            await ws_manager.broadcast(
                {
                    "type": "spoolman_unavailable",
                    "device_id": req.device_id,
                    "context": "nfc_tag_scanned",
                }
            )
            return {"status": "ok", "matched": False, "spool_id": None}
        except Exception as exc:
            logger.error(
                "Spoolman tag lookup failed unexpectedly for %s: %s",
                req.tag_uid,
                exc,
            )
            # Broadcast a distinct error event so operators can distinguish
            # "unexpected backend error" from "unregistered tag".
            await ws_manager.broadcast(
                {
                    "type": "spoolbuddy_lookup_error",
                    "device_id": req.device_id,
                }
            )
            # Same silent-return policy: an unexpected error must not break device operation
            # or trigger spurious duplicate-registration flows in the UI.
            return {"status": "ok", "matched": False, "spool_id": None}
    else:
        # Local mode — exclusive lookup, no Spoolman fallback.
        spool = await get_spool_by_tag(db, req.tag_uid, tray_uuid or "")
        if spool:
            await ws_manager.broadcast(
                {
                    "type": "spoolbuddy_tag_matched",
                    "device_id": req.device_id,
                    "tag_uid": req.tag_uid,
                    "tray_uuid": tray_uuid,
                    "spool": {
                        "id": spool.id,
                        "material": spool.material,
                        "subtype": spool.subtype,
                        "color_name": spool.color_name,
                        # Local inventory stores what the user or their tag
                        # set, and nothing else — never a stand-in (#3090).
                        "color_name_is_synthesized": False,
                        "rgba": spool.rgba,
                        "extra_colors": spool.extra_colors,
                        "effect_type": spool.effect_type,
                        "brand": spool.brand,
                        "label_weight": spool.label_weight,
                        "core_weight": spool.core_weight,
                        "weight_used": spool.weight_used,
                    },
                }
            )
            logger.info("SpoolBuddy tag matched (local): %s -> spool %d", req.tag_uid, spool.id)
            if tray_uuid:
                await _backfill_local_tray_uuid(db, spool, req.tag_uid, tray_uuid)
            return {"status": "ok", "matched": True, "spool_id": spool.id}

    await ws_manager.broadcast(
        {
            "type": "spoolbuddy_unknown_tag",
            "device_id": req.device_id,
            "tag_uid": req.tag_uid,
            "tray_uuid": tray_uuid,
            "sak": req.sak,
            "tag_type": req.tag_type,
        }
    )
    logger.info(
        "SpoolBuddy unknown tag: uid=%s (len=%d), tray_uuid=%s (len=%d), type=%s, sak=%s",
        req.tag_uid,
        len(req.tag_uid or ""),
        tray_uuid,
        len(tray_uuid or ""),
        req.tag_type,
        req.sak,
    )
    return {"status": "ok", "matched": False, "spool_id": None}


@router.post("/nfc/tag-removed")
async def nfc_tag_removed(
    req: TagRemovedRequest,
    _: User | None = RequirePermissionIfAuthEnabled(Permission.INVENTORY_UPDATE),
):
    """RPi reports NFC tag removed — broadcast event."""
    await ws_manager.broadcast(
        {
            "type": "spoolbuddy_tag_removed",
            "device_id": req.device_id,
            "tag_uid": req.tag_uid,
        }
    )
    return {"status": "ok"}


@router.post("/nfc/write-tag")
async def nfc_write_tag(
    req: WriteTagRequest,
    db: AsyncSession = Depends(get_db),
    _: User | None = RequirePermissionIfAuthEnabled(Permission.INVENTORY_UPDATE),
):
    """Queue an NFC tag write command for a SpoolBuddy device.

    The spool comes from the inventory in use: Spoolman when it is enabled,
    otherwise Bambuddy's own. Built-in spools are kept after switching to
    Spoolman, so one with the same id must not stand in for the Spoolman spool.
    """
    from backend.app.models.spool import Spool
    from backend.app.services.opentag3d import encode_opentag3d, encode_opentag3d_from_mapped

    # Find the device first (required regardless of spool source)
    result = await db.execute(select(SpoolBuddyDevice).where(SpoolBuddyDevice.device_id == req.device_id))
    device = result.scalar_one_or_none()
    if not device:
        raise HTTPException(status_code=404, detail="Device not registered")

    sm_client = await _get_spoolman_client_or_none(db)
    if sm_client is None and await _spoolman_mode(db):
        raise HTTPException(status_code=503, detail="Spoolman is unavailable")

    nfc_warnings: list[str] = []
    if sm_client is None:
        spool = (await db.execute(select(Spool).where(Spool.id == req.spool_id))).scalar_one_or_none()
        if spool is None:
            raise HTTPException(status_code=404, detail="Spool not found")
        ndef_data = encode_opentag3d(spool)
        data_origin = "local"
    else:
        from backend.app.api.routes._spoolman_helpers import _map_spoolman_spool

        async with _translate_spoolbuddy_errors():
            sm_spool = await sm_client.get_spool(req.spool_id)

        try:
            mapped = _map_spoolman_spool(sm_spool)
        except ValueError as exc:
            logger.warning("Spoolman returned invalid spool for write-tag: %s", exc)
            raise HTTPException(status_code=502, detail="Spoolman returned malformed spool data")

        if not mapped.get("material"):
            raise HTTPException(
                status_code=400,
                detail="Spoolman spool has no material set — cannot encode NFC tag",
            )

        # A Bambu spool created from the AMS is linked by its tray UUID in
        # extra.tag; a sticker would replace it there, and the next AMS sync,
        # no longer finding the spool, would create a duplicate (SM-C5). Not
        # when Spoolman also keeps that UUID as a native tag (0.27+): the sync
        # finds the spool by it first, and the sticker leaves it alone.
        from backend.app.api.routes._spoolman_helpers import _extract_extra_str

        extra_tag = _extract_extra_str(sm_spool.get("extra") or {}, "tag").strip().upper()
        native_uids = {str(t.get("uid", "")).upper() for t in sm_spool.get("tags") or [] if isinstance(t, dict)}
        if re.fullmatch(r"[0-9A-F]{32}", extra_tag) and extra_tag not in native_uids:
            raise HTTPException(
                status_code=409,
                detail="This spool is linked to its Bambu RFID tag through the AMS; "
                "a sticker would replace that link in Spoolman",
            )

        ndef_data = encode_opentag3d_from_mapped(mapped)
        data_origin = "spoolman"

        # Warn when fields that drive NFC content are absent in Spoolman.
        # The colour name is read the way the tag gets it: from the spool's
        # extra (where Bambuddy keeps it -- Spoolman's filament has no such
        # field, so checking that warned on every spool, SM-C6), else the
        # subtype stands in for it.
        if mapped.get("color_name") is None:
            nfc_warnings.append("color_name not set in Spoolman — tag encodes an empty color name")
        elif mapped.get("color_name_is_synthesized"):
            nfc_warnings.append(
                f"color_name not set in Spoolman — tag encodes the subtype ({mapped['color_name']}) as its color name"
            )
        if not mapped.get("nozzle_temp_min"):
            nfc_warnings.append("nozzle_temp_min not set in Spoolman — tag encodes 0 °C")
        if not mapped.get("subtype"):
            nfc_warnings.append("subtype not set in Spoolman — tag encodes empty subtype")
        if not mapped.get("brand"):
            nfc_warnings.append("brand/vendor not set in Spoolman — tag encodes empty brand")
        if not mapped.get("rgba"):
            nfc_warnings.append("rgba not set in Spoolman — tag encodes default colour")
        if not mapped.get("label_weight"):
            nfc_warnings.append("label_weight not set in Spoolman — tag encodes 0 g")
        if nfc_warnings:
            logger.warning(
                "NFC encode for Spoolman spool %d has incomplete data: %s",
                req.spool_id,
                "; ".join(nfc_warnings),
            )

    # Store write payload and set pending command
    device.pending_write_payload = json.dumps(
        {
            "spool_id": req.spool_id,
            "ndef_data_hex": ndef_data.hex(),
            "data_origin": data_origin,
        }
    )
    device.pending_command = "write_tag"
    await db.commit()

    logger.info(
        "Write tag queued for device %s, spool %d (%s, %d bytes)",
        req.device_id,
        req.spool_id,
        data_origin,
        len(ndef_data),
    )
    result: dict = {"status": "queued"}
    if nfc_warnings:
        result["warnings"] = nfc_warnings
    return result


@router.post("/nfc/write-result")
async def nfc_write_result(
    req: WriteTagResultRequest,
    db: AsyncSession = Depends(get_db),
    _: User | None = RequirePermissionIfAuthEnabled(Permission.INVENTORY_UPDATE),
):
    """Handle NFC tag write result from SpoolBuddy daemon."""
    # Find the device
    result = await db.execute(select(SpoolBuddyDevice).where(SpoolBuddyDevice.device_id == req.device_id))
    device = result.scalar_one_or_none()
    if not device:
        raise HTTPException(status_code=404, detail="Device not registered")

    # Capture data_origin before clearing the payload
    try:
        payload_dict = json.loads(device.pending_write_payload or "{}")
    except (json.JSONDecodeError, TypeError):
        payload_dict = {}
        logger.warning("Malformed pending_write_payload for device %s — treating as local", req.device_id)
    data_origin = payload_dict.get("data_origin", "local")

    device.pending_command = None
    device.pending_write_payload = None

    if req.success:
        if data_origin == "spoolman":
            # Update Spoolman extra.tag with the written NFC UID using a safe merge
            # (fetches current extra first to avoid overwriting other custom fields).
            sm_client = await _get_spoolman_client_or_none(db)
            if sm_client is None:
                logger.warning("Spoolman not configured; cannot persist tag link for spool %d", req.spool_id)
                await db.commit()
                await ws_manager.broadcast(
                    {
                        "type": "spoolbuddy_tag_link_failed",
                        "device_id": req.device_id,
                        "spool_id": req.spool_id,
                        "tag_uid": req.tag_uid,
                        "message": "Spoolman not configured",
                        "reason": "spoolman_not_configured",
                    }
                )
                raise HTTPException(
                    status_code=502,
                    detail="Tag written to NFC but Spoolman is not configured; link not persisted",
                )

            _tag_link_ok = False
            try:
                tag_value = json.dumps(req.tag_uid.upper())
                # Tag uniqueness: a single physical NFC UID must map to at most
                # one Spoolman spool, otherwise find_spool_by_tag returns
                # whichever spool comes first in the cached list (usually the
                # older one) and the dashboard shows the wrong spool when the
                # tag is scanned. Before binding the new owner, clear the tag
                # from any other spool that currently has it. Best-effort:
                # cleanup failure does not block the write itself, but the
                # warning surfaces in logs so a stale duplicate can be tracked
                # down manually.
                try:
                    cached_spools = await sm_client.get_spools()
                    duplicate = await sm_client.find_spool_by_tag(req.tag_uid, cached_spools=cached_spools)
                    if duplicate is not None and duplicate.get("id") != req.spool_id:
                        await sm_client.merge_spool_extra(int(duplicate["id"]), {"tag": ""})
                        logger.info(
                            "Spoolman: cleared tag %s from previous holder spool %d before binding to spool %d",
                            req.tag_uid,
                            duplicate["id"],
                            req.spool_id,
                        )
                except (SpoolmanNotFoundError, SpoolmanUnavailableError, SpoolmanClientError) as cleanup_exc:
                    logger.warning(
                        "Spoolman: failed to clear duplicate tag %s before binding to spool %d (proceeding anyway): %s",
                        req.tag_uid,
                        req.spool_id,
                        cleanup_exc,
                    )
                except Exception:
                    logger.exception(
                        "Spoolman: unexpected error clearing duplicate tag %s before binding to spool %d (proceeding anyway)",
                        req.tag_uid,
                        req.spool_id,
                    )

                # Spoolman 0.27+: the same tag as a native one. It was just written onto
                # this spool, so a previous holder gives it up here too. Linked before
                # extra.tag, as the step Spoolman can refuse; a failed extra.tag write
                # takes back what was added.
                uid = req.tag_uid.upper()
                added_native = False
                if await sm_client.has_tag_api():
                    before = await sm_client.get_spool(req.spool_id)
                    had = any(t.get("uid") == uid for t in before.get("tags") or [])
                    # A spool that already holds the tag has nothing to link or move.
                    if not had:
                        holder = await sm_client.link_native_tag(req.spool_id, uid)
                        if holder is not None and holder > 0:
                            previous = holder
                            await sm_client.unlink_native_tag(previous, uid)
                            holder = await sm_client.link_native_tag(req.spool_id, uid)
                            logger.info(
                                "Spoolman: native tag %s moved from spool %d to %d", uid, previous, req.spool_id
                            )
                        if holder is not None:
                            logger.warning("Native tag %s belongs to a filament or location, not linked", uid)
                        added_native = holder is None
                try:
                    await sm_client.merge_spool_extra(req.spool_id, {"tag": tag_value})
                except Exception:
                    if added_native:
                        try:
                            await sm_client.unlink_native_tag(req.spool_id, uid)
                        except (SpoolmanClientError, SpoolmanUnavailableError) as undo_exc:
                            logger.warning(
                                "Could not take back native tag %s from spool %d: %s", uid, req.spool_id, undo_exc
                            )
                    raise
                logger.info(
                    "Spoolman tag written and linked: spool %d -> tag %s",
                    req.spool_id,
                    req.tag_uid,
                )
                _tag_link_ok = True
            except (SpoolmanNotFoundError, SpoolmanUnavailableError, SpoolmanClientError) as exc:
                logger.error(
                    "Spoolman error during tag write-back for spool %d (type=%s, status=%s): %s",
                    req.spool_id,
                    type(exc).__name__,
                    getattr(exc, "status_code", "N/A"),
                    exc,
                )
                # fall through to broadcast + raise 502 below
            except Exception:
                logger.exception(
                    "Unexpected error during Spoolman tag write-back for spool %d",
                    req.spool_id,
                )
                # fall through to broadcast + raise 502 below

            await db.commit()
            if _tag_link_ok:
                await ws_manager.broadcast(
                    {
                        "type": "spoolbuddy_tag_written",
                        "device_id": req.device_id,
                        "spool_id": req.spool_id,
                        "tag_uid": req.tag_uid,
                    }
                )
            else:
                await ws_manager.broadcast(
                    {
                        "type": "spoolbuddy_tag_link_failed",
                        "device_id": req.device_id,
                        "spool_id": req.spool_id,
                        "tag_uid": req.tag_uid,
                        # Generic message — full exception (may contain internal URLs/hostnames)
                        # is logged server-side only to prevent information leakage via WebSocket.
                        "message": "Spoolman link failed",
                        "reason": "spoolman_link_failed",
                    }
                )
                raise HTTPException(
                    status_code=502,
                    detail="Tag written to NFC but Spoolman link failed",
                )
        else:
            # Link the tag to the local DB spool
            from backend.app.models.spool import Spool

            result = await db.execute(select(Spool).where(Spool.id == req.spool_id))
            spool = result.scalar_one_or_none()
            if spool is None:
                logger.warning(
                    "NFC tag written for spool %d but it no longer exists in local DB; tag is orphaned",
                    req.spool_id,
                )
                await db.commit()
                await ws_manager.broadcast(
                    {
                        "type": "spoolbuddy_tag_link_failed",
                        "device_id": req.device_id,
                        "spool_id": req.spool_id,
                        "message": "Spool not found",
                        "reason": "spool_not_found",
                    }
                )
                return {"status": "ok", "linked": False, "message": "Spool not found"}

            spool.tag_uid = req.tag_uid.upper()
            spool.tag_type = "ntag"
            spool.data_origin = "opentag3d"
            spool.encode_time = datetime.now(timezone.utc)
            logger.info("Tag written and linked: spool %d -> tag %s", spool.id, req.tag_uid)

            await db.commit()
            await ws_manager.broadcast(
                {
                    "type": "spoolbuddy_tag_written",
                    "device_id": req.device_id,
                    "spool_id": req.spool_id,
                    "tag_uid": req.tag_uid,
                }
            )
    else:
        await db.commit()
        await ws_manager.broadcast(
            {
                "type": "spoolbuddy_tag_write_failed",
                "device_id": req.device_id,
                "spool_id": req.spool_id,
                "message": req.message,
            }
        )
        logger.warning("Tag write failed for device %s: %s", req.device_id, req.message)

    return {"status": "ok"}


@router.post("/devices/{device_id}/cancel-write")
async def cancel_write(
    device_id: str,
    db: AsyncSession = Depends(get_db),
    _: User | None = RequirePermissionIfAuthEnabled(Permission.INVENTORY_UPDATE),
):
    """Cancel a pending write-tag command."""
    result = await db.execute(select(SpoolBuddyDevice).where(SpoolBuddyDevice.device_id == device_id))
    device = result.scalar_one_or_none()
    if not device:
        raise HTTPException(status_code=404, detail="Device not registered")

    if device.pending_command == "write_tag":
        device.pending_command = None
        device.pending_write_payload = None
        await db.commit()
        logger.info("Write tag cancelled for device %s", device_id)

    return {"status": "ok"}


# --- Scale endpoints ---


@router.post("/scale/reading")
async def scale_reading(
    req: ScaleReadingRequest,
    _: User | None = RequirePermissionIfAuthEnabled(Permission.INVENTORY_UPDATE),
):
    """RPi reports scale weight — broadcast to all clients."""
    await ws_manager.broadcast(
        {
            "type": "spoolbuddy_weight",
            "device_id": req.device_id,
            "weight_grams": req.weight_grams,
            "stable": req.stable,
            "raw_adc": req.raw_adc,
        }
    )
    return {"status": "ok"}


@router.post("/scale/update-spool-weight")
async def update_spool_weight(
    req: UpdateSpoolWeightRequest,
    db: AsyncSession = Depends(get_db),
    _: User | None = RequirePermissionIfAuthEnabled(Permission.INVENTORY_UPDATE),
):
    """Update spool's used weight from scale reading.

    Routes the update to whichever inventory backend Bambuddy is configured
    for: Spoolman exclusively when ``spoolman_enabled`` is true, local DB
    exclusively otherwise. The previous implementation tried local first and
    only consulted Spoolman on a local-DB miss, which meant a stale local row
    sharing a numeric id with a Spoolman spool would silently absorb the
    update while the Spoolman row the user is actually looking at stayed
    unchanged (#1530). Mirrors the routing already used by ``nfc/tag-scanned``.
    """
    from backend.app.api.routes._spoolman_helpers import _safe_float, spoolman_net_weight, spoolman_tare
    from backend.app.models.spool import Spool

    sm_client = await _get_spoolman_client_or_none(db)
    if sm_client is None and await _spoolman_mode(db):
        raise HTTPException(status_code=503, detail="Spoolman is unavailable")

    if sm_client is None:
        # Local mode — exclusive update, no Spoolman fallback.
        db_result = await db.execute(select(Spool).where(Spool.id == req.spool_id))
        spool = db_result.scalar_one_or_none()
        if not spool:
            raise HTTPException(status_code=404, detail="Spool not found")

        net_filament = max(0, req.weight_grams - spool.core_weight)
        spool.weight_used = max(0, spool.label_weight - net_filament)
        spool.last_scale_weight = req.weight_grams
        spool.last_weighed_at = datetime.now(timezone.utc)
        # A measured figure, which the AMS remain% sync must not overwrite
        # (as a hand-set one, see update_spool).
        spool.weight_locked = True
        await db.commit()
        await ws_manager.broadcast({"type": "inventory_changed"})
        logger.info(
            "SpoolBuddy updated spool %d weight: %.1fg on scale, %.1fg used",
            spool.id,
            req.weight_grams,
            spool.weight_used,
        )
        return {"status": "ok", "weight_used": spool.weight_used}

    # Spoolman mode — exclusive update, never touch local DB.
    async with _translate_spoolbuddy_errors():
        sm_spool = await sm_client.get_spool(req.spool_id)

    core_weight, tare_source = spoolman_tare(sm_spool)
    spool_weight_warning: str | None = None
    if tare_source == "fallback":
        logger.warning(
            "Spoolman spool %d has no spool_weight or vendor empty_spool_weight set; using 250g fallback for tare",
            req.spool_id,
        )
        spool_weight_warning = (
            "spool_weight_not_set: Spoolman spool, filament and vendor have no empty-spool weight configured; "
            "weight estimate uses 250g fallback"
        )
    label_weight = _safe_float(spoolman_net_weight(sm_spool), 1000.0)
    remaining_weight = max(0.0, req.weight_grams - core_weight)

    async with _translate_spoolbuddy_errors():
        await sm_client.update_spool(spool_id=req.spool_id, remaining_weight=remaining_weight)
    await ws_manager.broadcast({"type": "inventory_changed"})

    weight_used = max(0.0, label_weight - remaining_weight)
    logger.info(
        "SpoolBuddy updated Spoolman spool %d: %.1fg on scale, core=%.1fg → %.1fg remaining",
        req.spool_id,
        req.weight_grams,
        core_weight,
        remaining_weight,
    )
    result: dict = {"status": "ok", "weight_used": weight_used}
    if spool_weight_warning:
        result["warnings"] = [spool_weight_warning]
    return result


# --- Calibration endpoints ---


@router.post("/devices/{device_id}/calibration/tare")
async def tare_scale(
    device_id: str,
    db: AsyncSession = Depends(get_db),
    _: User | None = RequirePermissionIfAuthEnabled(Permission.INVENTORY_UPDATE),
):
    """Set pending tare command for the device to pick up."""
    result = await db.execute(select(SpoolBuddyDevice).where(SpoolBuddyDevice.device_id == device_id))
    device = result.scalar_one_or_none()
    if not device:
        raise HTTPException(status_code=404, detail="Device not registered")

    device.pending_command = "tare"
    await db.commit()
    return {"status": "ok", "message": "Tare command queued"}


@router.post("/devices/{device_id}/calibration/set-tare")
async def set_tare_offset(
    device_id: str,
    req: SetTareRequest,
    db: AsyncSession = Depends(get_db),
    _: User | None = RequirePermissionIfAuthEnabled(Permission.INVENTORY_UPDATE),
):
    """Store tare offset reported by the daemon after executing a tare."""
    result = await db.execute(select(SpoolBuddyDevice).where(SpoolBuddyDevice.device_id == device_id))
    device = result.scalar_one_or_none()
    if not device:
        raise HTTPException(status_code=404, detail="Device not registered")

    device.tare_offset = req.tare_offset
    device.last_calibrated_at = datetime.now(timezone.utc)
    await db.commit()

    logger.info("SpoolBuddy %s tare offset set to %d", device_id, req.tare_offset)
    return CalibrationResponse(
        tare_offset=device.tare_offset,
        calibration_factor=device.calibration_factor,
    )


@router.post("/devices/{device_id}/calibration/set-factor")
async def set_calibration_factor(
    device_id: str,
    req: SetCalibrationFactorRequest,
    db: AsyncSession = Depends(get_db),
    _: User | None = RequirePermissionIfAuthEnabled(Permission.INVENTORY_UPDATE),
):
    """Calculate and store calibration factor from a known weight."""
    result = await db.execute(select(SpoolBuddyDevice).where(SpoolBuddyDevice.device_id == device_id))
    device = result.scalar_one_or_none()
    if not device:
        raise HTTPException(status_code=404, detail="Device not registered")

    tare = req.tare_raw_adc if req.tare_raw_adc is not None else device.tare_offset
    raw_delta = req.raw_adc - tare
    if raw_delta == 0:
        raise HTTPException(status_code=400, detail="Raw ADC value equals tare offset — place weight on scale")

    device.calibration_factor = req.known_weight_grams / raw_delta
    if req.tare_raw_adc is not None:
        device.tare_offset = tare
    device.last_calibrated_at = datetime.now(timezone.utc)
    await db.commit()

    logger.info(
        "SpoolBuddy %s calibration factor set to %.6f (known=%.1fg, raw=%d, tare=%d)",
        device_id,
        device.calibration_factor,
        req.known_weight_grams,
        req.raw_adc,
        tare,
    )
    return CalibrationResponse(
        tare_offset=device.tare_offset,
        calibration_factor=device.calibration_factor,
    )


@router.get("/devices/{device_id}/calibration", response_model=CalibrationResponse)
async def get_calibration(
    device_id: str,
    db: AsyncSession = Depends(get_db),
    _: User | None = RequirePermissionIfAuthEnabled(Permission.INVENTORY_READ),
):
    """Get current calibration values for a device."""
    result = await db.execute(select(SpoolBuddyDevice).where(SpoolBuddyDevice.device_id == device_id))
    device = result.scalar_one_or_none()
    if not device:
        raise HTTPException(status_code=404, detail="Device not registered")

    return CalibrationResponse(
        tare_offset=device.tare_offset,
        calibration_factor=device.calibration_factor,
    )


# --- Display settings ---


@router.get("/devices/{device_id}/display")
async def get_display_settings(
    device_id: str,
    db: AsyncSession = Depends(get_db),
    _: User | None = RequirePermissionIfAuthEnabled(Permission.INVENTORY_UPDATE),
):
    """Read current display brightness and screen blank timeout for a device.

    Used by the SpoolBuddy kiosk idle watchdog on autostart to configure
    swayidle with the same timeout the user picked in the UI, without having
    to wait for the daemon heartbeat to arrive first.
    """
    result = await db.execute(select(SpoolBuddyDevice).where(SpoolBuddyDevice.device_id == device_id))
    device = result.scalar_one_or_none()
    if not device:
        raise HTTPException(status_code=404, detail="Device not registered")
    return {
        "brightness": device.display_brightness,
        "blank_timeout": device.display_blank_timeout,
    }


@router.put("/devices/{device_id}/display")
async def update_display_settings(
    device_id: str,
    req: DisplaySettingsRequest,
    db: AsyncSession = Depends(get_db),
    _: User | None = RequirePermissionIfAuthEnabled(Permission.INVENTORY_UPDATE),
):
    """Update display brightness and screen blank timeout for a device."""
    result = await db.execute(select(SpoolBuddyDevice).where(SpoolBuddyDevice.device_id == device_id))
    device = result.scalar_one_or_none()
    if not device:
        raise HTTPException(status_code=404, detail="Device not registered")

    device.display_brightness = req.brightness
    device.display_blank_timeout = req.blank_timeout
    await db.commit()

    logger.info(
        "SpoolBuddy %s display updated: brightness=%d%%, blank_timeout=%ds",
        device_id,
        req.brightness,
        req.blank_timeout,
    )
    return {"status": "ok", "brightness": req.brightness, "blank_timeout": req.blank_timeout}


@router.post("/devices/{device_id}/system/config")
async def queue_system_config_update(
    device_id: str,
    req: SystemConfigRequest,
    db: AsyncSession = Depends(get_db),
    _: User | None = RequirePermissionIfAuthEnabled(Permission.INVENTORY_UPDATE),
):
    """Queue update of SpoolBuddy .env config on the device."""
    result = await db.execute(select(SpoolBuddyDevice).where(SpoolBuddyDevice.device_id == device_id))
    device = result.scalar_one_or_none()
    if not device:
        raise HTTPException(status_code=404, detail="Device not registered")

    parsed = urlparse(req.backend_url.strip())
    if parsed.scheme not in ("http", "https") or not parsed.netloc:
        raise HTTPException(
            status_code=400,
            detail="backend_url must be a full URL with scheme, e.g. http://192.168.1.100:5000 or http://bambuddy.local",
        )

    payload = {
        "backend_url": req.backend_url.strip(),
    }
    if req.api_key is not None and req.api_key.strip():
        payload["api_key"] = req.api_key.strip()

    device.pending_system_payload = json.dumps(payload)
    device.pending_command = "apply_system_config"
    await db.commit()

    logger.info("Queued system config update for device %s", device_id)
    return {"status": "queued", "message": "System config update queued"}


VALID_SYSTEM_COMMANDS = {"reboot", "shutdown", "restart_daemon", "restart_browser"}


@router.post("/devices/{device_id}/system/command")
async def queue_system_command(
    device_id: str,
    req: SystemCommandRequest,
    db: AsyncSession = Depends(get_db),
    # Aligns with the rest of the kiosk-scoped device routes (calibration,
    # display, cancel-write, command-result — all INVENTORY_UPDATE). The
    # previous SETTINGS_UPDATE gate locked operators out of the QuickMenu's
    # Restart-Daemon / Restart-Browser / Reboot / Shutdown buttons even
    # though they had access to every other operation on the same device.
    # Reboot and shutdown remain recoverable via physical access — the
    # operator already has the kiosk in front of them.
    _: User | None = RequirePermissionIfAuthEnabled(Permission.INVENTORY_UPDATE),
):
    """Queue a system command (reboot, shutdown, restart_daemon, restart_browser) for the SpoolBuddy device."""
    if req.command not in VALID_SYSTEM_COMMANDS:
        raise HTTPException(
            status_code=400,
            detail=f"Invalid command. Must be one of: {', '.join(sorted(VALID_SYSTEM_COMMANDS))}",
        )

    result = await db.execute(select(SpoolBuddyDevice).where(SpoolBuddyDevice.device_id == device_id))
    device = result.scalar_one_or_none()
    if not device:
        raise HTTPException(status_code=404, detail="Device not registered")

    if not _is_online(device):
        raise HTTPException(status_code=409, detail="Device is offline")

    device.pending_command = req.command
    await db.commit()

    logger.info("System command queued for device %s: %s", device_id, req.command)
    return {"status": "queued", "command": req.command}


@router.post("/devices/{device_id}/system/command-result")
async def system_command_result(
    device_id: str,
    req: SystemCommandResultRequest,
    db: AsyncSession = Depends(get_db),
    _: User | None = RequirePermissionIfAuthEnabled(Permission.INVENTORY_UPDATE),
):
    """Receive completion status for queued system command from daemon."""
    result = await db.execute(select(SpoolBuddyDevice).where(SpoolBuddyDevice.device_id == device_id))
    device = result.scalar_one_or_none()
    if not device:
        raise HTTPException(status_code=404, detail="Device not registered")

    if not device.pending_command:
        logger.info("System command result from %s with no pending command: %s", device_id, req.command)
        return {"status": "ok", "message": "No pending command"}

    if req.command != device.pending_command:
        raise HTTPException(
            status_code=409,
            detail=f"Command mismatch: pending '{device.pending_command}', got '{req.command}'",
        )

    if req.command == "apply_system_config":
        device.pending_system_payload = None
    device.pending_command = None
    await db.commit()

    logger.info(
        "System command result from %s: %s success=%s message=%s",
        device_id,
        req.command,
        req.success,
        req.message,
    )
    return {"status": "ok"}


# --- Diagnostics ---


@router.post("/diagnostics/{device_id}/run")
async def queue_diagnostic(
    device_id: str,
    diagnostic: str,
    db: AsyncSession = Depends(get_db),
    _: User | None = RequirePermissionIfAuthEnabled(Permission.INVENTORY_UPDATE),
):
    """Queue a hardware diagnostic to run on the SpoolBuddy device.

    Args:
        device_id: The device ID
        diagnostic: 'scale' or 'nfc' to select which diagnostic to run

    Returns:
        Status message indicating diagnostic was queued
    """
    if diagnostic not in ("scale", "nfc", "read_tag"):
        raise HTTPException(status_code=400, detail="Unknown diagnostic. Must be 'scale', 'nfc', or 'read_tag'")

    result = await db.execute(select(SpoolBuddyDevice).where(SpoolBuddyDevice.device_id == device_id))
    device = result.scalar_one_or_none()
    if not device:
        raise HTTPException(status_code=404, detail="Device not registered")

    device.pending_command = f"run_{diagnostic}_diag"
    _diagnostic_results.pop((device_id, diagnostic), None)
    await db.commit()

    logger.info("Diagnostic queued for device %s: %s", device_id, diagnostic)
    return {"status": "queued", "diagnostic": diagnostic, "message": f"Diagnostic '{diagnostic}' queued for device"}


@router.get("/diagnostics/{device_id}/result")
async def get_diagnostic_result(
    device_id: str,
    diagnostic: str,
    db: AsyncSession = Depends(get_db),
    _: User | None = RequirePermissionIfAuthEnabled(Permission.INVENTORY_READ),
):
    """Get the latest diagnostic result for a device.

    Args:
        device_id: The device ID
        diagnostic: 'scale' or 'nfc'

    Returns:
        Diagnostic result or 404 if not found
    """
    if diagnostic not in ("scale", "nfc", "read_tag"):
        raise HTTPException(status_code=400, detail="Unknown diagnostic. Must be 'scale', 'nfc', or 'read_tag'")

    result = await db.execute(select(SpoolBuddyDevice).where(SpoolBuddyDevice.device_id == device_id))
    device = result.scalar_one_or_none()
    if not device:
        raise HTTPException(status_code=404, detail="Device not registered")

    diag_result = _diagnostic_results.get((device_id, diagnostic))
    if not diag_result:
        raise HTTPException(status_code=404, detail=f"No {diagnostic} diagnostic results available yet")
    return diag_result


@router.post("/diagnostics/{device_id}/result")
async def report_diagnostic_result(
    device_id: str,
    req: DiagnosticResultRequest,
    db: AsyncSession = Depends(get_db),
    _: User | None = RequirePermissionIfAuthEnabled(Permission.INVENTORY_UPDATE),
):
    """Report diagnostic result from SpoolBuddy device."""
    result = await db.execute(select(SpoolBuddyDevice).where(SpoolBuddyDevice.device_id == device_id))
    device = result.scalar_one_or_none()
    if not device:
        raise HTTPException(status_code=404, detail="Device not registered")

    if req.diagnostic not in ("nfc", "scale", "read_tag"):
        raise HTTPException(status_code=400, detail="Unknown diagnostic. Must be 'scale', 'nfc', or 'read_tag'")

    _diagnostic_results[(device_id, req.diagnostic)] = {
        "diagnostic": req.diagnostic,
        "success": req.success,
        "output": req.output,
        "exit_code": req.exit_code,
    }

    device.pending_command = None
    await db.commit()

    logger.info("Diagnostic result received for device %s: %s (success=%s)", device_id, req.diagnostic, req.success)
    return {"status": "ok", "message": "Diagnostic result recorded"}


# --- Update check ---


@router.get("/devices/{device_id}/update-check")
async def check_daemon_update(
    device_id: str,
    db: AsyncSession = Depends(get_db),
    _: User | None = RequirePermissionIfAuthEnabled(Permission.INVENTORY_READ),
):
    """Check if the SpoolBuddy daemon needs updating to match the Bambuddy backend version."""
    from backend.app.api.routes.updates import is_newer_version
    from backend.app.core.config import APP_VERSION

    result = await db.execute(select(SpoolBuddyDevice).where(SpoolBuddyDevice.device_id == device_id))
    device = result.scalar_one_or_none()
    if not device:
        raise HTTPException(status_code=404, detail="Device not registered")

    current = device.firmware_version or "0.0.0"

    return {
        "current_version": current,
        "latest_version": APP_VERSION,
        "update_available": is_newer_version(APP_VERSION, current),
    }


@router.post("/devices/{device_id}/update")
async def trigger_daemon_update(
    device_id: str,
    req: dict | None = None,
    db: AsyncSession = Depends(get_db),
    # Aligns with the rest of the kiosk-scoped device routes (calibration,
    # display, cancel-write, system/command — all INVENTORY_UPDATE).
    # SETTINGS_UPDATE is on the API-key deny-list, which blocks the Update
    # button from the kiosk's own Settings page even when the operator has
    # physical access. Update only acts on the device the operator already
    # controls (git fetch + pip install + systemctl restart on that one
    # host) — same blast radius as the restart_daemon command.
    _: User | None = RequirePermissionIfAuthEnabled(Permission.INVENTORY_UPDATE),
):
    """Trigger a SpoolBuddy update over SSH.

    Bambuddy SSHes into the device, pulls the matching branch, installs deps,
    and restarts the daemon. Progress is broadcast via WebSocket.
    """
    from backend.app.services.spoolbuddy_ssh import perform_ssh_update

    result = await db.execute(select(SpoolBuddyDevice).where(SpoolBuddyDevice.device_id == device_id))
    device = result.scalar_one_or_none()
    if not device:
        raise HTTPException(status_code=404, detail="Device not registered")

    if not _is_online(device):
        raise HTTPException(status_code=409, detail="Device is offline")

    if device.update_status == "updating":
        return {"status": "already_updating", "message": "Update already in progress"}

    device.update_status = "pending"
    device.update_message = "Starting SSH update..."
    await db.commit()

    logger.info("SpoolBuddy %s: SSH update triggered (ip=%s)", device_id, device.ip_address)
    await ws_manager.broadcast(
        {
            "type": "spoolbuddy_update",
            "device_id": device_id,
            "update_status": "pending",
        }
    )

    # Run the SSH update in the background — hold reference to prevent GC cancellation
    _ssh_update_task = asyncio.create_task(perform_ssh_update(device_id, device.ip_address))
    _ssh_update_task.add_done_callback(
        lambda t: (
            logger.error(
                "SSH update task for device %s ended unexpectedly (cancelled=%s)",
                device_id,
                t.cancelled(),
            )
            if (t.cancelled() or t.exception() is not None)
            else None
        )
    )

    return {"status": "ok", "message": "SSH update started"}


@router.get("/ssh/public-key")
async def get_ssh_public_key(
    _: User | None = RequirePermissionIfAuthEnabled(Permission.SETTINGS_READ),
):
    """Return the SSH public key for SpoolBuddy pairing."""
    from backend.app.services.spoolbuddy_ssh import get_public_key

    try:
        key = await get_public_key()
        return {"public_key": key}
    except Exception as e:
        logger.error("Failed to get SSH public key: %s", e)
        raise HTTPException(status_code=500, detail="Failed to retrieve SSH public key") from e


# --- Background watchdog ---


async def spoolbuddy_watchdog():
    """Check for devices that have gone offline (no heartbeat for 30s).

    Called periodically from the main app's background task loop.
    """
    from backend.app.core.database import async_session

    async with async_session() as db:
        result = await db.execute(select(SpoolBuddyDevice).where(SpoolBuddyDevice.last_seen.isnot(None)))
        devices = list(result.scalars().all())

        threshold = datetime.now(timezone.utc) - timedelta(seconds=OFFLINE_THRESHOLD_SECONDS)
        for device in devices:
            last_seen = device.last_seen.replace(tzinfo=timezone.utc) if device.last_seen else None
            if last_seen and last_seen < threshold:
                # Only broadcast once — clear last_seen after marking offline
                await ws_manager.broadcast(
                    {
                        "type": "spoolbuddy_offline",
                        "device_id": device.device_id,
                    }
                )
                device.last_seen = None
                logger.info("SpoolBuddy device offline: %s", device.device_id)

        await db.commit()