首页 / knowledge/代码解析/logic
ac_control.h
本页目录1. 文件职责2. 关键数据结构与宏3. 函数清单4. 核心逻辑解析4.1 两套状态枚举并不共用一套入口4.2 与
handle_priority.h 的枚举冲突4.3 通信协议 / 定时 / uCOS-II 配合5. 对外接口6. 依赖关系7. 备注与风险点源文件路径：
logic/ac_control.h所属模块：logic（能量调度核心） 代码行数：81
1. 文件职责
本文件是 logic/ac_control.c 的对外接口头文件：定义「AC 侧（并网机 / 交流耦合机）功率控制」两套状态机的状态枚举，并声明 AC 总功率控制与 AC 三相不平衡控制的函数原型。它把状态类型暴露给 logic/logic.c（顶层调度分发）、logic/dispatch.c（Sunspec 有功调度）使用；logic/csip_aus.c 也 include 了它（仅取类型，未直接调用函数）。所有 void ac_control_* 原型都包在 #ifdef INV_AC_CTRL 内，说明这套接口只在编译期选定「AC 控逆变器型号」的产品形态下生效。
2. 关键数据结构与宏
| 名称 | 类型 | 说明 |
|---|---|---|
__AC_CONTROL_H__ | 宏 | include guard |
SELFUSE_AC_CONTORL_STATE | 枚举（typedef 匿名枚举） | 自发自用「总功率」状态机状态集，DEFAULT_STATE 显式 = 0x00，共 9 个状态 |
DEFAULT_STATE | 枚举成员（= 0） | 默认态，fsm_total_power_ac_control() 中无 case，落 default 空处理 |
GRID_TRACK_WITH_PV_STATE | 枚举成员（= 1） | 有 PV 时按电表功率跟踪（电表归零 / 削顶） |
GRID_TRACK_WITHOUT_PV_STATE | 枚举成员（= 2） | 无 PV 时的电表跟踪 |
PV_TRACK_FEEDIN_GRID_STATE | 枚举成员（= 3） | 电池已满充，PV 追踪馈网（max feedin） |
GRID_ZERO_WITH_PV_STATE | 枚举成员（= 4） | 有 PV，电表归零 |
GRID_ZERO_WITHOUT_PV_STATE | 枚举成员（= 5） | 无 PV，电表归零 |
BAT_OPEN_WITH_PV_STATE | 枚举成员（= 6） | 有 PV 但电池未使能（电池开路），由 PV 并网 |
INV_OVER_CTRL_STATE | 枚举成员（= 7） | 状态切换瞬间的「超调控制」滞环态，直接跟随当前逆变功率 |
PREPAY_METER_STATE | 枚举成员（= 8） | 南非预付费电表态，在 ac_control.c 的 switch 中无对应 case |
THREE_PHASE_UNBALANCE_AC_CONTORL_STATE | 枚举（typedef 匿名枚举） | 三相不平衡状态集：前 6 个是「三相总状态」，后 4 个是「单相状态」 |
UNBALANCE_DEFAULT_STATE | 枚举成员（= 0） | 三相不平衡默认态 |
UNBALANCE_GRID_TRACK_WITH_PV_STATE | 枚举成员（= 1） | 三相不平衡 + 有 PV 电表跟踪 |
UNBALANCE_PV_TRACK_FEEDIN_GRID_STATE | 枚举成员（= 2） | 三相不平衡 + PV 追踪馈网 |
UNBALANCE_GRID_TRACK_WITHOUT_PV_STATE | 枚举成员（= 3） | 三相不平衡 + 无 PV 电表跟踪 |
UNBALANCE_BAT_OPEN_WITH_PV_STATE | 枚举成员（= 4） | 三相不平衡 + 电池开路 |
UNBALANCE_INV_OVER_CTRL_STATE | 枚举成员（= 5） | 三相不平衡超调控制态 |
GRID_METER_PHASE_INPUT_STATE | 枚举成员（= 6） | 单相状态：该相在买电（电表 > 自耗，且逆变未满） |
GRID_METER_PHASE_OUTPUT_STATE | 枚举成员（= 7） | 单相状态：该相在馈网（电表 < -50W） |
GRID_METER_PHASE_ZERO_STATE | 枚举成员（= 8） | 单相状态：该相电表在 ±50W 稳定区 |
INV_PHASE_POWER_FULL_STATE | 枚举成员（= 9） | 单相状态：该相逆变输出已接近单相额定 |
INV_AC_CTRL | 条件编译宏 | 由 midware/inverter/inverter.h 依据 INVERTER_TYPE 派生；未定义时本头文件全部函数原型不可见 |
说明：枚举值决定「打包成 u32」的位含义，见
ac_control.c第 4.3 节。
3. 函数清单
| 函数名 | 作用域 | 说明（一句话） |
|---|---|---|
ac_control_total_power_limit | 全局（原型） | AC 总功率控制模式的功率限幅（逆变功率上下限、充放电限值钳位），定义于 logic/ac_control.c:62 |
ac_control_total_power_bat_force_charge | 全局（原型） | AC 强充模式：充电限值取电池充电上限，执行强充控制 |
ac_control_total_power_bat_force_discharge | 全局（原型） | AC 强放模式：放电限值取电池放电上限，执行强放控制 |
ac_control_total_power_bat_power_control | 全局（原型） | AC 电池功率控制模式：直接把指令功率映射为逆变/电池限值 |
ac_control_total_power_self_use_calculate | 注释掉的声明（ac_control.h:61） | 旧版 AC 自发自用总功率计算，实现体在 ac_control.c 里被 #if 0 屏蔽，已废弃 |
ac_control_total_power_no_bat_calculate | 全局（原型） | AC 无电池模式：电池限值清零，仅按 max feedin 跟踪逆变功率 |
ac_control_total_power_gc_chgpower_calculate | 全局（原型） | AC 油机（发电机）充电功率模式下的功率计算 |
ac_control_total_power_self_use_calculate_new | 全局（原型） | 新版 AC 自发自用总功率计算（状态机 + 计算两段式），是当前生效入口 |
ac_control_Sunspec_ative_power | 全局（原型） | Sunspec/南澳调度有功功率控制入口，含 MPPT 开关判据 |
ac_control_Sunspec_unbalance_ctrl | 全局（原型） | Sunspec 有功控制下的三相不平衡功率再分配 |
ac_control_three_phase_power_limit | 全局（原型） | AC 三相不平衡各相功率限幅 |
ac_control_three_phase_power_self_use_calculate | 全局（原型） | AC 三相不平衡自发自用功率计算（状态机 + 限幅） |
ac_control_three_phase_power_bat_force_charge | 全局（原型） | AC 三相不平衡强充模式 |
ac_control_three_phase_power_bat_force_discharge | 全局（原型） | AC 三相不平衡强放模式 |
ac_control_three_phase_power_no_bat_calculate | 全局（原型） | AC 三相不平衡无电池模式 |
统计：
#ifdef INV_AC_CTRL段内（第 57~76 行）共 18 条原型声明、17 个不同函数名 —— 第 69 行与第 72 行重复声明了ac_control_three_phase_power_self_use_calculate。另外ac_control.c中还有两个非 static 全局函数未被本头文件声明：prepay_meter_ac_control_state_handle()（ac_control.c:904）与ac_control_three_phase_power_bat_force_control()（ac_control.c:1227），它们仅在ac_control.c内部调用，靠「定义在调用点之前」通过编译。
4. 核心逻辑解析
本文件是纯声明文件，不含可执行逻辑。契约层面要点如下：
4.1 两套状态枚举并不共用一套入口
SELFUSE_AC_CONTORL_STATE（总功率）由ac_control.c的fsm_total_power_ac_control_state_handle()/fsm_total_power_ac_control()使用，ac_control_total_power_self_use_calculate_new()、time_valley_fill_calculate()调用。THREE_PHASE_UNBALANCE_AC_CONTORL_STATE（三相不平衡）由fsm_threephase_unbalance_power_ac_control_state_handle()/fsm_threephase_unbalance_power_ac_control()使用，ac_control_three_phase_power_self_use_calculate()调用。- 两套枚举中「总状态」和「单相状态」混在同一个
THREE_PHASE_UNBALANCE_AC_CONTORL_STATE里（值 0~5 为总状态、6~9 为单相状态），这是为了能把 4 个字段（总状态 + A/B/C 相状态）塞进一个u32（ac_control.c:1536）。
4.2 与 handle_priority.h 的枚举冲突
logic/handle_priority.h 另有一套 PV_PRIORITY_AC_CONTORL_STATE，含 GRID_TRACK_WITHOUT_PV_STATE、GRID_ZERO_WITHOUT_PV_STATE、BAT_OPEN_WITH_PV_STATE 等同名成员，但数值不同（如 PRIORITY_GRID_TRACK_WITHOUT_PV_STATE = 3 vs 本文件 GRID_TRACK_WITHOUT_PV_STATE = 2）。logic/ac_control.c 同时 include 了两个头文件（ac_control.c:16-17），一旦写漏前缀就会静默编译通过并产生语义错误。
4.3 通信协议 / 定时 / uCOS-II 配合
无。本文件不涉及帧格式、校验、超时重试，不使用 uCOS-II API，不声明信号量或消息邮箱句柄。所有节拍控制都落实在 ac_control.c 内部对 g_t_logic_info.t_logic_control_parameter.u32_calculation_ac_total_inv_tick / u32_calculation_ac_three_phase_inv_tick 两个时间戳字段的读写上，本头文件仅通过 LOGIC_CONTROL_PARAMETER_T 间接触及。
5. 对外接口
导出（供外部使用）：
| 名称 | 使用方 |
|---|---|
SELFUSE_AC_CONTORL_STATE | logic/ac_control.c（fsm_total_power_ac_control_state_handle() 参数与 s_u32_prestate / l_u32_nextstate）；logic/logic.c 通过 g_t_logic_info 间接受影响 |
THREE_PHASE_UNBALANCE_AC_CONTORL_STATE | logic/ac_control.c（单相状态位打包/解包） |
ac_control_total_power_limit() | logic/logic.c:1750（logic_charge_dischg_power_limit() 内） |
ac_control_total_power_bat_force_charge() | logic/logic.c:1768（bat_force_charge() 内） |
ac_control_total_power_bat_force_discharge() | logic/logic.c:1789（bat_force_discharge() 内） |
ac_control_total_power_bat_power_control() | logic/logic.c:1810（bat_power_control() 内） |
ac_control_total_power_self_use_calculate_new() | logic/logic.c:1862（self_use_funtion() 内） |
ac_control_total_power_no_bat_calculate() | logic/logic.c:2030 |
ac_control_total_power_gc_chgpower_calculate() | logic/logic.c:2103（油机模式） |
ac_control_three_phase_power_limit() | logic/logic.c:1751 |
ac_control_three_phase_power_self_use_calculate() | logic/logic.c:1863 |
ac_control_three_phase_power_bat_force_charge() | logic/logic.c:1769 |
ac_control_three_phase_power_bat_force_discharge() | logic/logic.c:1790 |
ac_control_three_phase_power_no_bat_calculate() | logic/logic.c:2031 |
ac_control_Sunspec_ative_power() | logic/dispatch.c:1381（dispatch_Sunspec_ative_power_mode() 内） |
ac_ctrl_time_peak_clip_command() | logic/logic.c:555（time_peakshaving_command() 内） |
ac_ctrl_time_valley_fill_command() | logic/logic.c:564（time_peakshaving_command() 内） |
ac_control_Sunspec_unbalance_ctrl() | 无外部调用点，仅被 ac_control.c:1908 内部调用 |
本头文件不导出任何全局变量（所有结果都写回 g_t_logic_info，声明在 logic/logic.h）。
被调用（本文件引用的外部符号）：
| 名称 | 来源 |
|---|---|
chip.h | #include "chip.h"，提供 u8 / u32 / s32 等基础类型 |
inverter.h | #include "inverter.h"，提供 INV_AC_CTRL / INV_DC_CTRL、逆变器型号宏与逆变器接口 |
6. 依赖关系
依赖：
system/sys/chip.h（基础类型、uCOS-II 配置链）；midware/inverter/inverter.h（型号宏INVERTER_TYPE及由其派生的INV_AC_CTRL、INVERTER_MAX、ALPHAESS_TYPE等）。
被依赖（全部 include 点）：
logic/ac_control.c:12logic/dispatch.c:21logic/logic.c:14logic/csip_aus.c:15（仅为包含，未引用其中符号）
7. 备注与风险点
PREPAY_METER_STATE是「死枚举」：本头文件把它定义为 8 并注释成一种状态，但ac_control.c:1015的fsm_total_power_ac_control()里没有任何 case 处理它，fsm_total_power_ac_control_state_handle()也从不把*nextstate赋成该值。预付费电表逻辑实际通过独立函数prepay_meter_ac_control_state_handle()覆写状态实现，与该枚举无关。ac_control_total_power_self_use_calculate的声明被注释掉（ac_control.h:61），同时其实现在ac_control.c:103-431被#if 0整段屏蔽。这是版本遗留：新版接口为..._self_use_calculate_new()。若有人取消注释调用旧函数会直接链接失败。- 重复声明：
ac_control_three_phase_power_self_use_calculate在第 69 行与第 72 行各声明一次，属手写头文件的复制粘贴遗留，无功能影响但影响可读性。 - 头文件与实现不匹配：
prepay_meter_ac_control_state_handle、ac_control_three_phase_power_bat_force_control这两个非 static 全局函数从未在此声明。它们目前只在ac_control.c内部使用，属于「本该 static 却写成全局」的接口泄漏（详见ac_control.c文档第 7 节）。 - 整体依赖
INV_AC_CTRL的编译期开关：INVERTER_TYPE当前被硬编码为INVERTER_NULL（midware/inverter/inverter.h:172），此时INV_AC_CTRL未定义，本头文件所有函数原型都不可见，logic/logic.c、logic/dispatch.c中对应调用点也被#ifdef屏蔽。头文件本身因此在此配置下等于空壳。 - 缺少版本/日期信息：文件头
@version/@date均为空，与工程内其他文件（如handle_priority.h填写了日期）不一致，属遗留填写问题，无功能影响。