"""接入适配器基类与通用数据结构。"""

from __future__ import annotations

import uuid
from abc import ABC, abstractmethod
from dataclasses import dataclass, field

from sqlalchemy.orm import Session

from app.datahub.models import Entity, EntityRelationship, MetricEvent


@dataclass
class IngestResult:
    """单次适配器执行的输出汇总。"""

    entities: list[Entity] = field(default_factory=list)
    relationships: list[EntityRelationship] = field(default_factory=list)
    metric_events: list[MetricEvent] = field(default_factory=list)
    row_count: int = 0
    error_count: int = 0


class BaseAdapter(ABC):
    """接入适配器抽象基类。

    每个源明细表实现一个子类，负责将 staging 行映射到本体层。
    """

    # 子类须指定所适配的源系统标识（如 "BSS", "ERP"）
    source_system: str = ""
    # 子类须指定所适配的 staging 表名
    staging_table: str = ""

    @abstractmethod
    def ingest(
        self,
        session: Session,
        data_version_id: uuid.UUID | None = None,
        batch_size: int = 1000,
    ) -> IngestResult:
        """从 staging 表读取未处理行，映射写入本体层。

        Args:
            session: 数据库会话
            data_version_id: 当前批次的数据版本 ID
            batch_size: 每批处理行数

        Returns:
            IngestResult 汇总
        """
        ...