首页 / knowledge/代码解析/logic

handle_priority.h

本页目录1. 文件职责 2. 关键数据结构与宏 3. 函数清单 4. 核心逻辑解析 4.1 状态枚举与处理函数的对应关系 4.2 6 个功率函数之间的调用关系（契约层面）4.3 通信协议 / 定时 / uCOS-II 配合 5. 对外接口 6. 依赖关系 7. 备注与风险点

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

1. 文件职责

本文件是 logic/handle_priority.c 的对外接口头文件，声明「光伏优先（PV priority）」AC 控状态机的状态枚举 PV_PRIORITY_AC_CONTORL_STATE 与 7 个功率计算函数原型。它本身不含任何逻辑与数据定义，只做类型与原型暴露，供 logic/logic.c（状态迁移判定与分发）、logic/ac_control.c（自发自用状态机复用两个计算函数）以及 handle_priority.c 自身引用。文件头注释说明该组接口是因为 DC 控 / AC 控条件编译的需要，从 ac_control.c 的对外接口中拆分出来的。

2. 关键数据结构与宏

名称	类型	说明
`__HANDLE_PRIORITY_H__`	宏	include guard
`PV_PRIORITY_AC_CONTORL_STATE`	枚举（typedef 匿名枚举）	光伏优先 AC 控状态机状态集，显式从 `0x00` 起编号，共 6 个状态
`PRIORITY_DEFAULT_STATE`	枚举成员（= `0x00`）	默认态：不做电池限值，仅按馈网上限跟踪逆变功率
`PRIORITY_GRID_TRACK_BACKUP_BELOW_PV_STATE`	枚举成员（= 1）	低于 PV 的馈网跟踪备份态：允许充电、禁止放电
`PRIORITY_GRID_TRACK_BACKUP_OVER_PV_STATE`	枚举成员（= 2）	高于 PV 的馈网跟踪备份态：按电表增量给放电限值、禁止充电
`PRIORITY_GRID_TRACK_WITHOUT_PV_STATE`	枚举成员（= 3）	无 PV 追踪态
`PRIORITY_GRID_ZERO_WITHOUT_PV_STATE`	枚举成员（= 4）	无 PV 电表归零态
`PRIORITY_BAT_OPEN_WITH_PV_STATE`	枚举成员（= 5）	PV 有效但电池未使能态（无对应处理函数，见备注 3）

本文件不定义结构体、联合体、位域，也没有除 include guard 外的宏常量。

3. 函数清单

函数名	作用域	说明
`handle_priority_default_state`	全局（原型声明）	默认态功率处理，定义于 `handle_priority.c:88`
`handle_priority_grid_track_backup_below_pv_state`	全局（原型声明）	低于 PV 馈网跟踪备份态处理，定义于 `handle_priority.c:121`
`handle_priority_grid_track_backup_over_pv_state`	全局（原型声明）	高于 PV 馈网跟踪备份态处理，定义于 `handle_priority.c:154`
`handle_priority_grid_track_without_pv_state`	全局（原型声明）	无 PV 追踪态处理，定义于 `handle_priority.c:189`
`handle_priority_grid_zero_without_pv_state`	全局（原型声明）	无 PV 归零态处理，定义于 `handle_priority.c:201`
`total_power_control_grid_track_calculate`	全局（原型声明）	通用「追踪电表归零」计算，定义于 `handle_priority.c:26`，被 `ac_control.c` 复用
`total_power_control_grid_zero_without_pv_calculate`	全局（原型声明）	通用「无 PV 电表归零」计算，定义于 `handle_priority.c:42`，被 `ac_control.c` 复用

共 7 个原型声明，全部对应 handle_priority.c 中的全局定义，无 static 函数、无函数指针、无回调。

4. 核心逻辑解析

本文件是纯声明文件，不含可执行逻辑。要点集中在「接口契约」上：

4.1 状态枚举与处理函数的对应关系

枚举值	处理函数	是否存在
`PRIORITY_DEFAULT_STATE`	`handle_priority_default_state()`	是
`PRIORITY_GRID_TRACK_BACKUP_BELOW_PV_STATE`	`handle_priority_grid_track_backup_below_pv_state()`	是
`PRIORITY_GRID_TRACK_BACKUP_OVER_PV_STATE`	`handle_priority_grid_track_backup_over_pv_state()`	是
`PRIORITY_GRID_TRACK_WITHOUT_PV_STATE`	`handle_priority_grid_track_without_pv_state()`	是
`PRIORITY_GRID_ZERO_WITHOUT_PV_STATE`	`handle_priority_grid_zero_without_pv_state()`	是
`PRIORITY_BAT_OPEN_WITH_PV_STATE`	无	否，调用方 `logic/logic.c` 的 `switch` 会落到 `default` 分支

4.2 6 个功率函数之间的调用关系（契约层面）

handle_priority_grid_track_without_pv_state() 与 handle_priority_grid_zero_without_pv_state() 在本头文件里只是「状态入口」，其实现分别转调 total_power_control_grid_track_calculate() 与 total_power_control_grid_zero_without_pv_calculate()；而这两个 total_power_control_* 又是被 ac_control.c 直接复用的通用计算函数（ac_control.c:1022、ac_control.c:1030）。也就是说头文件里实际暴露了两层接口：5 个「状态处理函数」（仅光伏优先状态机用）+ 2 个「通用计算函数」（光伏优先与自发自用两条路径共用）。

4.3 通信协议 / 定时 / uCOS-II 配合

无。本文件不涉及通信帧、校验、超时，不涉及 uCOS-II API，不声明信号量或消息邮箱句柄。

5. 对外接口

导出（供外部使用）：

名称	使用方
`PV_PRIORITY_AC_CONTORL_STATE`	`logic/logic.c`（`pp_total_power_ac_control_state_handle()` 参数、`s_u32_prestate` / `l_u32_nextstate` 变量）
`handle_priority_default_state()`	`logic/logic.c:1947`、`logic/logic.c:1968`
`handle_priority_grid_track_backup_below_pv_state()`	`logic/logic.c:1951`
`handle_priority_grid_track_backup_over_pv_state()`	`logic/logic.c:1955`
`handle_priority_grid_track_without_pv_state()`	`logic/logic.c:1959`
`handle_priority_grid_zero_without_pv_state()`	`logic/logic.c:1963`
`total_power_control_grid_track_calculate()`	`logic/ac_control.c:1022`、`logic/handle_priority.c:191`
`total_power_control_grid_zero_without_pv_calculate()`	`logic/ac_control.c:1030`、`logic/handle_priority.c:203`

本头文件不导出任何全局变量（状态与功率结果都通过 g_t_logic_info 传递）。

被调用（本文件引用的外部符号）：

名称	来源
`chip.h`	`system/sys/chip.h`（`#include "chip.h"`，为后续包含者准备基础类型与平台定义）

6. 依赖关系

依赖：

system/sys/chip.h——唯一直接 include，用于给包含者铺平基础类型（u8 / s32 等）；
间接依赖 UCOSII/uCOS-CONFIG/includes.h 链（chip.h 内）。

被依赖（全部 include 点）：

logic/handle_priority.c:15
logic/logic.c:27
logic/ac_control.c:17

7. 备注与风险点

枚举名与自发自用状态机高度相似，存在混淆风险：ac_control.h 里另有一套 SELFUSE_AC_CONTORL_STATE，含 GRID_TRACK_WITH_PV_STATE / GRID_TRACK_WITHOUT_PV_STATE / GRID_ZERO_WITH_PV_STATE / GRID_ZERO_WITHOUT_PV_STATE / BAT_OPEN_WITH_PV_STATE 等同名成员（仅少了 PRIORITY_ 前缀）。两套枚举的序号含义完全不同（本文件 GRID_TRACK_WITHOUT_PV=3，自发自用里 GRID_TRACK_WITHOUT_PV_STATE=2），而 ac_control.c 同时 include 了两个头文件，任何一次写漏前缀都会静默编译通过并产生错误的语义。
头文件未包含任何类型定义头，只依赖 chip.h 的间接引入：u8 / s32 等类型并非本文件声明，若未来有人把 #include "chip.h" 挪到条件编译之外或调整包含顺序，会引发大范围编译错误。同时该 include 无 #ifdef 保护，属正常但耦合较紧。
PRIORITY_BAT_OPEN_WITH_PV_STATE 是「死枚举」：本头文件定义了它，但既没有对应的处理函数原型，logic.c 的 pp_total_power_ac_control() 也没有对应 case。该状态被判定出来后会落入 default（只有一句 // TODO:报错信息）并执行 handle_priority_default_state()。使用方 ac_control.c/logic.c 若把它当作「电池未使能」语义依赖，行为会与预期不符。
枚举显式指定 0x00 起始但其余成员未指定值：PRIORITY_DEFAULT_STATE = 0x00 之后靠隐式递增，中间插入新状态会改变后面所有状态的数值；由于这些枚举值可能被日志/调试打印（logic.c 里有一段被 #if 0 屏蔽的 printf("pp_next_state:%d\r\n", ...)），重新排序会影响历史日志的可读性。
头文件缺少版本/日期信息：@date :2026-0724 格式与工程内其他文件（2026-08-23 等）不一致，属遗留填写问题，无功能影响。