docs: 补充MUX丢包修复记录与回归结果

AT固件使用手册.md

@@ -382,6 +382,28 @@ AT+RESET\r\n
 1. `AT+SAVE\r\n`
 2. `AT+RESET\r\n`
 
+### 12.3 MUX 模式数据口有丢包
+
+若 `MUX=1` 下出现“主机侧已发送，但设备对端收到数量明显偏少”的现象，优先按以下顺序检查：
+
+1. 固件版本是否已经包含 `2026-04-18` 的 MUX 丢包修复。
+2. MUX 帧是否完整，尤其是：
+   - `SYNC=0x7E`
+   - `LEN_H/LEN_L`
+   - `SRCID`
+   - `DSTMASK`
+   - `TAIL=0x7F`
+3. 上位机发送方式是否把一帧拆成多个不连续小片段，或在帧间插入无效字节。
+4. TCP 对端是否出现拥塞、窗口缩小或应用层不及时取数，导致发送路径出现背压。
+5. RTT 中是否存在链路错误、发送失败或持续重连现象。
+
+当前版本的修复点如下：
+
+1. MUX 解析器改为在整帧完整到齐前不推进 UART RX ring 读指针，避免半帧被破坏性消费。
+2. TCP 发送路径与 UART 写入路径不再把背压和短写静默视为成功，便于及早暴露链路承载问题。
+
+现场回归结果：在修复后的固件中，MUX 模式持续发送 `670` 包，接收端 `670` 包全部到达，`0` 丢包。
+
 ## 13. 相关文件
 
 - AT 命令实现：[config.c](/D:/code/STM32Project/TCP2UART/App/config.c)

工程调试指南.md

@@ -448,6 +448,40 @@ MUX 模式启动后，一段时间后网口失联。重新插拔网线无法恢
 
 Keil MDK-ARM 构建 0 Error(s), 0 Warning(s)。Flash 52.7 KB / 64.0 KB (82.5%)，RAM 20.0 KB / 20.0 KB (100%)。
 
+### 9.5 2026-04-18 MUX 模式丢包修复记录
+
+#### 现象
+
+在 `MUX=1` 模式下进行持续发送测试时，主机侧发送 `500` 个数据包，只收到 `360` 个，存在明显丢包。
+
+#### 根因
+
+本轮定位确认软件侧至少存在以下两个直接丢包点：
+
+1. `App/uart_trans.c` 中 `uart_mux_try_extract_frame()` 在确认整帧完整前，就先消费 `SYNC` 与 header。若 MUX 帧跨越多个 poll 周期到达，半帧会被提前移出 RX ring，导致当前帧失步并被直接丢弃。
+2. `App/tcp_server.c`、`App/tcp_client.c` 与 `Core/Src/main.c` 的发送路径对背压与短写处理不完整：
+   - `tcp_sndbuf() < len`
+   - `tcp_write()` / `tcp_output()` 返回 `ERR_MEM`
+   - `uart_trans_write()` 只写入部分字节
+
+   以上情况在旧代码中会被上层静默忽略，表现为“发送函数返回但数据实际未完整进入下游链路”。
+
+#### 修复内容
+
+| 文件 | 修改 | 说明 |
+|------|------|------|
+| `App/uart_trans.c` | 将 `uart_mux_try_extract_frame()` 改为先窥视、后消费 | 只有在 `SYNC + header + payload + tail` 全部可用时才推进 `rx_tail`，避免半帧被破坏性消费 |
+| `App/tcp_server.c` | `tcp_server_send()` 对 `tcp_sndbuf()<len` 与 `ERR_MEM` 返回 `0` 并计入错误 | 明确表示本次发送未被底层接收，不再伪装成成功 |
+| `App/tcp_client.c` | `tcp_client_send()` 同步处理背压与 `ERR_MEM` | 逻辑与 server 侧保持一致 |
+| `Core/Src/main.c` | `App_SendToUart()` 检查 `uart_trans_write()` 是否完整写入 | TX ring 空间不足时立即显式失败 |
+| `Core/Src/main.c` | `App_RouteTcpTraffic()` / `App_RouteRawUartTraffic()` / `App_RouteMuxUartTraffic()` 统一检查发送结果 | 不再把背压、短写和未完整提交静默当成成功 |
+
+#### 结果验证
+
+1. Keil MDK-ARM 构建通过，`0 Error(s), 0 Warning(s)`。
+2. 在最新固件下重新进行 MUX 持续发送测试，主机侧发送 `670` 个数据包，接收 `670` 个，`0` 丢包。
+3. 本轮修复未增加新的常驻队列与缓冲区，保持当前 RAM 占用边界不变。
+
 ---
 
 ## 10. 常见误区