Files

T

marco 43f28d358b docs: 补全 API 与数据库文档

- 新增 device-liveness(无障碍存活监控)、internal(内部回写端点)、cps-redirect(CPS 短链落地)三族单文件文档
- API 总览补录此前缺失端点:coupon prompt 频控、report/invite、wxpay 回调、platform 客户端配置、feedback/user/ad 零散读端点
- database 新增 cps_wx_user / device_liveness / launch_confirm_sample 三表文档,更新 OVERVIEW/README/comparison_record/数据库迁移/后端技术实现

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-24 04:07:54 +08:00

2.8 KiB

Raw Blame History

设备 / 无障碍存活监控(device 族)

所属:device 组(前缀 /api/v1/device,源 app/api/v1/device.py) | 鉴权:全部 Bearer(设备绑登录用户) | ← 返回 API 索引

落库:device_liveness 表;后台 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 配置决定,不在接口里。

2.8 KiB Raw Blame History