generator.h
源文件路径：
logic/generator.h所属模块：logic（能量调度核心） 代码行数：35
1. 文件职责
本文件是 logic/generator.c 的对外接口头文件，定义柴油发电机（油机 / GC）的工作模式枚举 GENERATOR_MODE_E，并声明 7 个状态查询与控制函数。它是「油机功能」在工程内的公共契约：logic 层用它发起决策、midware 层（逆变器、电表、并机、干接点）用它查询油机运行状态、hmi 层用它渲染设置菜单、net 层用它上报油机功率。由于本文件 #include "includes.h"（工程总头），任何包含它的文件都会连带引入标准库、uCOS-II、GD32 库与 chip.h。它不含数据结构实现与全局变量定义，属于纯声明型头文件。
2. 关键数据结构与宏
| 名称 | 类型 | 说明 |
|---|---|---|
__GENERATOR_H | 宏 | include guard |
GENERATOR_MODE_E | 枚举（typedef 匿名枚举） | 油机工作模式：NONE_MODE = 0（未使用，无对应 case）、SOC_MODE = 1（按 SOC 启停）、TOU_MODE = 2（按时间段启停）、MANUAL_MODE = 4（手动常开）。枚举值 3 被显式跳过，取值不连续 |
includes.h | 头文件（非宏） | 通过 #include "includes.h" 引入，实际带来 <stdio.h> <string.h> <ctype.h> <stdlib.h> <stdarg.h>、ucos_ii.h、os_cpu.h、os_cfg.h、app_cfg.h、gd32f4xx.h、chip.h 全套依赖 |
本文件不定义结构体、联合体、位域，也没有除 include guard 外的常量宏（时间、阈值等常量在 generator.c 里以字面量出现）。
3. 函数清单
| 函数名 | 作用域 | 说明 |
|---|---|---|
generator_logic | 全局 | 油机启停主状态机，定义于 generator.c:240 |
get_offgrid_mode_grid_state | 全局 | 离网模式并网状态查询（TRUE 并网 / FALSE 离网），定义于 generator.c:111 |
get_generator_running_flag | 全局 | 返回对外生效的油机运行标志 g_t_logic_info.u8_generator_on，定义于 generator.c:218 |
get_generator_control_flag | 全局 | 判断是否进入油机充电序控模式（GC_CECONTROL），定义于 generator.c:198 |
get_generator_start_flag | 全局 | 返回本文件内部期望的启动标志 s_u8_generator_on，定义于 generator.c:229 |
get_offgrid_mode_gc_power | 全局 | 返回油机运行功率，并写回 g_t_logic_info.s32_generator_run_power，定义于 generator.c:140 |
get_offgrid_mode_gc_charge_power | 全局 | 返回油机给电池充电的功率，定义于 generator.c:169 |
共 7 个原型声明，全部对应 generator.c 中的全局定义；generator.c 里另有 2 个 static 函数（get_grid_state、get_time_control_mark）没有在本头文件暴露，是本文件有意隐藏的内部实现。
4. 核心逻辑解析
本文件是纯声明文件，无可执行逻辑。与接口契约相关的关键点如下：
4.1 两套「油机标志」的语义区分
头文件同时暴露了两个名字极易混淆的查询函数，它们返回的是不同来源的状态：
| 函数 | 返回值来源 | 语义 | 主要用法 |
|---|---|---|---|
get_generator_start_flag() | generator.c 文件级 static u8 s_u8_generator_on | 本文件即时决策结果，每周期都被重算与覆盖，甚至在同一次 generator_logic() 调用内就可能先置 TRUE 后被并网关闭逻辑置 FALSE | logic.c:2094 清零逆变器额定输入功率与充电限值；inverter.c:1014 用它做边沿检测切换 P-V / P-F down-load 标志 |
get_generator_running_flag() | 全局 g_t_logic_info.u8_generator_on | 对外生效的运行标志，经过第 3 步「三相关机仲裁」后才下降，且被干接点/并机/逆变器协议共同使用 | parallel.c:667/787/958 判断油机运行（并写 u8_gc_control_en） |
二者在「要求关闭但仲裁未通过」时会不一致（start flag 已是 FALSE，running flag 仍为 TRUE）；在并网强制关闭分支里二者又被同时置 FALSE。头文件没有任何注释提示这种差异，调用者只能通过名字猜（start 反而比 running 更「瞬时」）。这是本头文件最需要补充注释的地方。
4.2 模式枚举的使用契约
GENERATOR_MODE_E 的取值同时被多处使用：
generator.c:267的switch (g_t_logic_info.t_config_data.GeneratorMode)——决定启停判据，只处理 1 / 2 / 4（无default）；hmi/key.c（1108、1112、1116、3613-3645、6109-6142、7057-7065、8295-8312等）——用户在设置菜单里循环切换，并把LCD_RTDB.u8_generator_mode写回g_t_logic_info.t_config_data.GeneratorMode；logic/generator.c之外的hmi/ui/ui_setting_user_func_generator_mode*.c——界面渲染。
也就是说，这个枚举值会落盘到 Flash 配置区（t_config_data.GeneratorMode 是 u8），枚举的数值稳定性等同于持久化格式的稳定性。头文件里 MANUAL_MODE = 4 这种显式指定值、并跳过 3 的写法，暗示历史上存在过值 3 的模式被删除，但枚举中未留洞位注释。
4.3 通信协议帧格式
无。本文件不涉及任何帧结构、校验、超时；其声明的函数中与协议相关的只有 get_offgrid_mode_gc_power() 的返回值会被 net/ems.c 拼进上报 JSON 的 GCPower 字段。
4.4 定时 / uCOS-II 配合
本文件不声明任务、信号量、事件标志或消息邮箱句柄，也不含任何 uCOS-II 调用；但通过 #include "includes.h" 间接引入了 ucos_ii.h / os_cfg.h。generator.c 内部使用 OSTimeGet()（ms 滴答）做滞回计时，这一点在头文件中完全没有体现（无任何时间语义说明）。
5. 对外接口
导出（供外部使用）：
| 名称 | 使用方 |
|---|---|
GENERATOR_MODE_E（SOC_MODE / TOU_MODE / MANUAL_MODE） | hmi/key.c、hmi/ui/ui_setting_user_func_generator_mode.c、hmi/ui/ui_setting_user_func_generator_mode_select.c |
generator_logic() | logic/logic.c:2930 |
get_offgrid_mode_grid_state() | midware/meter/meter.c:626、3652、5460 |
get_generator_running_flag() | midware/inverter/parallel.c:667、787、958（parallel.c:145 为被注释掉的旧代码） |
get_generator_control_flag() | logic/logic.c:2193 |
get_generator_start_flag() | logic/logic.c:2094、midware/inverter/inverter.c:1014 |
get_offgrid_mode_gc_power() | data/resume_data/flash/flash_data_store.c:670、net/ems.c:540、1431、midware/auxiliary/system_aux.c:268、270 |
get_offgrid_mode_gc_charge_power() | midware/auxiliary/system_aux.c:300（所在统计函数当前被 #if 0 屏蔽） |
本头文件不导出任何全局变量或常量。
被调用（本文件引用的外部符号）：
| 名称 | 来源 |
|---|---|
includes.h | UCOSII/uCOS-CONFIG/includes.h（工程总头，连带 chip.h、gd32f4xx.h、ucos_ii.h 等） |
6. 依赖关系
依赖：
UCOSII/uCOS-CONFIG/includes.h——唯一直接 include，属「重量级」总头，使本头文件间接依赖标准库、uCOS-II、GD32 标准外设库与chip.h。
被依赖（全部 include 点，共 13 处，跨 5 个模块）：
- logic：
logic/logic.c:16、logic/generator.c:13 - data：
data/resume_data/flash/flash_data_store.c:31 - hmi：
hmi/key.c:29、hmi/ui/ui_setting_user_func_generator_mode.c:4、hmi/ui/ui_setting_user_func_generator_mode_select.c:3 - midware：
midware/auxiliary/system_aux.c:26、midware/inverter/inverter.c:32、midware/inverter/parallel.c:26、midware/inverter/alphaess/alphaess_comm_usart.c:22、midware/inverter/inovance/inovance_comm_usart.c:24、midware/meter/meter.c:24 - net：
net/ems.c:38
7. 备注与风险点
- 两个状态查询函数的语义差异无任何注释：
get_generator_start_flag()（内部即时标志）与get_generator_running_flag()（对外生效标志）在本文件里只是两行原型，看不出二者的来源、更新时机与「仲裁可能导致不一致」这一关键事实。实际调用方分别按「边沿检测」和「运行判断」两种完全不同的用法消费它们，一旦有人把二者互换，会出现逆变器 P-V/P-F 曲线提前切换或并机充电使能错误等难以复现的问题。建议在本文件补上两者的语义说明。 #include "includes.h"过重：本头文件本身只需要u8/s32等基础类型，却引入了整套标准库、RTOS 与芯片库。13 个包含者（含 HMI 界面文件）都被迫接受这一依赖，既拖慢编译也加剧了头文件之间的隐式耦合。建议改为#include "chip.h"（与同目录handle_priority.h、math_tools.h的定位一致）。GENERATOR_MODE_E缺少NONE_MODE的语义说明且值不连续：MANUAL_MODE = 4显式跳过 3，而NONE_MODE = 0在generator.c的switch里没有任何case。该枚举值会被持久化到 Flash（t_config_data.GeneratorMode为u8），因此 0 和 3 都是「合法但未定义行为」的取值——落进这两种值时油机既不启动也不关闭。头文件里没有注释说明哪些值是有效配置。- 本头文件完全没有函数注释：7 个原型无一有参数/返回值/副作用的说明（例如
get_offgrid_mode_gc_power()会写全局变量s32_generator_run_power这一副作用完全不可见；get_generator_control_flag()返回TRUE的真实含义是「应进入 GC 序控模式」而非字面的「控制标志」）。相比之下generator.c里每个函数都有 Doxygen 风格的注释块，只是多数@Brief是空的。 - 原型书写风格不统一：
u8 get_offgrid_mode_grid_state(void);与u8 get_generator_running_flag(void);（多一个空格）混排；7 个原型之间只有一条分隔注释线，没有按「查询」与「执行」分组，可读性一般。 - 文件头元信息不完整：
@brief后为空、@version与@date未填，与该目录下handle_priority.h（有@date :2026-0724）等文件的填写规范不一致，无功能影响。 - 接口暴露面偏大：头文件把 7 个内部辅助查询（如
get_offgrid_mode_gc_power/get_offgrid_mode_gc_charge_power）全部公开，实际其中get_offgrid_mode_gc_charge_power()的唯一调用链已被#if 0屏蔽（属事实死接口）。清理这类接口有助于缩小耦合面。