@ (#111)

docs/api目录文档分类和补全

---------

Co-authored-by: guke <guke@autohome.com.cn>
Reviewed-on: #111

docs/api/device/device-liveness.md

@@ -0,0 +1,52 @@
+# 设备 / 无障碍存活监控(device 族)
+
+> 所属:device 组(前缀 `/api/v1/device`,源 `app/api/v1/device.py`) | 鉴权:**全部 Bearer**(设备绑登录用户) | [← 返回 API 索引](../README.md)
+>
+> 落库:[`device_liveness`](../database/device_liveness.md) 表;后台 `heartbeat_monitor_worker` 据此检出心跳超时的设备并召回。设计见 spec `accessibility-liveness-push.md`(推送版)+ `accessibility-liveness-pull-prompt.md`(后置 pull 提醒版)。#65 新增。
+
+无障碍服务存活监控链路:客户端无障碍服务存活时周期上报心跳,后端发现「曾保护过、现已超时」的设备 → 召回(推送 / 客户端进 App 弹「开启自启动」引导)。
+
+## POST /register — 注册设备 / 更新推送 token
+App 前台、拿到极光 push token 时调。按 `(user_id, device_id)` upsert。
+
+**入参(JSON)**
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `device_id` | string | ✅ | 客户端 `DeviceId.get()` 生成的 per-install id |
+| `registration_id` | string \| null | ❌ | 极光推送 registration id(`JCollectionAuth` 同意后才有) |
+| `platform` | string | ❌ | 默认 `android` |
+| `app_version` | string \| null | ❌ | App 版本 |
+
+**出参**:`DeviceOut`(设备当前状态)。
+
+## POST /heartbeat — 上报心跳
+无障碍服务存活时周期调(**心跳也能自注册**)。`accessibility_enabled=true` 时刷新 `last_heartbeat_at`、状态机置 `alive`、清掉线告警。
+
+**入参(JSON)**
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `device_id` | string | ✅ | 同上 |
+| `accessibility_enabled` | bool | ✅ | 本机无障碍开关当前是否开 |
+| `registration_id` | string \| null | ❌ | 顺带更新 push token |
+
+**出参**:`{ "ok": true }`。
+
+## GET /liveness — 查本机掉线告警(后置检测)
+客户端进 App 时拉:本机是否被判定掉线过(`kill_alert_pending`)。命中 → 客户端弹「开启自启动」引导,之后调 `/liveness/ack` 清。设备从未注册过 → 返回默认(无告警)。
+
+**入参(query)**:`device_id`(string,必填)。
+**出参**:`LivenessOut`(含 `kill_alert_pending` 等)。
+
+## POST /liveness/ack — 确认已提醒(清掉线告警)
+客户端已弹过引导 → 清 `kill_alert_pending`(幂等;下次真掉线 worker 再置)。
+
+**入参(JSON)**:`{ device_id }`。
+**出参**:`{ "ok": true }`。
+
+## 错误
+- `401` 未鉴权 / token 失效。
+- `422` 缺 `device_id` 或字段类型不符。
+
+## 说明
+- **`kill_alert_pending` 与 `liveness_state` 解耦**:worker 检出掉线置 True,心跳恢复(`/heartbeat`)只重置 state、不动此标记,只由 `/liveness/ack` 清 → 规避「服务随 App 重启先发心跳把 state 重置回 alive、客户端进 App 漏看这次掉线」竞态。
+- 心跳超时阈值由 worker 配置决定,不在接口里。