FastAPI: Гайд по нормальной структуре для новичков (Часть 1. Слой домена)

from dataclasses import dataclass, field
from typing import Optional, Dict, Any
from uuid import UUID, uuid4

@dataclass(frozen=True)
class RecordingSourceId:
    """Уникальный идентификатор источника записи внутри нашей системы."""
    value: UUID

    @staticmethod
    def new() -> "RecordingSourceId":
        return RecordingSourceId(uuid4())

    def __str__(self) -> str:
        return str(self.value)


@dataclass(frozen=True)
class RecordingSourceExtra:
    """
    Необязательные данные об источнике.
    Сейчас здесь почти ничего нет, но именно сюда
    позже поедут метаданные о местоположении камеры
    """
    floor: Optional[int] = None
    location_label: Optional[str] = None
    meta: Dict[str, Any] = field(default_factory=dict)


class RecordingSource:
    """
    Источник записи (камера/логический канал).
    На уровне домена нам пока важно только то,
    что есть его идентификатор и необязательные доп.данные.
    """
    idx: RecordingSourceId
    extra: RecordingSourceExtra = RecordingSourceExtra()
    def __init__(
        self,
        idx: RecordingSourceId
        extra: RecordingSourceExtra = RecordingSourceExtra()
    ) -> None:
        self.idx: RecordingSourceId = idx
        self.source_id: RecordingSourceExtra = extra

from dataclasses import dataclass, field
from datetime import datetime
from typing import Optional, Dict, Any
from uuid import UUID, uuid4

from domain.entity.video_source import RecordingSourceId


@dataclass(frozen=True)
class VideoFileId:
    """Уникальный идентификатор видеозаписи внутри нашей системы."""
    value: UUID

    @staticmethod
    def new() -> "VideoFileId":
        return VideoFileId(uuid4())

    def __str__(self) -> str:
        return str(self.value)


@dataclass
class VideoFileExtra:
    """
    Необязательные тех.детали видео.
    Сейчас они нам не критичны, но сюда можно будет
    добавить конец записи, кодеки, размер кадра и т.п.
    """
    ended_at: Optional[datetime] = None
    duration_seconds: Optional[float] = None
    codec: Optional[str] = None
    frame_width: Optional[int] = None
    frame_height: Optional[int] = None
    meta: Dict[str, Any] = field(default_factory=dict)

class VideoFile:
    """
    Видеофайл/видеозапись.
    Нас сейчас интересует:
      - уникальный идентификатор видео;
      - время начала записи;
      - источник, с которого это видео пришло.
    Остальное — опционально и уезжает в VideoFileExtra.
    """

    def __init__(
        self,
        idx: VideoFileId,
        source_id: "RecordingSourceId",
        started_at: datetime,
        extra: Optional[VideoFileExtra] = None,
    ) -> None:
        self.idx: VideoFileId = idx
        self.source_id: RecordingSourceId = source_id
        self.started_at: datetime = started_at
        self.extra: VideoFileExtra = extra or VideoFileExtra()

from dataclasses import dataclass
from datetime import datetime
from typing import Any

from domain.entity.video_file import VideoFileIdx

@dataclass(frozen=True)
class FrameData:
    """
    Важный value object: «сырые» данные кадра.
    Сейчас нам не важно, это байты картинки, JPEG/PNG, numpy-массив
    или что-то ещё — главное, что это единый объект данных кадра.
    """
    value: Any


class Frame:
    """
    Один кадр видеозаписи.

    Для идентификации кадра в домене нам сейчас достаточно:
      - времени кадра;
      - идентификатора видеозаписи;
      - самих данных кадра (в каком-то виде).

    Остальные атрибуты (номер кадра, размер, формат и т.п.)
    считаем деталями реализации и пока в модель не тащим.
    """

    def __init__(
        self,
        video_idx: "VideoFileIdx",
        captured_at: datetime,
        data: FrameData,
    ) -> None:
        self.video_idx = video_idx
        self.captured_at = captured_at
        self.data = data

from dataclasses import dataclass, field
from datetime import datetime
from enum import Enum
from typing import Dict, Any, List, Optional
from uuid import UUID, uuid4

from domain.entity.video_file import VideoFileIdx


@dataclass(frozen=True)
class ObjectIdx:
    """Уникальный идентификатор объекта (человек, тележка, телефон и т.д.)."""
    value: UUID

    @staticmethod
    def new() -> "ObjectIdx":
        return ObjectIdx(uuid4())

    def __str__(self) -> str:
        return str(self.value)


@dataclass(frozen=True)
class ObjectClass:
    """
    Класс объекта:
      - сейчас нас интересует 'person',
      - в будущем: 'cart', 'phone', 'employee', 'thief' и т.д.
    """
    value: str  # например: "person", "cart", "phone"


@dataclass
class ObjectAttributes:
    """
    Дополнительные признаки объекта.
    Их мы будем заполнять пока в виде словаря,
    но потом мы сможем лучше конкретизировать эти объекты.
    Главное, что нам из-за этих изменений не придется переделывать
    саму сущность.
    """
    meta: Dict[str, Any] = field(default_factory=dict)

@dataclass(frozen=True)
class Coordinate:
    """
    Координаты объекта в кадре
    """
    x: int
    y: int
    width: int
    height: int


@dataclass(frozen=True)
class FrameRef:
    """
    Ссылка на кадр, в котором объект был зафиксирован.

    Мы не навязываем отдельный идентификатор кадра, а ссылаемся
    через пару (video_idx, captured_at), чего достаточно в домене,
    чтобы однозначно указать кадр.
    """
    video_idx: "VideoFileIdx"
    captured_at: datetime
    coordinate: Coordinate


# === Сущность ===
class DetectedObject:
    """
    Объект, обнаруженный в видеопотоке.

    На уровне домена нас интересует:
      - уникальный идентификатор объекта;
      - его класс (person/cart/phone/…);
      - дополнительные признаки (сейчас — пол);
      - список кадров, в которых этот объект встречается
        (для дальнейшей агрегации и аналитики).
    """

    def __init__(
        self,
        idx: ObjectIdx,
        object_class: ObjectClass,
        attributes: Optional[ObjectAttributes] = None,
        frames: Optional[List[FrameRef]] = None,
    ) -> None:
        self.idx = idx
        self.object_class = object_class
        self.attributes = attributes or ObjectAttributes()
        self.frames: List[FrameRef] = frames or []

from dataclasses import dataclass, field
from datetime import datetime
from typing import Dict, Any, List
from uuid import UUID, uuid4

from domain.entity.recording_source import RecordingSourceIdx
from domain.entity.video_file import VideoFileIdx
from domain.entity.detected_object import ObjectIdx


@dataclass(frozen=True)
class ReportIdx:
    """Уникальный идентификатор отчёта."""
    value: UUID

    @staticmethod
    def new() -> "ReportIdx":
        return ReportIdx(uuid4())

    def __str__(self) -> str:
        return str(self.value)


@dataclass(frozen=True)
class ReportType:
    """
    Тип отчёта:
      - сейчас достаточно, например, 'people_count', 'gender_distribution';
      - в будущем: 'traffic_heatmap', 'theft_suspects', 'queue_length' и т.д.
    """
    value: str


@dataclass(frozen=True)
class TimeRange:
    """Временной промежуток, за который строится отчёт."""
    start: datetime
    end: datetime


@dataclass
class ReportData:
    """
    Агрегированные данные отчёта.

    Сейчас оставляем это в виде произвольного словаря,
    чтобы не блокировать развитие. Когда домен стабилизируется,
    из meta можно будет вытащить отдельные данные
    """
    meta: Dict[str, Any] = field(default_factory=dict)


# === Сущность ===

class Report:
    """
    Отчёт для заказчика.
    """

    def __init__(
        self,
        idx: ReportIdx,
        report_type: ReportType,
        time_range: TimeRange,
        data: ReportData,
        source_idx_list: List["RecordingSourceIdx"],
        video_idx_list: List["VideoFileIdx"],
        object_idx_list: List["ObjectIdx"],
    ) -> None:
        self.idx = idx
        self.report_type = report_type
        self.time_range = time_range
        self.data = data

        self.source_idx_list = list(source_idx_list)
        self.video_idx_list = list(video_idx_list)
        self.object_idx_list = list(object_idx_list)

from abc import ABC, abstractmethod
from dataclasses import dataclass
from typing import Optional, BinaryIO

from domain.entity.video_file import VideoFileIdx


@dataclass(frozen=True)
class FileLocation:
    """
    Абстрактное местоположение файла.
    Это может быть путь на диске, ключ в объектном хранилище,
    URL и т.д. Конкретику решит инфраструктура.
    """
    value: str


@dataclass(frozen=True)
class FileSaveResult:
    """
    Результат сохранения файла.
    Главное — удалось или нет. Остальное опционально.
    """
    success: bool
    location: Optional[FileLocation] = None
    error_message: Optional[str] = None


class FileStorage(ABC):
    """
    Абстрактный сервис сохранения файлов.

    Детали (стриминг, буферизация, ретраи, конкретное хранилище)
    остаются за пределами домена. Здесь нас интересует только:
    «попробуй сохранить» → FileSaveResult.
    """

    @abstractmethod
    def save_video_content(
        self,
        video_idx: "VideoFileIdx",
        content: BinaryIO,
    ) -> FileSaveResult:
        """
        Сохранить бинарное содержимое видеозаписи,
        связав его с доменной сущностью VideoFile.

        Аргумент `content` — абстрактный поток байт:
        это может быть открытый файл, сетевой стрим и т.п.
        """
        raise NotImplementedError

from abc import ABC, abstractmethod
from typing import Iterable

from domain.entity.video_file import VideoFileIdx
from domain.entity.frame import Frame


class FrameExtractor(ABC):
    """
    Абстрактный сервис нарезки кадров из видео.

    На уровне домена нас интересует только то, что
    на вход подаётся идентификатор видеозаписи, а на выходе
    мы получаем набор сущностей Frame, достаточный для
    дальнейшей обработки и аналитики.
    """

    @abstractmethod
    def extract_frames(self, video_idx: "VideoFileIdx") -> Iterable["Frame"]:
        """
        Извлечь кадры для указанного видео.

        Конкретная реализация сама решает:
          - как прочитать файл (локальный диск, object storage и т.п.);
          - как именно и с какими параметрами вырезать кадры.
        """
        raise NotImplementedError

from abc import ABC, abstractmethod
from dataclasses import dataclass
from typing import List


from domain.entity.frame import Frame
from domain.entity.detected_object import ObjectClass, ObjectAttributes, Coordinate


@dataclass(frozen=True)
class RawDetection:
    """
    Результат работы нейросетей по одному объекту на кадре.

    На уровне сервиса обработки кадров нам достаточно:
      - класса объекта;
      - набора признаков (пока в виде ObjectAttributes);
      - координат объекта в кадре.
    """
    object_class: "ObjectClass"
    attributes: "ObjectAttributes"
    coordinate: "Coordinate"


class FrameProcessor(ABC):
    """
    Абстрактный сервис обработки кадров нейросетями.

    Мы не знаем:
      - какие именно нейросети будут использоваться;
      - сколько их будет и в каком порядке они запустятся;
      - на каком железе это всё будет крутиться.
    """

    @abstractmethod
    def process_frame(self, frame: "Frame") -> List[RawDetection]:
        """
        Обработать кадр и вернуть список найденных объектов
        с их классами, признаками и координатами.
        """
        raise NotImplementedError

from abc import ABC, abstractmethod
from dataclasses import dataclass
from typing import List

from domain.entity.frame import Frame
from domain.entity.detected_object import ObjectIdx, FrameRef
from domain.service.frame_processor import RawDetection

@dataclass(frozen=True)
class ObjectClassificationDecision:
    """
    Результат классификации одного «сыро обнаруженного» объекта.

    На уровне домена нас интересует:
      - какой доменной сущности DetectedObject он соответствует
        (существующий объект или новый);
      - в каком кадре и с какими координатами он был обнаружен;
      - исходные данные детекции (класс, признаки, координаты).
    """
    existing_object_idx: Optional["ObjectIdx"]  # None, если объект новый
    frame_ref: "FrameRef"
    raw_detection: "RawDetection"

    @property
    def is_new(self) -> bool:
        """True, если по этой детекции нужно создать новый объект."""
        return self.existing_object_idx is None


class ObjectClassifier(ABC):
    """
    Абстрактный сервис классификации/сопоставления объектов по кадрам.

    Его задача — только принять решение:
      - к какому уже существующему ObjectIdx отнести детекцию;
      - по каким детекциям нужно создать НОВЫЙ объект.

    Как именно это делается (трекеры, эвклидово расстояние, нейросети и т.п.) —
    детализация инфраструктуры, домен этого не знает.
    """

    @abstractmethod
    def classify_objects(
        self,
        frame: "Frame",
        detections: List["RawDetection"],
    ) -> List[ObjectClassificationDecision]:
        """
        На основании набора детекций на кадре решить,
        какие из них принадлежат уже существующим объектам,
        а для каких потребуется создать новый объект.
        """
        raise NotImplementedError

from abc import ABC, abstractmethod
from dataclasses import dataclass, field
from typing import Dict, Any, List

from domain.entity.detected_object import DetectedObject, ObjectIdx
from domain.entity.video_file import VideoFileIdx
from domain.entity.recording_source import RecordingSourceIdx


@dataclass
class ObjectAnalyticsResult:
    """
    Результат анализа уникальных объектов.

    Здесь мы собираем всё, что нужно для дальнейшего построения отчёта:
      - агрегированные метрики (meta),
      - «пруфы» — ссылки на источники, видео и объекты.
    """
    meta: Dict[str, Any] = field(default_factory=dict)
    source_idx_list: List["RecordingSourceIdx"] = field(default_factory=list)
    video_idx_list: List["VideoFileIdx"] = field(default_factory=list)
    object_idx_list: List["ObjectIdx"] = field(default_factory=list)


class ObjectAnalyzer(ABC):
    """
    Абстрактный сервис анализа найденных (уже классифицированных) объектов.

    Его задача:
      - взять набор уникальных объектов (DetectedObject),
      - «переварить» их,
      - выдать агрегированные данные, которые потом
        пойдут в построение доменной сущности отчёта.

    ВАЖНО: сервис ничего не знает о том, как будут выглядеть
    конкретные отчёты, он лишь добывает сырые аналитические данные
    и пруфы.
    """

    @abstractmethod
    def analyze_objects(
        self,
        objects: List["DetectedObject"],
    ) -> ObjectAnalyticsResult:
        """
        Проанализировать набор уникальных объектов и вернуть
        агрегированную информацию, пригодную для построения отчёта.
        """
        raise NotImplementedError

from abc import ABC, abstractmethod
from typing import Optional, List


from domain.entity.recording_source import RecordingSource, RecordingSourceIdx


class RecordingSourceRepository(ABC):
    """
    Абстрактный репозиторий источников записи.

    Детали хранилища (Postgres, NoSQL, файлики, in-memory)
    здесь не определяются.
    """

    @abstractmethod
    def save(self, source: "RecordingSource") -> None:
        """
        Сохранить или обновить источник записи.
        """
        raise NotImplementedError

    @abstractmethod
    def get_by_idx(self, idx: "RecordingSourceIdx") -> Optional["RecordingSource"]:
        """
        Получить источник по его доменному идентификатору.
        """
        raise NotImplementedError

    @abstractmethod
    def list_all(self) -> List["RecordingSource"]:
        """
        Вернуть все известные источники.
        (Пагинация уже как домашнее задание)
        """
        raise NotImplementedError

from abc import ABC, abstractmethod
from typing import Optional, List


from domain.entity.video_file import VideoFile, VideoFileIdx
from domain.entity.recording_source import RecordingSourceIdx


class VideoFileRepository(ABC):
    """
    Абстрактный репозиторий видеозаписей.

    Задачи:
      - сохранить/обновить сущность VideoFile;
      - уметь по доменному идентификатору VideoFileIdx быстро её найти;
      - при необходимости находить все видео, привязанные к источнику.
    """

    @abstractmethod
    def save(self, video: "VideoFile") -> None:
        """
        Сохранить или обновить видеозапись.
        """
        raise NotImplementedError

    @abstractmethod
    def get_by_idx(self, idx: "VideoFileIdx") -> Optional["VideoFile"]:
        """
        Найти видеозапись по её доменному идентификатору.
        """
        raise NotImplementedError

    @abstractmethod
    def list_by_source_idx(self, source_idx: "RecordingSourceIdx") -> List["VideoFile"]:
        """
        Получить все видеозаписи, пришедшие с указанного источника.
        """
        raise NotImplementedError

from abc import ABC, abstractmethod
from datetime import datetime
from typing import Optional, List

from domain.entity.frame import Frame
from domain.entity.video_file import VideoFileIdx


class FrameRepository(ABC):
    """
    Абстрактный репозиторий кадров.

    Задачи:
      - сохранять проанализированные кадры как «пруф» работы системы;
      - уметь находить кадры по видеозаписи и времени;
      - уметь получать набор кадров по видеозаписи и/или диапазону времени.
    """

    @abstractmethod
    def save(self, frame: "Frame") -> None:
        """
        Сохранить или обновить кадр.
        """
        raise NotImplementedError

    @abstractmethod
    def get_by_video_and_time(
        self,
        video_idx: "VideoFileIdx",
        captured_at: datetime,
    ) -> Optional["Frame"]:
        """
        Найти конкретный кадр по видеозаписи и времени съёмки.
        Эта пара (video_idx, captured_at).
        """
        raise NotImplementedError

    @abstractmethod
    def list_by_video_idx(
        self,
        video_idx: "VideoFileIdx",
        *,
        start_time: Optional[datetime] = None,
        end_time: Optional[datetime] = None,
    ) -> List["Frame"]:
        """
        Получить кадры для указанного видео.
        """
        raise NotImplementedError

from abc import ABC, abstractmethod
from dataclasses import dataclass, field
from datetime import datetime
from typing import Optional, List, Dict, Any

from domain.entity.detected_object import DetectedObject, ObjectIdx, ObjectClass
from domain.entity.recording_source import RecordingSourceIdx
from domain.entity.video_file import VideoFileIdx


@dataclass
class ObjectSearchCriteria:
    """
    Критерии поиска объектов.

    Это абстрактный фильтр, который можно постепенно расширять
    по мере появления новых сценариев в сервисах.
    """
    object_classes: Optional[List["ObjectClass"]] = None
    source_idx: Optional["RecordingSourceIdx"] = None
    video_idx: Optional["VideoFileIdx"] = None

    # Временной диапазон, в котором объект хоть раз появлялся
    appeared_from: Optional[datetime] = None
    appeared_to: Optional[datetime] = None

    # Фильтрация по признакам (ключи/значения в ObjectAttributes.meta)
    attributes: Dict[str, Any] = field(default_factory=dict)


class ObjectRepository(ABC):
    """
    Абстрактный репозиторий объектов (DetectedObject).
    """

    @abstractmethod
    def save(self, obj: "DetectedObject") -> None:
        """
        Сохранить или обновить объект.
        """
        raise NotImplementedError

    @abstractmethod
    def get_by_idx(self, idx: "ObjectIdx") -> Optional["DetectedObject"]:
        """
        Получить объект по доменному идентификатору.
        """
        raise NotImplementedError

    @abstractmethod
    def search(
        self,
        criteria: ObjectSearchCriteria,
        *,
        limit: Optional[int] = None,
        offset: Optional[int] = None,
    ) -> List["DetectedObject"]:
        """
        Поиск объектов по набору критериев.
        """
        raise NotImplementedError

from abc import ABC, abstractmethod
from datetime import datetime
from typing import Optional, List

from domain.entity.report import Report, ReportIdx, ReportType


class ReportRepository(ABC):
    """
    Абстрактный репозиторий отчётов.
    """

    @abstractmethod
    def save(self, report: "Report") -> None:
        """
        Сохранить или обновить отчёт.
        """
        raise NotImplementedError

    @abstractmethod
    def get_by_idx(self, idx: "ReportIdx") -> Optional["Report"]:
        """
        Получить отчёт по его доменному идентификатору.
        """
        raise NotImplementedError

    @abstractmethod
    def list_by_type(
        self,
        report_type: "ReportType",
        *,
        start_time: Optional[datetime] = None,
        end_time: Optional[datetime] = None,
        limit: Optional[int] = None,
        offset: Optional[int] = None,
    ) -> List["Report"]:
        """
        Получить отчёты указанного типа.

        Временной промежуток задаёт интересующий нас диапазон
        по времени, за который построены отчёты.

        Реализация сама решает:
          - как интерпретировать start_time/end_time относительно
            поля TimeRange у отчёта;
          - как оптимизировать выборку и пагинацию.
        """
        raise NotImplementedError

    @abstractmethod
    def list_all(
        self,
        *,
        limit: Optional[int] = None,
        offset: Optional[int] = None,
    ) -> List["Report"]:
        """
        Вернуть все отчёты (с возможной пагинацией).
        """
        raise NotImplementedError

from dataclasses import dataclass
from typing import Optional

from domain.entity.recording_source import (
    RecordingSource,
    RecordingSourceIdx,
    RecordingSourceExtra,
)


@dataclass
class RecordingSourceFactory:
    """
    Фабрика источников записи.
    """

    def create(
        self,
        extra: Optional["RecordingSourceExtra"] = None,
    ) -> "RecordingSource":
        idx = RecordingSourceIdx.new()
        return RecordingSource(
            idx=idx,
            extra=extra or "RecordingSourceExtra"()
        )

from dataclasses import dataclass
from datetime import datetime
from typing import Optional

from domain.entity.video_file import VideoFile, VideoFileIdx, VideoFileExtra
from domain.entity.recording_source import RecordingSourceIdx


@dataclass
class VideoFileFactory:
    """
    Фабрика видеозаписей.
    """

    def create(
        self,
        source_idx: RecordingSourceIdx,
        started_at: datetime,
        extra: Optional["VideoFileExtra"] = None,
    ) -> "VideoFile":
        video_idx = VideoFileIdx.new()
        return VideoFile(
            idx=video_idx,
            source_idx=source_idx,
            started_at=started_at,
            extra=extra or VideoFileExtra(),
        )

from dataclasses import dataclass
from datetime import datetime
from typing import Any

from domain.entity.frame import Frame, FrameData
from domain.entity.video_file import VideoFileIdx


@dataclass
class FrameFactory:
    """
    Фабрика кадров.
    """

    def create(
        self,
        video_idx: VideoFileIdx,
        captured_at: datetime,
        raw_data: Any,
    ) -> "Frame":
        frame_data = FrameData(value=raw_data)
        return Frame(
            video_idx=video_idx,
            captured_at=captured_at,
            data=frame_data,
        )

from dataclasses import dataclass
from typing import Optional

from domain.entity.detected_object import (
    DetectedObject,
    ObjectIdx,
    ObjectClass,
    ObjectAttributes,
    FrameRef,
)


@dataclass
class DetectedObjectFactory:
    """
    Фабрика доменных объектов (DetectedObject).
    """

    def create_new(
        self,
        object_class: ObjectClass,
        attributes: Optional[ObjectAttributes] = None,
        first_frame: Optional[FrameRef] = None,
    ) -> DetectedObject:
        idx = ObjectIdx.new()
        frames = [first_frame] if first_frame is not None else None

        return DetectedObject(
            idx=idx,
            object_class=object_class,
            attributes=attributes or ObjectAttributes(),
            frames=frames,
        )

from dataclasses import dataclass

from domain.entity.report import (
    Report,
    ReportIdx,
    ReportType,
    TimeRange,
    ReportData,
)
from domain.service.object_analyzer import ObjectAnalyticsResult


@dataclass
class ReportFactory:
    """
    Фабрика отчётов.
    """

    def create_from_analytics(
        self,
        report_type: ReportType,
        time_range: TimeRange,
        analytics: ObjectAnalyticsResult,
    ) -> Report:
        idx = ReportIdx.new()

        data = ReportData(meta=analytics.meta)

        return Report(
            idx=idx,
            report_type=report_type,
            time_range=time_range,
            data=data,
            source_idx_list=analytics.source_idx_list,
            video_idx_list=analytics.video_idx_list,
            object_idx_list=analytics.object_idx_list,
        )

class RecordingSource:
    # старый код

    def update_extra(self, extra: RecordingSourceExtra) -> None:
        """
        Обновить дополнительные данные об источнике.
        """
        self.extra = extra

class VideoFile:
    # старый код

    def mark_ended(self, ended_at: Optional[datetime] = None) -> None:
        """
        Пометить видеозапись как завершённую.
        """
        new_ended_at = ended_at or datetime.utcnow()

        if new_ended_at < self.started_at:
            raise ValueError("ended_at cannot be earlier than started_at")

        if self.extra.ended_at is not None and new_ended_at <= self.extra.ended_at:
            return

        self.extra.ended_at = new_ended_at
        self.extra.duration_seconds = (new_ended_at - self.started_at).total_seconds()

    def update_duration(self, duration_seconds: float) -> None:
        """
        Обновить длительность видеозаписи в секундах.
        """
        if duration_seconds < 0:
            raise ValueError("duration_seconds cannot be negative")

        self.extra.duration_seconds = duration_seconds

    def update_technical_info(
        self,
        *,
        codec: Optional[str] = None,
        frame_width: Optional[int] = None,
        frame_height: Optional[int] = None,
        meta: Optional[Dict[str, Any]] = None,
    ) -> None:
        """
        Обновить технические параметры видеозаписи.
        """
        if frame_width is not None and frame_width <= 0:
            raise ValueError("frame_width must be positive")

        if frame_height is not None and frame_height <= 0:
            raise ValueError("frame_height must be positive")

        if codec is not None:
            self.extra.codec = codec

        if frame_width is not None:
            self.extra.frame_width = frame_width

        if frame_height is not None:
            self.extra.frame_height = frame_height

        if meta:
            self.extra.meta.update(meta)

    def update_extra(self, extra: VideoFileExtra) -> None:
        """
        Полностью заменить объект с дополнительными данными.
        """
        self.extra = extra

class Frame:
    # старый код

    def update_data(self, data: FrameData) -> None:
        """
        Заменить данные кадра.

        Смысл:
          - кадр мог быть перекодирован,
          - к нему могла быть применена анонимизация/маскирование,
          - данные могли быть уменьшены (даунскейл, JPEG и т.п.).

        Вместо прямого присваивания снаружи, всё изменение «сырых» данных
        кадра проходит через этот метод.
        """
        self.data = data

    def is_in_time_range(self, start: datetime, end: datetime) -> bool:
        """
        Проверить, попадает ли кадр во временной интервал [start, end).
        """
        return start <= self.captured_at < end

class DetectedObject:
    # старый код

    def add_frame(self, frame_ref: FrameRef) -> None:
        """
        Зафиксировать, что объект был замечен ещё в одном кадре.
        """
        self.frames.append(frame_ref)

    def last_seen_at(self) -> Optional[datetime]:
        """
        Вернуть момент времени, когда объект был замечен последним.
        """
        if not self.frames:
            return None
        return max(ref.captured_at for ref in self.frames)

    def was_seen_in_range(self, start: datetime, end: datetime) -> bool:
        """
        Проверить, встречался ли объект в интервале [start, end).
        """
        return any(start <= ref.captured_at < end for ref in self.frames)

    def update_attributes(self, meta: Dict[str, Any]) -> None:
        """
        Обновить признаки объекта (attributes.meta).
        """
        self.attributes.meta.update(meta)

class Report:
    # старый код

    def covers_moment(self, moment: datetime) -> bool:
        """
        Проверить, относится ли указанный момент ко времени этого отчёта.
        """
        return self.time_range.start <= moment < self.time_range.end

    def overlaps_with(self, start: datetime, end: datetime) -> bool:
        """
        Проверить, пересекается ли отчёт с временным интервалом [start, end).
        """
        r_start = self.time_range.start
        r_end = self.time_range.end
        return not (end <= r_start or r_end <= start)

    def add_source_idx(self, source_idx: "RecordingSourceIdx") -> None:
        """
        Добавить источник в список «пруфов» отчёта.
        """
        if source_idx not in self.source_idx_list:
            self.source_idx_list.append(source_idx)

    def add_video_idx(self, video_idx: "VideoFileIdx") -> None:
        """
        Добавить видеозапись в список «пруфов» отчёта.
        """
        if video_idx not in self.video_idx_list:
            self.video_idx_list.append(video_idx)

    def add_object_idx(self, object_idx: "ObjectIdx") -> None:
        """
        Добавить объект в список «пруфов» отчёта.
        """
        if object_idx not in self.object_idx_list:
            self.object_idx_list.append(object_idx)