C 语言指南 · 开发文档

适用：ESP-IDF 5.x 与 Linux C / C++。接口与字段说明见 API 参考。以下均为占位配置片段。

接入流程

使用所属系统的 API Key、HTTPS 客户端和 JSON 解析库，联网后校准时间。
将稳定设备码写入持久存储，登记设备并轮询绑定状态。
获取 data.access_token，调用本周作业接口，按 tracks[].url 下载。
播放后保存听音事件到本地队列，联网批量同步。

设备 Token 与网页账号会话独立；网页切换登录不要求固件重新获取 Token。

可先在后台在线测试点击“准备测试设备”，查询设备状态并获取作业，再接入固件。

HTTPS 客户端

ESP-IDF

使用 esp_http_client、cJSON 和可信根证书包；请求只指向受控配置的 API 基址。以下片段应放入已初始化网络的固件中，api_key 从设备安全存储读取。

#include "esp_http_client.h"
#include "esp_crt_bundle.h"

esp_http_client_config_t config = {
    .url = "https://saas.example.com/api/terminal/listening-rules",
    .method = HTTP_METHOD_GET,
    .crt_bundle_attach = esp_crt_bundle_attach,
    .disable_auto_redirect = true,
    .timeout_ms = 20000,
};
esp_http_client_handle_t client = esp_http_client_init(&config);
if (client) {
    esp_http_client_set_header(client, "X-API-Key", api_key);
    esp_err_t result = esp_http_client_perform(client);
    int status = esp_http_client_get_status_code(client);
    // 先检查 result 与 status；按需添加事件处理器收集并解析 JSON。
    esp_http_client_cleanup(client);
}

使用 .event_handler 处理响应分片并限制缓冲区大小。解析 JSON 前检查响应完整性；网络错误不代表服务端未处理请求。

Linux / libcurl

新建独立句柄，设置受控的 HTTPS API URL 和本次所需的单一鉴权头；保留证书校验并关闭自动重定向：

curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 1L);
curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 2L);
curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 0L);
curl_easy_setopt(curl, CURLOPT_CONNECTTIMEOUT, 8L);
curl_easy_setopt(curl, CURLOPT_TIMEOUT, 20L);

3xx 响应先核对基址，不把鉴权头转发到其他主机。参考 ESP-IDF HTTP Client 与 libcurl 重定向说明。

下载与同步

场景	实现要求
音频下载	使用独立 HTTPS 客户端，不携带 API Key、Bearer Token 或 Cookie；流式写入临时文件，校验后原子重命名
断点续传	发送 `Range: bytes={offset}-`；仅在 `206` 且 `Content-Range` 偏移匹配时追加，`200` 时从头覆盖
URL 失效	音频返回 `403` 时重新获取作业中的 URL，不修改或拼接签名参数
Token 失效	Bearer 接口返回 `401` 时重新查询绑定状态，清除旧 Token
离线补传	持久化事件和幂等键，确认成功或重复后再出队；重试不得换键
凭证与日志	Key/Token 使用加密存储，解绑后清除；日志只记录状态码、错误码、Request ID，不记录凭证、个人数据或签名 URL

上线前验证完整收听链路、断网恢复、重复上报不重复计数，以及下载文件校验。有效听音时长、作业完成度与资源权限均以服务端结果为准。

服务端的数据压缩与回执切换不改变 C 终端协议。客户端继续以原幂等键重试，并以接口响应判断是否成功或重复，不得假设服务端会永久保留原始上报明细。