"""Pydantic models for the ingest (document ingestion) API.

文档入库接口的请求/响应数据模型。
定义入库触发请求体和任务状态响应体。
"""

from __future__ import annotations

from typing import Any

from pydantic import BaseModel, Field


class IngestRequest(BaseModel):
    """Payload for ``POST /ingest/trigger``."""

    doc_id: str = Field(..., description="唯一文档标识")
    file_path: str = Field("", description="文件路径（相对于 file_storage_path）")
    metadata: dict[str, Any] = Field(default_factory=dict, description="附加元数据")


class IngestStatus(BaseModel):
    """Status report for a running / completed ingest task."""

    task_id: str
    status: str = Field(..., description="PENDING | PROCESSING | COMPLETED | PARTIAL_FAILED | FAILED | REVOKED")
    progress: float = Field(0.0, ge=0.0, le=1.0, description="0.0 – 1.0 进度")
    error: str | None = Field(None, description="错误信息（仅当 status=FAILURE）")
    deduplicated: bool = Field(False, description="是否通过去重快速路径处理")
    content_hash: str | None = Field(None, description="内容哈希（MD5）")