"""
抽象接口定义（面向接口编程骨架）

注意：
- 本文件只定义抽象基类（ABC），不提供任何具体实现。
- 其他模块（例如 doc_worker 适配层）应实现这些接口。
"""

from __future__ import annotations

from abc import ABC, abstractmethod
from dataclasses import dataclass
from pathlib import Path
from typing import Any, Dict, List, Optional


# ======================
# 文档输入与上下文
# ======================


@dataclass
class DocumentSource:
    """文档输入抽象，既可表示本地文件，也可表示内存字节流。"""

    path: Optional[Path] = None
    content: Optional[bytes] = None
    file_type: Optional[str] = None  # 'pdf' / 'docx' / 'doc' / 其他


class ConfigProvider(ABC):
    """配置访问接口，屏蔽具体配置系统（yaml/env/数据库等）。"""

    @abstractmethod
    def get(self, key_path: str, default: Any = None) -> Any:
        """按点号路径获取配置值，例如 'text_splitting.max_chunk_size'。"""


# ======================
# 目录相关接口
# ======================


class TOCExtractor(ABC):
    """目录提取接口（PDF / Word 等统一使用这一层）。"""

    @abstractmethod
    def extract_toc(self, source: DocumentSource) -> Dict[str, Any]:
        """
        提取目录信息。

        约定返回结构：
        {
            "toc_items": [
                {
                    "title": str,
                    "page": int | str,
                    "level": int,
                    "original": str,
                    # 可选扩展字段...
                },
                ...
            ],
            "toc_count": int,
            "toc_pages": List[int],
        }
        """


class HierarchyClassifier(ABC):
    """目录层级/章节分类接口。"""

    @abstractmethod
    def classify(self, toc_items: List[Dict[str, Any]], target_level: int) -> Dict[str, Any]:
        """
        对指定层级的目录项进行分类。

        约定返回结构（示例）：
        {
            "items": [
                {
                    "title": str,
                    "page": int | str,
                    "level": int,
                    "category": str,
                    "category_code": str,
                    # 其他统计/调试字段...
                },
                ...
            ],
            "total_count": int,
            "target_level": int,
        }
        """


# ======================
# 正文与分块接口
# ======================


class FullTextExtractor(ABC):
    """全文提取接口（按页返回文本内容）。"""

    @abstractmethod
    def extract_full_text(self, source: DocumentSource) -> List[Dict[str, Any]]:
        """
        提取全文。

        约定返回结构：
        [
            {
                "page_num": int,
                "text": str,
                "start_pos": int,
                "end_pos": int,
                "source_file": str,
            },
            ...
        ]
        """


class TextSplitter(ABC):
    """按目录层级与长度约束切分正文的接口。"""

    @abstractmethod
    def split_by_hierarchy(
        self,
        classification_items: List[Dict[str, Any]],
        pages_content: List[Dict[str, Any]],
        toc_info: Dict[str, Any],
        target_level: int,
        max_chunk_size: int,
        min_chunk_size: int,
    ) -> List[Dict[str, Any]]:
        """
        按层级与长度切分正文。

        约定 chunk 结构示例：
        {
            "file_name": str,
            "chunk_id": str,
            "section_label": str,
            "project_plan_type": str,
            "element_tag": {
                "page": int,
                "chunk_id": str,
                "serial_number": str,
            },
            "review_chunk_content": str,
            # 其他元数据...
        }
        """


# ======================
# 输出与持久化接口
# ======================


class ResultWriter(ABC):
    """结果写出接口，可以有多种实现（JSON / Markdown / DB 等）。"""

    @abstractmethod
    def write(self, result: Dict[str, Any]) -> None:
        """
        写出处理结果。

        约定 result 基本结构：
        {
            "source": DocumentSource | str,
            "toc_info": {...},
            "classification": {...},
            "chunks": [...],
            "meta": {...},
        }
        """


# ======================
# 流程接口
# ======================


class DocumentPipeline(ABC):
    """单文档处理流水线接口。"""

    @abstractmethod
    def run(
        self,
        source: DocumentSource,
        target_level: Optional[int] = None,
        max_chunk_size: Optional[int] = None,
        min_chunk_size: Optional[int] = None,
    ) -> Dict[str, Any]:
        """
        运行完整流程：目录提取 -> 分类 -> 全文提取 -> 切分 -> 聚合结果。

        返回统一结构：
        {
            "toc_info": {...},
            "classification": {...},
            "chunks": [...],
            "meta": {...},
        }
        """


class FileParseFacade(ABC):
    """对上层调用者暴露的统一入口接口。"""

    @abstractmethod
    def process_file(
        self,
        file_path: str | Path,
        target_level: Optional[int] = None,
        max_chunk_size: Optional[int] = None,
        min_chunk_size: Optional[int] = None,
    ) -> Dict[str, Any]:
        """处理单个文件并返回标准化结果。"""












