handle_priority.c

源文件路径：logic/handle_priority.c 所属模块：logic（能量调度核心） 代码行数：206

1. 文件职责

本文件实现「光伏优先（PV priority）」AC 控模式下总功率目标值的下发动作函数集合，是 PV_PRIORITY_AC_CONTORL_STATE 状态机的执行层（状态判断在上层、功率赋值在本文件）。文件头注释说明它是因为 DC 控 / AC 控条件编译的需要，从 logic/ac_control.c 中拆分出来的。它只写入 g_t_logic_info 里 AC 侧的总设值（s32_ac_total_set_inv_power、s32_ac_total_set_bat_charge_limit_power、s32_ac_total_set_bat_discharge_limit_power、u8_ac_total_set_bat_forced_charge_en），不做逆变器/电池的直接硬件操作。驱动方有两个：logic/logic.c 的 ac_control_total_power_photovoltaic_priority_calculate()（光伏优先状态机，软定时限制调整速率）与 logic/ac_control.c 的 fsm_total_power_ac_control()（自发自用状态机，INV_AC_CTRL 条件编译内）。数据流位置：电表/逆变器采样 → t_logic_control_parameter → 本文件的反馈闭环计算 → s32_ac_total_set_* → 上层限幅与逆变器下发。

2. 关键数据结构与宏

本文件没有定义结构体、联合体或位域，也没有自定义宏常量（阈值全部以字面量出现在表达式中）。

3. 函数清单

共 7 个函数，全部为文件级非 static 定义（尽管注释块里写着 static）。

4. 核心逻辑解析

4.1 状态机与驱动时序

状态迁移条件不在本文件，而在 logic/logic.c 的 pp_total_power_ac_control_state_handle() 内，本文件只负责「进入某状态后如何算功率」。迁移判定依据（t_logic_control_parameter）：

驱动时序：ac_control_total_power_photovoltaic_priority_calculate() 每次先用 OSTimeGet() 与 u32_calculation_ac_total_inv_tick / u32_calculation_interval 做软定时门控（未到间隔直接 return），然后「先判状态、再执行动作」（pp_total_power_ac_control() 的 switch）。整个调用链在 task_system_logic_control 任务中周期执行（该任务同时被 g_t_fast_dispatch_flag 事件标志触发快调度）。

4.2 关键算法与公式

（1）馈网跟踪的增量闭环（total_power_control_grid_track_calculate、handle_priority_grid_track_backup_below_pv_state、handle_priority_grid_track_backup_over_pv_state 三处完全相同的代码）：

s32_ac_total_set_inv_power += s32_pgrid_metert / u8_regulator_speed;

s32_pgrid_metert 为正表示电表侧取电、为负表示馈网。取电时增大逆变目标功率以抵消，馈网时减小。这是一个纯增量（积分型）调节器，u8_regulator_speed（取值 1~5，由 get_inv_regulator_speed() 按机型/电网功率给出）是调节步长分母，值越大调节越慢。

（2）大偏差直接前馈 + 小偏差增量微调（handle_priority_default_state 等）：

if (abs(s32_max_feedin_power + s32_pgrid_metert) > 100)
    s32_ac_total_set_inv_power = s32_max_feedin_power + s32_pgrid_metert + s32_pinvt;
else
    s32_ac_total_set_inv_power += (s32_max_feedin_power + s32_pgrid_metert) / u8_regulator_speed;

即：当「馈网上限 + 实际电表功率」的绝对值超过 100 W 时，用前馈方式一步把目标拉到 max_feedin + pgrid_metert + pinvt；进入 ±100 的死区后改用增量微调，避免在设定点附近来回过冲。

（3）无 PV 归零态的三段判断（total_power_control_grid_zero_without_pv_calculate，含 static u8 s_u8_cnt 去抖）：

第三段连续 3 次（受计算间隔门控，实际约 3 个调度周期）才动作，起的是「确认进入稳态再恢复电池能力」的去抖作用。

（4）各状态的电池限值：

handle_priority_default_state / ..._below_pv_state / ..._over_pv_state 三者在结尾都有统一的负值保护：

if (g_t_logic_info.s32_ac_total_set_inv_power < 0) g_t_logic_info.s32_ac_total_set_inv_power = 0;

4.3 通信协议帧格式

本文件不涉及任何通信收发，无帧格式、校验、超时重试逻辑（属 net/、midware/ 模块）。

4.4 与 uCOS-II 的配合

本文件不直接调用任何 uCOS-II API，不使用信号量/消息邮箱。它运行在 task_system_logic_control 任务上下文内，被事件标志 g_t_fast_dispatch_flag（POST_PEND_FAST_ENABLE）加速；跨任务同步由调用方通过 g_t_logic_info 结构体字段的「写—读」隐式完成，本文件自身无临界区保护。

4.5 关键全局变量读写

5. 对外接口

导出（供外部调用）——均通过 handle_priority.h 声明：

本文件不导出任何全局变量（全部输出都通过 g_t_logic_info 生效）。

被调用（外部依赖）：

6. 依赖关系

依赖：

• logic/logic.h（#include "logic.h"）——提供 g_t_logic_info、t_logic_control_parameter、FALSE、abs() 链条；
• logic/handle_priority.h（#include "handle_priority.h"）——PV_PRIORITY_AC_CONTORL_STATE 与自身原型的声明；
• 间接依赖 system/sys/chip.h（handle_priority.h 内 #include "chip.h"）。

被依赖：

• logic/logic.c——状态机迁移判定 + pp_total_power_ac_control() 分发；
• logic/ac_control.c——自发自用状态机复用其中两个计算函数；
• logic/handle_priority.h 被 ac_control.c、logic.c、handle_priority.c 三处 include。

7. 备注与风险点

1. 函数头注释与实际定义不符：20 行、36 行的注释写 @Name :static void total_power_control_grid_track_calculate()，但 26 行/42 行的真实定义没有 static；同理其余 5 个函数头都挂着错误的 @Name（例如 114 行的函数名叫 handle_priority_grid_track_with_pv_state、147/182/194 行的注释全部重复成 ..._backup_over_pv_state）。这些是复制粘贴遗留，容易误导调用者，建议同步修正。
2. 大量重复代码：handle_priority_default_state、..._below_pv_state、..._over_pv_state 三个函数里「前馈 + 增量」的逆变功率计算块字节级相同（仅电池限值不同），是典型的三份拷贝，后续修改极易漏改其中一份。
3. PRIORITY_BAT_OPEN_WITH_PV_STATE 没有对应处理函数：logic.c 的 pp_total_power_ac_control() 没有该 case，会落到 default 分支静默执行 handle_priority_default_state()。也就是说「PV 有效但电池未使能」这一状态在光伏优先路径下与默认态行为完全相同，与该状态的语义可能不一致（自发自用路径 ac_control.c 里有独立的 BAT_OPEN_WITH_PV_STATE/total_power_control_bat_open_with_pv_calculate() 处理）。switch 的 default 里只有一句 // TODO:报错信息，无任何告警上报。
4. 除法无零保护：4 处 s32_pgrid_metert / u8_regulator_speed 与 2 处 (max_feedin + pgrid_metert) / u8_regulator_speed 都直接以配置量为分母。当前 get_inv_regulator_speed()（inverter.c:2634）的默认值是 REGULATOR_SPEED_5 且所有分支都赋 1~5，不会为 0；但该值来自运行期机型判断，一旦被外部或未覆盖分支写成 0 就会触发除零（GD32F407 上为硬件异常）。
5. 整数除法截断与闭环死区：pgrid_metert / regulator_speed 在 |pgrid_metert| < regulator_speed（即 <5 W）时结果为 0，目标功率会「卡死」不再调整；负值除法向零取整（C99），在馈网方向与取电方向的步长不对称。
6. 累积量无上限：s32_ac_total_set_inv_power += ... 是累加写，只有 < 0 的下限钳位，没有上限钳位。若上层限幅函数（logic_charge_dischg_power_limit()）不兜底，持续同向偏差会让该值单向爬升到 s32 饱和。相对地，前馈分支是直接赋值、不累加，两种语义混在同一变量上。
7. 魔法数字：100（死区/阈值 W）、-50（判定馈网的功率门限）、200（馈网上限允许偏差）、20 / 40（归零态固定逆变设值）、140（逆变功率门限）、10（电表功率门限）、> 2（去抖次数）、s32_inv_rated_output_power - 100。这些既无宏、也无注释说明量纲（推断为 W），建议提取为具名常量。
8. 去抖计数期间限值保持旧值：total_power_control_grid_zero_without_pv_calculate() 的第三段在 s_u8_cnt <= 2 时既不写充电限值也不写放电限值，而是保留上一状态遗留在 g_t_logic_info 中的值。若上一状态是放电（如 ..._over_pv_state 刚写过放电限值），这 3 个周期内电池仍沿用旧限值，属于状态切换瞬态的未定义行为。
9. 注释与实现不一致：第 65 行注释写「电池放电满足电表归零」，但该分支实际把充电限值也恢复成了满值 s32_bat_charge_power_limit；第 157 行注释掉的 s32_ac_total_set_bat_charge_limit_power = 0; 在 174 行又原样出现；第 158 行先把放电限值置 0，第 173 行又立刻覆盖，属冗余赋值。
10. 跨任务可见性：本文件写的 g_t_logic_info 字段被其他任务（逆变器下发、并机、云端上报）读取，而写入过程（例如 4 个字段的非原子赋值序列）没有关中断/临界区保护。若读方在写入中途取值，会看到「电压目标已更新但电池限值还是上一状态」的混合状态。