Improve TLS WebSocket and network failure diagnostics

docs/voice_diagnostics.md

@@ -33,3 +33,32 @@
 `inc/app_gnss_log.h` 中的 `APP_GNSS_LOG_ENABLED` 默认是 `0`，关闭应用侧全部 GNSS/NMEA 原始输出、解析失败、模式切换、卫星搜索、坐标打印和 GPS 查询提示。需要恢复时可在编译参数中设置 `-DAPP_GNSS_LOG_ENABLED=1`。语音与 NITZ 时间校准诊断继续输出。
 
 GNSS 数据解析、定位上报和硬件开关流程继续运行。原先放在打印参数内的四处 `ql_gnss_close()` 已分离为独立操作，避免禁用日志时跳过关闭定位。`python3 tools/test_gnss_logging.py` 在日志开启和关闭两种配置下验证真实解析代码、无卫星退出、卫星不足退出、搜索超时退出及 FAST 切换 SLOW 的关闭路径。
+
+## 连接失败与提示音诊断
+
+`WSS-DIAG` 使用 `stage` 区分 TLS 握手、TLS 读取、WebSocket 升级。日志记录阶段、实际耗时、超时配置、错误码和收包情况，不输出原始响应头、Cookie 或音频内容。TLS 握手仍是 20 秒总窗口，WebSocket 升级仍是 10 秒窗口，HTTP select 等待仍是 2 秒。
+
+| 日志字段 | 含义和排查方向 |
+| --- | --- |
+| `stage=tls_handshake result=timeout phase=server hello` | TLS 等待服务器 Hello 超时，不能据此判断证书错误。结合 `last_step`、`want_read`/`want_write`、`phase_ms`、`calls_ms` 判断等待和本地计算耗时 |
+| `stage=tls_connect failed_at=… verify_flags=…` | 记录 TLS 初始化/建连的失败步骤和证书校验标志；校验标志仅在已进行证书校验时有解释意义 |
+| `stage=tls_read reason=peer_close_notify` | 对端发送 TLS 关闭通知；仅证明关闭由对端通知，不证明为何关闭 |
+| `stage=tls_read reason=tls_eof/tls_read_timeout/tls_read_error` | 分别表示读取返回 0、TLS 读取超时、其他读取错误；保留原始十进制和十六进制返回值 |
+| `stage=ws_upgrade reason=no_response_timeout` | 升级等待超时，缓冲中没有响应数据；对照 `rx_bytes=0`，服务端需核查请求是否到达及是否返回 101 |
+| `stage=ws_upgrade reason=incomplete_headers_timeout` | 收到部分数据，但在窗口内未收到完整 HTTP 响应头 |
+| `stage=ws_upgrade reason=http_rejected http=…` | 收到了完整响应头及非 101 状态；按实际 HTTP 状态检查代理或后端 |
+| `stage=ws_upgrade reason=invalid_upgrade_response` | 收到非法或不符合 WebSocket 校验的响应；例如 101 响应的 Accept/Upgrade/Connection 不符合要求，或响应格式错误；当前不进一步细分具体头字段 |
+| `stage=ws_upgrade reason=transport_error` | 等待升级期间底层连接出错，结合紧邻的 `tls_read` 日志及断开回调的具体错误描述 |
+| `HTTP-DIAG stage=tcp_connect/response_header/response_body` | HTTP 在建连、响应头或响应体等待期间失败；`timeout` 表示 select 返回 0，`select_error` 表示负值，并记录立即保存的 errno；超时的 errno 字段为 0，不能用历史 errno 推断原因 |
+| `NET-GATE leave recording=… pending=… mqtt=… action=…` | 记录留言键为什么被拦截，区分正在录音、等待留言请求回复和 MQTT 离线。忙碌分支当前仍播放原有网络提示并清除 pending，此次仅增加诊断 |
+| `NET-GATE tip=network_ok reason=mqtt_connected voice_service=not_checked` | “已连上网络”仅由 MQTT 连通触发，不表示 TLS/WebSocket/语音业务已验证 |
+
+例如此次无响应升级会输出类似以下摘要（示例，并非当前固件已有的历史日志）：
+
+```text
+[WSS-DIAG] stage=ws_upgrade result=failed reason=no_response_timeout http=0 elapsed_ms=10000 timeout_ms=10000 rx_bytes=0 buffered=0 header_bytes=0 parser=0 polls=...
+```
+
+`http=0` 表示尚未解析到有效状态码，不是服务器返回的 HTTP 状态码。成功 TLS 写入只证明本地传输层接受了数据，设备端仍不能独自证明请求到达服务器或定位中间链路丢包。诊断不会改变现有提示音、重试或业务状态机。
+
+验证：`python3 tools/test_wss_receive.py` 覆盖完整/分段 101、零响应超时、部分响应头超时、503 拒绝、非法 Accept、对端关闭、TLS 读取超时等分支；`python3 tools/test_wss_handshake.py` 验证真实握手函数的超时/失败摘要及原有时限、重试和 tick 回绕。以上为主机侧函数测试，需重新构建并烧录目标固件后采集新日志。