"""@file spectrum_stream.py
@brief Разбор потока спектра и гармоник от прибора на STM32.

Прибор снимает сигнал вибродатчика или микрофона, считает быстрое
преобразование Фурье прямо на месте и передаёт готовый результат: сам спектр
и параметры найденных гармоник. Задача этого модуля — превратить поток байтов
в структуры, с которыми работает вкладка.

Модуль не зависит от Qt и от последовательного порта: на вход подаются байты,
на выход идут кадры. Так его можно проверить тестами без прибора и без окна.

Формат строки повторяет привычный по навигационным приборам вид: доллар,
поля через запятую, звёздочка и контрольная сумма::

    $SPEC,<seq>,<fs>,<fft>,<bins>,<top>,<range>,<hex>*<cs>
    $HARM,<seq>,<f0>,<a0>,<thd>,<snr>,<rms>,<n>[,<f>,<a>,<db>]...*<cs>

Текстовый формат выбран намеренно, хотя двоичный вышел бы компактнее.
Прибор отлаживается через обычный терминал, и возможность увидеть поток
глазами дороже экономии канала. Спектр при этом ужат до одного байта
на элемент, поэтому кадр укладывается примерно в 290 байт и на скорости
115200 бод спокойно идёт пять раз в секунду.
"""

from __future__ import annotations

from dataclasses import dataclass, field

#: Начальный символ строки.
LINE_START = "$"

#: Разделитель контрольной суммы.
CHECKSUM_MARK = "*"

#: Тип строки со спектром.
TAG_SPECTRUM = "SPEC"

#: Тип строки с гармониками.
TAG_HARMONICS = "HARM"

#: Наибольшее число гармоник в кадре; совпадает с пределом прошивки.
MAX_HARMONICS = 8

#: Наибольшая длина строки. Защита от мусора в канале: без неё обрыв связи
#: посреди передачи привёл бы к бесконечному накоплению в буфере.
MAX_LINE_LENGTH = 4096


def checksum(payload: str) -> int:
    """@brief Считает контрольную сумму строки.

    @param payload Содержимое между ``$`` и ``*``.
    @return Побайтовое исключающее ИЛИ, 0..255.

    Сумма именно такая простая не от небрежности: канал короткий и
    проводной, а задача суммы здесь — отсеять строку, склеенную из двух
    обрывков, а не защитить от искажения одного бита.
    """
    value = 0
    for char in payload.encode("ascii", errors="replace"):
        value ^= char
    return value & 0xFF


@dataclass(frozen=True)
class Harmonic:
    """@brief Одна найденная гармоника."""

    index: int
    """Номер гармоники: 2 — вторая, 3 — третья и так далее."""

    frequency_hz: float
    """Измеренная частота."""

    amplitude_mv: float
    """Амплитуда."""

    relative_db: float
    """Уровень относительно основного тона, децибелы. Всегда отрицателен
    у исправного тракта: гармоника слабее основного тона."""


@dataclass(frozen=True)
class HarmonicsFrame:
    """@brief Параметры основного тона и его гармоник."""

    seq: int
    fundamental_hz: float
    fundamental_mv: float
    thd_percent: float
    """Коэффициент гармонических искажений."""
    snr_db: float
    rms_mv: float
    harmonics: tuple[Harmonic, ...] = ()


@dataclass(frozen=True)
class SpectrumFrame:
    """@brief Спектр целиком."""

    seq: int
    sample_rate_hz: int
    fft_size: int
    top_dbmv: float
    """Верхняя граница шкалы уровней, децибелы относительно милливольта."""
    range_db: float
    """Полный размах шкалы уровней."""
    levels_db: tuple[float, ...] = field(default=())
    """Уровни элементов спектра в децибелах относительно милливольта."""

    @property
    def bin_width_hz(self) -> float:
        """@brief Шаг по частоте между элементами переданного спектра.

        Учитывает, что прибор мог проредить спектр перед передачей: делится
        не на размер преобразования, а на фактическое число элементов.
        """
        if not self.levels_db:
            return 0.0
        top_frequency = self.sample_rate_hz / 2.0
        return top_frequency / len(self.levels_db)

    def frequency_of(self, index: int) -> float:
        """@brief Частота, соответствующая элементу спектра.

        @param index Номер элемента.
        @return Частота в герцах.
        """
        return index * self.bin_width_hz


class SpectrumStreamError(Exception):
    """@brief Строка не разобрана. Несёт причину для журнала."""


def _split_line(line: str) -> tuple[str, list[str]]:
    """@brief Проверяет обрамление и контрольную сумму, возвращает поля.

    @param line Одна строка без перевода строки.
    @return Кортеж «тип строки, список полей».
    @throws SpectrumStreamError При нарушении формата или суммы.
    """
    if not line.startswith(LINE_START):
        raise SpectrumStreamError("строка не начинается с '$'")

    star = line.rfind(CHECKSUM_MARK)
    if star < 0:
        raise SpectrumStreamError("нет контрольной суммы")

    payload = line[1:star]
    tail = line[star + 1 :].strip()

    if len(tail) != 2:
        raise SpectrumStreamError("контрольная сумма не из двух знаков")

    try:
        expected = int(tail, 16)
    except ValueError as exc:
        raise SpectrumStreamError("контрольная сумма не шестнадцатеричная") from exc

    actual = checksum(payload)
    if actual != expected:
        raise SpectrumStreamError(
            f"контрольная сумма не сошлась: получено {expected:02X}, "
            f"посчитано {actual:02X}"
        )

    fields = payload.split(",")
    if not fields:
        raise SpectrumStreamError("пустая строка")

    return fields[0], fields[1:]


def _decode_levels(hex_data: str, top_dbmv: float, range_db: float) -> tuple[float, ...]:
    """@brief Разворачивает упакованный спектр в уровни.

    @param hex_data  Элементы спектра, по два знака на элемент.
    @param top_dbmv  Верхняя граница шкалы.
    @param range_db  Размах шкалы.
    @return Уровни в децибелах.

    Прибор передаёт каждый элемент одним байтом: ноль означает нижнюю
    границу шкалы, 255 — верхнюю. Такое сжатие теряет доли децибела,
    что для картины спектра несущественно, зато уменьшает кадр вчетверо
    относительно передачи чисел текстом.
    """
    if len(hex_data) % 2 != 0:
        raise SpectrumStreamError("нечётное число знаков в данных спектра")

    bottom = top_dbmv - range_db
    levels: list[float] = []

    for pos in range(0, len(hex_data), 2):
        chunk = hex_data[pos : pos + 2]
        try:
            raw = int(chunk, 16)
        except ValueError as exc:
            raise SpectrumStreamError(f"неверный знак в данных: '{chunk}'") from exc
        levels.append(bottom + (raw / 255.0) * range_db)

    return tuple(levels)


def parse_line(line: str) -> SpectrumFrame | HarmonicsFrame:
    """@brief Разбирает одну строку.

    @param line Строка без перевода строки.
    @return Кадр спектра или кадр гармоник.
    @throws SpectrumStreamError При любой ошибке разбора.
    """
    tag, fields = _split_line(line)

    if tag == TAG_SPECTRUM:
        if len(fields) != 7:
            raise SpectrumStreamError(
                f"в строке спектра {len(fields)} полей вместо 7"
            )
        try:
            seq = int(fields[0])
            sample_rate = int(fields[1])
            fft_size = int(fields[2])
            bins = int(fields[3])
            top = float(fields[4])
            span = float(fields[5])
        except ValueError as exc:
            raise SpectrumStreamError("нечисловое поле в строке спектра") from exc

        if span <= 0.0:
            raise SpectrumStreamError("размах шкалы должен быть положительным")

        levels = _decode_levels(fields[6], top, span)

        # Заявленное число элементов обязано совпасть с переданным: иначе
        # шкала частот сдвинется, и оператор увидит тон не на своей частоте.
        if len(levels) != bins:
            raise SpectrumStreamError(
                f"заявлено {bins} элементов, передано {len(levels)}"
            )

        return SpectrumFrame(
            seq=seq,
            sample_rate_hz=sample_rate,
            fft_size=fft_size,
            top_dbmv=top,
            range_db=span,
            levels_db=levels,
        )

    if tag == TAG_HARMONICS:
        if len(fields) < 6:
            raise SpectrumStreamError("слишком короткая строка гармоник")
        try:
            seq = int(fields[0])
            fundamental_hz = float(fields[1])
            fundamental_mv = float(fields[2])
            thd = float(fields[3])
            snr = float(fields[4])
            rms = float(fields[5])
            count = int(fields[6]) if len(fields) > 6 else 0
        except ValueError as exc:
            raise SpectrumStreamError("нечисловое поле в строке гармоник") from exc

        if count < 0 or count > MAX_HARMONICS:
            raise SpectrumStreamError(f"недопустимое число гармоник: {count}")

        expected_fields = 7 + count * 3
        if len(fields) != expected_fields:
            raise SpectrumStreamError(
                f"для {count} гармоник нужно {expected_fields} полей, "
                f"получено {len(fields)}"
            )

        harmonics: list[Harmonic] = []
        for item in range(count):
            base = 7 + item * 3
            try:
                harmonics.append(
                    Harmonic(
                        index=item + 2,
                        frequency_hz=float(fields[base]),
                        amplitude_mv=float(fields[base + 1]),
                        relative_db=float(fields[base + 2]),
                    )
                )
            except ValueError as exc:
                raise SpectrumStreamError(
                    f"нечисловое поле у гармоники {item + 2}"
                ) from exc

        return HarmonicsFrame(
            seq=seq,
            fundamental_hz=fundamental_hz,
            fundamental_mv=fundamental_mv,
            thd_percent=thd,
            snr_db=snr,
            rms_mv=rms,
            harmonics=tuple(harmonics),
        )

    raise SpectrumStreamError(f"неизвестный тип строки: '{tag}'")


class SpectrumStream:
    """@brief Накопитель байтов, отдающий разобранные кадры.

    Данные из порта приходят кусками произвольного размера: строка может
    прийти по частям, а в одном куске может оказаться несколько строк.
    Накопитель собирает их обратно.
    """

    def __init__(self) -> None:
        self._buffer = ""
        self.parsed = 0
        """Число успешно разобранных строк."""
        self.errors = 0
        """Число отброшенных строк."""
        self.last_error: str = ""
        """Причина последней ошибки — для журнала вкладки."""

    def reset(self) -> None:
        """@brief Сбрасывает накопитель и счётчики."""
        self._buffer = ""
        self.parsed = 0
        self.errors = 0
        self.last_error = ""

    def feed(self, chunk: str | bytes) -> list[SpectrumFrame | HarmonicsFrame]:
        """@brief Добавляет очередной кусок потока.

        @param chunk Данные из порта.
        @return Список кадров, разобранных из накопленного.

        Ошибочные строки отбрасываются, но не прерывают разбор: одиночная
        помеха в канале не должна ронять поток целиком.
        """
        if isinstance(chunk, (bytes, bytearray)):
            chunk = chunk.decode("ascii", errors="replace")

        self._buffer += chunk

        # Защита от мусора без переводов строки: иначе буфер рос бы
        # неограниченно и приложение съело бы всю память.
        if len(self._buffer) > MAX_LINE_LENGTH:
            cut = self._buffer.rfind("\n")
            self._buffer = self._buffer[cut + 1 :] if cut >= 0 else ""
            self.errors += 1
            self.last_error = "строка длиннее допустимой, буфер очищен"

        frames: list[SpectrumFrame | HarmonicsFrame] = []

        while "\n" in self._buffer:
            line, _, self._buffer = self._buffer.partition("\n")
            line = line.strip("\r\n \t")
            if not line:
                continue
            try:
                frames.append(parse_line(line))
                self.parsed += 1
            except SpectrumStreamError as exc:
                self.errors += 1
                self.last_error = str(exc)

        return frames


def build_spectrum_line(
    seq: int,
    sample_rate_hz: int,
    fft_size: int,
    levels_db: list[float] | tuple[float, ...],
    top_dbmv: float,
    range_db: float,
) -> str:
    """@brief Собирает строку спектра.

    @return Строка с переводом строки в конце.

    Нужна для тестов и для демонстрационного источника, но главное — она
    задаёт формат в одном месте с разбором. Если формат изменят только
    в прошивке, круговой тест это заметит.
    """
    bottom = top_dbmv - range_db
    parts: list[str] = []

    for level in levels_db:
        ratio = (level - bottom) / range_db if range_db > 0.0 else 0.0
        raw = int(round(max(0.0, min(1.0, ratio)) * 255.0))
        parts.append(f"{raw:02X}")

    payload = (
        f"{TAG_SPECTRUM},{seq},{sample_rate_hz},{fft_size},"
        f"{len(parts)},{top_dbmv:.1f},{range_db:.1f},{''.join(parts)}"
    )
    return f"{LINE_START}{payload}{CHECKSUM_MARK}{checksum(payload):02X}\n"


def build_harmonics_line(frame: HarmonicsFrame) -> str:
    """@brief Собирает строку гармоник.

    @param frame Данные для передачи.
    @return Строка с переводом строки в конце.
    """
    parts = [
        TAG_HARMONICS,
        str(frame.seq),
        f"{frame.fundamental_hz:.1f}",
        f"{frame.fundamental_mv:.1f}",
        f"{frame.thd_percent:.2f}",
        f"{frame.snr_db:.1f}",
        f"{frame.rms_mv:.1f}",
        str(len(frame.harmonics)),
    ]
    for harmonic in frame.harmonics:
        parts.append(f"{harmonic.frequency_hz:.1f}")
        parts.append(f"{harmonic.amplitude_mv:.1f}")
        parts.append(f"{harmonic.relative_db:.1f}")

    payload = ",".join(parts)
    return f"{LINE_START}{payload}{CHECKSUM_MARK}{checksum(payload):02X}\n"