433_STM32/Core/Src/cmd_parser.c

/**
  ******************************************************************************
  * @file    cmd_parser.c
  * @brief   ASCII指令解析模块实现
  * @author  Application Layer
  * @version 1.1
  ******************************************************************************
  * @attention
  * 本模块实现ASCII文本指令的解析和处理
  * 关键特性：
  * 1. 状态机解析，健壮可靠
  * 2. 完善的安全防护（缓冲区边界检查、超时重置、字符过滤）
  * 3. 异或校验，FF特权后门
  * 4. 支持RL、DI、ECHO指令
  *
  * 修订历史：
  * v1.1 - 修复审查报告高危-6、中危-7/8
  ******************************************************************************
  */

#include "cmd_parser.h"
#include "uart2_print.h"
#include "io_monitor.h"
#include "relay_control.h"
#include <string.h>
#include <ctype.h>
#include <stdio.h>  // snprintf
#include <stdlib.h> // atoi

/*==============================================================================
 * 调试宏定义
 *============================================================================*/
/* DEBUG_CMD_PARSER: 调试日志开关，置1时启用解析过程日志输出 */
#define DEBUG_CMD_PARSER  1

#if DEBUG_CMD_PARSER
/* 调试日志宏，带模块前缀"[CMD]"方便过滤 */
#define DEBUG_LOG(fmt, ...)  UART2_Print_Printf("[CMD] " fmt "\r\n", ##__VA_ARGS__)
#else
#define DEBUG_LOG(fmt, ...)
#endif

/*==============================================================================
 * 解析器状态机定义
 *============================================================================*/
/**
  * @brief  指令解析器状态枚举
  * @note   状态机各状态定义，描述指令解析的完整生命周期
  *
  * 状态转换图：
  *
  *   [空闲] ---'$'---> [解析命令]
  *   [解析命令] ---','---> [解析参数1]
  *   [解析命令] ---'*'---> [解析校验和]
  *   [解析参数1] ---','---> [解析参数2]
  *   [解析参数1] ---'*'---> [解析校验和]
  *   [解析参数2] ---'*'---> [解析校验和]
  *   [解析校验和] ---'\n'---> [完成]
  *   [完成] ---'$'---> [解析命令]
  *   任何状态 ---超时---> [空闲]
  *
  * 各状态说明：
  *   - PARSE_IDLE: 等待帧起始符'$'，处于空闲状态
  *   - PARSE_CMD: 正在解析命令字段(直到遇到','或'*')
  *   - PARSE_PARAM1: 正在解析第一个参数(直到遇到','或'*')
  *   - PARSE_PARAM2: 正在解析第二个参数(直到遇到'*')
  *   - PARSE_CHECKSUM: 正在解析校验和(两个十六进制字符直到'\n')
  *   - PARSE_COMPLETE: 完整帧已解析完成，等待处理
  */
typedef enum {
    PARSE_IDLE = 0,      /**< 空闲状态，等待帧起始 */
    PARSE_CMD,           /**< 正在解析命令字段 */
    PARSE_PARAM1,        /**< 正在解析第一个参数 */
    PARSE_PARAM2,        /**< 正在解析第二个参数 */
    PARSE_CHECKSUM,      /**< 正在解析校验和 */
    PARSE_COMPLETE       /**< 解析完成，可处理 */
} parse_state_t;

/*==============================================================================
 * 数据结构定义
 *============================================================================*/
/**
  * @brief  解析器上下文数据结构
  * @note   保存指令解析的完整状态信息，包括当前状态、已解析字段和统计计数
  *
  * 设计目的：
  *   解析器需要记忆多个中间状态：当前解析状态、已接收的各字段内容、
  *   校验和累加值、上下文字符索引等。这些信息集中保存在此结构体中，
  *   实现无状态的逐字节处理(Stateless Byte-by-Byte Processing)模式。
  *
  * 字段说明：
  *   - state: 当前解析状态机的状态
  *   - frame: 已解析完成的指令帧结构(cmd_frame_t类型)
  *   - field_index: 当前字段的字符写入位置索引
  *   - checksum_acc: 校验和累加器，逐字节异或得到
  *   - cs_buffer: 接收的校验和字符缓存(两个HEX字符)
  *   - cs_index: 校验和字符缓存的当前写入位置
  *   - last_rx_tick: 上次接收到数据的时间戳(用于超时检测)
  *   - error_count: 解析错误累计次数
  *   - valid_count: 有效指令帧累计次数
  */
typedef struct {
    parse_state_t state;             /**< 解析状态机当前状态 */
    cmd_frame_t frame;                /**< 已解析指令帧数据 */
    uint8_t field_index;             /**< 当前字段的字符写入位置 */
    uint8_t checksum_acc;             /**< 校验和累加器(异或运算) */
    uint8_t cs_buffer[2];            /**< 接收的校验和字符缓存 */
    uint8_t cs_index;                /**< 校验和字符缓存写入位置 */
    uint32_t last_rx_tick;           /**< 上次接收时间戳(毫秒) */
    uint32_t error_count;            /**< 解析错误累计次数 */
    uint32_t valid_count;            /**< 有效帧累计次数 */
} parser_context_t;

/*==============================================================================
 * 全局变量定义
 *============================================================================*/
/**
  * @brief  解析器上下文实例
  * @note   static修饰确保仅本文件内可访问，保存解析过程全部状态
  */
static parser_context_t ctx;

/**
  * @brief  响应回调函数指针
  * @note   用于将响应发送到正确的源端口
  */
static cmd_response_callback_t g_response_callback = NULL;

/**
  * @brief  当前源端口ID
  * @note   记录当前正在解析的指令来自哪个端口
  */
static uint8_t g_current_source_port = 0;

/*==============================================================================
 * 内部静态函数声明
 *============================================================================*/
static void reset_parser(void);
static bool is_valid_cmd_char(char c);
static bool is_valid_param_char(char c);
static uint8_t hex_char_to_val(char c);
static uint8_t hex_to_byte(char high, char low);
static uint8_t calc_checksum(const char *data, uint8_t len);
static void send_response_ok(const char *content);
static void send_response_err(const char *err_code);
static bool is_str_empty(const char *str);
static bool is_str_numeric(const char *str);
static void process_cmd_frame(const cmd_frame_t *frame);

/*==============================================================================
 * 内部辅助函数实现
 *============================================================================*/
/**
  * @brief  重置解析器到初始状态
  * @note   清除所有上下文信息，准备接收新指令帧
  *
  * @param  无
  * @return 无
  *
  * 重置内容：
  *   - 状态恢复为PARSE_IDLE
  *   - 字段索引清零
  *   - 校验和累加器清零
  *   - 校验和缓存索引清零
  *   - cmd_frame结构体全部清零
  *
  * 调用时机：
  *   - 解析出错时
  *   - 解析完成处理后
  *   - 接收到完整帧后的空闲期
  */
static void reset_parser(void)
{
    ctx.state = PARSE_IDLE;
    ctx.field_index = 0;
    ctx.checksum_acc = 0;
    ctx.cs_index = 0;
    memset(&ctx.frame, 0, sizeof(ctx.frame));
}

/**
  * @brief  验证命令字符合法性
  * @note   命令字段只能包含大写字母和数字
  *
  * @param  c: 待验证的字符(输入)
  * @return bool: true=合法，false=非法
  *
  * 过滤规则：
  *   - 允许: 'A'-'Z', '0'-'9'
  *   - 禁止: 小写字母、标点符号、控制字符等
  *
  * 安全意义：
  *   - 限制命令字符集可防止注入攻击
  *   - 简化解析逻辑，避免处理边界情况
  */
static bool is_valid_cmd_char(char c)
{
    return isupper((unsigned char)c) || isdigit((unsigned char)c);
}

/**
  * @brief  验证参数字符合法性
  * @note   参数字段可包含大部分可打印字符，但排除特殊分隔符
  *
  * @param  c: 待验证的字符(输入)
  * @return bool: true=合法，false=非法
  *
  * 过滤规则：
  *   - 允许: isprint()返回true的字符，但不包括'*'
  *   - 禁止: '*'、'\r'、'\n'及其他不可打印字符
  *
  * 特殊说明：
  *   - '*'是校验和起始分隔符，不能出现在参数中
  *   - '\r'和'\n'是帧结束符
  */
static bool is_valid_param_char(char c)
{
    return isprint((unsigned char)c) && c != '*' && c != '\r' && c != '\n';
}

/**
  * @brief  十六进制字符转换为数值
  * @note   将单个十六进制字符('0'-'9','A'-'F')转换为对应的4位数值
  *
  * @param  c: 十六进制字符(输入)
  * @return uint8_t: 转换后的数值(0-15)，非法字符返回0
  *
  * 转换规则：
  *   '0'-'9' -> 0-9
  *   'A'-'F' -> 10-15
  *   'a'-'f' -> 10-15 (小写也支持)
  *   其他字符 -> 0 (默认处理)
  */
static uint8_t hex_char_to_val(char c)
{
    if (c >= '0' && c <= '9') return c - '0';
    if (c >= 'A' && c <= 'F') return c - 'A' + 10;
    if (c >= 'a' && c <= 'f') return c - 'a' + 10;
    return 0;
}

/**
  * @brief  将两个十六进制字符转换为一个字节
  * @note   高位字符在前，地位字符在后，组合成完整的字节值
  *
  * @param  high: 高位十六进制字符(输入)
  * @param  low:  低位十六进制字符(输入)
  * @return uint8_t: 组合后的字节值(0-255)
  *
  * 计算公式：result = (high_nibble << 4) | low_nibble
  *
  * 示例：
  *   hex_to_byte('A', 'F') 返回 0xAF (十进制175)
  */
static uint8_t hex_to_byte(char high, char low)
{
    return (hex_char_to_val(high) << 4) | hex_char_to_val(low);
}

/**
  * @brief  计算异或校验和
  * @note   对输入数据的每个字节执行异或运算，生成校验码
  *
  * @param  data: 待计算校验和的数据缓冲区(输入)
  * @param  len:  数据长度，以字节为单位(输入)
  * @return uint8_t: 校验和(异或结果)
  *
  * 算法原理：
  *   遍历数据缓冲区，将每个字节与累加器进行异或操作。
  *   初始累加器为0，最终结果为所有字节的异或和。
  *   XOR的特性：a^a=0, a^0=a, 具有可逆性，适合简单校验
  */
static uint8_t calc_checksum(const char *data, uint8_t len)
{
    uint8_t cs = 0;
    for (uint8_t i = 0; i < len; i++) {
        cs ^= (uint8_t)data[i];
    }
    return cs;
}

/**
  * @brief  发送成功响应消息
  * @note   构造并发送指令执行成功的响应帧
  *
  * @param  content: 响应内容字符串指针(输入)
  * @return 无
  *
  * 响应帧格式：
  *   $OK,<content>*<checksum>\r\n
  *
  * 校验和计算范围：
  *   从'$'之后到'*'之前的全部内容(不含$和*)
  *
  * 使用示例：
  *   send_response_ok("RL,1") -> $OK,RL,1*XX\r\n
  */
static void send_response_ok(const char *content)
{
    char msg[64];
    uint8_t cs;

    int len = snprintf(msg, sizeof(msg), "$OK,%s*", content);
    cs = calc_checksum(msg + 1, len - 1);
    snprintf(msg + len, sizeof(msg) - len, "%02X\r\n", cs);

    if (g_response_callback != NULL) {
        g_response_callback(g_current_source_port, msg);
    } else {
        UART2_Print_String(msg);
    }
}

/**
  * @brief  发送错误响应消息
  * @note   构造并发送指令执行失败的响应帧
  *
  * @param  err_code: 错误代码字符串(输入)，如"PARAM"、"CS"、"CMD"
  * @return 无
  *
  * 响应帧格式：
  *   $ERR,<err_code>*<checksum>\r\n
  *
  * 错误代码含义：
  *   - "PARAM": 参数格式或值非法
  *   - "CS": 校验和不匹配
  *   - "CMD": 命令无法识别
  */
static void send_response_err(const char *err_code)
{
    char msg[32];
    uint8_t cs;

    int len = snprintf(msg, sizeof(msg), "$ERR,%s*", err_code);
    cs = calc_checksum(msg + 1, len - 1);
    snprintf(msg + len, sizeof(msg) - len, "%02X\r\n", cs);

    if (g_response_callback != NULL) {
        g_response_callback(g_current_source_port, msg);
    } else {
        UART2_Print_String(msg);
    }
}

/**
  * @brief  判断字符串是否为空
  * @note   检查指针是否为NULL或首字符是否为'\0'
  *
  * @param  str: 待检查的字符串指针(输入)
  * @return bool: true=空字符串或NULL，false=非空
  */
static bool is_str_empty(const char *str)
{
    return (str == NULL || str[0] == '\0');
}

/**
  * @brief  判断字符串是否全为数字
  * @note   验证字符串中的所有字符是否都是十进制数字
  *
  * @param  str: 待检查的字符串指针(输入)
  * @return bool: true=全为数字，false=包含非数字字符或为空
  *
  * 实现逻辑：
  *   从字符串开头遍历到'\0'，检查每个字符是否满足isdigit()。
  *   一旦遇到非数字字符立即返回false。
  */
static bool is_str_numeric(const char *str)
{
    /* 空字符串检查 */
    if (is_str_empty(str)) {
        return false;
    }
    /* 逐字符检查是否为数字 */
    while (*str) {
        if (!isdigit((unsigned char)*str)) {
            return false;
        }
        str++;
    }
    return true;
}

/**
  * @brief  指令帧处理函数
  * @note   根据解析出的命令类型分发到相应的处理函数
  *
  * @param  frame: 已解析完成的指令帧结构指针(输入)
  * @return 无
  *
  * 支持的指令列表：
  *   - RL <relay_id> <state>: 控制继电器开关
  *   - DI [channel]: 查询数字输入状态
  *   - ECHO: 回显测试指令
  *
  * 处理流程：
  *   1. 调试日志输出指令详情
  *   2. 根据cmd字段分发到对应处理分支
  *   3. 参数合法性校验
  *   4. 调用业务层函数执行操作
  *   5. 发送成功/失败响应
  */
static void process_cmd_frame(const cmd_frame_t *frame)
{
    /*----------------------------------------------------------
     * 调试日志：打印完整指令信息
     *----------------------------------------------------------*/
    DEBUG_LOG("CMD=%s P1=%s P2=%s CS=%02X/%02X %s",
              frame->cmd, frame->param1, frame->param2,
              frame->received_cs, frame->calculated_cs,
              frame->skip_checksum ? "(skip)" : "");

    /*----------------------------------------------------------
     * 继电器控制指令: RL <state>
     * 格式: $RL,<state>*<checksum>
     * 说明: 单路继电器，state为0(关)或1(开)
     *----------------------------------------------------------*/
    if (strcmp(frame->cmd, "RL") == 0) {
        /* 参数合法性检查：param1必须为数字 */
        if (!is_str_numeric(frame->param1)) {
            send_response_err("PARAM");
            DEBUG_LOG("Invalid RL param: not numeric");
            return;
        }

        /* 将参数字符串转换为整数 */
        int state = atoi(frame->param1);

        /* 状态值范围检查: 0或1 */
        if (state == 0 || state == 1) {
            /* 调用业务层函数设置继电器状态 */
            Relay_SetState(state ? true : false);

            /* 构造并发送成功响应 */
            char resp[32];
            snprintf(resp, sizeof(resp), "RL,%d", state);
            send_response_ok(resp);

            DEBUG_LOG("Relay -> %s", state ? "ON" : "OFF");
        } else {
            /* 参数值超出有效范围 */
            send_response_err("PARAM");
            DEBUG_LOG("Invalid RL param: state=%d", state);
        }
    }
    /*----------------------------------------------------------
     * 数字输入查询指令: DI [channel]
     * 格式1(查询全部): $DI*<checksum> 或 $DI,0*<checksum>
     * 格式2(查询单通道): $DI,<channel>*<checksum>
     *----------------------------------------------------------*/
    else if (strcmp(frame->cmd, "DI") == 0) {
        /*----------------------------------------------------------
         * 分支1: 查询全部通道状态
         * param1为空或为"0"时触发
         *----------------------------------------------------------*/
        if (is_str_empty(frame->param1) || strcmp(frame->param1, "0") == 0) {
            /* 获取所有通道状态的组合掩码 */
            uint8_t states = IO_Monitor_GetAllStates();
            /* 构造响应消息，将四路状态按位展开为ASCII字符 */
            char resp[32];
            snprintf(resp, sizeof(resp), "DI,%d%d%d%d",
                     (states >> 0) & 1, (states >> 1) & 1,
                     (states >> 2) & 1, (states >> 3) & 1);
            send_response_ok(resp);
            DEBUG_LOG("DI all states: 0x%02X", states);
        }
        /*----------------------------------------------------------
         * 分支2: 查询指定单通道状态
         * param1为数字时触发
         *----------------------------------------------------------*/
        else if (is_str_numeric(frame->param1)) {
            int channel = atoi(frame->param1);
            /* 通道编号范围检查: 1-4 */
            if (channel >= 1 && channel <= 4) {
                /* 获取该通道的当前状态(内部使用0-base索引) */
                uint8_t state = IO_Monitor_GetState(channel - 1);
                char resp[32];
                snprintf(resp, sizeof(resp), "DI,%d,%d", channel, state);
                send_response_ok(resp);
                DEBUG_LOG("DI%d = %d", channel, state);
            } else {
                /* 通道编号超出范围 */
                send_response_err("PARAM");
                DEBUG_LOG("Invalid DI channel: %d", channel);
            }
        }
        /*----------------------------------------------------------
         * 分支3: 参数格式非法
         *----------------------------------------------------------*/
        else {
            send_response_err("PARAM");
            DEBUG_LOG("Invalid DI param: not numeric");
        }
    }
    /*----------------------------------------------------------
     * 回显测试指令: ECHO
     * 格式: $ECHO*<checksum>
     * 用途: 测试通信链路是否正常
     *----------------------------------------------------------*/
    else if (strcmp(frame->cmd, "ECHO") == 0) {
        send_response_ok("ECHO");
        DEBUG_LOG("ECHO response sent");
    }
    /*----------------------------------------------------------
     * 未知命令处理
     *----------------------------------------------------------*/
    else {
        send_response_err("CMD");
        DEBUG_LOG("Unknown command: %s", frame->cmd);
    }
}

/*==============================================================================
 * 公共函数实现
 *============================================================================*/
/**
  * @brief  指令解析器初始化
  * @note   在系统启动时调用，初始化解析器上下文
  *
  * @param  无
  * @return 无
  *
  * 初始化内容：
  *   - 使用memset将整个上下文结构清零
  *   - 将状态显式设置为PARSE_IDLE
  *
  * 注意：
  *   全局变量ctx本身是static且初始化为{0}，
  *   此函数调用memset是确保明确初始化，
  *   防止未来新增字段时出现未初始化问题
  */
void CmdParser_Init(void)
{
    memset(&ctx, 0, sizeof(ctx));
    ctx.state = PARSE_IDLE;

    DEBUG_LOG("Init OK");
}

/**
  * @brief  向解析器输入一个字节
  * @note   核心解析函数，实现状态机逻辑，应对每个接收字节调用一次
  *
  * @param  byte:        待解析的接收字节(输入)
  * @param  current_tick: 当前系统时间戳，毫秒单位(输入)
  * @return 无
  *
  * 算法说明 - 状态机核心逻辑：
  *   本函数是整个解析器的核心，实现了有限状态机(FSM)。
  *   每次调用处理一个字节，根据当前状态(ctx.state)和输入字节
  *   决定状态转换和动作。
  *
  * 状态转换详细说明：
  *
  *   [PARSE_IDLE]:
  *     - byte='$' -> reset_parser(), state=PARSE_CMD
  *     - 其他字节 -> 忽略，保持IDLE
  *
  *   [PARSE_CMD]:
  *     - byte=',' -> 字段结束，state=PARSE_PARAM1，field_index=0
  *     - byte='*' -> 字段结束，state=PARSE_CHECKSUM，cs_index=0
  *     - is_valid_cmd_char(byte) -> 写入cmd缓冲区，checksum_acc^=byte
  *     - 其他情况 -> error_count++, reset_parser()
  *
  *   [PARSE_PARAM1]:
  *     - byte=',' -> 字段结束，state=PARSE_PARAM2，field_index=0
  *     - byte='*' -> 字段结束，state=PARSE_CHECKSUM，cs_index=0
  *     - is_valid_param_char(byte) -> 写入param1缓冲区，checksum_acc^=byte
  *     - 其他情况 -> error_count++, reset_parser()
  *
  *   [PARSE_PARAM2]:
  *     - byte='*' -> 字段结束，state=PARSE_CHECKSUM，cs_index=0
  *     - is_valid_param_char(byte) -> 写入param2缓冲区，checksum_acc^=byte
  *     - 其他情况 -> error_count++, reset_parser()
  *
  *   [PARSE_CHECKSUM]:
  *     - byte='\n' -> 校验和接收完成，验证并设置state=PARSE_COMPLETE
  *     - byte='\r' -> 忽略(回车符)
  *     - 其他情况 -> 写入cs_buffer[cs_index++]，最多2个字符
  *
  *   [PARSE_COMPLETE]:
  *     - reset_parser()
  *     - byte='$' -> state=PARSE_CMD (允许连续帧)
  *
  * 超时处理：
  *   如果当前状态不是IDLE且距离上次接收超过PARSE_TIMEOUT_MS，
  *   则判定为接收超时，重置解析器到IDLE状态
  */
void CmdParser_FeedByte(uint8_t byte, uint32_t current_tick)
{
    /*----------------------------------------------------------
     * 超时检测
     * 如果接收到新字节且距离上次接收已超时，则重置解析器
     *----------------------------------------------------------*/
    if (ctx.state != PARSE_IDLE && ctx.state != PARSE_COMPLETE) {
        if (current_tick - ctx.last_rx_tick >= PARSE_TIMEOUT_MS) {
            ctx.error_count++;
            DEBUG_LOG("Timeout, reset parser");
            reset_parser();
            /* 超时后如果收到'$'，立即开始解析新帧 */
            if (byte == '$') {
                ctx.state = PARSE_CMD;
            }
            return;
        }
    }
    /* 更新最后接收时间戳 */
    ctx.last_rx_tick = current_tick;

    /*----------------------------------------------------------
     * 状态机主分支：根据当前状态处理输入字节
     *----------------------------------------------------------*/
    switch (ctx.state) {
        /*----------------------------------------------------------
         * PARSE_IDLE: 等待帧起始符'$'
         *----------------------------------------------------------*/
        case PARSE_IDLE:
            if (byte == '$') {
                reset_parser();
                ctx.state = PARSE_CMD;
            }
            break;

        /*----------------------------------------------------------
         * PARSE_CMD: 解析命令字段
         *----------------------------------------------------------*/
        case PARSE_CMD:
            if (byte == ',') {
                /* 命令字段结束符，遇到逗号转入参数1解析 */
                ctx.frame.cmd[ctx.field_index] = '\0';
                ctx.state = PARSE_PARAM1;
                ctx.field_index = 0;
            } else if (byte == '*') {
                /* 无参数命令，遇到'*'直接转入校验和解析 */
                ctx.frame.cmd[ctx.field_index] = '\0';
                ctx.state = PARSE_CHECKSUM;
                ctx.field_index = 0;
                ctx.cs_index = 0;
            } else if (is_valid_cmd_char(byte)) {
                /* 有效的命令字符，写入缓冲区 */
                if (ctx.field_index < CMD_MAX_LEN - 1) {
                    ctx.frame.cmd[ctx.field_index++] = byte;
                    ctx.checksum_acc ^= byte;  /* 累加到校验和 */
                } else {
                    /* 缓冲区溢出，命令过长 */
                    ctx.error_count++;
                    reset_parser();
                }
            } else {
                /* 无效字符，命令只能包含大写字母和数字 */
                ctx.error_count++;
                reset_parser();
            }
            break;

        /*----------------------------------------------------------
         * PARSE_PARAM1: 解析第一个参数
         *----------------------------------------------------------*/
        case PARSE_PARAM1:
            if (byte == ',') {
                /* 参数1结束符，遇到逗号转入参数2解析 */
                ctx.frame.param1[ctx.field_index] = '\0';
                ctx.state = PARSE_PARAM2;
                ctx.field_index = 0;
            } else if (byte == '*') {
                /* 参数1结束符，遇到'*'直接转入校验和解析 */
                ctx.frame.param1[ctx.field_index] = '\0';
                ctx.state = PARSE_CHECKSUM;
                ctx.field_index = 0;
                ctx.cs_index = 0;
            } else if (is_valid_param_char(byte)) {
                /* 有效参数字符，写入缓冲区 */
                if (ctx.field_index < PARAM_MAX_LEN - 1) {
                    ctx.frame.param1[ctx.field_index++] = byte;
                    ctx.checksum_acc ^= byte;
                } else {
                    /* 缓冲区溢出，参数过长 */
                    ctx.error_count++;
                    reset_parser();
                }
            } else {
                /* 无效字符 */
                ctx.error_count++;
                reset_parser();
            }
            break;

        /*----------------------------------------------------------
         * PARSE_PARAM2: 解析第二个参数
         *----------------------------------------------------------*/
        case PARSE_PARAM2:
            if (byte == '*') {
                /* 参数2结束符，遇到'*'转入校验和解析 */
                ctx.frame.param2[ctx.field_index] = '\0';
                ctx.state = PARSE_CHECKSUM;
                ctx.field_index = 0;
                ctx.cs_index = 0;
            } else if (is_valid_param_char(byte)) {
                /* 有效参数字符，写入缓冲区 */
                if (ctx.field_index < PARAM_MAX_LEN - 1) {
                    ctx.frame.param2[ctx.field_index++] = byte;
                    ctx.checksum_acc ^= byte;
                } else {
                    ctx.error_count++;
                    reset_parser();
                }
            } else {
                ctx.error_count++;
                reset_parser();
            }
            break;

        /*----------------------------------------------------------
         * PARSE_CHECKSUM: 解析校验和
         *----------------------------------------------------------*/
        case PARSE_CHECKSUM:
            if (byte == '\n') {
                /* 帧结束符'\n'到达，校验和解析完成 */
                /* 将两个十六进制字符转换为字节 */
                ctx.frame.received_cs = hex_to_byte(ctx.cs_buffer[0], ctx.cs_buffer[1]);
                ctx.frame.calculated_cs = ctx.checksum_acc;
                /* 0xFF作为特殊值，跳过校验和验证(后门) */
                ctx.frame.skip_checksum = (ctx.frame.received_cs == 0xFF);

                /*----------------------------------------------------------
                 * 校验和验证
                 *----------------------------------------------------------*/
                if (ctx.frame.skip_checksum ||
                    ctx.frame.received_cs == ctx.frame.calculated_cs) {
                    /* 校验通过，设置帧有效标志 */
                    ctx.frame.valid = true;
                    ctx.state = PARSE_COMPLETE;
                    ctx.valid_count++;
                } else {
                    /* 校验失败，发送错误响应 */
                    ctx.error_count++;
                    DEBUG_LOG("Checksum error: recv=%02X calc=%02X",
                              ctx.frame.received_cs, ctx.frame.calculated_cs);
                    send_response_err("CS");
                    reset_parser();
                }
            } else if (byte != '\r') {
                /* 忽略回车符'\r'，接收校验和字符(最多2个HEX) */
                if (ctx.cs_index < 2) {
                    ctx.cs_buffer[ctx.cs_index++] = byte;
                }
            }
            break;

        /*----------------------------------------------------------
         * PARSE_COMPLETE: 解析完成状态
         *----------------------------------------------------------*/
        case PARSE_COMPLETE:
            /* 重置解析器，准备接收下一帧 */
            reset_parser();
            /* 如果立即收到'$'，允许连续帧解析 */
            if (byte == '$') {
                ctx.state = PARSE_CMD;
            }
            break;
    }
}

/**
  * @brief  指令解析器任务函数
  * @note   在主循环中周期性调用，处理已解析完成的指令帧
  *
  * @param  无
  * @return 无
  *
  * 工作模式：
  *   CmdParser_FeedByte()负责接收字节并解析，
  *   此函数负责在帧解析完成后执行相应的业务处理。
  *
  * 处理流程：
  *   1. 检查是否处于PARSE_COMPLETE状态
  *   2. 检查帧是否valid
  *   3. 调用process_cmd_frame()执行指令
  *   4. 重置解析器到IDLE状态
  *
  * 注意：
  *   此设计将"接收解析"与"业务处理"分离，
  *   避免了中断处理函数中执行复杂业务逻辑
  */
void CmdParser_Task(void)
{
    if (ctx.state == PARSE_COMPLETE && ctx.frame.valid) {
        process_cmd_frame(&ctx.frame);
        reset_parser();
    }
}

/**
  * @brief  查询是否存在已完成的指令帧
  * @note   非阻塞查询接口，供外部模块检查是否有待处理帧
  *
  * @param  frame: 帧数据输出指针，如果不为NULL则复制帧数据(输出)
  * @return bool: true=存在有效帧，false=无有效帧
  *
  * 使用场景：
  *   外部模块(如主循环)可轮询此函数，
  *   当返回true时获取帧数据进行处理
  *
  * 注意：
  *   此函数只是查询，不自动清除帧数据。
  *   帧数据的清除需要调用CmdParser_Acknowledge()
  */
bool CmdParser_HasCompleteFrame(cmd_frame_t *frame)
{
    if (ctx.state == PARSE_COMPLETE && ctx.frame.valid) {
        if (frame) {
            memcpy(frame, &ctx.frame, sizeof(cmd_frame_t));
        }
        return true;
    }
    return false;
}

/**
  * @brief  确认并清除已完成的指令帧
  * @note   在处理完一帧后调用，重置解析器到初始状态
  *
  * @param  无
  * @return 无
  *
  * 使用说明：
  *   当外部模块通过CmdParser_HasCompleteFrame获取帧数据后，
  *   处理完毕应调用此函数清除状态，防止重复处理
  */
void CmdParser_Acknowledge(void)
{
    reset_parser();
}

/**
  * @brief  获取解析错误累计次数
  * @note   用于诊断通信质量或协议错误统计
  *
  * @param  无
  * @return uint32_t: 错误帧累计次数
  *
  * 错误类型包括：
  *   - 字符验证失败
  *   - 缓冲区溢出
  *   - 校验和不匹配
  *   - 接收超时
  */
uint32_t CmdParser_GetErrorCount(void)
{
    return ctx.error_count;
}

/**
  * @brief  获取有效帧累计次数
  * @note   用于诊断通信成功率统计
  *
  * @param  无
  * @return uint32_t: 有效帧累计次数
  *
  * 计算公式：成功率 = valid_count / (valid_count + error_count)
  */
uint32_t CmdParser_GetValidCount(void)
{
    return ctx.valid_count;
}

/**
  * @brief  设置响应回调函数
  * @note   用于将响应路由到正确的源端口
  *
  * @param  callback: 回调函数指针
  * @return 无
  *
  * 回调函数原型：
  *   void callback(uint8_t source_port, const char *response)
  *
  * 参数说明：
  *   - source_port: 指令来源端口ID
  *   - response: 待发送的响应字符串
  */
void CmdParser_SetResponseCallback(cmd_response_callback_t callback)
{
    g_response_callback = callback;
}

/**
  * @brief  设置当前源端口
  * @note   在开始解析新指令前调用，记录指令来源
  *
  * @param  port_id: 端口ID
  * @return 无
  */
void CmdParser_SetSourcePort(uint8_t port_id)
{
    g_current_source_port = port_id;
}