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

工程调试指南.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. 常见误区