/*
 * 模块名称：保护定值模型（P1，L5-1 载体）
 * 模块功能：保护定值的 RAM 模型——编号 / 通讯地址 / 范围 / 默认值 / 校验和自检。
 *           纯逻辑（仅 stdint.h），主机侧可离线单测；持久化（cfg_file 定值段）
 *           属 P4，本层只提供 load_raw/validate 的装载接口。
 *
 * 设计口径（docs/算法/继电保护功能复现规划.md §5）：
 *   - 定点存储：Q10（×1024），与参考系统定点系数 2^10 一致（§5.3）；
 *   - 通讯地址：与参考 g_tCommSetParaTab（Comm/Pub/Const_CommSetPara.c）逐项对齐，
 *     基址 0x8820（=34848）；告警类沿用运行参数段 0x8027/0x8029；
 *   - 校验和（L5-1）：sum32 正码 + 反码成对封存（参考 tagPRS 的
 *     dwTagSum/dwTagSumN 模式），selfcheck 失配 → 置闭锁；
 *   - ⚠ 默认值/范围为**拟定值**：参考 EEPROM 出厂默认表未在本仓库，
 *     待对照后逐项修订（规划 §10.3 待补项）；范围先按 DTU 馈线典型量级。
 *
 * 线程约定：装载（init/load_raw）在 defaultTask（P4 起）；读在保护消费者任务。
 *   读接口返回快照值（单个 int32 读取原子）；写与封存必须同一任务（P4 定）。
 *
 * 创建日期：2026-10-11
 */
#ifndef PROT_SET_H
#define PROT_SET_H

#include <stdint.h>

/* Q10 定点：工程量 × 1024（与参考 2^10 口径一致） */
#define PROT_SET_Q10(v)   ((int32_t)(((double)(v)) * 1024.0))
#define PROT_SET_FROM_Q10(v)  ((float)((double)(v) / 1024.0))

/* 定值项编号（枚举序 = RAM 数组序 = 校验和覆盖序，只增不删不改序） */
typedef enum {
    /* --- 三段式相间过流（A 相，L3-1）：投退/跳闸投退/电流/延时 --- */
    PS_OC1_EN = 0,   /* 0x8856 Ⅰ段投退 */
    PS_OC1_TRIP,     /* 0x8857 Ⅰ段跳闸投退（0 告警 / 1 跳闸） */
    PS_OC1_CUR,      /* 0x8858 Ⅰ段电流定值（A，二次值） */
    PS_OC1_DLY,      /* 0x8859 Ⅰ段延时（ms） */
    PS_OC2_EN,       /* 0x885A */
    PS_OC2_TRIP,     /* 0x885B */
    PS_OC2_CUR,      /* 0x885C */
    PS_OC2_DLY,      /* 0x885D */
    PS_OC3_EN,       /* 0x885E */
    PS_OC3_TRIP,     /* 0x885F */
    PS_OC3_CUR,      /* 0x8860 */
    PS_OC3_DLY,      /* 0x8861 */
    /* --- 过负荷（A 相，L3-3） --- */
    PS_OL_EN,        /* 0x8871 */
    PS_OL_TRIP,      /* 0x8872 */
    PS_OL_CUR,       /* 0x8873 */
    PS_OL_DLY,       /* 0x8874 */
    /* --- 过压 / 欠压（UA，L3-4；沿用参考告警段 0x8029/0x8027） --- */
    PS_OV_EN,        /* 本地投退（参考告警类无独立投退，V0.1 补） */
    PS_OV_VOL,       /* 0x8029 过电压门限（V，二次值） */
    PS_OV_DLY,       /* 0x802A 过电压延时（ms） */
    PS_UV_EN,        /* 本地投退 */
    PS_UV_VOL,       /* 0x8027 低电压门限（V，二次值） */
    PS_UV_DLY,       /* 0x8028 低电压延时（ms） */
    /* --- 零序过压（UN，L3-6） --- */
    PS_3U0_EN,       /* 0x888E */
    PS_3U0_VOL,      /* 0x888F 3U0 定值（V，二次值） */
    PS_3U0_DLY,      /* 0x8890 延时（ms） */
    /* --- 公共 --- */
    PS_RET_OVER,     /* 过量返回系数（返回门槛 = 定值 × 系数，<1） */
    PS_RET_UNDER,    /* 欠量返回系数（返回门槛 = 定值 × 系数，>1） */
    PS_PT_PRI,       /* 0x8820 PT 一次额定（V） */
    PS_PT_SEC,       /* 0x8821 PT 二次额定（V） */
    PS_CT_PRI,       /* 0x8825 CT 一次额定（A） */
    PS_CT_SEC,       /* 0x8826 CT 二次额定（A） */
    PS_ID_COUNT
} prot_set_id_t;

/* 定值项元数据（ROM 常量表，校验和自检不覆盖它——只覆盖 RAM 值区） */
typedef struct {
    uint16_t comm_addr;   /* 通讯信息体地址（0 = 本地项，不上送） */
    uint8_t  is_ctl;      /* 1 = 投退/枚举项（0/1），0 = 模拟量项 */
    int32_t  def;         /* 默认值（Q10；投退项为 0/1 的 Q10） */
    int32_t  min;         /* 下限（Q10） */
    int32_t  max;         /* 上限（Q10） */
} prot_set_meta_t;

extern const prot_set_meta_t g_prot_set_meta[PS_ID_COUNT];

/*
 * 函数功能：装载出厂默认值并封存校验和（幂等，内核启动前可调）
 */
void prot_set_init(void);

/*
 * 函数功能：整表装载外部值（P4 起由 cfg_file 定值段调用），逐项范围校验
 * 入口参数：vals - PS_ID_COUNT 个 Q10 值
 * 返 回 值：0 全部合法（已装载并封存）/ -1 存在越界项（**整表不装载**，
 *           返回前可经 prot_set_bad_mask() 取越界位图）
 */
int prot_set_load_raw(const int32_t *vals);

/* 越界位图（bit i = 第 i 项越界；load_raw 失败后有效） */
uint32_t prot_set_bad_mask(void);

/*
 * 函数功能：单项写入（范围校验；**不自动重封校验和**——批量改完必须
 *           显式 prot_set_seal()，否则 selfcheck 判"定值被非法改写"）
 * 返 回 值：0 / -1 越界拒写
 */
int prot_set_set(prot_set_id_t id, int32_t q10);

int32_t prot_set_get(prot_set_id_t id);          /* Q10 原值 */
float   prot_set_get_f(prot_set_id_t id);        /* 工程量浮点 */
uint8_t prot_set_get_ctl(prot_set_id_t id);      /* 投退项：!=0 视为投入 */

/* 校验和（L5-1）：sum32 覆盖 RAM 值区；seal 封存正/反码对 */
uint32_t prot_set_checksum(void);
void     prot_set_seal(void);
/* 自检：重算并与封存值比对，失配 → 置闭锁并返回 -1（已闭锁也返回 -1） */
int  prot_set_selfcheck(void);
uint8_t prot_set_locked(void);

#endif /* PROT_SET_H */