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
@@ -13,7 +13,7 @@
 * 旧 N-30 定案矩阵（对照 vs "CONNECT 事件未收到捕获自 accept"修复组）保留在 s_vars[]/
 * bench_round()，由 s_bench_legacy=0 停泊不运行。
 *
- * 2026-10-13 自愈收敛阶段 2 前置实验（task-9）：同一固件合并跑 E2/E3/E4——
+ * 驱动原语前置实验：同一固件合并跑 E2/E3/E4——
 *   E2 = GET_SOCKET_STATUS 单次 SPI 成本（DWT 周期计数）+ TCP_LISTEN 可见延迟矩阵；
 *   E3 = GET_CMD_STATUS 判别力矩阵（OPEN/LISTEN/CLOSE/SET_SOUR_PORT/SET_PROTO_TYPE，
 *        含"命令未发时"对照读，复核 Trap 记录的 SET 类无判别力 + 陈旧 BUSY 残留）；
@@ -392,7 +392,7 @@ static void bench_round(unsigned idx) {
 }

 /* =====================================================================
- * 自愈收敛阶段 2 前置实验区（2026-10-13）：E2 / E3 / E4 一次固件合并跑
+ * 驱动原语前置实验区：E2 / E3 / E4 一次固件合并跑
 * ===================================================================== */

 /* 旧 N-30 定案矩阵停泊开关：0 = 不运行（保留代码备查，勿删） */
@@ -67,7 +67,7 @@ extern "C" {
                                 * E11 实证）；勿与 Phase 6/9/10/13 混选（recv 互抢数据） */
 /* ---- 链路时延基线（M1；分段/阈值见 docs/测试说明/链路延迟测试说明.md）---- */
 //#define ENABLE_PHASE12_TESTS     /* [硬] SPI 字节命令 / DMA 时延基线（L1/L2，无需 PC）—— M1 已完成，基线见说明文档 §6.1 */
-//#define ENABLE_PHASE15_TESTS     /* [硬] 自愈收敛阶段 2 驱动原语：状态回读一致性/cmd_done/sock_reset 状态机跑通/链路缓存（无需 PC）——TC 详见 docs/测试说明/CH395F_Test_Guide.md 阶段 15；2026-10-13 台架 20/20 PASS */
+//#define ENABLE_PHASE15_TESTS     /* [硬] 自愈驱动原语：状态回读一致性/cmd_done/sock_reset 状态机跑通/链路缓存（无需 PC）——TC 详见 docs/测试说明/CH395F_Test_Guide.md 阶段 15；台架 20/20 PASS */
 /* ---- 链路时延（M2/M3；分段/阈值见 docs/测试说明/链路延迟测试说明.md）---- */
 //#define ENABLE_PHASE13_TESTS     /* [网] 芯片 + 队列时延（L3~L7/L10，需 PC peer）—— M2 已完成，基线见说明文档 §6.2 */
 #define ENABLE_PHASE14_TESTS     /* [网] 生产路径时延（L8~L11 + 模拟器 Δ）—— M3，需 peer --mode remo（:7003）；
@@ -1580,7 +1580,7 @@ static void phase5_run(void) {
 #endif

 /* ===================================================================
- * Phase 15 — 自愈收敛阶段 2 驱动原语（无需 PC）
+ * Phase 15 — 自愈驱动原语（无需 PC）
 *
 * 测试目的：验证 ch395f 新增原语（设计 docs/网络/网络自愈架构设计.md §4.4）
 *          语义正确：类型化状态回读一致性 / cmd_done（E3 定案=状态回读）/
@@ -1734,7 +1734,7 @@ void ch395f_test_run(void)
        net_latency_phase12_run();
 #endif
 #ifdef ENABLE_PHASE15_TESTS
-        /* Phase 15（自愈收敛阶段 2 驱动原语）：独占态下直调驱动，放 HW 层末尾 */
+        /* Phase 15（自愈驱动原语）：独占态下直调驱动，放 HW 层末尾 */
        phase15_run();
 #endif
    }
@@ -760,10 +760,10 @@ void net_latency_phase13_run(int32_t sockfd)
        if (s_p13_state != P13_ST_ABORT) {
            return;   /* 正常完成/DONE：会话终态，不再处理 */
        }
-        /* 自愈收敛阶段1（F-NET-3）：原"进 abort 分状态手动重同步 + 10s 周期 relisten"
-         * 已删——三种去向全部由 net 层自动机制认领（run8 静默回收滞留 ESTABLISHED
-         * → 对账⑤ RESYNC；CLOSED 失位 → pump 100ms 认领重建；LISTENING 静默丢
-         * 监听 → pump"芯片不在听"判据），手动 API net_resync_listen/net_relisten
+        /* F-NET-3：原"进 abort 分状态手动重同步 + 10s 周期 relisten"
+         * 已删——三种去向全部由 net 层自动机制认领（静默回收滞留 ESTABLISHED
+         * → 对账⑤ RESYNC；CLOSED 失位 → 对账③④ 认领重建；LISTENING 静默丢
+         * 监听 → 形态③"芯片不在听"判据），手动 API net_resync_listen/net_relisten
         * 已退役。此处只保留收包与 peer re-HELLO 探测。 */
        n = net_recv(sockfd, s_p13_rx, (int)sizeof(s_p13_rx), NET_MSG_DONTWAIT);
        if (n > 0) {
@@ -7,7 +7,7 @@
     全体消费者的队列消息停摆最长 30s；
  2. 2s 后从 PC 发起 FTP(:21) 连接，测 banner 到达时延 = 队列响应性：
     修复前 ≈ 25~30s（队头冻结），修复后 ≈ 数百 ms 内；
-  3. 34s 时 30s 总预算应已耗尽：设备拆掉该会话（自愈收敛阶段 3 net_drop_conn：
+  3. 34s 时 30s 总预算应已耗尽：设备拆掉该会话（net_drop_conn：
      FIN 关闭 + 本层收口 + 重监听），随后**本探针模拟守规矩对端**：
      close 自己的 socket；
  4. 芯片回 CLOSED（TC-NET-204 模式 A：TIME_WAIT 过渡 ~150ms）→ relisten，
@@ -235,7 +235,7 @@ int net_close(int sockfd) {
    return 0;
 }

-/* ---- net_drop_conn（自愈收敛阶段 3 E-02 收口）：计数 + 记录 fd ---- */
+/* ---- net_drop_conn（E-02 收口）：计数 + 记录 fd ---- */
 static int s_drop_calls;
 static int s_drop_socks[32];

@@ -511,7 +511,7 @@ static void tc_open_listener(void) {
 }

 /* ===================== TC-TS-020..029：handle_conn =====================
- * ⚠ 自愈收敛阶段1（2026-10-13）契约变更：handle_conn **不再** net_close
+ * ⚠ 契约变更：handle_conn **不再** net_close
 * （单连接模式下 conn==listen，close 会连监听一起毁）；会话收尾只返回外层，
 * 由 time_sync_task 在 `conn != ls`（模拟器多连接后端）时才关数据 fd。
 * 故本组断言一律为 s_close_calls == 0；任务级关闭见 TC-TS-040e。 */
@@ -530,7 +530,7 @@ static void tc_handle_conn(void) {
    CHECK(s_set_unix_last == 0x12345678u, "TC-TS-020b epoch 按大端解析");
    CHECK((s_recv_calls == 1) && (s_recv_len_log[0] == 16), "TC-TS-020c 首次请求 16 字节");
    CHECK(s_recv_to_log[0] == 50U, "TC-TS-020d 单次等待片长 = 50ms");
-    CHECK(s_close_calls == 0, "TC-TS-020e 处理完**不**关闭连接（自愈收敛阶段1：close 交外层 conn!=ls 分支）");
+    CHECK(s_close_calls == 0, "TC-TS-020e 处理完**不**关闭连接（close 交外层 conn!=ls 分支）");
    CHECK(s_drop_calls == 0, "TC-TS-020g 成功会话不拆（drop 只用于放弃路径）");
    CHECK(g_tstest_info_count == 1, "TC-TS-020f 留痕 wall clock updated");

@@ -605,7 +605,7 @@ static void tc_handle_conn(void) {
    CHECK(s_recv_calls == 1, "TC-TS-027 预算耗尽后不再读（只读 1 次）");
    CHECK(g_tstest_info_count == 1, "TC-TS-027b 留痕 no TIME packet in 30s, drop conn");
    CHECK(s_close_calls == 0, "TC-TS-027c 预算耗尽也不关闭连接");
-    CHECK(s_drop_calls == 1, "TC-TS-027d 预算耗尽主动拆会话（自愈收敛阶段 3 E-02 收口：net_drop_conn 拆连接保监听）");
+    CHECK(s_drop_calls == 1, "TC-TS-027d 预算耗尽主动拆会话（E-02 收口：net_drop_conn 拆连接保监听）");

    /* 9) 剩余预算不足一片 */
    fakes_reset();
@@ -57,7 +57,7 @@ def main():
                # 关键：发送后保持连接打开，给板子留出读完 8 字节的窗口。
                # 若立即 close，CH395F 收到 FIN 会丢弃接收缓冲里尚未被板子读出的
                # 8 字节时间包，导致板子 net_recv 看到 CLOSED 而无数据、时间同步失败。
-                # 自愈收敛阶段1-5 起板子会话收尾**不再 close**（单连接监听跨会话常驻，
+                # 板子会话收尾**不再 close**（单连接监听跨会话常驻，
                # EOF 时 net_close 会连监听一起毁掉）——这里 recv 等 2s 宽限后由
                # 本端关闭；板子 net 层 auto_relisten 随即恢复监听，下一轮照常连接。
                sock.settimeout(2.0)