# =============================================================================
# 企微IT智能服务台 — Neo4j 图节点/关系 Pydantic 模型
# =============================================================================
# 说明：定义 Neo4j 图数据库中节点和关系的 Pydantic 数据模型，
#   用于图数据的序列化、验证和传输。
#
# 图 Schema 对齐：复杂场景重构 v1.1 TeliChat 白盒模型
#   节点：Issue(问题) / Action(动作) / Info(信息项) / Session(会话)
#   关系：LEADS_TO / RELATES_TO / HAS_ACTION / PROVIDED / CORRECTED_TO
#
# 命名映射约定（§8.1）：
#   Issue.name    → Issue.name    (完全对齐)
#   Issue.category → Issue.category (完全对齐)
#   Action.name   → Action.name   (完全对齐)
#   RELATES_TO    → CAN_JUMP_TO   (语义简化)
# =============================================================================

from datetime import datetime
from typing import Any, Dict, List, Optional

from pydantic import BaseModel, Field


class IssueNode(BaseModel):
    """Neo4j Issue 节点模型 — 对应 :Issue 标签。

    表示 IT 问题域中的问题描述，是知识图谱的核心节点类型。
    通过 MERGE name 实现幂等去重。

    Attributes:
        uuid: 节点唯一标识（Neo4j 自动生成 UUID）
        name: 问题名称（唯一业务键，如"VPN问题"）
        category: 问题分类（硬件/软件/网络/安全/账号/其他）
        created_at: 创建时间
        updated_at: 更新时间
        source_suggestion_id: 来源建议ID（关联 KnowledgeSuggestion）
    """

    uuid: str = Field(default="", description="节点唯一标识（Neo4j UUID）")
    name: str = Field(..., description="问题名称（业务唯一键）", max_length=256)
    category: str = Field(default="其他", description="问题分类", max_length=64)
    created_at: Optional[datetime] = Field(default=None, description="创建时间")
    updated_at: Optional[datetime] = Field(default=None, description="更新时间")
    source_suggestion_id: Optional[str] = Field(
        default=None, description="来源建议ID（关联 KnowledgeSuggestion）"
    )


class ActionNode(BaseModel):
    """Neo4j Action 节点模型 — 对应 :Action 标签。

    表示针对 Issue 的具体解决方案/动作。
    与 Issue 通过 LEADS_TO 关系关联。

    Attributes:
        uuid: 节点唯一标识
        name: 动作名称（唯一业务键，如"个人VPN开通"）
        description: 动作描述
        created_at: 创建时间
        source_suggestion_id: 来源建议ID
    """

    uuid: str = Field(default="", description="节点唯一标识")
    name: str = Field(..., description="动作名称（业务唯一键）", max_length=256)
    description: str = Field(default="", description="动作描述")
    created_at: Optional[datetime] = Field(default=None, description="创建时间")
    source_suggestion_id: Optional[str] = Field(
        default=None, description="来源建议ID"
    )


class InfoNode(BaseModel):
    """Neo4j Info 节点模型 — 对应 :Info 标签。

    表示信息项节点，借鉴 TeliChat 信息项修饰机制。
    六种修饰：固定/增量/明确/隐含/复述/必需。

    Attributes:
        uuid: 节点唯一标识
        name: 信息项名称
        value: 信息项值
        modifiers: 修饰符列表
        created_at: 创建时间
    """

    uuid: str = Field(default="", description="节点唯一标识")
    name: str = Field(..., description="信息项名称", max_length=256)
    value: str = Field(default="", description="信息项值")
    modifiers: List[str] = Field(
        default_factory=list,
        description="修饰符列表：固定/增量/明确/隐含/复述/必需",
    )
    created_at: Optional[datetime] = Field(default=None, description="创建时间")


class RelationEdge(BaseModel):
    """Neo4j 关系边模型 — 对应图中的关系。

    表示两个节点之间的有向关系边。
    支持 Issue→Issue、Issue→Action 等多种关系类型。

    Attributes:
        from_uuid: 起始节点 uuid
        to_uuid: 目标节点 uuid
        type: 关系类型（LEADS_TO / RELATES_TO / CAN_JUMP_TO）
        order: 排序序号
        weight: 关系权重（0.0-1.0）
    """

    from_uuid: str = Field(..., description="起始节点 uuid")
    to_uuid: str = Field(..., description="目标节点 uuid")
    type: str = Field(default="LEADS_TO", description="关系类型")
    order: int = Field(default=0, description="排序序号", ge=0)
    weight: float = Field(default=1.0, description="关系权重", ge=0.0, le=1.0)