# 数据契约 — 华创 HUACHUANG CCWE-2000/116 (马王 一期, 2.0MW)
# schema: docs/OEM_KB/OEM_knowledge_base_v1.md §3. 校验器: scripts/validate_contract.py
# 用途: 分析前的"门"。任一 BLOCK → 拒绝进分析 (不在下游补救)。
#
# ⚠ 马王=3 OEM 90台混场 (app_ETL/configs/contracts/mawang_machine_map.csv):
#   一期 华创 CCWE-2000/116 ×8(机号1-3,5-9) [本契约] + 明阳 MY2.0-121/80 ×42(4,10-50)
#   二期 上海电气 W2500-135 ×40(51-90, 2.5MW)
# 华创/明阳 共用 一期统一 SCADA (294列1秒 schema 相同), 但 状态enum/功率曲线/单位细节 per-OEM 不同, 已实证 → 必分契约。
# 本契约源自: scripts/mw_hc_goem.py (8台13M行 G-OEM) + mw_hc_powercurve_check.py + mw_hc_peek/compare (10min).
meta:
  oem: 华创风能 HUACHUANG (CCWE)
  model: CCWE-2000/116           # 收资表机型; /116 = 转子直径 116m
  topology: unverified           # 收资表未给传动型式 (待厂家手册); 暂不假设 DFIG/直驱
  rated_kw: 2000
  rotor_diameter_m: 116
  hub_height_m: null             # 收资表未给, 待 GPS 布置图/手册核
  source_farm: 马王 (广西; 华创机号 1-3,5-9 = 第一回集电独立区)
  units_count: 8
  device_id_map: "机号N ↔ raw 20146{N:03d} (N∈{1,2,3,5,6,7,8,9}); 机号4,10=明阳(同zip,排除)"
  sampling:
    raw_1sec_s: 1               # 1-10号风机.zip 内 20146{001-003,005-009}_YYYYMMDD.csv.gz; 294列英文; 8台全1.0s实测
    yearly_10min_s: 600         # 收资表/一期/华创2023年10分钟数据.csv; 全年2023; 6列中文
    window_1sec: "2023-12-15 09:24 → 2024-01-03 23:59 (20天, 8台一致; ⚠订正: 明阳契约曾写~22天, 实测20天)"
    caveat: "1秒仅20天冬窗(Dec-Jan); 10min全年2023. 偏航/桨距/状态只在1秒层; 10min无."
  provenance: "无官方华创状态/功率曲线表 (官方xlsx仅明阳); 状态enum=行为自解 (configs/fault_dicts/huachuang_ccwe2000_status_enum_mawang.csv)"
  power_curve_ref: "收资表 2.0MW 功率曲线表 (1.18场站密度+1.225标准); 名义适用一期全部, 但华创冬窗实测 nac_ws12 仅~80% → 见 traps (窗口/季节/self_ref 混淆, 未坐实欠发)"

# ============ 全年 10-min 层 (full-year primary; 收资表 6列) ============
turbine:
  required: ["平均功率(kW)", "平均风速(m/s)"]    # ★ 真实列名带半角括号(实测对齐)
  columns:
    "平均功率(kW)":
      canonical_id: WAPC_active_power
      unit: kW                       # max~2046 (额定2000✓), 无瓦特陷阱
      valid_range: [-100, 2200]
    "平均风速(m/s)":
      canonical_id: WMET_wind_speed_nacelle
      unit: m/s
      valid_range: [0, 40]
      self_ref_risk: true            # ★ 机舱风, 功率曲线自指 (finding 89); 真功率曲线必测风塔
    "平均风向（机舱）":                # ★ 风向列名用全角括号（机舱）(实测, 异于功率/风速半角)
      canonical_id: WYAW_nacelle_winddir
      unit: deg
      frame: nacelle                 # ★ ±180 机舱坐标, 非地理; 10-min 不做偏航
      valid_range: [-180, 180]
    平均塔基温度: {canonical_id: WNAC_tower_base_temp, unit: degC, valid_range: [-20, 80]}
  note_10min: "6列(时间/风机/平均功率(kW)/平均风速(m/s)/平均风向（机舱,全角括号）/平均塔基温度); 无哨兵, P min=-1≈idle. 无桨距/偏航误差/状态码 → 深挖回1秒. ⚠列名括号半/全角混用. 文件名带导出日2023-12-17但实为全年(~358k行/8台)."

# ============ 1秒 raw 层 (深挖: 偏航/桨距/状态; 20天冬窗) ============
# 294列英文 i*; 与明阳共schema. ⚠ 本块语义=华创 (状态enum/plim/可用率列 与明阳不同, 已实证)。
turbine_1sec:
  required: [iGenPower, iWindSpeed, WT_Runcode]
  columns:
    iGenPower: {canonical_id: WAPC_active_power, unit: kW, valid_range: [-100, 2300]}   # max 2237 实测, min -11 (轻微电动/待机)
    iWindSpeed: {canonical_id: WMET_wind_speed_nacelle, unit: m/s, valid_range: [0, 40], self_ref_risk: true}
    iGenSpeed: {canonical_id: WGEN_speed, unit: rpm, valid_range: [0, 2100]}             # max 1951 实测
    iPitchAngle1: {canonical_id: WROT_pitch_1, unit: deg, valid_range: [0, 95]}          # range[0.44,91.42] 实测, ★无-1设定(异于XEMC/DEC)
    iPitchAngle2: {canonical_id: WROT_pitch_2, unit: deg, valid_range: [0, 95]}
    iPitchAngle3: {canonical_id: WROT_pitch_3, unit: deg, valid_range: [0, 95]}
    iVaneDiiection:                  # ★ 原始拼写 (Diiection); 风向标/偏航误差
      canonical_id: WYAW_yaw_error
      unit: deg
      frame: nacelle                 # ±180; 华创 中位 -0.03° IQR[-7.1,8.1] (紧, 对风良好); range[-147,142]
      valid_range: [-180, 180]
    iwindDirection:                  # ★ 0-360 真地理 (rare; 偏航对风地理参考)
      canonical_id: WMET_wind_direction_geo
      unit: deg
      frame: geographic
      valid_range: [0, 360]          # range[0.16,359.83] 实测
    iNacellePositionLtd: {canonical_id: WYAW_nacelle_heading, unit: deg, valid_range: [0, 360], note: "机舱航向; iwindDirection≈iNacellePositionLtd+iVaneDiiection (见明阳B2结构定论)"}
    iNacellePositionTotal: {canonical_id: WYAW_nacelle_position, unit: deg, valid_range: [0, 720], note: "累积位置含扭缆"}
    iPressureOutdoor: {canonical_id: WMET_pressure, dead_channel: true}     # ★ 全0 死列(med0/max0实测) → 密度用测风塔
    iAirDensity: {canonical_id: WMET_air_density, dead_channel: true}       # ★ 全0 死列
    iActivePowerRate: {canonical_id: WAPC_power_rate, dead_channel: true}   # ★ 全0 死列
    iAvailabillityToday:             # ★★ 华创专有 catch: 全0 死列 (≠明阳, 明阳此列 valid pct)
      canonical_id: WTUR_avail_today
      dead_channel: true
      note: "华创该列恒0 (实测 range[0,0]); 不可作可用率信号 → 可用率必由 WT_Runcode 状态派生"
    iAvailabillityTotal: {canonical_id: WTUR_avail_total, valid_range: [0, 100], note: "Total 可能有值, Today死; 用前验"}
    iPowerLimit_Flag:
      canonical_id: WAPC_powerlimit_flag
      semantic: "⚠⚠ 非限电! OEM默认常数 (华创恒=0 全态, 实测全值=[0]; 明阳恒=10) → 不可作弃风信号 (C4陷阱). ★限功率真信号 = 下面 iActivePoweiSetPointValue (2026-09-02 原生层复核, 转发层死列≠信号死)"
    iActivePoweiSetPointValue:       # ★ 原始拼写 (Powei); 有功设定值 = 限功率直接信号 (2026-09-02 1秒层 8台×20天 实测)
      canonical_id: WAPC_power_setpoint
      unit: kW
      valid_range: [0, 2100]
      semantic: "活列, 与 iGenPower corr 0.90-0.97 (设定值变化台); 2000=不限, <1990∧WT_Runcode=3 = 限功率运行 (功率贴设定值±5% 占限功率时长 64-85% = binding 型). 冬窗实测: 1#/5# 全 20 天设定值恒 200 kW (功率 p99≈222, 有风 ws>8 达 156 h) = 长期降容; 2/3/7/8# 46-64% 时段在 1700/1500/1000 等档; 6/9# 2-4%. iPowerLimit_Flag 同期恒 0 ⇒ 限功率判定与剥离必用本列, 禁引 flag. 全年 10min 层无此列 (6 列) → 年度定量须另证. 详 outputs/mawang/华创_限功率设定值_原生层复核.md"
    WT_Runcode:
      canonical_id: WSLG_turbine_state
      status_enum_ref: configs/fault_dicts/huachuang_ccwe2000_status_enum_mawang.csv
      semantic: "华创自有enum (9码, 行为自解, 无官方表): 3=发电(74.2%), 9=顺桨待机低风(22.4%), 4=有风停机(2.3%真损候选), 5/7/2/6=停机变体, 11=高风过渡, 0=初始. ⚠华创park=9无8 (明阳才用8); 同SCADA列跨OEM语义不同, 必各自解."
    WT_Faultcode:
      canonical_id: WALM_fault_code
      semantic: "故障码; 码值≠官方事件代码 (join key待解); 全年事件用故障日志csv(自描述). 明阳故障字典不适用华创."
  note_1sec: "294列全英文名; 华创=机号1-3,5-9(raw 20146001-003/005-009). iTurbineOperationMode=运行细分(非WT_Runcode)."

# ============ 测风塔 (自由来流; 同马王站, 同明阳契约 mast) ============
# ⚠ 空间: 华创=第一回集电独立区, 单测风塔不代表华创区来流 (compare 已证 finding89); 真功率曲线/per-turbine性能需华创区测风。
mast:
  required: [轮毂风速平均值]
  columns:
    轮毂风速平均值: {canonical_id: WMET_free_stream_ws_hub, unit: m/s, valid_range: [0, 40], frame: geographic}
    轮毂风向平均值: {canonical_id: WMET_free_stream_wdir_hub, unit: deg, valid_range: [0, 360], frame: geographic}
    环境温度平均值(℃): {canonical_id: WMET_ambient_temp, unit: degC, valid_range: [-40, 55]}
    环境压强平均值:
      canonical_id: WMET_pressure
      unit: Pa
      valid_range: [80000, 110000]   # ★ 我们5-29清洗有 scale 断裂(95100→9885 ×10错); 越界=未修, 密度前必修 (阜山baro陷阱)
  note_mast: "2022-11→2023-11; 多高度. 华创区空间偏置 → OEM对比/绝对性能 单塔不可判."

# ============ 跨表清洗规则 ============
cleaning:
  physical:
    - "测风塔 环境压强 ∉[80000,110000]Pa → rho不可信 (修scale断裂后再算密度)"
    - "1秒 iPressureOutdoor/iAirDensity/iActivePowerRate/iAvailabillityToday 死列(全0) 弃"
  semantic:
    - "iPowerLimit_Flag 华创恒0 非限电 → 勿当弃风; 真限电需调度令/台账"
    - "WT_Runcode 按华创enum解 (9码自解, ≠明阳); 可用率由状态派生 (iAvailabillityToday死)"
    - "机舱风(平均风速/iWindSpeed)自指 → 真功率曲线必测风塔自由来流"
traps:
  - "★华创状态enum无官方表 (官方xlsx仅明阳) → 9码全为行为自解; park=9无8; 用前看 confidence 列"
  - "★iAvailabillityToday 华创死列(全0) — 明阳此列有效 → per-OEM 不可照搬, 可用率必状态派生"
  - "★1秒功率曲线 7-gate雷: 冬窗(Dec-Jan) nac_ws12 仅~80%契约, 既非纯1秒滞后(中风+77kW/高风未补)亦未坐实欠发=窗口/季节(疑结冰/湍流)+self_ref混淆; 全年10min nac_ws12→1994达额定 → 华创功率曲线 INSUFFICIENT from 冬窗1秒, 勿判欠发"
  - "iPowerLimit_Flag 假'限电' (华创恒0): 盲读→假弃风 (C4陷阱)"
  - "WT_Faultcode 码≠官方事件代码; 故障字典join key待解; 明阳故障字典不适用华创"
  - "马王1秒'1-10号'zip 里 001-003/005-009=华创非明阳(004,010=明阳), 必按机号过滤"
  - "华创区(第一回)vs测风塔/明阳区 空间不同 → OEM性能对比含空间veer, 不下单机定论 (finding89)"