"""
向量存储抽象基类

定义向量存储的统一接口，所有向量存储后端必须实现这些方法。
"""
import logging
from abc import ABC, abstractmethod
from dataclasses import dataclass, field
from typing import Any, Dict, List, Optional

logger = logging.getLogger(__name__)


@dataclass
class VectorPoint:
    """向量数据点"""
    id: str
    vector: List[float]
    payload: Dict[str, Any] = field(default_factory=dict)


@dataclass
class VectorSearchResult:
    """向量搜索结果"""
    id: str
    score: float
    payload: Dict[str, Any] = field(default_factory=dict)


class BaseVectorStore(ABC):
    """
    向量存储抽象基类
    
    每个知识库对应一个 collection，collection 名称格式: kb_{knowledge_base_id}
    """

    @staticmethod
    def collection_name(knowledge_base_id: str) -> str:
        """生成 collection 名称"""
        return f"kb_{knowledge_base_id.replace('-', '_')}"

    @abstractmethod
    async def ensure_collection(
        self,
        knowledge_base_id: str,
        vector_size: int,
    ) -> None:
        """
        确保 collection 存在，不存在则创建
        
        Args:
            knowledge_base_id: 知识库 ID
            vector_size: 向量维度
        """
        ...

    @abstractmethod
    async def delete_collection(self, knowledge_base_id: str) -> None:
        """
        删除 collection（删除知识库时调用）
        
        Args:
            knowledge_base_id: 知识库 ID
        """
        ...

    @abstractmethod
    async def upsert(
        self,
        knowledge_base_id: str,
        points: List[VectorPoint],
    ) -> None:
        """
        批量写入/更新向量
        
        Args:
            knowledge_base_id: 知识库 ID
            points: 向量数据点列表
        """
        ...

    @abstractmethod
    async def delete(
        self,
        knowledge_base_id: str,
        point_ids: List[str],
    ) -> None:
        """
        批量删除向量
        
        Args:
            knowledge_base_id: 知识库 ID
            point_ids: 要删除的向量 ID 列表
        """
        ...

    @abstractmethod
    async def search(
        self,
        knowledge_base_id: str,
        query_vector: List[float],
        top_k: int = 10,
        score_threshold: float = 0.0,
        filter_conditions: Optional[Dict[str, Any]] = None,
    ) -> List[VectorSearchResult]:
        """
        向量相似度搜索
        
        Args:
            knowledge_base_id: 知识库 ID
            query_vector: 查询向量
            top_k: 返回数量
            score_threshold: 最低相似度阈值
            filter_conditions: 过滤条件（如 {"document_id": "xxx"}）
            
        Returns:
            搜索结果列表，按相似度降序排列
        """
        ...

    @abstractmethod
    async def delete_by_filter(
        self,
        knowledge_base_id: str,
        filter_conditions: Dict[str, Any],
    ) -> None:
        """
        按条件删除向量（如删除某个文档的所有向量）
        
        Args:
            knowledge_base_id: 知识库 ID
            filter_conditions: 过滤条件（如 {"document_id": "xxx"}）
        """
        ...

    async def health_check(self) -> bool:
        """健康检查"""
        return True
