设备统计 API

这些接口用于自愿匿名安装统计，不是账号注册、设备管理权限或硬件身份。未注册也可访问未被限制的音乐接口，但网关可将请求归为未识别安装实例/IP活动。

1. 隐私说明

`GET /api/device/privacy`

无参数。200：

{
  "consent_required":true,
  "fields":["random_installation_id","last_ip","app_version","variant","last_activity"],
  "retention_days":30,
  "online_seconds":300,
  "legacy_ip_statistics":true,
  "note":"不采集硬件标识、音乐内容或关键词。匿名ID不是物理设备身份；清除数据可改变。"
}

封禁状态下仍允许访问；策略读取错误仍可能503。legacy_ip_statistics沿用历史字段命名，不表示所有无凭证访问都是旧版本。IP记录不能当作用户人数。

2. 注册

`POST /api/device/register`

请求JSON：

字段	类型	必需	说明
`consent`	boolean	是	必须为真正的true，不接受字符串true/1
`version`	string	否	应用版本，网关转换字符串后截取32字符
`variant`	string	否	phone/watch/desktop等，截取16字符

{"consent":true,"version":"2.2.2","variant":"phone"}

200：

{"token":"<32_HEX_ID>.<64_HEX_SIGNATURE>","device_id":"<32_HEX_ID>","online_window_seconds":300,"retention_days":30}

token为设备请求头凭证，应本地保护保存，不放查询参数、日志、网页截图或导出歌单。服务器不会读取IMEI、序列号或硬件指纹。

注册以网关识别IP为准，不接受用户传ip覆盖。每IP每小时5次，重复注册生成新的匿名实例，不是幂等“获取已有设备”；应保存既有token，不在每次启动时注册。

错误：400没有真实consent或请求结构无效；403IP/设备被限制；429注册过频；503策略/统计服务不可用。

3. 心跳

`POST /api/device/heartbeat`

请求头 X-Wristhyme-Device: <TOKEN> 必需，建议同时带版本及variant头；JSON body为 {}。

200：{"ok":true,"online_seconds":300}。

在线定义为最近300秒API活动；普通音乐API也可计活动。客户端进入前台后约每120秒心跳，退出前台停止，不需要常驻后台轮询。服务器约30秒聚合活动、异步有界队列上报，200不保证每次都增加一次数据库requests。

错误：400请求无效；401设备凭证无效；403访问受限；503服务不可用。

4. 撤回统计

`POST /api/device/forget`

请求头 X-Wristhyme-Device: <TOKEN> 必需，body为 {}。200：{"ok":true}。

删除该实例的活动记录。
保留30天单向哈希撤回标记，用于丢弃异步队列中的迟到活动；不是保留原始设备活动。
清除统计不会解除IP或设备封禁。有效凭证在封禁状态下仍允许该请求。
当前token签名没有被撤销列表永久作废，客户端必须停止携带旧token并停止心跳；不能把forget理解为服务器使token立即密码学失效。
关闭统计时先停止新心跳/活动携带；删除失败保留待删除凭证以重试，不应重新开启统计或丢掉唯一删除凭证。
随后无凭证请求仍可能记为独立IP活动；匿名实例统计撤回不等于关闭所有服务端IP安全/活动处理。

错误：400JSON等无效；401头部凭证无效；内部层另有400设备凭证无效分支；503策略/统计服务失败。封禁并不自动禁止合法forget。

5. POST 约束

三接口均要求application/json、JSON对象、单一Content-Length，body 1..4096字节，不接受Transfer-Encoding。注册/心跳/撤回没有管理Cookie或CSRF要求；不要因此混用管理员凭证。

网络统计信息可能延迟/丢失：队列最多1024条，工作线程批量最多64条，每次内部调用2秒；失败不会无界重试，以免阻塞媒体。后台“在线”和requests是活动观察值，不是精确播放计数。

6. 典型生命周期

保持统计默认关闭，展示与产品一致的隐私说明。
用户同意后register一次，将token存本地私有存储。
仅向官方HTTPS /api/带身份头；禁止转发到第三方音频域名或重定向目标。
前台按需heartbeat；普通网关活动也可刷新last。
撤回时停止携带token和心跳，forget并清本地凭证；失败时仅保留删除重试所需token。

管理员 /admin/api/forget 是人工清除活动记录，不写用户撤回标记；两者不能混为同一隐私行为。