/*
 * 模块名称：保护元件框架（L3，P1 子集）
 * 模块功能：通用"越限 + 返回系数滞回 + 定时限"元件核 + 实例表（数据驱动，
 *           同 phasor 实例表模式）。判据为**纯逻辑**（吃测量值 + 定值），
 *           主机侧可离线单测；出口/SOE（L4）与任务编排为后续。
 *
 * V0.1 有效实例（N-18：仅 TPAFE 三路）：
 *   OC1/OC2/OC3 三段式相间过流（A 相 IA，L3-1）
 *   OL          过负荷（A 相 IA，L3-3）
 *   OV/UV       过压/欠压（UA，L3-4）
 *   3U0         零序过压（UN 外部零序电压通道，L3-6）
 *   OF/UF       过频/低频（测量量 = freq 层测得频率，L3-5，B8 落地）
 *
 * 测量数组口径：相量类实例 = 基波有效值（A/V）；OF/UF = 测得频率（Hz）。
 *   run() 按实例表 src 字段取数（0=phasor rms，1=freq）。freq 无有效读数
 *   （未启动收敛或幅值门失效）→ 该行按方向填"必不启动"值（过量填 0、
 *   欠量填极大值 → 滞回核比较恒假 → 元件复位不误动），**不整拍跳过**
 *   （否则浮空台架会把 OC/UV 等全部饿死，B5 行为回归）。
 *
 * 与参考系统的口径差异（有意简化，均已在规划文档登记）：
 *   - 返回门槛 = 定值 × 返回系数（参考经 CN_SET_RET 独立定值，等价）；
 *   - 返回**即时**（参考 GRly_TimeRelay 带 10 ms 返回延时——V0.1 无出口硬件，
 *     抖动只影响日志，P4 接出口时再补返回延时）；
 *   - 复压/方向/无压无流闭锁（dwSetFyCtrl 类）随 P2/P3 元件扩展；
 *   - 工程量↔码值换算系数暂为 1（L1-5 标定未实现，同 phasor 层口径）。
 *
 * 线程约定：init 内核启动前或保护消费者任务上下文；eval/run 仅保护消费者任务
 *   上下文（B5 起 = protectTask）；request_reset 任意上下文（跨上下文复归请求，
 *   如 104 遥控 YK11 在 iec104Task 落请求、下一拍 eval 头部消费）。板端接线
 *   走栈预算 + IWDG 心跳门禁。
 *
 * 创建日期：2026-10-11
 */
#ifndef PROT_ELM_H
#define PROT_ELM_H

#include <stdint.h>

/* 元件实例编号（枚举序 = 实例表序 = 测量数组序；尾追加，编号不回收） */
typedef enum {
    PE_OC1 = 0,   /* 过流 Ⅰ 段（IA） */
    PE_OC2,       /* 过流 Ⅱ 段（IA） */
    PE_OC3,       /* 过流 Ⅲ 段（IA） */
    PE_OL,        /* 过负荷（IA） */
    PE_OV,        /* 过压（UA） */
    PE_UV,        /* 欠压（UA，欠量方向） */
    PE_3U0,       /* 零序过压（UN） */
    PE_OF,        /* 过频（测量量 = freq 层测得频率，B8，L3-5） */
    PE_UF,        /* 低频（测量量 = freq 层测得频率，欠量方向，B8，L3-5） */
    PE_COUNT
} prot_elm_id_t;

/* 单元件状态快照（读侧拷贝语义，见 prot_elm_state） */
typedef struct {
    uint8_t  enabled;    /* 本拍投入（定值投退 && 未闭锁） */
    uint8_t  picked;     /* 越限启动（滞回后电平） */
    uint8_t  asserted;   /* 定时限到点（动作） */
    uint32_t pick_ms;    /* 本次启动起始时基（0 = 未启动过；asserted 延时观测用） */
} prot_elm_state_t;

/*
 * 函数功能：复位全部元件状态（定值不动；幂等，内核启动前可调）
 * 限定条件：内核启动前，或保护消费者任务上下文（跨上下文请用 request_reset）
 */
void prot_elm_init(void);

/*
 * 函数功能：登记"复归元件状态"请求（任意上下文安全，单字标志）
 * 函数说明：下一拍 prot_elm_eval() 头部消费并执行 prot_elm_init()。
 *           104 遥控 YK11（iec104Task 上下文）必须走本接口，不得直接调
 *           prot_elm_init()（会与 protectTask 的 eval 竞态）。
 */
void prot_elm_request_reset(void);

/*
 * 函数功能：纯判据步进——按当前定值（prot_set RAM）+ 给定测量值推进所有元件
 * 入口参数：now_ms - 单调时基（tick ms，回绕安全：差值法）
 *           meas   - PE_COUNT 个测量值（工程量：A / V），NULL 视为全 0
 * 返 回 值：无
 * 限定条件：仅保护消费者任务上下文；调用方保证定值已装载
 * 函数说明：越限方向由实例表决定；投退=0 或定值闭锁（L5-1）→ 状态复位、
 *           不判据。延时判定用 (uint32_t)(int32_t)(now - t0) >= dly，回绕安全。
 */
void prot_elm_eval(uint32_t now_ms, const float meas[PE_COUNT]);

/*
 * 函数功能：适配层——从 phasor 使用区取 rms 组装测量数组后调 prot_elm_eval
 * 入口参数：now_ms - 同上
 * 说明：phasor 未就绪（-2，未满一周波）的实例本拍按"测量=上一拍值"处理会
 *       引入陈旧判据 → 直接**整拍跳过**（不 eval），与 adc_task 跳拍同口径。
 */
void prot_elm_run(uint32_t now_ms);

/* 状态快照拷贝（NULL 安全；越界全零） */
void prot_elm_state(prot_elm_id_t id, prot_elm_state_t *out);

/* 动作位图（bit i = 元件 i asserted），供 L4 出口 / 心跳日志 */
uint32_t prot_elm_active_mask(void);

/* 实例名（ROM 常量，日志用） */
const char *prot_elm_name(prot_elm_id_t id);

#endif /* PROT_ELM_H */