"""LangGraph 共享状态定义。

所有节点都读写 AgentState。键全部 optional（total=False），
因此单个节点崩溃 / 返回空时不会破坏整图，下游可用上一节点的残余数据继续。
"""
from typing import TypedDict, List, Dict, Any, Optional


class AgentState(TypedDict, total=False):
    # —— 路由 / 配置 ——
    country: str                                   # 当前处理的国家代码（US/GB/JP/AU）
    config: Dict[str, Any]                         # 全局配置（config.yaml）
    country_config: Dict[str, Any]                 # 该国合并后的配置（全局 + configs/countries/*.yaml + prompts/<country>/aesthetics.yaml）
    prompts_dir: str                               # prompts/<country> 绝对路径
    output_dir: str                                # output/<country> 绝对路径
    cache_dir: str                                 # output/<country> 根目录（采集缓存/去重/简报缓存）
    task_timestamp: str                            # 任务开始时间戳（OSS 路径段 / 产物文件夹名）
    oss_seq: int                                   # 货号计数（000 起，最多 999）
    base_image: str                                # 平铺衣服底图路径（可选，印图用）

    # —— 流水线数据（逐节点累积）——
    raw_rows: List[Dict[str, Any]]                 # fetch 产出：各源原始行（统一格式）
    filtered_rows: List[Dict[str, Any]]            # filter 产出：去黑名单/人名/泛词后
    scored_rows: List[Dict[str, Any]]              # score 产出：归一化 + 融合 + 综合分
    screened: List[Dict[str, Any]]                 # screen 产出：合规风险 + 结构化四要素
    briefs: List[Dict[str, Any]]                   # prompt_build 产出：含最终 image/wearable/composite 提示词
    composite: List[Dict[str, Any]]                # compose 产出：封装提示词包（= briefs 子集，便于下游印图）
    designs: List[Dict[str, Any]]                  # compose 产出：纯印花设计稿 [{topic, path}]（product 用它做图2）
    product: List[Dict[str, Any]]                  # product 产出：产品图生成（SPU/SKU/底图/印花/模特合成）
    seed_words: Dict[str, Any]                     # seed 产出：动态种子词（含 llm_style_seeds / llm_related_seeds）

    # —— 可观测性 ——
    errors: List[Dict[str, Any]]                   # 各节点兜底捕获的错误：{node, type, message, trace}
    stats: Dict[str, Any]                          # 各阶段统计：{fetch, filter, score, screen, prompt, compose}
