"""Pydantic models for the document detail API.

文档详情接口的请求/响应数据模型。
定义文档元数据详情、版本列表、知识子图节点/边等结构。
"""

from __future__ import annotations

from datetime import date, datetime
from typing import Any

from pydantic import BaseModel, Field


class RelatedDoc(BaseModel):
    """A document related to the current one (正文 or 附件)."""

    doc_id: str
    title: str = ""
    relation_type: str = Field("附件", description="关系类型：正文 | 附件")


class RelatedDocsUpdateRequest(BaseModel):
    """Request body for updating related documents (全量声明式)."""

    related_docs: list[RelatedDoc] = Field(default_factory=list)


class RelatedDocsWarning(BaseModel):
    """A single warning from related docs sync."""

    doc_id: str = ""
    code: str = Field("", description="SELF_REFERENCE | DUPLICATE | TARGET_NOT_FOUND | TARGET_UPDATE_FAILED | SYNC_EXCEPTION")
    reason: str = ""


class RelatedDocsSyncResponse(BaseModel):
    """Response for PUT /{doc_id}/related-docs."""

    doc_id: str
    related_docs: list[RelatedDoc] = Field(default_factory=list)
    affected_doc_ids: list[str] = Field(default_factory=list, description="实际成功写入的目标文档 ID")
    warnings: list[RelatedDocsWarning] = Field(default_factory=list)


class DocumentDetail(BaseModel):
    """Full metadata view of a single document."""

    doc_id: str
    content_hash: str = ""
    title: str
    doc_number: str | None = None
    issuing_org: str | None = None
    doc_type: str | None = None
    knowledge_category: str | None = None
    subject_words: list[str] = Field(default_factory=list)
    signer: str | None = None
    publish_date: date | None = None
    summary: str | None = None
    chunk_count: int | None = 0
    page_count: int | None = 0
    file_path: str | None = None
    file_type: str | None = None
    source_system: str | None = None
    source_article_id: str | None = None
    source_attachment_id: str | None = None
    source_site_code: str | None = None
    source_target_code: str | None = None
    source_url: str | None = None
    source_metadata: dict[str, Any] = Field(default_factory=dict)
    related_docs: list[RelatedDoc] = Field(default_factory=list, description="关联文件列表")
    created_at: datetime | None = None
    updated_at: datetime | None = None


class DocumentVersion(BaseModel):
    """A single document version sharing the same content."""

    doc_id: str
    title: str
    doc_number: str | None = None
    issuing_org: str | None = None
    doc_type: str | None = None
    publish_date: date | None = None
    signer: str | None = None


class VersionListResponse(BaseModel):
    """Response for ``GET /document/versions/{content_hash}``."""

    content_hash: str
    versions: list[DocumentVersion]
    total: int


class GraphNode(BaseModel):
    """A single node in a document's knowledge sub-graph."""

    id: str
    labels: list[str]
    properties: dict[str, Any] = Field(default_factory=dict)
    x: float | None = None
    y: float | None = None


class GraphEdge(BaseModel):
    """A directed edge in the knowledge sub-graph."""

    source: str
    target: str
    type: str
    properties: dict[str, Any] = Field(default_factory=dict)


class GraphSubData(BaseModel):
    """Sub-graph structure returned for a document."""

    nodes: list[GraphNode] = Field(default_factory=list)
    edges: list[GraphEdge] = Field(default_factory=list)