feat: add button-activated field network diagnostics

docs/现场网络诊断.md

@@ -0,0 +1,42 @@
+# 现场网络诊断固件
+
+GPIO84 原报警/留言按键改为诊断键。释放时按住超过 50 ms、少于 3 秒，开启主动模式。超过或等于 3 秒不执行动作。重复短按只打印已开启，不创建重复任务；重启恢复关闭。该按键不再报警、留言、播放提示音或停止音频。
+
+设备处于定时休眠、OTA 或关机流程时不响应开启。开启之后遇到这些状态，暂停采样和新探测，已有探测可能继续到返回。没有新增常亮、常唤醒或自动重启操作；主动网络流量本身仍可能影响空闲态和耗电。
+
+## 查看日志
+
+使用原有固件日志串口，终端设置 UTF-8，保存完整串口输出。搜索 `[现场诊断]` 可筛出诊断行。时间为开机毫秒（目标平台计数会回绕），不是北京时间。日志不写 Flash、不上传服务器；断网时电脑仍可留存串口日志。
+
+- 每约 2 秒：注册状态、PDP 数据连接、MQTT、WSS，及 LTE 信号原始字段。
+- 每约 10 秒：SINR 原始值、LTE 驻留小区 CID/PCI/EARFCN 和 MCC/MNC。标记小区变化。
+- 主动探测：依次 Ping `223.5.5.5` 和当前业务域名 `banban.api.talkingq.com`，每目标 1 个 32 字节载荷，ICMP 超时 2000 ms；整轮完成后等待 10 秒。域名解析和 SDK 调度可能增加耗时，非严格周期。
+- 即时事件：数据连接回调、当前 WSS 的建立/断开；注册/PDP 的采样变化、不可用和恢复。
+- 每次探测后：本次开机的已发送、收到、未回应、未回应率和执行异常数量。超时连续次数遇到收到回应时清零。未获得有效发包统计的 SDK 错误单独计数。
+
+示例（演示数据，并非现场测量）：
+
+```text
+[现场诊断][12000 ms][连接] 注册=已注册本地网络(1) 数据连接=已连接 MQTT=已连接 WSS=已连接
+[现场诊断][12000 ms][信号原始值] RSSI=-71 RSRP=-97 RSRQ=-12 CQI=8；单位/无效值以模组为准
+[现场诊断][12500 ms][探测成功] 参照节点 223.5.5.5；往返=123 ms
+[现场诊断][12500 ms][累计统计] 参照节点；已发送=20 收到=19 未回应=1 未回应率=5% 执行异常=0（本次开机累计）
+```
+
+## 判断边界
+
+信号值以 SDK 返回的原始字段记录。必须结合模组实际单位、无效值和无线制式确认后解释，暂不直接分档。注册成功不代表有互联网；MQTT/WSS 状态是业务维护的状态，断网瞬间可能滞后。当前按 LTE 项目设计，其他制式不能直接使用 LTE 字段判读。
+
+参照节点属于外部公共服务，可能限速或禁 ICMP；业务域名对应入口也可能不回答 Ping。两者均不是 AI 服务健康检查。ICMP 未回应率不等于语音业务丢包率；域名探测结果中的 RTT 是 ICMP 往返时间，不包括 DNS 或 AI 处理时间。
+
+网络不可用计时依据注册状态和实际 PDP 查询；查询失败不虚构掉线/恢复。时间包含采样误差和暂停期间，不能当作精确无线断线时间。小区变化表示驻留记录改变，不等同于已确认发生连接态切换。
+
+本次实现侧重网络现场日志，尚未新增每轮对话的 VAD/上传/服务端/首音分段计时，也未新增 DNS/TCP/TLS 独立探测。若网络记录正常但回复仍慢，需结合已有 WSS/TLS/音频日志和服务端记录继续定位。
+
+## 验证与上板
+
+运行 `python3 tools/test_net_diag.py`，以 SDK 头文件和模拟模组接口编译运行真实诊断源码，验证任务创建失败重试、重复开启、成功/无回应/执行异常统计、网络恢复计时和休眠暂停；并检查按键分支没有原报警/留言/音频操作。
+
+macOS 测试仅在临时副本中移除 SDK 与宿主不兼容的 32 位 size_t 定义，不改 SDK 文件。该测试不代表 ARM 完整固件编译或硬件验收。正式构建沿用项目 Windows ARM Compiler 5 构建流程。
+
+上板后核对：UTF-8 中文是否正确；50 ms 以下抖动、正常短按、重复短按、3 秒以上长按；断网仍可开启诊断；两目标成功和不回应；恢复网络；对话时不因按键中断声音；OTA/定时休眠暂停；重启关闭。核实实际模组信号单位、Ping 回调和内存余量。