afci_comm.h

源文件路径：midware/afci/afci_comm.h 所属模块：midware / afci（电弧故障断路器 AFCI 通信与日志） 代码行数：110

1. 文件职责

本头文件是 AFCI 常规通信模块的对外契约：它声明了 AFCI 的从站地址、全部寄存器地址/数量常量、3 个业务状态枚举、日志上传状态块 AFCI_LOG_DATA_TABLE、该状态块的全局实例 g_t_afci_log_tab，以及 afci_comm.c 对外暴露的 13 个函数原型。

它同时充当模块间的常量共享中心：VERSION_AFCI_HARD / AFCI_TYPE_BYTE_WATT_* 被 net/afci_download.c 用于机型与硬版本上报，DEBUG_ALPHAESS_AFCI 还被 alphaess_comm_usart.c 当作 AFCI 分支的调试开关使用。

文件本身不含任何可执行代码，唯一被 include 的依赖是工程总头 includes.h。

2. 关键数据结构与宏

AFCI_LOG_DATA_TABLE 字段表

sizeof(AFCI_LOG_DATA_TABLE) ≈ 1137 字节（含对齐），落在 SDRAM_AFCI_FAULT_LOG_ADDR 预留的 2 KB 区间内。

3. 函数清单

本文件不定义函数，只声明以下 13 个原型（全部定义于 afci_comm.c）：

声明缺口：afci_comm.c:747 定义的全局函数 send_clear_afci_log_data() 未在本头文件声明，外部模块无法正常引用（仅本文件内部使用）。

4. 核心逻辑解析

4.1 三组常量构成的寻址空间

USART2 上跑着三个逻辑设备，靠首字节区分（这是使用方 alphaess_afci_recv_data / alphaess_recv_data 的判据）：

AFCI 的寄存器映射（功能码含义见 .c 文档）：

注意 0x00E0 与 0xE0：同一个数值既是寄存器地址（配功能码 0x06）又是功能码（裸帧），是本模块最容易混淆的设计点。

4.2 日志缓冲尺寸的推导链

AFCI_GET_MAX_LOG_DATA_LEN = 64        // 单帧最多 64 字节原始数据
AFCI_LOG_MAX_FRAME_NUM    = 17        // 缓冲按 17 帧规划
AFCI_LOG_TOTAL_MAX_LEN    = 64*17 = 1088   // = afci_log_buff 字符容量
AFCI_LOG_GROUP_SIZE       = 8         // 但每 8 帧就成组发出

因为缓冲存的是 %02X HEX 文本，1088 字符只承载 544 字节原始数据。上界守卫在 afci_comm.c:800 用 >= 判断，因此刚好填满也判 BUF_FULL，留出末字节给 '\0'（实际 '\0' 写在 afci_log_buff[send_len]，因守卫是严格 <，下标必然 ≤ 1087，安全）。

由于 AFCI_LOG_GROUP_SIZE(8) < AFCI_LOG_MAX_FRAME_NUM(17)，正常流程下每组只用掉 8×64×2 = 1024 字符就发出，1088 的容量是给「一条帧就返回长数据」或残包兜底用的，AFCI_QRY_BUF_FULL 分支正是为此准备的。

4.3 状态枚举的隐式赋值与外部契约

ALPHAESS_AFCI_STATE_E 与 AFCI_QRY_RET_E 无显式初值，靠声明顺序取 0,1,2(,3)。它们只在 afci_comm.c 内部作为 static u8 的比较对象使用，改动顺序会静默改变语义（不会编译报错）。

AFCI_LOG_UPDATA_STATE_E 则是对外协议：0x01 = 中途包、0x02 = 末包，直接进入 net/ems.c:2700 的 JSON "UploadStatus":"%d"，云端据此重组文件；net/server.c:7084 的 set_afci_log_data_upload_send_status() 又用 status == AFCI_UPDATA_COMPLETE 决定是否清除 AFCI 侧记录。因此这个枚举值一旦修改，云端协议与 AFCI 清记录时机都会一起错位。

5. 对外接口

本文件导出：

• 全局变量声明：extern AFCI_LOG_DATA_TABLE g_t_afci_log_tab;（:95）—— 由 afci_comm.c:27 定义并定址到 SDRAM；被 net/ems.c（fill_send_afci_log、发送条件判定、清应答标志）与 net/server.c:7084 读写。
• 13 个函数原型（见第 3 节）。实际调用方集中在 midware/inverter/alphaess/alphaess_comm_usart.c（:5060/5065/5071/5076/5209/5411/5412）、midware/afci/afci_upgrade.c（:55/56/432）、net/ems.c:2270（inverter_read_ver_afci）、net/server.c:7084（set_afci_log_data_upload_send_status）。
• 宏常量：VERSION_AFCI_HARD / AFCI_TYPE_BYTE_WATT_S / AFCI_TYPE_BYTE_WATT_T 被 net/afci_download.c（get_afci_hard_version / get_afci_type）使用；DEBUG_ALPHAESS_AFCI 被 alphaess_comm_usart.c 使用。

本文件调用的外部符号：仅 includes.h（:13）。这是工程的总汇头，会引入 stdint/string/uCOS-II/gd32f4xx 等全部基础依赖，因此任何包含本头文件的模块都会被动引入庞大的编译面。

6. 依赖关系

依赖：includes.h（:13）。

被依赖（include afci_comm.h 的文件）：

• midware/afci/afci_comm.c:15、midware/afci/afci_upgrade.c:15
• midware/inverter/alphaess/alphaess_comm_usart.c:30
• net/ems.c:56、net/server.c:55、net/afci_download.c:20

7. 备注与风险点

1. send_clear_afci_log_data 未声明：afci_comm.c:747 定义、:934 调用，但本头文件没有对应原型。若外部模块需要调用只能自行 extern，且编译器无法做原型检查（见 afci_comm.c 风险点 10）。
2. 声明的两个函数全工程无调用点：get_afci_soft_version()（:105）与 send_afci_clear_info()（:107）。get_afci_soft_version 与 inverter_read_ver_afci 功能几乎重复（后者多一次 '\0' 兜底），实际云端上报走的是 inverter_read_ver_afci（net/ems.c:2270）。两者保留易误用。
3. u16_afci_log_seq 是遗留字段：注释为“当前帧序号”，但实现改用函数内 static l_u16_frame_seq。该字段从未被读写，仍占 4 字节（含对齐），并出现在定址到 SDRAM 的结构体里。
4. 0x00E0 与 0xE0 语义重载：AFCI_ADDR_REG_SEND_CLEAR_INFO_CMD（寄存器地址）与 AFCI_FUNC_REG_SEND_CLEAR_DATA_CMD（功能码）值相近、命名相近、用途不同，极易在后续维护中写错。
5. AFCI_LOG_TOTAL_MAX_LEN 与 AFCI_LOG_GROUP_SIZE 的关系未在注释中说明：1088 的容量按 17 帧规划，而实际每 8 帧成组发送，容量偏大近一倍；若后续把 AFCI_LOG_GROUP_SIZE 调到 > 17，长数据帧会立刻触发 AFCI_QRY_BUF_FULL 分支（该分支会把残包当作末组发出），行为会静默改变。
6. AFCI_TYPE_BYTE_WATT_T 的值是 "BYTE_AFCI_T" 而非 "BYTE_AFCI_T10"：与逆变器机型枚举 INVERTER_TYPE_BYTE_WATT_T（对应 SUB_T10）命名不平行，云端型号串匹配依赖此字面量，改动需与云端同步。
7. VERSION_AFCI_HARD 是硬编码字符串：get_afci_hard_version() 直接返回该宏，与实物 AFCI 上报的软版本（运行期读取）无一致性校验路径，硬件改版必须手工改宏。
8. DEBUG_ALPHAESS_AFCI 定义在业务头文件里：该开关控制 alphaess_comm_usart.c 的打印行为，把调试粒度耦合到 AFCI 头文件；同时 afci_comm.c 内有大量 printf 只在 == 1 时编译，长期处于关闭状态意味着这些代码缺少编译验证（例如 :305 用了 for(int i=...) 的 C99 写法，与其他位置的 u8 i 风格不一致）。
9. 除 AFCI_LOG_UPDATA_STATE_E 外均无显式初值：ALPHAESS_AFCI_STATE_E(3 个)、AFCI_QRY_RET_E(4 个) 都依赖声明顺序取值，且被赋给 u8 变量。若有人插入新成员，状态机比较会静默错位。