智大星（FocusDesktop）数据埋点上报接口协议

协议版本 v1 · protocol = 1 · 适用端 FocusShell / FocusConfig / FocusGuardService

1. 接口总览

POST /v1/track    批量上报事件（HMAC-SHA256 签名鉴权，逐事件校验+幂等）
GET  /v1/config    远程配置（开关/采样率/上报频率熔断）

所有上报数据自包含——device_id、版本、OS 等公共字段冗余在每条事件内，一条事件=一条完整文档，服务端无需关联其他表直接落库。

2. 鉴权（请求头）

X-App-Key:        focus-desktop-windows
X-Timestamp:      请求生成时刻 Unix 毫秒
X-Nonce:          每次请求随机的 16~32 位字符串
X-Sign:           小写 hex
Content-Type:     application/json
Content-Encoding: gzip (请求体>1KB 时可选)

签名算法：
signString = appKey + "\n" + timestamp + "\n" + nonce + "\n" + sha256_hex(原始请求体字节)
X-Sign     = hmac_sha256_hex(appSecret, signString)

服务端校验：①签名不符→401 ②时间戳偏移>±5min→401 ③nonce 在窗口内重复→401。

3. 上报信封（POST /v1/track）

{
  "protocol": 1,
  "app_key": "focus-desktop-windows",
  "events": [
    {
      "type": "track",
      "device_id": "<GUID v4>",
      "user_id": null,
      "session_id": "<GUID v4>",
      "event": "app_start",
      "time": 1758800000000,
      "seq": 1,
      "properties": { "$app": "focusshell", ... }
    }
  ]
}

约束：单批 1~200 条、≤512KB；单条 ≤4KB；properties 仅 string/int/bool，禁止嵌套对象与数组。

4. track 事件字典（v1 冻结）

app_starttrack

进程启动完成、主窗口/服务就绪后

first_install(bool)·upgraded_from(string)·launch_mode(string)

heartbeattrack

进程存活期间周期发送，用于活跃度统计

uptime_sec(int)·active_sec(int)

app_exittrack

正常退出

uptime_sec(int)·reason(string)

feature_usedtrack

用户完成一个被登记的功能动作

feature(string)·result(string)

errortrack

捕获到非致命异常/崩溃记录

type(string)·fatal(bool)·message_hash(string)

5. 首批 feature 点登记

config.openconfig.website_rule_savedconfig.time_rule_savedeasyfile.open_defaulteasyfile.open_with_dialogeasyfile.open_with_changedbind.qr_shownbind.success

6. 响应格式

200 请求级成功（逐事件校验，合法入库，非法标注 rejected 不影响其余）：
{ "code": 0, "msg": "ok", "accepted": 198, "rejected": [{ "index": 7, "code": "unknown_event" }], "server_ts": 1758801801234 }

拒绝码：unknown_event / invalid_props / invalid_time / duplicated
请求级错误：400(40001 信封非法) · 401(40101 鉴权失败) · 413(41301 过大) · 429(42901 限流) · 5xx(50000 服务端错误)

幂等键 = device_id + session_id + seq，同键重复只保留首次收到的一条。