"""大纲生成端点的请求/响应 schema（C3 扩 / ARCH §5.4, §7.2）。

snake_case；前端经 OpenAPI 生成 TS 类型消费（改字段 → 前端 `pnpm gen:api`）。
大纲生成是**作者显式动作**（不变量 #3：outliner `writes=["outline"]` 声明经此端点落地，
非 AI 静默写其它表）。窗口字段供前端 T3.6 渲染伏笔窗口徽标。
"""

from __future__ import annotations

from pydantic import BaseModel, Field


class OutlineGenerateRequest(BaseModel):
    """POST /projects/:id/outline：触发大纲生成 + 持久化。

    M3 简单分卷：`volume` 缺省=1（schema 无逐章卷号；本端点把整批章节落到同一卷）。
    """

    volume: int = Field(default=1, ge=1, description="本批大纲所属卷号（M3 默认全卷 1）")


class ForeshadowWindowView(BaseModel):
    """单章关联的伏笔回收窗口（snake_case；形对齐 `ww_agents.ForeshadowWindow`）。"""

    code: str
    plant_chapter: int | None = None
    expected_close_from: int | None = None
    expected_close_to: int | None = None


class OutlineChapterView(BaseModel):
    """单章大纲视图：章号 + 卷 + 节拍 + 伏笔窗口。"""

    no: int
    volume: int
    beats: list[str] = Field(default_factory=list)
    foreshadow_windows: list[ForeshadowWindowView] = Field(default_factory=list)


class OutlineResponse(BaseModel):
    """大纲生成响应：逐章已持久化的大纲（含窗口，供前端 T3.6）。"""

    chapters: list[OutlineChapterView] = Field(default_factory=list)