from dataclasses import dataclass, field
from typing import Optional

@dataclass
class PipelineDefinition:
    """流水线定义——YAML 文件的 Python 对象表示"""

    name: str                                   # 流水线名称
    steps: list["StepDefinition"]              # 步骤列表
    description: str = ""                       # 流水线描述
    crs: Optional[str] = None                  # 全局 CRS
    variables: dict = field(default_factory=dict)  # 变量字典
    outputs: dict = field(default_factory=dict)    # 输出配置

PipelineDefinition(
    name="城市绿地分析",
    description="分析城市绿地覆盖率",
    crs="EPSG:4326",
    variables={
        "buffer_distance": 500,
        "min_area": 100,
    },
    steps=[
        StepDefinition(id="read_data", use="io.read_vector", ...),
    ],
    outputs={
        "result": "$steps.analysis_result",
    },
)

@dataclass
class StepDefinition:
    """步骤定义——单个处理步骤的声明"""

    id: str                         # 步骤唯一标识
    use: str                        # 步骤类型（注册表 ID）
    params: dict = field(default_factory=dict)   # 参数字典
    when: Optional[str] = None      # 条件表达式
    on_error: str = "fail"          # 错误处理策略
    backend: Optional[str] = None   # 指定后端

@dataclass
class StepResult:
    """步骤执行结果"""

    output: Any = None              # 输出数据
    stats: dict = field(default_factory=dict)     # 统计信息
    metadata: dict = field(default_factory=dict)  # 元数据
    issues: list = field(default_factory=list)    # QC 问题列表

    def __getattr__(self, name):
        """魔法方法：允许通过属性访问 stats 和 metadata

        使得 result.feature_count 等价于
        result.stats.get("feature_count")
        """
        if name.startswith("_"):
            raise AttributeError(name)

        # 先查 stats
        if name in self.stats:
            return self.stats[name]

        # 再查 metadata
        if name in self.metadata:
            return self.metadata[name]

        raise AttributeError(
            f"'StepResult' has no attribute '{name}'"
        )

    def summary(self):
        """生成结果摘要字符串"""
        parts = [f"StepResult:"]

        if self.output is not None:
            output_type = type(self.output).__name__
            parts.append(f"  output: {output_type}")

        if self.stats:
            parts.append(f"  stats: {self.stats}")

        if self.issues:
            parts.append(f"  issues: {len(self.issues)} issue(s)")

        return "\n".join(parts)

result = StepResult(
    output=gdf,
    stats={"feature_count": 500, "total_area": 12345.6},
    metadata={"crs": "EPSG:4326"},
)

# 直接属性访问（通过 __getattr__）
result.feature_count   # → 500（从 stats 获取）
result.total_area      # → 12345.6（从 stats 获取）
result.crs             # → "EPSG:4326"（从 metadata 获取）

# 等价的显式访问
result.stats["feature_count"]    # → 500
result.metadata["crs"]           # → "EPSG:4326"

result = StepResult(
    output=gdf,
    stats={"feature_count": 500, "issue_count": 3},
    issues=[QcIssue(...), QcIssue(...), QcIssue(...)],
)

print(result.summary())
# StepResult:
#   output: GeoDataFrame
#   stats: {'feature_count': 500, 'issue_count': 3}
#   issues: 3 issue(s)

from dataclasses import dataclass, field
from typing import Any, Optional

@dataclass
class QcIssue:
    """质检问题数据模型

    记录单个质检发现的问题，包含问题位置、
    严重级别和诊断详情。
    """

    rule_id: str                          # 规则标识
    severity: str                         # 严重级别
    feature_index: Optional[int] = None   # 要素索引
    message: str = ""                     # 问题描述
    geometry: Any = None                  # 问题几何
    details: dict = field(default_factory=dict)  # 扩展详情

    def to_dict(self):
        """序列化为字典（JSON 兼容）"""
        d = {
            "rule_id": self.rule_id,
            "severity": self.severity,
            "message": self.message,
        }

        if self.feature_index is not None:
            d["feature_index"] = self.feature_index

        if self.geometry is not None:
            d["geometry"] = self.geometry.wkt

        if self.details:
            d["details"] = self.details

        return d

issue = QcIssue(
    rule_id="attribute_completeness",
    severity="error",
    feature_index=42,
    message="Field 'name' is null or empty",
    geometry=Point(116.39, 39.91),
    details={"field": "name", "value": None},
)

issue.to_dict()
# {
#     "rule_id": "attribute_completeness",
#     "severity": "error",
#     "feature_index": 42,
#     "message": "Field 'name' is null or empty",
#     "geometry": "POINT (116.39 39.91)",
#     "details": {"field": "name", "value": null}
# }

@dataclass
class StepInfo:
    """步骤注册元数据"""

    id: str                     # 步骤 ID（如 "vector.buffer"）
    name: str                   # 步骤显示名称
    description: str = ""       # 步骤描述
    category: str = ""          # 分类（如 "vector", "io", "qc"）
    params: list = field(default_factory=list)    # 参数定义列表
    input_type: str = ""        # 输入类型
    output_type: str = ""       # 输出类型

    def get_param(self, name):
        """根据名称获取参数定义"""
        for p in self.params:
            if p.get("name") == name:
                return p
        return None

    def to_dict(self):
        """序列化为字典"""
        return {
            "id": self.id,
            "name": self.name,
            "description": self.description,
            "category": self.category,
            "params": self.params,
            "input_type": self.input_type,
            "output_type": self.output_type,
        }

{
    "name": "distance",        # 参数名
    "type": "number",          # 参数类型
    "required": True,          # 是否必需
    "default": None,           # 默认值
    "description": "缓冲距离",  # 参数描述
}

from geopipeagent.registry import step

@step(
    id="vector.buffer",
    name="缓冲区分析",
    description="为几何要素创建缓冲区",
    category="vector",
    params=[
        {"name": "input", "type": "geodataframe", "required": True},
        {"name": "distance", "type": "number", "required": True},
        {"name": "resolution", "type": "integer", "required": False,
         "default": 16},
    ],
    input_type="geodataframe",
    output_type="geodataframe",
)
def buffer(ctx):
    ...

# 装饰器自动生成并绑定 StepInfo
buffer.step_info
# StepInfo(
#     id="vector.buffer",
#     name="缓冲区分析",
#     ...
# )

info = buffer.step_info
info.to_dict()
# {
#     "id": "vector.buffer",
#     "name": "缓冲区分析",
#     "description": "为几何要素创建缓冲区",
#     "category": "vector",
#     "params": [
#         {"name": "input", "type": "geodataframe", "required": true},
#         {"name": "distance", "type": "number", "required": true},
#         {"name": "resolution", "type": "integer", "required": false,
#          "default": 16},
#     ],
#     "input_type": "geodataframe",
#     "output_type": "geodataframe"
# }

# 步骤定义中
{"name": "input", "type": "geodataframe", "required": True}

# YAML 中的使用
params:
  input: "$steps.read_data"   # 引用另一步骤的 GeoDataFrame 输出

# 步骤函数中的获取
gdf = ctx.input("input")      # → GeoDataFrame 对象

raster_info = {
    "data": np.ndarray,           # 栅格数据数组 (bands, height, width)
    "transform": Affine,          # 仿射变换矩阵
    "crs": CRS,                   # 坐标参考系
    "profile": {                  # rasterio profile
        "driver": "GTiff",
        "dtype": "float32",
        "width": 1000,
        "height": 1000,
        "count": 1,               # 波段数
        "crs": CRS,
        "transform": Affine,
        "nodata": -9999,
    },
    "path": str | None,           # 源文件路径
}