"""续审 Agent 的结构化输出 schema（ARCH §5.4 continuity 行 / §6.1 冲突分类）。

snake_case，Pydantic v2。网关经 instructor 保证产出符合这些 schema（C1/§4.4）。

不变量 #3：四审只读——审稿期只产**冲突清单**，不产 digest（digest 在验收时
从终稿另提，见不变量 #4 / ARCH §5.5）。
"""

from __future__ import annotations

from typing import Literal

from pydantic import BaseModel, Field

# ARCH §6.1 五类冲突；受限枚举，便于前端就地裁决分类与统计。
ConflictType = Literal[
    "性格漂移",
    "能力不符",
    "设定违例",
    "地理矛盾",
    "时间线倒错",
]


class Conflict(BaseModel):
    """单条一致性冲突（ARCH §6.1）。"""

    type: ConflictType = Field(description="冲突分类（五类之一）")
    where: str = Field(description="本章定位：哪一段/哪句触发冲突")
    refs: list[str] = Field(
        default_factory=list,
        description="冲突来源引用：相关章节号、设定项或人物卡条目",
    )
    suggestion: str = Field(description="改法建议")


class ContinuityReview(BaseModel):
    """续审结构化产出：仅冲突清单（无 digest）。

    digest 不在审稿期产——那是验收时从**终稿**另提（不变量 #4）。
    """

    conflicts: list[Conflict] = Field(
        default_factory=list,
        description="检出的一致性冲突；无冲突时为空列表",
    )