# 数据契约 — 昌平坳风电场 (farm#5, 大唐) — 明阳 MINGYANG MY2.0-class 2.0MW DFIG geared
# schema: docs/OEM_KB/OEM_knowledge_base_v1.md §3. 校验器: scripts/validate_contract.py
# 用途: 分析前的"门"。任一 BLOCK → 拒绝进分析 (不在下游补救)。
#
# 🔴 OEM 坐实方式 (无机台表/收资/曲线 → 从数据坐实, 不假设):
#   - 控制器签名: 1秒raw=英文 i* 列(WT_Runcode/SCW001-043/iListOfActiveStatuscodesToSCADA/RemCOM)
#     = 马王一期"统一SCADA"同家族(华创+明阳共用此控制器导出格式).
#   - ★ OEM 判别器 (马王实证, KB §4): 华创 iAvailabillityToday=全0死列 & iPowerLimit_Flag=恒0;
#     明阳 iAvailabillityToday=有效值 & iPowerLimit_Flag=恒10.
#     昌平坳实测: iAvailabillityToday 有效(med~80-100) + iPowerLimit_Flag=10 全25台 → **明阳固件**.
#   - 功率等级: P_max ~2100-2160kW (25台) → 额定 2.0MW; geared DFIG (GS发电~1480rpm/rotor~8.8rpm).
#   - ⚠ 机型变体 (MY2.0-110/116/121/130? 转子直径/轮毂高) = INSUFFICIENT (无机台表; SCADA不含转子直径).
#   - verdict: OEM=明阳[高置信, 判别器双中+schema+功率级]; 具体机型/转子=INSUFFICIENT.
meta:
  farm: 昌平坳风电场
  farm_code: CPA
  oem: 明阳智能 MINGYANG   # 判别器坐实, 非假设
  model: MY2.0-class (2.0MW geared DFIG; 具体变体INSUFFICIENT无机台表)
  oem_confidence: "high (固件判别器avail+PL双中 / 1秒schema同马王明阳 / 2.0MW geared)"
  topology: dfig_geared
  rated_kw: 2000          # P_max 2087-2162 实测(25台), 额定2000+overshoot
  rotor_diameter_m: null  # INSUFFICIENT 无机台表
  hub_height_m: null      # INSUFFICIENT
  n_turbines: 25          # 坐实: min层风机列27#-51# + sec设备ID 20049027..20049051 (两源一致)
  turbine_ids: "20049027 .. 20049051 (短号27-51)"
  province: null          # INSUFFICIENT (无收资表)
  sampling:
    sec_s: 1              # ★ 86400行/天/台 = 24×3600 精确1秒 (逐文件验); 同吉山一期最富档
    min_s: 600           # min/CPA{YYYYMM}.csv 月度10-min聚合(max/min/平均)
  windows:
    sec: "2024-02-17 .. 2024-05-14 (~3月, 25台, sec/两大zip+27号松散)"
    min: "2023-04 .. 2024-04 (~13月, 92列GBK)"
    overlap: "2024-02..04 (sec∩min ~2.5月)"
  met_mast: none         # 🔴 文件树无测风塔 → 自由来流不可得 → 绝对功率曲线INSUFFICIENT(同金华山尺度)
  power_curve_table: none  # 🔴 无合同/保证功率曲线 → 绝对达成率不可锚
  event_table: none      # 🔴 无事件代码定义表; 故障码解码借马王同控制器官方表(MY2.0)
  encoding: gbk
  provenance: "scripts/cpa_goem.py, cpa_goem2.py(跨25台), cpa_anom.py(异常逐日); 解码借 马王风电场故障代码表、风机状态表.xlsx(MY2.0官方)"

# ============ 1秒 raw 层 (主分析层, 209列英文 i*; 偏航/桨距/状态/振动/温度全在此) ============
turbine_1sec:
  required: [iGenPower, iWindSpeed, WT_Runcode]
  columns:
    iGenPower:
      canonical_id: WAPC_active_power
      unit: kW              # max~2160, 无瓦特陷阱
      valid_range: [-100, 2300]
      note: "min~-78电动/待机(RC3微负=噪声), clip floor -100"
    iGenSpeed:
      canonical_id: WGEN_speed
      unit: rpm
      valid_range: [0, 2100]   # 发电~1480, max~1880
      sentinel: [-100]         # ★ 罕见(turbine31等), -100=哨兵→NaN
    iRotorSpeedPDM: {canonical_id: WROT_speed, unit: rpm, valid_range: [0, 20]}  # 发电~8.8, geared比~167
    iWindSpeed:
      canonical_id: WMET_wind_speed_nacelle
      unit: m/s
      valid_range: [0, 40]
      self_ref_risk: true    # ★ 机舱风, 功率曲线自指(finding89); 无测风塔→真功率曲线不可做
    iWindSpeed_real: {canonical_id: WMET_wind_speed_nacelle_real, unit: m/s, valid_range: [0, 40], self_ref_risk: true, note: "另一机舱风源, med略高于iWindSpeed"}
    iWindSpeed1: {canonical_id: WMET_wind_speed_alt1, unit: m/s, valid_range: [0, 40], note: "≈iWindSpeed_real"}
    iWindSpeed2: {canonical_id: WMET_wind_speed_alt2, dead_channel: true}  # ★ 全0死列, 弃
    iPitchAngle1: {canonical_id: WROT_pitch_1, unit: deg, valid_range: [-2, 95], sentinel: [-10]}  # ★ -10=故障态(RC4)占位符非真角(turbine27 17%全RC4/P0/GS0)→NaN; 发电细桨~-0.5
    iPitchAngle2: {canonical_id: WROT_pitch_2, unit: deg, valid_range: [-2, 95], sentinel: [-10]}
    iPitchAngle3: {canonical_id: WROT_pitch_3, unit: deg, valid_range: [-2, 95], sentinel: [-10]}
    iVaneDiiection:          # ★ 原始拼写(Diiection); = 风向标/偏航误差
      canonical_id: WYAW_yaw_error
      unit: deg
      frame: nacelle         # ±180, 发电态中位~小角=对风良好 → 偏航对风可用(直接误差列)
      valid_range: [-180, 180]
    iwindDirection:          # ★ 0-360 真地理 (rare!)
      canonical_id: WMET_wind_direction_geo
      unit: deg
      frame: geographic
      valid_range: [0, 360]
    iNacellePositionLtd: {canonical_id: WYAW_nacelle_position, unit: deg, valid_range: [0, 360], note: "限幅0-360机舱朝向"}
    iNacellePositionTotal: {canonical_id: WYAW_nacelle_position_total, unit: deg, valid_range: [-720, 720], note: "累积含扭缆, 非heading"}
    iCableTwistTotal: {canonical_id: WYAW_cable_twist, unit: deg, valid_range: [-720, 720], note: "累积扭缆角"}
    iFiequency: {canonical_id: WGRID_frequency, unit: Hz, valid_range: [0, 55], sentinel_zero: true, note: "原始拼写; 0=脱网, ~50发电"}
    iUL1_690V: {canonical_id: WGRID_voltage_l1, unit: V, valid_range: [0, 800]}
    iUL2_690V: {canonical_id: WGRID_voltage_l2, unit: V, valid_range: [0, 800]}
    iUL3_690V: {canonical_id: WGRID_voltage_l3, unit: V, valid_range: [0, 800]}
    iIL1_690V: {canonical_id: WGRID_current_l1, unit: A, valid_range: [-10, 3000]}
    iIL2_690V: {canonical_id: WGRID_current_l2, unit: A, valid_range: [-10, 3000]}
    iIL3_690V: {canonical_id: WGRID_current_l3, unit: A, valid_range: [-10, 3000]}
    iVibrationY: {canonical_id: WNAC_vibration_y, unit: "m/s2|g", valid_range: [-5, 5], note: "中位0, ±0.2量级; level粗筛"}
    iVibrationZ: {canonical_id: WNAC_vibration_z, unit: "m/s2|g", valid_range: [-5, 5]}
    iAirDensity: {canonical_id: WMET_air_density, unit: "kg/m3", valid_range: [0.9, 1.2], note: "~1.03-1.09; 控制器算; 可归一功率曲线"}
    iPressureOutdoor: {canonical_id: WMET_pressure, dead_channel: true}   # ★ 全0死列 → 密度用iAirDensity
    iPowerLimit_Flag:
      canonical_id: WTUR_power_limit_flag
      semantic: "明阳常数=10 全25台 ≠ 限电 (C4陷阱免疫); 真限电需同步性判别+功率封顶, 非此列"
      curtailment_truth: false
    iAvailabillityToday:
      canonical_id: WTUR_avail_today
      unit: pct
      valid_range: [0, 100]
      reliability: glitchy   # 🔴🔴 turbine30/47大段=0却满发(P~2100/gen%70-100) → 不可盲信! 必交叉发电态; 本场可用率改WT_Runcode状态派生
    iAvailabillityTotal: {canonical_id: WTUR_avail_total, unit: pct, valid_range: [0, 100], note: "累积寿命可用率~70%(含投运期?); 慎用"}
    WT_Runcode:
      canonical_id: WTUR_run_code
      status_enum_ref: configs/fault_dicts/mingyang_my2_0_changpingao_runcode_enum.csv
      semantic: "★主状态源(cross-tab坐实): 3发电81%/9待风11%/2启动4%/4故障停2%/5,6,7停机/1解缆/11电网故障"
    WT_Faultcode:
      canonical_id: WTUR_fault_code
      note: "码≠官方事件代码(join key待解, 同马王); 657↔RC9待风/757↔RC4故障 = 状态reason非failure; 故障归因用WT_Runcode+iListOfActiveStatuscodesToSCADA"
    iTurbineOperationMode: {canonical_id: WTUR_op_mode, note: "SINT16另一编码: 20↔RC3发电/6↔RC9待风/1↔RC4故障/16↔RC2; 用WT_Runcode为主"}
    # 温度组 (全在1秒, CMS/部件健康)
    iTempGearOil_1sec: {canonical_id: WTRM_gearbox_oil_temp, unit: degC, valid_range: [-20, 100], note: "原列名 iTemp1GearOil_1sec"}
    iTempRotorBearA_1sec: {canonical_id: WTRM_main_bearing_temp_a, unit: degC, valid_range: [-20, 100]}
    iTempRotorBearB_1sec: {canonical_id: WTRM_main_bearing_temp_b, unit: degC, valid_range: [-20, 100]}
    iTempGenBearDE_1sec: {canonical_id: WGEN_bearing_temp_de, unit: degC, valid_range: [-20, 120]}
    iTempGenBearNDE_1sec: {canonical_id: WGEN_bearing_temp_nde, unit: degC, valid_range: [-20, 120]}
    iTempGenStatorU_1sec: {canonical_id: WGEN_stator_temp_u, unit: degC, valid_range: [-20, 180]}
    iTempGenStatorV_1sec: {canonical_id: WGEN_stator_temp_v, unit: degC, valid_range: [-20, 180]}
    iTempGenStatorW_1sec: {canonical_id: WGEN_stator_temp_w, unit: degC, valid_range: [-20, 180]}

# ============ 10-min 层 (全年2023-04→2024-04, 92列GBK中文; 长窗趋势) ============
turbine_10min:
  required: [平均功率, 平均风速(m/s)]
  columns:
    平均功率: {canonical_id: WAPC_active_power, unit: kW, valid_range: [-100, 2300]}
    平均风速(m/s): {canonical_id: WMET_wind_speed_nacelle, unit: m/s, valid_range: [0, 40], self_ref_risk: true}
    平均风角度（对北）: {canonical_id: WMET_wind_direction_geo, unit: deg, valid_range: [0, 360], frame: geographic}
    平均风向（机舱）: {canonical_id: WYAW_winddir_nacelle, unit: deg, frame: nacelle}
    平均桨叶1角度: {canonical_id: WROT_pitch_1, unit: deg, valid_range: [-10, 95]}
    平均桨叶2角度: {canonical_id: WROT_pitch_2, unit: deg, valid_range: [-10, 95]}
    平均桨叶3角度: {canonical_id: WROT_pitch_3, unit: deg, valid_range: [-10, 95]}
    平均空气密度: {canonical_id: WMET_air_density, unit: "kg/m3", valid_range: [0.9, 1.2]}
  note_10min: "🔴 92列无状态码/无限电/无可利用率 → 限电/可用率/故障归因必去1秒层(状态码只在sec). x/y振动(此层有)+全温度=长窗趋势."

cleaning:
  physical:
    - "iGenSpeed=-100 → NaN (哨兵)"
    - "iPitchAngle{1,2,3}=-10 → NaN (故障态RC4占位符, 非真角)"
    - "iGenPower clip [-100,2300]; iFiequency=0=脱网(保留, 状态用)"
    - "温度物理界 clip + 罕见坏点<0.01% → NaN"
  semantic:
    - "iPowerLimit_Flag=10 ≠ 限电 (明阳常数); 勿当弃风 (C4陷阱)"
    - "iAvailabillityToday glitchy(报0却发电) → 可用率改 WT_Runcode 状态派生, 不用内置"
    - "iWindSpeed/iWindSpeed_real/1 = 机舱风 self_ref → 不做绝对功率曲线 (无测风塔)"
    - "iPressureOutdoor/iWindSpeed2 = 死列, 弃"

traps:
  - "★★ 内置可利用率 glitchy: turbine30/47 大段iAvailabillityToday=0却满发 → '内置可利用率优先'资产必加'先验真(交叉发电态)'前置, 本场改状态派生"
  - "★ pitch=-10 = 故障态(RC4)哨兵非真角(turbine27 17%); 集距死全场(spread p95=0)→不平衡只能振动"
  - "★ turbine39 间歇降额(3月-4月初 P_max~1500, 但02-17/04-10/05-08满2160) = 降额候选, 非1.5MW混型 (单日快照差点误判混型 → 异常台必逐日核)"
  - "★ 无测风塔+无合同曲线 → 绝对功率曲线/绝对达成率 INSUFFICIENT (机舱风self_ref, 同金华山尺度hedging)"
  - "★ 限电无ground truth列(iPowerLimit_Flag假/无集控状态) → 用同步性判别器(全场同时停+频率)+功率封顶, 不臆断"
  - "★ WT_Faultcode≠官方事件代码; 故障归因用WT_Runcode状态+iListOfActiveStatuscodesToSCADA_H/L栈"
  - "Feb26-27 多台全天0出力 → 疑站级事件, 分析时查同步性"
  - "iAvailabillityTotal~70%累积(含投运?) ≠ 运营期可用率, 慎引"