refactor(NET): 源码注释去阶段化 + 网络两份文档重构 + 不稳根因图更新

- 源码注释：删去自愈收敛阶段 1/1.5/3等 scaffolding 称谓，改为语义引用（E-02 收口 / F-NET-2/3/4 / docs/网络/网络自愈架构设计.md §5.2 E13）；涉及 net_socket/.h、net_events、net_listener、net_pending、net_types、 net_config、ch395f、time_sync、iec104_serv、ui_net_sink、lftpd、 simulator/sim/net_socket_sim、board/host 测试与探针 - 文档重构：网络自愈架构设计.md 与 Net层阻塞模型架构设计.md 改为现状口径（删历史节与阶段叙事），NET/README.md、docs/README.md 同步 - 工具与配图：gen_net_instability_svg.py 与 docs/images/网络不稳根因总览.svg 随源码口径一并更新 - 门禁：@build 0 错误 0 警告
2026-10-14 22:05:53 +08:00
parent cea2b51efb
commit d770e36c7c
30 changed files with 574 additions and 682 deletions
@@ -37,8 +37,8 @@ typedef enum {
    NET_MSG_CONNECT,
    NET_MSG_LISTEN,
    NET_MSG_ACCEPT,
-    NET_MSG_DROP_CONN,   /* 自愈收敛阶段 3（E-02 收口）：主动拆会话、保监听（见 net_drop_conn） */
-    /* 自愈收敛阶段1（F-NET-2/3）：NET_MSG_RESYNC_LISTEN / NET_MSG_RELISTEN 已删——
+    NET_MSG_DROP_CONN,   /* E-02 收口：主动拆会话、保监听（见 net_drop_conn） */
+    /* F-NET-2/3：NET_MSG_RESYNC_LISTEN / NET_MSG_RELISTEN 已删——
     * 静默回收由对账⑤自动认领（net_reconcile_tick），重建由 reconciler
     * 形态③④/D10 单一
     * 所有者负责；手动自愈 API 面退役（生产调用者本就为零） */
@@ -51,7 +51,7 @@ typedef struct {
    int             len;            /* 数据长度/缓冲区大小 */
    int             flags;          /* 接收标志 */
    uint32_t        timeout_ms;     /* 接收超时（入队方向；0 = 无限等待，无默认预算——
-                                     * 自愈收敛阶段 1.5 删除 NET_RECV_TIMEOUT_MS 30s 默认） */
+                                     * NET_RECV_TIMEOUT_MS 30s 默认已删除） */
    TaskHandle_t    caller;         /* 调用方任务句柄 */
    int             result;         /* 操作结果 */
    /* 连接参数 */
@@ -154,7 +154,7 @@ int net_listen(int sockfd);
 */
 int net_accept(int sockfd, struct net_sockaddr *addr, int *addrlen);

-/* 自愈收敛阶段1（F-NET-4）：net_can_accept 已退役——只认 ESTABLISHED 的旧门控会把
+/* F-NET-4：net_can_accept 已退役——只认 ESTABLISHED 的旧门控会把
 * "监听器在服役、本轮待 CONNECT"窗口全挡掉（CONNECT 事件补 accept 探针因此从不运行）；
 * 监听 accept 门控统一用 net_listener_armed()，recv 门控 net_can_read() 保留。 */

@@ -165,18 +165,18 @@ int net_accept(int sockfd, struct net_sockaddr *addr, int *addrlen);
 * 返回值：1 - 就绪（ESTABLISHED 待 accept / LISTENING / CLOSED+auto_relisten
 *              +残留数据）；0 - 不就绪                                     int
 * 限定条件：net_init() 已调用；任意任务上下文
- * 函数说明：1. N-32（P1 不变量 II，自愈收敛阶段1 补齐 ESTABLISHED 放行）：取代已退役的
+ * 函数说明：1. 不变量 II（单一重建所有者；补齐 ESTABLISHED 放行）：取代已退役的
 *              `net_can_accept()`（只认 ESTABLISHED）作为监听 accept 门控——原门控使
 *              :7003 永不进 `net_accept()`，
 *              `net_lost_connect_probe`（CONNECT 事件未收到补 accept，N-30 实证的
 *              "数据被吞/425"主根因修复）对该端口等于从未运行
 *           2. 放行 LISTENING：探针与 "closed-but-readable 接受" 都发生在
 *              `net_accept_locked` **内部**，门控挡在外面就永远到不了
- *           2b. 放行 ESTABLISHED（自愈收敛阶段1 台架修正）：单连接模型下 CONNECT 处理
+ *           2b. 放行 ESTABLISHED（i104 台架实证）：单连接模型下 CONNECT 处理
 *              （net_poll 分派 / 探针补 accept / 对账② standalone accept）把监听 fd
 *              转 ESTABLISHED，这正是"待 accept"电平——漏放行则任务周期慢的消费者
 *              （i104 200ms 抢不过对账② ~400ms 去抖）永不 accept、会话整场饿死
- *              （2026-10-13 实测全 18 项 FAIL）。此态 accept 必返 fd，无风暴风险
+ *              （实测全 18 项 FAIL）。此态 accept 必返 fd，无风暴风险
 *           3. 放行 CLOSED+auto_relisten **且 readable≠0**（有残留数据）：
 *              保住 N-30 的 "closed-but-readable" 接受；**无残留时必须返回 0**，
 *              否则调用方会在整个 CLOSED 窗口内每轮发起 `net_accept`（RPC 无上界）
@@ -242,7 +242,7 @@ int net_connect(int sockfd, const struct net_sockaddr *addr, int addrlen);
 int net_send(int sockfd, const void *buf, int len, int flags);

 /*
- * 函数功能：接收数据（TCP，**默认无限阻塞**——自愈收敛阶段 1.5 语义主流化）
+ * 函数功能：接收数据（TCP，**默认无限阻塞**）
 * 入口参数：sockfd  - socket 描述符
 *          buf     - 接收缓冲区
 *          len     - 缓冲区大小
@@ -263,7 +263,7 @@ int net_send(int sockfd, const void *buf, int len, int flags);
 int net_recv(int sockfd, void *buf, int len, int flags);

 /*
- * 函数功能：接收数据（非阻塞具名入口，原 NET_MSG_DONTWAIT 路径转正——自愈收敛阶段 1.5）
+ * 函数功能：接收数据（非阻塞具名入口，原 NET_MSG_DONTWAIT 路径转正）
 * 入口参数：sockfd  - socket 描述符
 *          buf     - 接收缓冲区
 *          len     - 缓冲区大小
@@ -277,7 +277,7 @@ int net_recv_nb(int sockfd, void *buf, int len);

 /*
 * 函数功能：设置 Socket 阻塞/非阻塞**模式属性**（对齐 BSD O_NONBLOCK / Python
- *          setblocking——自愈收敛阶段 1.5，模式挂 socket 控制块属性）
+ *          setblocking，模式挂 socket 控制块属性）
 * 入口参数：sockfd - socket 描述符
 *          on     - 1 = 阻塞（net_socket 默认）；0 = 非阻塞
 * 返回值：0 成功；-1 失败（描述符无效/未占用）
@@ -298,7 +298,7 @@ int net_setblocking(int sockfd, int on);
 *           timeout_ms - 单次调用在 netTask 内的最长等待（毫秒，>0）
 * 返回值：>0 实际字节数；0 = 对端关闭(EOF)；-1 = 真错误（errno 可查）；**-2 = 超时无数据**
 * 限定条件：非 netTask 上下文；Socket 已连接
- * 函数说明：1. **显式预算**便捷入口（等价 Python settimeout，自愈收敛阶段 1.5 起
+ * 函数说明：1. **显式预算**便捷入口（等价 Python settimeout，
 *              不再有隐藏默认值）：net_recv 的无限阻塞 + 本接口的显式预算构成
 *              超时语义的全部来源；超时首选仍是 net_select
 *           2. E-02 修复配套：lftpd 等"等对端下一行/下一块数据"的调用方
@@ -335,7 +335,7 @@ int net_sendto(int sockfd, const void *buf, int len, int flags,
 * 返回值：实际接收字节数，失败返回 -1
 * 限定条件：socket 已创建，指针非空
 * 函数说明：1. 读取 CH395F 接收缓冲区，获取对端地址
- *           2. 阻塞语义与 net_recv 同（自愈收敛阶段 1.5）：blocking 属性下无数据
+ *           2. 阻塞语义与 net_recv 同：blocking 属性下无数据
 *              无限等待，DONTWAIT / 非阻塞属性立即 NET_ERR_WOULDBLOCK；
 *              本接口为轮询自旋实现（历史遗留，UDP 专用），受 IWDG 监控的
 *              任务同样禁止对其无限等待
@@ -353,7 +353,7 @@ int net_recvfrom(int sockfd, void *buf, int len, int flags,
 int net_close(int sockfd);

 /*
- * 函数功能：主动拆掉当前 TCP 会话，**保留监听**（自愈收敛阶段 3，E-02 收口）
+ * 函数功能：主动拆掉当前 TCP 会话，**保留监听**（E-02 收口）
 * 入口参数：sockfd - socket 描述符
 * 返回值：0 成功（含幂等：无活动会话），-1 失败
 * 限定条件：非 netTask 上下文（经消息队列委托，同其它 net_* API）
@@ -409,7 +409,7 @@ int net_get_errno(void);
 */
 int net_sock_state(int sockfd);

-/* 自愈收敛阶段1（F-NET-3）：net_resync_listen / net_relisten 声明已删——
+/* F-NET-3：net_resync_listen / net_relisten 声明已删——
 * 静默回收形态由对账⑤自动认领（2 轮去抖 + 1s 冷却，纪律"不发芯片命令"
 * 原样保留在认领动作内）；监听重建由 reconciler 形态③④（100ms 周期）/
 * D10（30ms 重试）单一所有者。勿再引入"应用层手动自愈"入口。 */