# 多通信接口统一指令处理系统开发计划

**项目名称**：E32-433TBH-SC 多接口统一指令处理扩展
**版本**：V1.0
**制定日期**：2026-03-27
**适用范围**：STM32F103嵌入式系统

***

## 1. 项目概述

### 1.1 背景与目标

**现有系统状况**：

- UART2作为调试专用接口，已实现ASCII指令（`$CMD,param*CS`格式）解析
- 指令覆盖继电器控制（RL）、数字输入查询（DI）、回显测试（ECHO）
- 四路DI状态变化通过UART2自动上报（`$DI_EVENT`格式）
- RF433模块通过UART1通信，485模块预留给UART3

**目标**：在不破坏现有UART2调试接口功能的前提下，将UART1（RF433）和UART3（485）纳入统一指令处理体系，使这三个接口能够：

1. **接收相同格式指令**并执行相同的业务操作
2. **向指令来源接口返回响应**（而非统一从UART2返回）
3. **所有收发数据在UART2上打印详细调试日志**

### 1.2 范围与边界

| 纳入范围                        | 排除范围                |
| --------------------------- | ------------------- |
| UART1（RF433）、UART3（485）指令接收 | 现有RF433 TX/RX应用逻辑修改 |
| 多路响应路由机制                    | 物理层驱动修改             |
| 全链路调试日志系统                   | 协议层（protocol.h）重构   |
| 共享资源并发保护                    | <br />              |

### 1.3 预期交付物

| 交付物                       | 说明                  |
| ------------------------- | ------------------- |
| `multi_uart_router.[c/h]` | 多UART统一路由核心模块       |
| `cmd_router.[c/h]`        | 指令路由与响应分发模块         |
| `debug_log.[c/h]`         | 增强型调试日志系统           |
| 修改后的 `cmd_parser.c`       | 支持多实例解析器（可选）或响应路由接口 |
| 修改后的 `main.c`             | 中断回调和任务调度整合         |
| 测试用例与验证方案                 | <br />              |

***

## 2. 系统架构设计

### 2.1 当前架构分析

```
┌─────────────────────────────────────────────────────────────────────┐
│                           main.c                                    │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐                 │
│  │ UART2_Rx    │  │ UART1_Rx    │  │ UART3_Rx    │                 │
│  │ Interrupt    │  │ (RF433)     │  │ (RS485)     │                 │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘                 │
│         │                │                │                        │
│         ▼                ▼                ▼                        │
│  ┌─────────────────────────────────────────────────────┐            │
│  │              CmdParser (仅UART2专用)                 │            │
│  │         CmdParser_FeedByte() + Task()              │            │
│  └─────────────────────────┬───────────────────────────┘            │
│                            │                                          │
│         ┌──────────────────┼──────────────────┐                     │
│         ▼                  ▼                  ▼                      │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐                 │
│  │Relay_Ctrl   │  │ IO_Monitor  │  │   (其他)    │                 │
│  └─────────────┘  └─────────────┘  └─────────────┘                 │
│                            │                                          │
│                            ▼                                          │
│                   ┌─────────────────┐                                 │
│                   │  UART2_Print   │  ◄── 所有响应固定从UART2输出    │
│                   │   (Ring Buffer) │                                 │
│                   └─────────────────┘                                 │
└─────────────────────────────────────────────────────────────────────┘
```

**关键问题**：

1. `cmd_parser.c`中`send_response_ok()`和`send_response_err()`**硬编码**使用`UART2_Print_String()`
2. `IO_Monitor`中`send_di_event()`同样**硬编码**使用`UART2_Print_String()`
3. UART1和UART3的接收中断**未接入指令解析体系**
4. 缺乏统一的**响应路由**机制

### 2.2 目标架构设计

#### 2.2.1 整体数据流图

```
                              UART2_Print (调试日志)
                                      ▲
                                      │ DEBUG_LOG()
                                      │
┌─────────────────────────────────────┴─────────────────────────────────────┐
│                         [UART2 - 调试专用通道]                             │
│  调试命令输入 ──► Rx Interrupt ──► CmdParser ──► 执行 ──► 响应UART2        │
└───────────────────────────────────────────────────────────────────────────┘

┌───────────────────────────────────────────────────────────────────────────┐
│                      [UART1 - RF433无线模块]                              │
│  RF433数据 ──► Rx Interrupt ──► ┬── FeedByte() ──► 解析 ──► 执行 ──► 响应UART1
│                                 │                    ▲                     │
│                                 │                    │                     │
│  ┌──────────────────────────────┴────────────────────┴────────────────┐    │
│  │              Multi-UART Command Router (新增核心)                    │    │
│  │  ┌────────────┐  ┌────────────┐  ┌────────────┐                   │    │
│  │  │UART1_Recv  │  │UART2_Recv  │  │UART3_Recv  │                   │    │
│  │  │RingBuffer  │  │RingBuffer  │  │RingBuffer  │                   │    │
│  │  └─────┬──────┘  └─────┬──────┘  └─────┬──────┘                   │    │
│  │        │               │               │                          │    │
│  │        └───────────────┼───────────────┘                          │    │
│  │                        ▼                                            │    │
│  │              ┌─────────────────┐                                   │    │
│  │              │ Unified Parser  │ ◄── 共享解析状态机                  │    │
│  │              │ (CmdParser)     │                                   │    │
│  │              └────────┬────────┘                                   │    │
│  │                       │                                              │    │
│  │        ┌──────────────┼──────────────┐                              │    │
│  │        ▼              ▼              ▼                              │    │
│  │  ┌───────────┐  ┌───────────┐  ┌───────────┐                        │    │
│  │  │Relay_Ctrl │  │IO_Monitor│  │ (Future)  │                        │    │
│  │  └─────┬─────┘  └─────┬─────┘  └───────────┘                        │    │
│  │        │              │                                             │    │
│  │        └──────────────┼─────────────────────────────────────┐      │    │
│  │                       │ Response Router                       │      │    │
│  │                       ▼                                       │      │    │
│  │  ┌─────────────────────────────────────────────────────────┐  │      │    │
│  │  │ port_table[] = {                                       │  │      │    │
│  │  │   {UART1, &huart1, "RF433"},                           │  │      │    │
│  │  │   {UART2, &huart2, "DEBUG"},  // 保持原样               │  │      │    │
│  │  │   {UART3, &huart3, "RS485"}                            │  │      │    │
│  │  │ }                                                       │  │      │    │
│  │  └─────────────────────────────────────────────────────────┘  │      │    │
└────┴──────────────────────────────────────────────────────────────┴──────┘
                                                                         
┌───────────────────────────────────────────────────────────────────────────┐
│                      [UART3 - RS485有线模块]                              │
│  485数据 ──► Rx Interrupt ──► ──► FeedByte() ──► 解析 ──► 执行 ──► 响应UART3
└───────────────────────────────────────────────────────────────────────────┘
```

#### 2.2.2 模块划分与职责

| 模块名                   | 职责                          | 文件位置                          |
| --------------------- | --------------------------- | ----------------------------- |
| **Multi-UART Router** | 三个UART接收通道管理、环形缓冲区、响应路由表    | `multi_uart_router.[c/h]`（新增） |
| **Cmd Router**        | 指令解析器封装、响应目标指定、响应构造与发送      | `cmd_router.[c/h]`（新增）        |
| **Debug Log**         | 统一日志接口，支持来源标签、十六进制 dump、时间戳 | `debug_log.[c/h]`（新增）         |
| **CmdParser**         | 状态机解析（修改：移除硬编码响应，改为回调方式）    | 修改现有                          |
| **UART2\_Print**      | 底层环形缓冲区发送（复用）               | 现有                            |

### 2.3 关键设计决策

#### 2.3.1 指令格式一致性策略

**决策**：保持现有`$CMD,param1,param2*CS`格式不变，三个UART共用同一解析器。

**理由**：

- 现有`cmd_parser.c`已实现完整的状态机解析，去抖、超时、校验和验证
- 复用解析器避免代码膨胀（STM32F103资源有限：64KB Flash，20KB RAM）
- 统一格式降低后续维护复杂度

#### 2.3.2 响应路由机制

**方案**：引入**端口上下文表（port\_context\_table）**

```c
typedef struct {
    UART_HandleTypeDef *huart;   // 指向具体UART句柄
    const char *port_name;       // 端口名称标签，用于日志
    ring_buffer_t *rx_ring;     // 接收环形缓冲区
    uint8_t rx_tmp;              // 单字节接收暂存
} uart_port_context_t;
```

**路由原理**：

- 指令解析完成后，业务函数返回**响应数据**和**来源端口句柄**
- `Response_Send()`根据句柄查找对应UART发送
- UART2保持原有直接调用方式，**不经过路由层**（调试专用）

#### 2.3.3 日志记录策略

**分层日志级别**：

| 级别    | 宏定义           | 触发条件           | 示例输出                                               |
| ----- | ------------- | -------------- | -------------------------------------------------- |
| ERROR | `LOG_ERROR()` | 校验失败、超时、参数错误   | `[UART1] ERR: CS mismatch recv=0xA1 calc=0x3C`     |
| WARN  | `LOG_WARN()`  | 缓冲区边缘、异常状态     | `[UART3] WARN: RX buffer 90% full`                 |
| INFO  | `LOG_INFO()`  | 指令接收、响应发送      | `[UART1] RX: $RL,1*2F` → `[UART1] TX: $OK,RL,1*00` |
| DEBUG | `LOG_DEBUG()` | 十六进制 dump、详细状态 | `[UART1] DUMP: [A1 B2 C3 D4]`                      |

**日志格式模板**：

```
[TIMESTAMP][PORT] <LEVEL>: <message>
示例：
[012345][UART1] INFO: CMD=RL P1=1 P2=空
[012346][UART1] INFO: Relay -> ON
[012347][UART1] TX: $OK,RL,1*00
```

***

## 3. 详细设计

### 3.1 多UART数据接收层

#### 3.1.1 UART1/UART3中断+DMA/环形缓冲区设计

**推荐方案：中断+环形缓冲区**（对比DMA方案）

| 方案           | 优点         | 缺点           | 适用场景      |
| ------------ | ---------- | ------------ | --------- |
| **中断+环形缓冲区** | 实现简单，代码量小  | 中断频繁（约每字节一次） | 数据量小、指令简短 |
| DMA+环形缓冲区    | 中断少，CPU效率高 | 实现复杂，内存占用大   | 高速大数据流    |

**选定**：中断+环形缓冲区（现有UART2已验证可行）

**环形缓冲区设计**：

```c
#define UART_RX_BUFFER_SIZE  128   // 每个端口接收缓冲区大小

typedef struct {
    uint8_t buffer[UART_RX_BUFFER_SIZE];
    volatile uint16_t head;        // 写入位置（中断写入）
    volatile uint16_t tail;        // 读取位置（主循环读取）
    volatile uint16_t count;       // 有效数据计数
} uart_rx_ring_t;
```

**关键约束**：

- `head`和`tail`使用`volatile`防止编译器优化
- 缓冲区大小需为2的幂次，便于模运算优化（本项目128=2^7）
- 中断中**只负责**将数据压入缓冲区，**禁止**复杂逻辑

#### 3.1.2 数据接收状态机

```
                    ┌─────────────────────────────────────────┐
                    │           UART ISR (每字节)               │
                    └──────────────────┬──────────────────────┘
                                       │
                    ┌──────────────────▼──────────────────────┐
                    │  写入 rx_ring.buffer[head]              │
                    │  head = (head + 1) % RX_BUFFER_SIZE      │
                    │  count++                                │
                    └──────────────────┬──────────────────────┘
                                       │
                    ┌──────────────────▼──────────────────────┐
                    │  count >= RX_BUFFER_SIZE ?              │
                    │    overflow_count++ (丢弃)              │
                    │    head 回绕覆盖旧数据                  │
                    └──────────────────┬──────────────────────┘
                                       │
                    ┌──────────────────▼──────────────────────┐
                    │  启动下次接收: HAL_UART_Receive_IT()    │
                    └─────────────────────────────────────────┘
```

**防溢出策略**：

- 新数据覆盖最旧数据（Lossy Ring Buffer）
- 溢出时记录`overflow_count`，供诊断使用

### 3.2 统一指令路由模块

#### 3.2.1 模块接口设计（关键函数原型）

```c
/**
 * @brief  指令路由模块初始化
 * @note   初始化所有UART端口的接收缓冲区和解析器
 * @param  无
 * @retval 无
 */
void CmdRouter_Init(void);

/**
 * @brief  向指定端口的解析器喂入数据
 * @note   由UART中断回调调用，线程安全
 * @param  port_id: 端口ID (PORT_UART1/PORT_UART2/PORT_UART3)
 * @param  byte: 接收到的字节
 * @param  current_tick: 系统时间戳
 * @retval 无
 */
void CmdRouter_FeedByte(port_id_t port_id, uint8_t byte, uint32_t current_tick);

/**
 * @brief  指令路由任务（主循环调用）
 * @note   轮询所有端口的解析器状态，执行已就绪的指令
 * @param  无
 * @retval 无
 */
void CmdRouter_Task(void);

/**
 * @brief  发送响应到指定端口
 * @note   根据port_id查找对应UART句柄，发送响应数据
 * @param  port_id: 目标端口ID
 * @param  data: 响应数据缓冲区
 * @param  len: 数据长度
 * @retval 无
 */
void CmdRouter_SendResponse(port_id_t port_id, const uint8_t *data, uint16_t len);

/**
 * @brief  发送格式化响应
 * @note   支持printf风格格式化，自动计算校验和
 * @param  port_id: 目标端口ID
 * @param  fmt: 格式化字符串
 * @retval 无
 */
void CmdRouter_SendResponseFmt(port_id_t port_id, const char *fmt, ...);
```

#### 3.2.2 指令包结构定义

```c
/** 端口ID枚举 */
typedef enum {
    PORT_UART1 = 0,   /**< RF433模块 */
    PORT_UART2 = 1,   /**< 调试串口 */
    PORT_UART3 = 2,   /**< RS485模块 */
    PORT_COUNT
} port_id_t;

/**
 * @brief  带源端口信息的指令帧结构
 * @note   解析完成后携带来源端口信息，用于响应路由
 */
typedef struct {
    cmd_frame_t frame;        /**< 原始指令帧数据 */
    port_id_t source_port;    /**< 指令来源端口 */
    uint32_t recv_tick;       /**< 接收完成时间戳 */
} routed_cmd_frame_t;

/**
 * @brief  端口上下文结构
 * @note   管理每个UART端口的接收缓冲区和解析状态
 */
typedef struct {
    UART_HandleTypeDef *huart;        /**< UART句柄指针 */
    const char *name;                 /**< 端口名称（用于日志） */
    uart_rx_ring_t rx_ring;          /**< 接收环形缓冲区 */
    parser_context_t parser;          /**< 解析器上下文 */
    uint8_t rx_tmp;                   /**< 中断接收暂存 */
    uint32_t rx_count;                /**< 累计接收字节数 */
    uint32_t error_count;             /**< 解析错误计数 */
} uart_port_context_t;
```

#### 3.2.3 与现有`CmdParser`的集成方式

**方案：扩展而非修改**

1. **新增`CmdRouter`层**：封装现有`CmdParser`，添加端口追踪能力
2. **保持`CmdParser`独立**：不修改现有`cmd_parser.c`，通过回调钩子实现集成

**集成接口设计**：

```c
/**
 * @brief  注册指令处理回调
 * @note   当指令解析完成时调用，传入来源端口信息
 * @param  callback: 回调函数指针
 * @retval 无
 */
void CmdParser_RegisterCallback(void (*callback)(const routed_cmd_frame_t *frame));
```

**替代方案（可选）**：

如果项目允许适度修改`cmd_parser.c`，推荐直接将`send_response_ok/err()`改为通过回调输出：

```c
// cmd_parser.h 新增
typedef void (*response_callback_t)(port_id_t port_id, const char *response, uint16_t len);

void CmdParser_SetResponseCallback(response_callback_t callback);
```

### 3.3 多路响应处理模块

#### 3.3.1 响应路由表设计

```c
/**
 * @brief  响应路由表
 * @note   静态表，根据port_id索引查找对应UART句柄
 */
static UART_HandleTypeDef* const g_port_uart_map[PORT_COUNT] = {
    [PORT_UART1] = &huart1,   // RF433
    [PORT_UART2] = &huart2,   // DEBUG
    [PORT_UART3] = &huart3,   // RS485
};

/**
 * @brief  端口名称表（用于日志输出）
 */
static const char* const g_port_name_map[PORT_COUNT] = {
    [PORT_UART1] = "UART1",
    [PORT_UART2] = "UART2",
    [PORT_UART3] = "UART3",
};
```

#### 3.3.2 响应发送队列管理

**设计原则**：

- 复用现有`UART2_Print`的环形缓冲区机制
- 为UART1和UART3**各创建一个发送环形缓冲区**
- 发送流程：业务层构造响应 → 写入目标端口缓冲区 → UART Tx ISR驱动发送

```c
/** 发送环形缓冲区（与uart2_print结构兼容） */
typedef struct {
    uint8_t buffer[UART_TX_BUFFER_SIZE];
    volatile uint16_t head;
    volatile uint16_t tail;
    volatile uint16_t count;
    volatile bool is_sending;
} uart_tx_ring_t;

/** 端口发送上下文 */
typedef struct {
    uart_tx_ring_t tx_ring;
    UART_HandleTypeDef *huart;
    volatile uint16_t overflow_count;
} uart_tx_context_t;
```

**关键API**：

```c
/**
 * @brief  初始化指定端口的发送缓冲区
 * @param  port_id: 端口ID
 * @retval 无
 */
void MultiUART_TxInit(port_id_t port_id);

/**
 * @brief  发送数据到指定端口（非阻塞）
 * @param  port_id: 端口ID
 * @param  data: 数据缓冲区
 * @param  len: 数据长度
 * @retval 无
 */
void MultiUART_Send(port_id_t port_id, const uint8_t *data, uint16_t len);

/**
 * @brief  指定端口发送完成回调（供HAL_UART_TxCpltCallback调用）
 * @param  port_id: 端口ID
 * @retval 无
 */
void MultiUART_TxCpltCallback(port_id_t port_id);
```

### 3.4 增强型调试日志系统

#### 3.4.1 日志格式标准（具体示例）

**基础格式**：

```
[HHHHHH][PORT] LEVEL: message\r\n
  │       │     │      │
  │       │     │      └── 具体日志内容
  │       │     └───────── 日志级别 (ERROR/WARN/INFO/DEBUG)
  │       └─────────────── 来源端口 (UART1/UART2/UART3/ALL)
  └─────────────────────── 系统运行时间（十六进制，毫秒）
```

**示例输出**：

```
[0001F4][UART1] INFO: RX len=12 "$RL,1*2F\r\n"
[0001F5][UART1] INFO: CMD=RL P1=1 valid=true
[0001F6][UART1] INFO: Relay -> ON
[0001F7][UART1] TX: "$OK,RL,1*00\r\n"
[0001F8][UART3] INFO: RX len=15 "$DI,2*5A\r\n"
[0001F9][UART3] INFO: CMD=DI P1=2 valid=true
[0001FA][UART3] INFO: DI2 = HIGH
[0001FB][UART3] TX: "$OK,DI,2,1*2B\r\n"
[00020A][UART1] ERROR: CS mismatch recv=0xA1 calc=0x3C
[00020B][UART1] TX: "$ERR,CS*XX\r\n"
```

**十六进制Dump格式（DEBUG级别）**：

```
[0001FC][UART1] DEBUG: HEX dump (16 bytes)
[0001FC]        24 52 4C 2C 31 2A 32 46 0D 0A FF FF FF FF FF FF FF
                 $  R  L  ,  1  *  2  F  CR LF
```

#### 3.4.2 日志分级与过滤机制

**编译期分级**（通过`DEBUG_LOG_LEVEL`宏）：

```c
#define DEBUG_LEVEL_NONE   0   // 全部禁用
#define DEBUG_LEVEL_ERROR  1   // 仅错误
#define DEBUG_LEVEL_WARN  2   // 错误+警告
#define DEBUG_LEVEL_INFO   3   // 错误+警告+信息
#define DEBUG_LEVEL_DEBUG  4   // 全部

#ifndef DEBUG_LOG_LEVEL
#define DEBUG_LOG_LEVEL DEBUG_LEVEL_INFO
#endif

// 日志宏定义
#if DEBUG_LOG_LEVEL >= DEBUG_LEVEL_ERROR
#define LOG_ERROR(fmt, ...)  UART2_Print_Printf("[%06X][%s] ERROR: " fmt "\r\n", \
    (unsigned int)HAL_GetTick(), port_name, ##__VA_ARGS__)
#else
#define LOG_ERROR(fmt, ...)
#endif

#if DEBUG_LOG_LEVEL >= DEBUG_LEVEL_WARN
#define LOG_WARN(fmt, ...)   UART2_Print_Printf("[%06X][%s] WARN: " fmt "\r\n", \
    (unsigned int)HAL_GetTick(), port_name, ##__VA_ARGS__)
#else
#define LOG_WARN(fmt, ...)
#endif

#if DEBUG_LOG_LEVEL >= DEBUG_LEVEL_INFO
#define LOG_INFO(fmt, ...)   UART2_Print_Printf("[%06X][%s] INFO: " fmt "\r\n", \
    (unsigned int)HAL_GetTick(), port_name, ##__VA_ARGS__)
#else
#define LOG_INFO(fmt, ...)
#endif

#if DEBUG_LOG_LEVEL >= DEBUG_LEVEL_DEBUG
#define LOG_DEBUG(fmt, ...)  UART2_Print_Printf("[%06X][%s] DEBUG: " fmt "\r\n", \
    (unsigned int)HAL_GetTick(), port_name, ##__VA_ARGS__)
#define LOG_HEXDUMP(data, len)  Print_HexDump(port_name, data, len)
#else
#define LOG_DEBUG(fmt, ...)
#define LOG_HEXDUMP(data, len)
#endif
```

#### 3.4.3 性能影响评估

| 指标        | 估算值          | 说明                  |
| --------- | ------------ | ------------------- |
| Flash占用增量 | +4KB \~ +6KB | 路由层+日志系统            |
| RAM占用增量   | +1KB \~ +2KB | 环形缓冲区（RX+TX各两个UART） |
| CPU开销     | <5%          | 日志仅在指令收发时产生，中断驱动    |
| UART2带宽占用 | 峰值约30%       | 假设每帧响应产生约50字节日志     |

**优化措施**：

- 使用`__attribute__((section(".flash.text")))`将日志函数放入Flash
- 环形缓冲区大小根据实际数据量调整，避免过大
- 日志输出异步化，不阻塞主流程

### 3.5 资源保护与并发控制

#### 3.5.1 共享资源访问冲突解决方案

**共享资源识别**：

| 共享资源                        | 访问方      | 潜在冲突    |
| --------------------------- | -------- | ------- |
| `Relay_SetState()`          | 多指令入口    | 同时控制继电器 |
| `IO_Monitor_GetState()`     | 多指令入口    | 读操作，可并发 |
| `IO_Monitor_GetAllStates()` | 多指令入口    | 读操作，可并发 |
| 环形缓冲区（TX/RX）                | 中断 + 主循环 | 需要临界区保护 |

**解决方案：优先级继承 + 临界区**

```c
/**
 * @brief  继电器控制（线程安全版本）
 * @note   内部使用临界区保护，防止并发访问
 * @param  port_id: 来源端口（用于日志）
 * @param  state: 目标状态
 * @retval 无
 */
void Relay_SetState_Safe(port_id_t port_id, bool state)
{
    uint32_t irq_flags;
    __disable_irq();                  // 进入临界区
    irq_flags = __get_PRIMASK();       // 保存中断状态
    
    // 继电器操作
    Relay_SetState(state);
    
    // 日志输出（允许中断嵌套，日志本身有保护）
    LOG_INFO("Relay -> %s (from %s)", state ? "ON" : "OFF", 
             g_port_name_map[port_id]);
    
    __set_PRIMASK(irq_flags);         // 恢复中断状态
    __enable_irq();                    // 退出临界区
}
```

**中断优先级配置建议**：

```c
// 在SystemClock_Config()之后调用
void Configure_UART_Priorities(void)
{
    // STM32F103中断优先级（数字越小优先级越高）
    // 建议配置：
    // - UART1 (RF433): 优先级=5，子优先级=0（较高优先级）
    // - UART2 (DEBUG): 优先级=6，子优先级=0（中优先级）
    // - UART3 (RS485): 优先级=5，子优先级=1（与UART1同级别）
    // - Systick: 优先级=15（最低，保证系统心跳）
    
    HAL_NVIC_SetPriority(USART1_IRQn, 5, 0);
    HAL_NVIC_SetPriority(USART2_IRQn, 6, 0);
    HAL_NVIC_SetPriority(USART3_IRQn, 5, 1);
}
```

***

## 4. 实施路线图

### 阶段1：架构验证与框架搭建（第1-2周）

**目标**：验证环形缓冲区机制和路由架构的可行性

| 任务                                | 交付物  | 验收标准          |
| --------------------------------- | ---- | ------------- |
| 1.1 创建`multi_uart_router.c/h`基础框架 | 源码文件 | 编译通过，无语法错误    |
| 1.2 实现UART1/UART3接收环形缓冲区          | 单元测试 | 收发数据一致，无丢失    |
| 1.3 实现端口上下文表和初始化函数                | 函数实现 | 三个端口均可正确初始化   |
| 1.4 实现`CmdRouter_FeedByte()`接口    | 函数实现 | 字节可正确路由到对应解析器 |

**关键里程碑代码片段**：

```c
// multi_uart_router.h
#ifndef __MULTI_UART_ROUTER_H
#define __MULTI_UART_ROUTER_H

#include "usart.h"
#include "cmd_parser.h"

typedef enum {
    PORT_UART1 = 0,
    PORT_UART2 = 1,
    PORT_UART3 = 2,
    PORT_COUNT
} port_id_t;

void MultiUART_Init(void);
void MultiUART_FeedByte(port_id_t port_id, uint8_t byte, uint32_t tick);
void MultiUART_Task(void);
void MultiUART_Send(port_id_t port_id, const uint8_t *data, uint16_t len);
void MultiUART_SendString(port_id_t port_id, const char *str);

#endif
```

### 阶段2：UART1/RF433接口实现（第3-4周）

**目标**：UART1能够接收指令并返回响应

| 任务                       | 交付物                | 验收标准                         |
| ------------------------ | ------------------ | ---------------------------- |
| 2.1 修改`main.c`中UART1中断回调 | 修改后main.c          | 中断正确调用`MultiUART_FeedByte()` |
| 2.2 实现UART1 TX环形缓冲区发送    | `MultiUART_Send()` | 响应正确发送到UART1                 |
| 2.3 实现响应路由功能             | 路由表                | UART1指令响应返回UART1             |
| 2.4 全链路日志打印              | 日志输出               | UART2显示完整收发流程                |

**关键修改**：

```c
// main.c 修改 - UART1中断回调
void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart)
{
    if (huart->Instance == USART1) {
        MultiUART_FeedByte(PORT_UART1, rf433_uart_rx_tmp, HAL_GetTick());
        HAL_UART_Receive_IT(&huart1, &rf433_uart_rx_tmp, 1);
    }
    // ... 其他端口保持原样 ...
}
```

### 阶段3：UART3/485接口实现（第5-6周）

**目标**：UART3能够接收指令并返回响应

| 任务                  | 交付物    | 验收标准         |
| ------------------- | ------ | ------------ |
| 3.1 实现UART3接收中断处理   | 中断处理   | 指令正确喂入解析器    |
| 3.2 实现UART3 TX发送功能  | 发送函数   | 响应正确发送到UART3 |
| 3.3 RS485方向控制（如果需要） | 方向控制逻辑 | 半双工切换正确      |
| 3.4 多端口并发测试         | 测试报告   | 两端口同时收发正常    |

### 阶段4：集成测试与优化（第7-8周）

**目标**：系统稳定性和性能优化

| 任务            | 交付物    | 验收标准            |
| ------------- | ------ | --------------- |
| 4.1 多接口并发指令测试 | 测试报告   | 无竞争条件、无数据丢失     |
| 4.2 大数据量压力测试  | 压力测试报告 | 1000帧连续收发无错误    |
| 4.3 异常情况处理测试  | 异常测试报告 | 校验失败、超时等处理正确    |
| 4.4 性能优化与内存调整 | 优化报告   | RAM<70%，CPU<80% |

### 阶段5：文档完善与交付（第9周）

| 任务          | 交付物                   |
| ----------- | --------------------- |
| 5.1 API接口文档 | cmd\_router\_api.md   |
| 5.2 修改说明文档  | migration\_guide.md   |
| 5.3 测试验证报告  | validation\_report.md |
| 5.4 最终代码归档  | 完整源码包                 |

***

## 5. 测试验证计划

### 5.1 单元测试策略

**测试框架**：使用`unity`或自定义最小测试框架（嵌入式友好）

| 模块    | 测试用例                     | 验证点             |
| ----- | ------------------------ | --------------- |
| 环形缓冲区 | `test_ring_push_pop()`   | 数据先进先出，无损坏      |
| 环形缓冲区 | `test_ring_overflow()`   | 溢出时旧数据被覆盖       |
| 环形缓冲区 | `test_ring_concurrent()` | 中断+主循环并发安全      |
| 路由表   | `test_port_lookup()`     | 端口ID正确映射到UART句柄 |
| 响应构造  | `test_response_format()` | 校验和计算正确         |

### 5.2 集成测试用例

#### 5.2.1 多接口并发指令测试

**测试场景**：同时从UART1和UART3发送继电器控制指令

**测试步骤**：

1. UART1发送：`$RL,1*2F`（期望Relay开启）
2. UART3发送：`$RL,0*2E`（期望Relay关闭）
3. 间隔50ms交替发送10轮

**验收标准**：

- 每次操作后继电器状态与最后一条指令一致
- 两个端口各自收到正确的响应帧
- UART2日志完整记录所有收发过程

#### 5.2.2 大数据量压力测试

**测试场景**：连续快速发送1000帧指令

**测试步骤**：

1. UART1以10ms间隔连续发送DI查询指令
2. 记录丢包率、错误率
3. 监测RAM占用峰值

**验收标准**：

- 丢包率 < 0.1%
- 无内存溢出
- 平均响应时间 < 20ms

#### 5.2.3 异常情况处理测试

| 测试场景       | 输入                    | 期望行为                |
| ---------- | --------------------- | ------------------- |
| 校验和错误      | `$RL,1*A1`（实际应为2F）    | 返回`$ERR,CS*XX`，日志记录 |
| 未知命令       | `$ABC*00`             | 返回`$ERR,CMD*XX`     |
| 参数越界       | `$DI,5*XX`（通道1-4）     | 返回`$ERR,PARAM*XX`   |
| 帧超时        | 发送`$RL`后等待2秒          | 解析器重置，日志输出timeout   |
| 端口同时发送相同指令 | UART1和UART3同时发`$ECHO` | 各自收到独立响应            |

### 5.3 验收标准

| 指标        | 目标值        | 测量方法        |
| --------- | ---------- | ----------- |
| 指令处理成功率   | ≥99.5%     | 1000帧测试统计   |
| 响应延迟      | ≤50ms（P99） | 示波器或时间戳统计   |
| Flash占用增量 | ≤8KB       | 编译后.map文件分析 |
| RAM占用增量   | ≤2KB       | 运行时内存分析     |
| CPU空闲率    | ≥70%       | Systick空闲计数 |

***

## 6. 风险评估与应对

### 6.1 技术风险

| 风险                    | 概率 | 影响 | 应对措施                                      |
| --------------------- | -- | -- | ----------------------------------------- |
| **数据丢失**：高频率指令导致缓冲区溢出 | 中  | 高  | 1. 动态调整缓冲区大小2. 实现流量控制（XOFF/XON）3. 丢帧时日志记录 |
| **响应延迟**：复杂指令阻塞发送     | 中  | 中  | 1. 指令处理异步化2. 预计算校验和3. DMA加速发送             |
| **竞争条件**：多端口同时访问继电器   | 低  | 高  | 1. 临界区保护2. 命令队列化3. 最小切换间隔保护（已有）           |
| **内存碎片**：频繁分配/释放      | 低  | 中  | 1. 全部使用静态缓冲区2. 避免动态malloc                 |

### 6.2 资源风险

| 风险                     | 概率 | 影响 | 应对措施                                                                        |
| ---------------------- | -- | -- | --------------------------------------------------------------------------- |
| **Flash不足**：代码量超过64KB  | 低  | 高  | 1. 启用-O2优化2. 精简日志字符串3. 评估裁剪非必要功能                                            |
| **RAM不足**：缓冲区+解析器上下文超支 | 低  | 高  | 1. 缓冲区实际需求计算：　RX: 3×128=384B　TX: 2×256=512B　解析器: 3×128B=384B　总计约1.3KB（余量充足） |
| **中断风暴**：高频率字节接收导致系统假死 | 低  | 高  | 1. 配置合适的中断优先级2. 使用DMA分担CPU负载                                                |

### 6.3 应对措施优先级

```
P0（立即处理）:
├─ 临界区保护实现（防止竞争条件）
└─ 环形缓冲区溢出处理（日志+计数）

P1（本阶段完成）:
├─ 中断优先级配置
└─ 内存使用量测量验证

P2（集成测试阶段）:
├─ 压力测试暴露潜在问题
└─ 性能优化调参
```

***

## 7. 附录

### 附录A：关键数据结构定义

```c
/**
 * @brief  接收环形缓冲区
 */
typedef struct {
    uint8_t buffer[UART_RX_BUFFER_SIZE];
    volatile uint16_t head;    /**< 写入索引 */
    volatile uint16_t tail;    /**< 读取索引 */
    volatile uint16_t count;   /**< 有效数据计数 */
} uart_rx_ring_t;

/**
 * @brief  发送环形缓冲区
 */
typedef struct {
    uint8_t buffer[UART_TX_BUFFER_SIZE];
    volatile uint16_t head;
    volatile uint16_t tail;
    volatile uint16_t count;
    volatile bool is_sending;
    volatile uint16_t overflow_count;
} uart_tx_ring_t;

/**
 * @brief  端口上下文
 */
typedef struct {
    UART_HandleTypeDef *huart;
    const char *name;
    uart_rx_ring_t rx_ring;
    uart_tx_ring_t tx_ring;
    parser_context_t parser;
    uint8_t rx_tmp;
    uint32_t rx_count;
    uint32_t error_count;
} uart_port_context_t;

/**
 * @brief  带路由信息的指令帧
 */
typedef struct {
    cmd_frame_t frame;
    port_id_t source_port;
    uint32_t recv_tick;
} routed_cmd_frame_t;
```

### 附录B：接口API文档

#### B.1 CmdRouter模块

| 函数                          | 原型                                                                               | 说明           |
| --------------------------- | -------------------------------------------------------------------------------- | ------------ |
| `CmdRouter_Init`            | `void CmdRouter_Init(void)`                                                      | 初始化所有端口上下文   |
| `CmdRouter_FeedByte`        | `void CmdRouter_FeedByte(port_id_t port, uint8_t byte, uint32_t tick)`           | 向指定端口喂入数据    |
| `CmdRouter_Task`            | `void CmdRouter_Task(void)`                                                      | 主循环调用，处理就绪指令 |
| `CmdRouter_SendResponse`    | `void CmdRouter_SendResponse(port_id_t port, const uint8_t *data, uint16_t len)` | 发送原始响应       |
| `CmdRouter_SendResponseFmt` | `void CmdRouter_SendResponseFmt(port_id_t port, const char *fmt, ...)`           | 发送格式化响应      |

#### B.2 DebugLog模块

| 宏                        | 说明          |
| ------------------------ | ----------- |
| `LOG_ERROR(fmt, ...)`    | 错误级别日志      |
| `LOG_WARN(fmt, ...)`     | 警告级别日志      |
| `LOG_INFO(fmt, ...)`     | 信息级别日志      |
| `LOG_DEBUG(fmt, ...)`    | 调试级别日志      |
| `LOG_HEXDUMP(data, len)` | 十六进制内存 dump |

#### B.3 回调接口

```c
/**
 * @brief  指令执行完成回调（由CmdRouter内部调用）
 * @param  frame: 带路由信息的指令帧
 * @retval 无
 */
void App_OnCommandReceived(const routed_cmd_frame_t *frame);
```

### 附录C：响应格式规范

**成功响应**：`$OK[,content]*CS\r\n`

- 示例：`$OK,RL,1*00\r\n`（继电器控制成功）
- 示例：`$OK,DI,1101*2B\r\n`（四路DI状态）

**错误响应**：`$ERR,err_code*CS\r\n`

- err\_code: PARAM（参数错误）、CS（校验和错误）、CMD（未知命令）、TIMEOUT（超时）
- 示例：`$ERR,CS*XX\r\n`

**事件上报**：`$DI_EVENT,channel,state*CS\r\n`

- 示例：`$DI_EVENT,1,1*A5\r\n`（通道1变为高电平）

***

## 文档版本历史

| 版本  | 日期         | 作者  | 变更说明   |
| --- | ---------- | --- | ------ |
| 1.0 | 2026-03-27 | 架构师 | 初始版本创建 |

***

**文档结束**