banban/docs/app_ntp_test.md

纯 APP 的设备侧 NTP 测试

本次测试只新增 APP 代码，不需要编译、修改或更新内核。测试使用设备自己的 PDP 1 和 SIM 网络，不使用电脑网络来判断白名单是否放行。

编译与运行

在现有 Windows 构建环境执行 build.bat app，按现有 APP OTA 流程生成、校验和更新 APP 镜像，核对分区容量。保留目标设备原内核和 RTC/NVM 状态。不要为了运行这个测试执行 build.bat kernel 或烧录全分区包；分支之前的内核诊断改动不是本测试的依赖。

每次启动后，PDP 首次成功激活会自动启动独立测试任务，不阻塞 MQTT 联网流程。每次启动只测试一次，不依赖串口命令。默认服务器为现有 GNSS 配置所用的 ntp.aliyun.com，端口为 UDP 123；可在编译时用 APP_NTP_TEST_SERVER 替换为白名单中的服务器。

测试会实际调用现有 SDK NTP 接口，可能校正 APP RTC。这是连通性与校时效果的测试版本，不包含正式修复所需的周期校时、退避重试和 WSS 等待策略。

判定流程

1. 在设备 PDP 上解析目标域名，输出解析到的 IP。dns_ok 不表示 NTP 可用。
2. 向解析到的第一个 IPv4 地址发送 NTP 请求，接收窗口为 5 秒。使用连接的 UDP socket，并检查响应模式、版本、闰秒状态、层级、请求时间戳回显及时间范围。合法响应输出 UDP_RESPONSE_VERIFIED 和服务器 UTC 秒数。支持 2036 年 NTP era 翻转，范围限定在 2024 年至目标 signed 32 位时间上限。
3. 检查原内核是否导出已有的 ql_ntp_set_server、ql_ntp_set_cid、ql_ntp_sync_ex。缺少接口时明确失败，不把动态转发接口静默返回当成成功。
4. 通过公开 SDK 接口向同一域名发起 APP 校时，等待回调最多 25 秒。超时后不启动第二个请求；信号量保留到本次启动结束，以便迟到回调安全返回。
5. 读取 time(NULL) 的返回值和 RTC 日历。要求回调成功、RTC 读取成功、APP UTC 有效，且 APP UTC 与第一次独立响应按运行计时外推后的时间相差不超过 6 秒，才输出 PASS。该容差涵盖首次响应最多 5 秒的传输窗口及秒级取整；不是精密授时指标。

网络超时只能说明这次没有取得响应，不能单凭超时确定是白名单拦截，也可能是服务器、DNS、路由或临时网络故障。该 NTP 测试不提供服务器身份认证。

日志示例

以下是格式示例，不是本次设备实测结果：

[APP-NTP-TEST] begin server=ntp.aliyun.com port=123 protocol=UDP pdp=1
[APP-NTP-TEST] dns_ok ip=... response_not_yet_verified=1
[APP-NTP-TEST] UDP_RESPONSE_VERIFIED ip=... epoch=... rtt_ms=...
[APP-NTP-TEST] sdk_sync_begin app_before=...
[APP-NTP-TEST] sdk_result callback=0 app_before=... app_after=... expected=... delta_s=0 rtc_rc=0
[APP-NTP-TEST] PASS udp_response=verified app_utc=verified wss_still_requires_separate_handshake_check=1

FAIL stage=dns、receive_wait、sdk_api_unavailable、sdk_callback_timeout、app_clock_verification 分别定位到解析、接收、内核接口兼容、SDK 回调和 APP 时间结果。

设备上出现 PASS 证明该次网络响应及 APP 校时读回通过，WSS 实际握手仍需另行核对。发布前还需验证原内核、故障现场 NVM、重启、断网恢复等场景。

本机检查与当前状态

python3 tools/test_app_ntp_test.py 编译实际测试模块，使用模拟网络和 SDK 验证响应校验、成功与失败路径、SDK 缺失、时区偏差、迟到回调及资源释放。这些模拟测试不向设备或公网发包。

当前 macOS 环境无法运行仓库的 Windows 完整固件构建工具链。设备串口已有程序占用，且当前 APP 没有 NTP 测试指令，因此尚未执行本测试固件的设备侧验证，不能宣称白名单已经放行。