feat(ota): 实现 GD32 Flash 存储抽象层和 OTA 协调器接口解耦

- 新增 storage/gd32_flash_store.cpp 组件，提供 GD32 Flash 存储抽象层
- 修改 ota_coordinator.cpp/h 使其继承 IRelayListener 接口，实现与
  OtaRelay 的解耦设计
- 将 GD32 相关存储操作统一通过协调器访问，解决 H3 绕过协调器的问题
- 添加完整的 Doxygen 注释到所有公共接口和关键函数
- 更新 CMakeLists.txt 构建配置，添加 storage 组件依赖
- 重构元数据加载/清除操作使用 Gd32FlashStore 实例而非 OtaRelay 直接访问
- 添加中继事件回调接口实现，使 OtaRelay 可通知协调器状态变化

main/transport/protocol.cpp

@@ -55,6 +55,10 @@ void Protocol::init()
 
 /**
  * @brief 根据时间戳、地址和随机种子生成 16 字节 nonce。
+ * @param timestamp 当前时间戳（tick）。
+ * @param mem_addr 内存地址（增加随机性）。
+ * @param rand_seed 随机种子。
+ * @param nonce_out 输出 16 字节 nonce 缓冲区。
  */
 void Protocol::scrambleGenerate(uint32_t timestamp, uint32_t mem_addr,
                                 uint32_t rand_seed, uint8_t *nonce_out)
@@ -84,7 +88,10 @@ void Protocol::scrambleGenerate(uint32_t timestamp, uint32_t mem_addr,
 }
 
 /**
- * @brief 会话密钥初始化
+ * @brief 会话密钥初始化。
+ * @param sess 会话上下文指针。
+ * @param k_session 16 字节会话密钥。
+ * @return 0 成功，-1 参数无效。
  */
 int Protocol::sessionKeyInit(session_ctx_t *sess, const uint8_t *k_session)
 {
@@ -100,6 +107,7 @@ int Protocol::sessionKeyInit(session_ctx_t *sess, const uint8_t *k_session)
 
 /**
  * @brief 清除会话上下文中的密钥和状态。
+ * @param sess 会话上下文指针。
  */
 void Protocol::sessionKeyClear(session_ctx_t *sess)
 {

main/transport/protocol.h

@@ -18,8 +18,8 @@
 #define FRAME_OVERHEAD     (6)       // SOF + CMD + LEN(2) + CRC16(2)
 
 // 安全常量（定义在 app_config.h 中）
-inline constexpr size_t MASTER_KEY_HERE_LEN = 16;
-inline constexpr size_t CHIP_UID_LEN = 12;
+inline constexpr size_t MASTER_KEY_HERE_LEN = 16; ///< AES-128 主密钥长度（字节）
+inline constexpr size_t CHIP_UID_LEN = 12;        ///< GD32 芯片 UID 长度（字节）
 
 // AES 会话上下文
 typedef struct {

main/transport/spi_master.h

@@ -16,8 +16,8 @@
 #define SPI_MASTER_CS_GPIO    (4)           // CS 片选引脚
 #define SPI_CLOCK_HZ          (4 * 1000 * 1000)  // 4MHz
 #define SPI_MODE              (0)           // CPOL=0, CPHA=0
-#define SPI_QUEUE_SIZE        (1)
-#define SPI_OTA_FRAME_MAX     (96)
+#define SPI_QUEUE_SIZE        (1)           ///< SPI 事务队列深度
+#define SPI_OTA_FRAME_MAX     (96)          ///< SPI OTA 单帧最大字节数
 
 // GD32 SPI OTA 帧类型
 #define SPI_OTA_SOF           (0xA5)