# 数据契约 — 国电 GUP UP2000 2.0MW DFIG (阜山)
# schema: docs/OEM_KB/OEM_knowledge_base_v1.md §3. 校验器: scripts/validate_contract.py
# 用途: 分析前的"门"。任一 BLOCK 级违规 → 拒绝进分析 (不在下游补救)。
meta:
  oem: 国电联合动力 GUP
  model: UP2000 2.0MW DFIG
  topology: dfig_geared
  rated_kw: 2080
  source_farm: 阜山 (A01-A18)
  sampling:
    default_s: 600          # 真实=混采
    caveat: "10月=1s, 其余=10min; 必逐时段 t.diff() 测, 全局 median 会撒谎"
  provenance: "outputs/fushan/阜山_测风塔集成.md; findings 87-91"

# ---- 机组 SCADA (raw 列名来自 GBK CSV) ----
turbine:
  required: [变频器有功, 风速1, 功率设定]
  columns:
    变频器有功:
      canonical_id: WAPC_active_power
      raw_unit: W                 # ★ 陷阱: 原始是瓦特, 非 kW
      to_canonical: "/1000"       # → kW
      valid_range_canonical: [0, 2200]   # kW (校验在换算后值上跑)
      block_if_raw_exceeds: 50000        # raw>5e4 = 仍是瓦特未换算 → BLOCK
    风速1:
      canonical_id: WMET_wind_speed_nacelle
      unit: m/s
      valid_range: [0, 40]
      self_ref_risk: true          # ★ 机舱风, 功率曲线自指 (finding 89)
    风速2:
      canonical_id: WMET_wind_speed_2
      unit: m/s
      dead_channel: true           # ★ 中位 0.46 = 死通道, 弃
    风向1:
      canonical_id: WYAW_yaw_error
      raw_unit: rad                # ★ 弧度 ±π, 非度
      to_canonical: "*57.2958"
      frame: nacelle               # ★ nacelle-frame, 非地理 → 偏航不可作地理扇区
      valid_range_canonical: [-180, 180]
    功率设定:
      canonical_id: WAPC_setpoint
      raw_unit: W
      to_canonical: "/1000"
      semantic: "<额定 = 限电标志 (已校正 kW 后比)"
    机舱位置:
      canonical_id: WYAW_nacelle_position
      frame: na                    # ★ 范围 -5.7~10.7 非航向 → 不可用
      unusable: true

# ---- 测风塔 (raw 列名来自 utf-8 CSV; cache: fushan_mast.parquet) ----
mast:
  required: [ws_free, rho]
  columns:
    ws_free:
      canonical_id: WMET_free_stream_ws
      unit: m/s
      valid_range: [0, 40]
      sentinel: [-99]              # ★ -99 哨兵 (72.8% 行); 未转 NaN = BLOCK
      frame: geographic
      note: "仅 Oct16-Jan 有效; 缺失(NaN)可接受, 但残留 -99 字面值不可接受"
    wdir_geo:
      canonical_id: WMET_free_stream_wdir
      unit: deg
      valid_range: [0, 360]
      sentinel: [-99]
      frame: geographic
    baro_kpa:
      canonical_id: WMET_pressure
      unit: kPa
      valid_range: [80, 110]       # ★ 有 ×10 污染子集(~1000), 越界 → 该行 rho 不可信
    temp:
      canonical_id: WMET_ambient_temp
      unit: degC
      valid_range: [-40, 50]
    rho:
      canonical_id: WMET_air_density
      unit: kg/m3
      valid_range: [0.90, 1.45]    # ★ 物理门; 未门 → 13.5 (baro 污染传导)

# ---- 跨表清洗规则 ----
cleaning:
  physical:
    - "哨兵 -99 → NaN (ws_free/wdir_geo)"
    - "baro ∉[80,110] → 该行 rho 置 NaN"
    - "rho 物理门 [0.90,1.45]"
  semantic:
    - "功率设定 < 额定 = 限电 (非坏值)"
    - "风速2 死通道 直接弃, 勿当缺失填补"
traps:
  - "变频器有功=瓦特: 盲用差 1000 倍 (险酿大错)"
  - "采样混采: 全局 median t.diff()=1s 是 98% 行来自10月的假象"
  - "单 mast: 机舱风/自由来流比 ±9% → 立方 ±27% 功率, 不下绝对性能 (finding 89)"