pqAutomationApp/drivers/ucd_driver.py

"""UCD 驱动层。

唯一暴露给上层的入口为 :class:`IUcdDevice` 抽象接口，以及实现：
:class:`UCD323Device`（生产）和 :class:`FakeUcdDevice`（单测）。

实现策略
--------
:class:`UCD323Device` 对外暴露完整的 :class:`IUcdDevice` 接口；SDK 调用
当前仍委托给 :class:`drivers.UCD323_Function.UCDController`。
上层（Service / GUI）**不得**直接访问 ``UCDController``。
后续可将 SDK 调用逐步迁入本模块并删除旧文件。

文件分区：
    §1 DeviceInfo / list_devices
    §2 IUcdDevice 抽象接口
    §3 UCD323Device 真实实现
    §4 FakeUcdDevice 单测实现
"""

from __future__ import annotations

from contextlib import contextmanager
import logging
import threading
from abc import ABC, abstractmethod
from dataclasses import dataclass
from typing import TYPE_CHECKING

from app.ucd_domain import (
    ConnectionChanged,
    EventBus,
    Interface,
    PatternApplied,
    PatternKind,
    PatternSpec,
    SignalApplied,
    SignalFormat,
    TimingSpec,
    UcdApplyFailed,
    UcdConfigError,
    UcdNotConnected,
    UcdSdkError,
    UcdState,
    UcdStateError,
    assert_transition,
)

if TYPE_CHECKING:
    from drivers.UCD323_Function import UCDController

log = logging.getLogger(__name__)

_DEVICE_LOCK_TIMEOUT_SECONDS = 8.0


# ─── §1 DeviceInfo / list_devices ────────────────────────────────


@dataclass(frozen=True)
class DeviceInfo:
    """UCD 设备发现条目。

    ``display`` 是 SDK 给出的完整字符串（``"0: UCD-323 #12345678"``）；
    ``index`` / ``serial`` / ``model`` 通过解析得到，解析失败时为 None。
    """

    display: str
    index: int | None = None
    serial: str | None = None
    model: str | None = None

    @classmethod
    def parse(cls, display: str) -> "DeviceInfo":
        idx: int | None = None
        model: str | None = None
        serial: str | None = None
        try:
            head, rest = display.split(":", 1)
            idx = int(head.strip())
            rest = rest.strip()
            # 形如 "UCD-323 #12345678" 或 "UCD-323 #12345678 (in use)"
            tokens = rest.split()
            if tokens:
                model = tokens[0]
            for tok in tokens[1:]:
                if tok.startswith("#") and len(tok) >= 2:
                    serial = tok.lstrip("#")
                    break
        except Exception:  # noqa: BLE001 - 解析失败保留原 display 即可
            pass
        return cls(display=display, index=idx, serial=serial, model=model)


def list_devices(controller: "UCDController") -> list[DeviceInfo]:
    """通过给定的底层 controller 枚举可用 UCD 设备。"""
    try:
        raw_list = controller.search_device()
    except Exception as exc:  # noqa: BLE001
        raise UcdSdkError("枚举 UCD 设备失败") from exc
    return [DeviceInfo.parse(s) for s in (raw_list or [])]


# ─── §2 IUcdDevice 抽象接口 ──────────────────────────────────────


class IUcdDevice(ABC):
    """UCD 信号发生器抽象设备。

    上层（Service / GUI）**只**通过本接口操作硬件，不得穿透到
    UniTAP SDK 或具体实现细节。
    """

    @property
    @abstractmethod
    def state(self) -> UcdState: ...

    @property
    @abstractmethod
    def info(self) -> DeviceInfo | None: ...

    @abstractmethod
    def open(self, info: DeviceInfo, *, interface: Interface = Interface.HDMI) -> None:
        """打开设备并选择接口角色。失败抛 :class:`UcdSdkError` 等。"""

    @abstractmethod
    def close(self) -> None:
        """关闭设备（幂等）。"""

    @abstractmethod
    def configure(self, signal: SignalFormat, timing: TimingSpec) -> bool:
        """写入信号格式与 timing（未 apply）。返回 ``format_changed``。"""

    @abstractmethod
    def set_pattern(self, pattern: PatternSpec) -> None:
        """设置当前图案（未 apply）。"""

    @abstractmethod
    def apply(self) -> None:
        """将已配置的信号格式 + 图案一次性提交给硬件。"""

    @abstractmethod
    def current_resolution(self) -> tuple[int, int]:
        """读取当前 timing 的 (width, height)；未连接时返回默认 (3840, 2160)。"""

    @abstractmethod
    def search_devices(self) -> list[str]:
        """枚举可用设备的 SDK 显示字符串列表。"""

    @property
    @abstractmethod
    def format_changed(self) -> bool:
        """最近一次视频模式提交是否相对上次发生变化。"""

    @property
    @abstractmethod
    def last_error(self) -> str | None:
        """最近一次配置/应用失败时的错误描述。"""

    @abstractmethod
    def apply_signal_format(
        self,
        *,
        color_space: str | None = None,
        data_range: str | None = None,
        bit_depth: str | None = None,
        color_format: str | None = None,
        max_cll: int | None = None,
        max_fall: int | None = None,
    ) -> bool:
        """仅更新信号格式（沿用当前 timing），不切换图案。"""

    @abstractmethod
    def set_ucd_params(self, config) -> bool:
        """按 PQConfig stage 色彩 / Timing / Pattern 类型（不 apply 输出）。"""

    @abstractmethod
    def send_current_pattern_params(self, pattern_params) -> bool:
        """更新当前 pattern 参数并 apply 到硬件。"""

    @abstractmethod
    def apply_config_and_run(self, config, pattern_params) -> bool:
        """set_ucd_params + set_pattern + run 复合操作。"""


# ─── §3 UCD323Device 真实实现 ────────────────────────────────────


class UCD323Device(IUcdDevice):
    """生产环境实现。内部委托给传统 :class:`UCDController`（Phase 1）。"""

    def __init__(self, bus: EventBus, controller: "UCDController | None" = None):
        from drivers.UCD323_Function import UCDController as _UCDController

        self._bus = bus
        self._controller: "UCDController" = controller or _UCDController()
        self._state: UcdState = UcdState.CLOSED
        self._info: DeviceInfo | None = None
        self._interface: Interface = Interface.HDMI
        self._lock = threading.RLock()
        self._lock_owner_tid: int | None = None
        self._lock_owner_name: str | None = None

        self._curr_signal: SignalFormat | None = None
        self._curr_timing: TimingSpec | None = None
        self._curr_pattern: PatternSpec | None = None
        self._last_applied: tuple[SignalFormat, TimingSpec] | None = None

    @contextmanager
    def _acquire_device_lock(self, op_name: str):
        current = threading.current_thread()
        log.info(
            "UCD323Device.%s acquiring lock timeout=%.1fs tid=%s thread=%s owner_tid=%s owner_thread=%s",
            op_name,
            _DEVICE_LOCK_TIMEOUT_SECONDS,
            threading.get_ident(),
            current.name,
            self._lock_owner_tid,
            self._lock_owner_name,
        )
        acquired = self._lock.acquire(timeout=_DEVICE_LOCK_TIMEOUT_SECONDS)
        if not acquired:
            raise UcdStateError(
                "UCD device busy: lock timeout in "
                f"UCD323Device.{op_name}, "
                f"owner_tid={self._lock_owner_tid}, owner_thread={self._lock_owner_name}"
            )
        prev_owner_tid = self._lock_owner_tid
        prev_owner_name = self._lock_owner_name
        self._lock_owner_tid = threading.get_ident()
        self._lock_owner_name = current.name
        log.info(
            "UCD323Device.%s lock acquired tid=%s thread=%s",
            op_name,
            self._lock_owner_tid,
            self._lock_owner_name,
        )
        try:
            yield
        finally:
            self._lock_owner_tid = prev_owner_tid
            self._lock_owner_name = prev_owner_name
            self._lock.release()

    # -- 读访问 --------------------------------------------------

    @property
    def state(self) -> UcdState:
        return self._state

    @property
    def info(self) -> DeviceInfo | None:
        return self._info

    # -- 生命周期 ------------------------------------------------

    def open(self, info: DeviceInfo, *, interface: Interface = Interface.HDMI) -> None:
        with self._acquire_device_lock("open"):
            assert_transition(self._state, UcdState.OPENED)
            if interface is not Interface.HDMI:
                # Phase 1：底层 UCDController.open() 写死了 HDMISource。
                raise UcdConfigError(
                    f"暂不支持接口 {interface.value}；当前仅实现 HDMI"
                )
            try:
                ok = self._controller.open(info.display)
            except Exception as exc:  # noqa: BLE001
                raise UcdSdkError(f"打开设备失败: {info.display}") from exc
            if not ok:
                raise UcdSdkError(f"打开设备失败: {info.display}")
            self._info = info
            self._interface = interface
            self._state = UcdState.OPENED
            self._bus.publish(ConnectionChanged(True, info.serial))

    def close(self) -> None:
        with self._acquire_device_lock("close"):
            if self._state == UcdState.CLOSED:
                return
            try:
                self._controller.close()
            except Exception:  # noqa: BLE001
                log.exception("关闭 UCD 时发生异常")
            self._state = UcdState.CLOSED
            self._curr_signal = None
            self._curr_timing = None
            self._curr_pattern = None
            self._last_applied = None
            prev_serial = self._info.serial if self._info else None
            self._info = None
            self._bus.publish(ConnectionChanged(False, prev_serial))

    # -- 配置 ----------------------------------------------------

    def configure(self, signal: SignalFormat, timing: TimingSpec) -> bool:
        with self._acquire_device_lock("configure"):
            if self._state == UcdState.CLOSED:
                raise UcdNotConnected("UCD 未连接，无法 configure")
            try:
                # 颜色模式（color_format / bpc / colorimetry）
                if not self._controller.set_color_mode(
                    signal.color_format.value,
                    int(signal.bpc),
                    _colorimetry_to_legacy_key(signal),
                ):
                    raise UcdConfigError(
                        f"set_color_mode 失败: {signal!r}"
                    )
                # dynamic_range 在新接口中是一等公民
                self._apply_dynamic_range(signal)

                # Timing
                if not self._controller.set_timing_from_string(str(timing)):
                    raise UcdConfigError(f"set_timing_from_string 失败: {timing}")
            except UcdConfigError:
                raise
            except Exception as exc:  # noqa: BLE001
                raise UcdSdkError("configure 异常") from exc

            self._curr_signal = signal
            self._curr_timing = timing
            self._state = UcdState.CONFIGURED
            return (signal, timing) != self._last_applied

    def set_pattern(self, pattern: PatternSpec) -> None:
        with self._acquire_device_lock("set_pattern"):
            # Phase 2 过渡：允许从 OPENED 直接 set_pattern——遗留路径
            # （test_runner 等）通过旧 controller.apply_signal_format 写入
            # 信号格式，未经过本设备的 configure。此时 self._state 仍为
            # OPENED，但硬件实际已处于可接收 pattern 状态。
            if self._state == UcdState.CLOSED:
                raise UcdNotConnected("UCD 未连接，无法 set_pattern")
            self._curr_pattern = pattern
            # 仅本地暂存，真正写硬件在 apply()

    def apply(self) -> None:
        with self._acquire_device_lock("apply"):
            if self._state == UcdState.CLOSED:
                raise UcdNotConnected("UCD 未连接，无法 apply")
            if self._curr_pattern is None:
                raise UcdStateError("apply 前必须先 set_pattern")
            try:
                ok = self._apply_pattern_via_controller(self._curr_pattern)
            except Exception as exc:  # noqa: BLE001
                raise UcdSdkError(
                    f"apply 异常: {type(exc).__name__}: {exc}"
                ) from exc
            if not ok:
                raise UcdApplyFailed(
                    f"apply 失败: pattern={self._curr_pattern.kind.value}"
                )

            # SignalApplied 事件仅在通过新 API configure 过时发出；
            # 遗留路径下 self._curr_signal/_curr_timing 可能为 None。
            if self._curr_signal is not None and self._curr_timing is not None:
                changed = (self._curr_signal, self._curr_timing) != self._last_applied
                self._last_applied = (self._curr_signal, self._curr_timing)
                self._bus.publish(
                    SignalApplied(self._curr_signal, self._curr_timing, changed)
                )
            self._state = UcdState.APPLIED
            self._bus.publish(PatternApplied(self._curr_pattern))

    # -- 查询 ----------------------------------------------------

    def current_resolution(self) -> tuple[int, int]:
        try:
            return self._controller.get_current_resolution((3840, 2160))
        except Exception:  # noqa: BLE001
            return (3840, 2160)

    def search_devices(self) -> list[str]:
        try:
            return self._controller.search_device() or []
        except Exception as exc:  # noqa: BLE001
            raise UcdSdkError("枚举 UCD 设备失败") from exc

    @property
    def format_changed(self) -> bool:
        return bool(getattr(self._controller, "format_changed", True))

    @property
    def last_error(self) -> str | None:
        err = getattr(self._controller, "last_error", None)
        return str(err) if err else None

    def apply_signal_format(
        self,
        *,
        color_space: str | None = None,
        data_range: str | None = None,
        bit_depth: str | None = None,
        color_format: str | None = None,
        max_cll: int | None = None,
        max_fall: int | None = None,
    ) -> bool:
        with self._acquire_device_lock("apply_signal_format"):
            if self._state == UcdState.CLOSED:
                raise UcdNotConnected("UCD 未连接，无法 apply_signal_format")
            return bool(
                self._controller.apply_signal_format(
                    color_space=color_space,
                    data_range=data_range,
                    bit_depth=bit_depth,
                    color_format=color_format,
                    max_cll=max_cll,
                    max_fall=max_fall,
                )
            )

    def set_ucd_params(self, config) -> bool:
        with self._acquire_device_lock("set_ucd_params"):
            if self._state == UcdState.CLOSED:
                raise UcdNotConnected("UCD 未连接，无法 set_ucd_params")
            return bool(self._controller.set_ucd_params(config))

    def send_current_pattern_params(self, pattern_params) -> bool:
        with self._acquire_device_lock("send_current_pattern_params"):
            if self._state == UcdState.CLOSED:
                raise UcdNotConnected("UCD 未连接，无法 send_current_pattern_params")
            ok = bool(self._controller.send_current_pattern_params(pattern_params))
            if ok:
                self._state = UcdState.APPLIED
            return ok

    def apply_config_and_run(self, config, pattern_params) -> bool:
        with self._acquire_device_lock("apply_config_and_run"):
            if self._state == UcdState.CLOSED:
                raise UcdNotConnected("UCD 未连接，无法 apply_config_and_run")
            ctrl = self._controller
            if not ctrl.set_ucd_params(config):
                return False
            if not ctrl.set_pattern(ctrl.current_pattern, pattern_params):
                return False
            ok = bool(ctrl.run())
            if ok:
                self._state = UcdState.APPLIED
            return ok

    # -- 内部辅助 ------------------------------------------------

    def _apply_dynamic_range(self, signal: SignalFormat) -> None:
        import UniTAP  # 局部导入，避免本模块在无 SDK 环境下导入即失败

        from app.ucd_domain import DynamicRange

        ci = self._controller.color_info
        if ci is None:
            return
        if signal.dynamic_range is DynamicRange.FULL:
            ci.dynamic_range = UniTAP.ColorInfo.DynamicRange.DR_VESA
        else:
            ci.dynamic_range = UniTAP.ColorInfo.DynamicRange.DR_CTA

    def _apply_pattern_via_controller(self, pattern: PatternSpec) -> bool:
        """根据 PatternKind 走最合适的旧 controller 路径。"""
        if pattern.kind is PatternKind.IMAGE:
            if not pattern.image_path:
                raise UcdConfigError("IMAGE pattern 必须提供 image_path")
            return bool(self._controller.send_image_pattern(pattern.image_path))

        # 预定义图案路径：复用 controller.set_pattern + run()
        from drivers.UCD323_Enum import UCDEnum  # 局部导入避免循环

        video_pattern = UCDEnum.VideoPatternInfo.get_video_pattern(pattern.kind.value)
        if video_pattern is None:
            raise UcdConfigError(f"不支持的 PatternKind: {pattern.kind!r}")
        self._controller.current_pattern = video_pattern

        params: list[int] | None = None
        if pattern.kind is PatternKind.SOLID:
            if pattern.solid_rgb is None:
                raise UcdConfigError("SOLID pattern 必须提供 solid_rgb")
            params = list(pattern.solid_rgb)
        elif pattern.extras:
            params = list(pattern.extras)

        if not self._controller.set_pattern(video_pattern, params):
            raise UcdApplyFailed("controller.set_pattern 返回 False")
        # Skip apply_video_mode() (i.e. pg.set_vm) – the video format is already
        # configured by the main signal panel and re-applying it blocks until the
        # device re-locks, causing an apparent UI freeze for pattern-only sends.
        if not self._controller.apply_pattern():
            raise UcdApplyFailed("controller.apply_pattern 返回 False")
        if getattr(self._controller, "current_timing", None) is None:
            raise UcdConfigError(
                "current_timing is None; please apply selected test profile/timing before sending pattern"
            )
        try:
            pg, _ = self._controller.get_tx_modules()
            if not self._controller._apply_pg_output(pg):
                raise UcdApplyFailed("controller.apply_pg_output 返回 False")
        except UcdApplyFailed:
            raise
        except Exception as exc:
            raise UcdSdkError("pg.apply() 失败") from exc
        return True


def _colorimetry_to_legacy_key(signal: SignalFormat) -> str:
    """新 :class:`Colorimetry` → 旧 ``UCDEnum.ColorInfo.get_colorimetry`` 的 key。

    BT.2020 在 YCbCr / RGB 输出下走不同 SDK 枚举（参考旧
    ``_get_colorimetry_from_color_space`` 的逻辑），这里也做同样的分支。
    """
    from app.ucd_domain import Colorimetry, is_ycbcr

    cm = signal.colorimetry
    ycbcr = is_ycbcr(signal.color_format)

    if cm is Colorimetry.BT2020:
        return "bt2020ycbcr" if ycbcr else "bt2020rgb"
    return {
        Colorimetry.SRGB: "srgb",
        Colorimetry.BT709: "bt709",
        Colorimetry.BT601: "bt601",
        Colorimetry.DCI_P3: "dcip3",
        Colorimetry.ADOBE_RGB: "adobergb",
    }.get(cm, "srgb")


# ─── §4 FakeUcdDevice 单测实现 ───────────────────────────────────


class FakeUcdDevice(IUcdDevice):
    """无硬件依赖的 Fake 实现；记录调用序列供单测断言。"""

    def __init__(self, bus: EventBus | None = None) -> None:
        self._bus = bus or EventBus()
        self._state = UcdState.CLOSED
        self._info: DeviceInfo | None = None
        self._signal: SignalFormat | None = None
        self._timing: TimingSpec | None = None
        self._pattern: PatternSpec | None = None
        self._last_applied: tuple[SignalFormat, TimingSpec] | None = None
        self.calls: list[tuple] = []  # ("open", info) / ("configure", ...) ...

    @property
    def state(self) -> UcdState:
        return self._state

    @property
    def info(self) -> DeviceInfo | None:
        return self._info

    def open(self, info: DeviceInfo, *, interface: Interface = Interface.HDMI) -> None:
        assert_transition(self._state, UcdState.OPENED)
        self.calls.append(("open", info, interface))
        self._info = info
        self._state = UcdState.OPENED
        self._bus.publish(ConnectionChanged(True, info.serial))

    def close(self) -> None:
        if self._state == UcdState.CLOSED:
            return
        self.calls.append(("close",))
        self._state = UcdState.CLOSED
        prev = self._info.serial if self._info else None
        self._info = None
        self._signal = self._timing = self._pattern = None
        self._last_applied = None
        self._bus.publish(ConnectionChanged(False, prev))

    def configure(self, signal: SignalFormat, timing: TimingSpec) -> bool:
        if self._state == UcdState.CLOSED:
            raise UcdNotConnected()
        self.calls.append(("configure", signal, timing))
        self._signal, self._timing = signal, timing
        self._state = UcdState.CONFIGURED
        return (signal, timing) != self._last_applied

    def set_pattern(self, pattern: PatternSpec) -> None:
        if self._state == UcdState.CLOSED:
            raise UcdNotConnected()
        self.calls.append(("set_pattern", pattern))
        self._pattern = pattern

    def apply(self) -> None:
        if self._signal is None or self._timing is None:
            raise UcdStateError("apply 前必须 configure")
        if self._pattern is None:
            raise UcdStateError("apply 前必须 set_pattern")
        self.calls.append(("apply",))
        changed = (self._signal, self._timing) != self._last_applied
        self._last_applied = (self._signal, self._timing)
        self._state = UcdState.APPLIED
        self._bus.publish(SignalApplied(self._signal, self._timing, changed))
        self._bus.publish(PatternApplied(self._pattern))

    def current_resolution(self) -> tuple[int, int]:
        if self._timing is None:
            return (3840, 2160)
        return (self._timing.width, self._timing.height)

    def search_devices(self) -> list[str]:
        return []

    @property
    def format_changed(self) -> bool:
        return self._last_applied is None

    @property
    def last_error(self) -> str | None:
        return None

    def apply_signal_format(self, **kwargs) -> bool:
        if self._state == UcdState.CLOSED:
            raise UcdNotConnected()
        self.calls.append(("apply_signal_format", kwargs))
        return True

    def set_ucd_params(self, config) -> bool:
        if self._state == UcdState.CLOSED:
            raise UcdNotConnected()
        self.calls.append(("set_ucd_params", config))
        self._state = UcdState.OPENED
        return True

    def send_current_pattern_params(self, pattern_params) -> bool:
        if self._state == UcdState.CLOSED:
            raise UcdNotConnected()
        self.calls.append(("send_current_pattern_params", pattern_params))
        self._state = UcdState.APPLIED
        return True

    def apply_config_and_run(self, config, pattern_params) -> bool:
        if self._state == UcdState.CLOSED:
            raise UcdNotConnected()
        self.calls.append(("apply_config_and_run", config, pattern_params))
        self._state = UcdState.APPLIED
        return True


__all__ = [
    "DeviceInfo",
    "list_devices",
    "IUcdDevice",
    "UCD323Device",
    "FakeUcdDevice",
]