/**
  ******************************************************************************
  * @file    uart3_passthrough.h
  * @brief   UART3透传引擎模块头文件
  * @author  Application Layer
  * @version 1.0
  ******************************************************************************
  * @attention
  * 设计依据：UART3智能数据路由与透传功能开发计划 第3.2节
  *
  * 功能说明：
  * 本模块实现透传数据缓冲与发送功能，将UART3接收的透传数据转发至UART1
  *
  * 数据结构（严格按文档3.2.2节定义）：
  * - passthrough_node_t: 透传数据节点
  * - passthrough_queue_t: 透传队列
  * - passthrough_context_t: 透传引擎上下文
  *
  * 配置参数（严格按附录D定义）：
  * - PASSTHROUGH_NODE_SIZE: 128字节
  * - PASSTHROUGH_MAX_NODES: 4个节点
  * - PASSTHROUGH_TOTAL_BUFFER: 512字节
  ******************************************************************************
  */

#ifndef __UART3_PASSTHROUGH_H
#define __UART3_PASSTHROUGH_H

#ifdef __cplusplus
extern "C" {
#endif

#include <stdint.h>
#include <stdbool.h>

/*==============================================================================
 * 透传引擎配置参数
 * 设计依据：文档附录D配置参数
 *============================================================================*/
/**
  * @brief  每个透传节点大小
  */
#ifndef PASSTHROUGH_NODE_SIZE
#define PASSTHROUGH_NODE_SIZE         128
#endif

/**
  * @brief  最大节点数量
  */
#ifndef PASSTHROUGH_MAX_NODES
#define PASSTHROUGH_MAX_NODES         4
#endif

/**
  * @brief  发送缓冲区总大小
  */
#ifndef PASSTHROUGH_TOTAL_BUFFER
#define PASSTHROUGH_TOTAL_BUFFER      (PASSTHROUGH_NODE_SIZE * PASSTHROUGH_MAX_NODES)
#endif

/*==============================================================================
 * 透传数据节点结构体
 * 设计依据：文档第3.2.2节核心数据结构
 *============================================================================*/
/**
  * @brief  透传数据节点
  * @note   每个节点存储一段待发送的透传数据
  */
typedef struct {
    uint8_t data[PASSTHROUGH_NODE_SIZE];  /**< 数据缓冲区 */
    uint16_t length;                      /**< 有效数据长度 */
    uint16_t offset;                      /**< 已发送偏移 */
    bool valid;                          /**< 节点是否有效 */
} passthrough_node_t;

/*==============================================================================
 * 透传队列结构体
 * 设计依据：文档第3.2.2节核心数据结构
 *============================================================================*/
/**
  * @brief  透传队列
  * @note   管理多个透传数据节点的FIFO队列
  */
typedef struct {
    passthrough_node_t nodes[PASSTHROUGH_MAX_NODES];  /**< 节点数组 */
    uint8_t write_index;                              /**< 写入位置 */
    uint8_t read_index;                               /**< 读取位置 */
    volatile uint16_t pending_count;                  /**< 待发送字节总数 */
} passthrough_queue_t;

/*==============================================================================
 * 透传统计结构体
 * 设计依据：文档第3.2.1节模块接口设计
 *============================================================================*/
/**
  * @brief  透传统计信息
  * @note   记录透传引擎的运行状态
  */
typedef struct {
    uint32_t total_bytes_sent;      /**< 累计发送字节数 */
    uint32_t total_packets;          /**< 累计发送数据包数 */
    uint32_t overflow_count;         /**< 缓冲区溢出次数 */
    uint32_t busy_count;             /**< UART1忙等待次数 */
} passthrough_stats_t;

/*==============================================================================
 * 透传引擎上下文结构体
 * 设计依据：文档第3.2.2节核心数据结构
 *============================================================================*/
/**
  * @brief  透传引擎上下文
  * @note   保存透传引擎全部状态信息
  */
typedef struct {
    passthrough_queue_t queue;       /**< 透传队列 */
    passthrough_stats_t stats;       /**< 透传统计 */
    bool initialized;               /**< 初始化标志 */
} passthrough_context_t;

/*==============================================================================
 * 全局变量声明
 * 设计依据：文档第3.2.2节
 *============================================================================*/
extern passthrough_context_t g_passthrough_ctx;

/*==============================================================================
 * 函数接口声明
 * 设计依据：文档第3.2.1节模块接口设计
 *============================================================================*/
/**
  * @brief  透传引擎初始化
  * @note   初始化透传队列和统计信息
  * @param  无
  * @retval 无
  */
void Passthrough_Init(void);

/**
  * @brief  压入单字节到透传缓冲区
  * @note   将单个字节添加到透传发送队列
  * @param  byte: 待发送字节
  * @retval bool: true=成功，false=缓冲区满
  */
bool Passthrough_PushByte(uint8_t byte);

/**
  * @brief  压入数据块到透传缓冲区
  * @note   将数据块添加到透传发送队列
  * @param  data: 数据缓冲区指针
  * @param  length: 数据长度
  * @retval uint16_t: 实际写入的字节数
  */
uint16_t Passthrough_PushBuffer(const uint8_t *data, uint16_t length);

/**
  * @brief  透传引擎任务
  * @note   在主循环中周期性调用，每次尝试发送一个字节
  * @param  无
  * @retval 无
  */
void Passthrough_Task(void);

/**
  * @brief  UART1发送完成回调
  * @note   应在HAL_UART_TxCpltCallback中调用，触发下一次发送
  * @param  无
  * @retval 无
  */
void Passthrough_OnTxComplete(void);

/**
  * @brief  检查UART1是否可发送
  * @note   检查UART1发送缓冲区是否有空间
  * @param  无
  * @retval bool: true=可发送，false=忙
  */
bool Passthrough_CanSend(void);

/**
  * @brief  获取透传统计信息
  * @note   获取透传引擎的运行统计
  * @param  stats: 统计结构指针
  * @retval 无
  */
void Passthrough_GetStats(passthrough_stats_t *stats);

/**
  * @brief  重置统计信息
  * @note   清零所有统计计数器
  * @param  无
  * @retval 无
  */
void Passthrough_ResetStats(void);

/**
  * @brief  获取待发送字节数
  * @note   获取队列中等待发送的字节总数
  * @param  无
  * @retval uint16_t: 待发送字节数
  */
uint16_t Passthrough_GetPendingCount(void);

#ifdef __cplusplus
}
#endif

#endif