文档同步net错误码回传约束与单连接断开语义,关闭已修复的FTP 21待办

docs/BSD_Socket_API_使用指南.md

@@ -1134,6 +1134,23 @@ if (len < 0 && net_get_errno() == NET_ERR_WOULDBLOCK) {
 }
 ```
 
+**⚠ 单连接模型（MCU 端 CH395F）的断开处理**：监听 Socket 在 CONNECT 后**自身即数据通道**
+（`g_client == g_listen`）；`net_recv()` 返回 0（EOF）时 net 层已自动把该 Socket 放回 LISTEN
+（`auto_relisten`，BSD 风格"监听常驻"）。此时**不得**再对它调 `net_close()`——那会把监听一起关掉，
+后续连接直接被拒（连接与监听同一 fd，重建还受 Trap 09 时序限制）。正确写法：
+
+```c
+} else if (len == 0) {
+    if (client_fd != listen_fd) {
+        net_close(client_fd);   /* 多连接后端（PC 模拟器）：数据通道独立，需显式关闭 */
+    }
+    client_fd = -1;             /* 单连接后端：监听已由 net 层恢复，直接等下一次 accept */
+}
+```
+
+（2026-09-21 台架实证：`ui_net_sink` 曾在 EOF 时无条件 `net_close`，表现为 7003 答完一帧即断连、
+端口随后"连接被拒"。）
+
 **方式三：事件回调**
 ```c
 void callback(int sockfd, net_event_t event, void *arg)
@@ -1224,12 +1241,24 @@ CH395F 底层驱动返回的状态码（`ch395f_get_cmd_status()` 或 `ch395f_po
 
 由 CubeMX 在 `MX_FREERTOS_Init()` 中创建（`osMessageQueueNew(8, sizeof(net_msg_t), NULL)`），在 `osKernelInitialize()` 之后执行，确保 FreeRTOS 内核已就绪。
 
+**问题：`net_recv()` 返回 -1 后，`net_get_errno()` 的 `NET_ERR_WOULDBLOCK` 是谁设置的？**
+
+消息体是**按值拷入队列**的：`osMessageQueuePut()` 复制整个 `net_msg_t`，`netTask` 改的是它自己那份副本，
+**调用方看不到**（极易踩坑）。因此实现上不靠消息字段回传错误码，而是把它搭在 `xTaskNotify()` 的通知值上：
+失败时通知值 = 具体错误码（负值，如 `NET_ERR_WOULDBLOCK`），成功时 = 实际字节数/描述符；
+公开 API 再把它恢复为 `s_net_errno`，并按 BSD 语义对外统一返回 -1。
+
+推论：**不要给 `net_msg_t` 加"回传用"字段**——调用方读到的只会是自己的初值/栈垃圾；
+需要回传请用调用方提供的指针，或复用通知值。（2026-09-21 实证：曾按"加 `msg.err` 字段"方式修错误码，
+结果 `ui_net_sink` 每次空轮询都拿到栈垃圾 → 误判为"真错误" → 连上即 `net_close`。）
+
 ---
 
 ## 变更记录
 
 | 日期 | 变更 |
 |------|------|
+| 2026-09-21 | **修正公开 API 的错误码回传**：`net_msg_t` 按值拷入队列 → netTask 对消息的写入调用方不可见，改用 `xTaskNotify()` 通知值回传具体错误码（负值），公开 API 恢复 errno 后统一返回 -1（此前被覆盖成 `NET_ERR`，使 `net_get_errno() != NET_ERR_WOULDBLOCK` 的"空轮询"判断恒成立 → `ui_net_sink` 连上即 `net_close`）；§12.4 补单连接模型断开处理（EOF 时不得 `net_close` 监听 socket）；§12.9 补错误码回传约束 |
 | 2026-09-15 | 同步配置引擎属主变更（P1-3）：`net_init` 调用方说明改为"netTask 只读 RAM 副本"（网口配置由 defaultTask 在就绪屏障前加载）；模拟器端启动序列补 `net_cfg_save_run()`（主循环 = 模拟器侧配置引擎属主，执行 UI 保存请求） |
 | 2026-09-13 | 从 git 历史恢复（`4e9ac0d` 2026-08-28 误删）；同步当前代码：`net_init` 4 参数（新增 `mac`）、`net_socket` 2 参数（移除 `protocol`）、新增 `net_get_generation` / `net_generation_inc` / `net_listen_locked`、`NET_NO_OS` 双端构建、netTask 周期 10ms → 1ms |
 | 2026-09-13 | 配图：§2.1 分层架构改 SVG 生成器产物（`tools/arch_diagram/gen_net_stack_svg.py` → `docs/images/BSD网络栈分层.svg`）；§2.4 状态机、§3.2 消息队列时序改 Mermaid（状态名对齐代码 `net_sock_state_t`，补 `UDP_OPEN` / `auto_relisten` 迁移，修正旧 ASCII 图不准处） |