from __future__ import annotations

from typing import Protocol

from app.features.personalized_reco.content_repository.types import ContentProfileDTO


class ContentRepository(Protocol):
    """
    推荐引擎依赖的内容数据访问抽象接口（用于解耦 ORM/SQL）。
    """

    async def fetch_candidates(
        self,
        *,
        scene: str,
        user_profile: object,
        fallback_level: int,
        limit: int,
        locale: str,
        exclude_content_ids: list[int] | None = None,
    ) -> list[ContentProfileDTO]:
        """
        按场景与用户画像拉取候选内容画像（用于候选池）。
        """

    async def fetch_contents_by_ids(
        self,
        *,
        content_ids: list[int],
        locale: str,
    ) -> list[ContentProfileDTO]:
        """
        按 content_id 批量获取内容画像（去重、按输入顺序返回；缺语言/缺记录的 id 跳过）。
        """