feat(device): 无障碍保护存活心跳检测 + 掉线终端告警

- 新增 device 表 + /api/v1/device/{register,heartbeat} + 迁移 device_table
- heartbeat_monitor_worker 周期扫描心跳超时(App 被杀/无障碍停)→ 服务器终端打印告警
  (推送本期未接,先用 logger 终端打印代替真实通知;integrations/jpush.py 已备,后续直接替换)
- config / .env.example 增 JPUSH_* / HEARTBEAT_*
- 见 spec(仓库外 e:\codes\spec\accessibility-liveness-push.md)

注:本提交同时快照了并行 session 未提交的 coupon_state 改动 + 相关 migration
(与本功能同迁移链耦合,无法单独拆分,经确认一并提交)。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

app/api/v1/coupon.py

@@ -27,6 +27,7 @@ from app.schemas.coupon_state import (
     CouponCompletedTodayOut,
     CouponPromptDismissIn,
     CouponPromptShouldShowOut,
+    CouponPromptShownIn,
 )
 
 logger = logging.getLogger("shagua.coupon")
@@ -112,8 +113,10 @@ async def coupon_step(
     user_id = _to_int(meta.get("user_id"))  # 登录态才带;判断不靠它,资产留痕用
     trace_id = meta.get("trace_id")
 
-    # 领券任务首帧(step=0)= 用户已发起领券 → 记一条今日 engagement(claim_started),
-    # 今天这台设备不再弹引导窗(对齐前台"点一键领取即 markEngaged")。写库失败绝不能
+    # 领券任务首帧(step=0)= 用户已发起领券 → 记一条今日 engagement(claim_started)。
+    # 透传链路拿不到发起 App 的包名 → 写 app_package=NULL 的全局兜底行:只对旧式不带
+    # package 的 should-show 查询生效;按 App 频控(2026-06-12)由客户端 /prompt/shown
+    # 负责,本行不堵其他 App 的弹窗(领一半终止,其他平台还要弹)。写库失败绝不能
     # 连累领券主流程,整段吞掉。
     if device_id and meta.get("step") == 0:
         try:
@@ -188,37 +191,66 @@ async def coupon_step(
     return resp_json
 
 
+@router.post("/prompt/shown", summary="领券引导窗已对某 App 弹出(按 App 频控主判据)")
+def coupon_prompt_shown(payload: CouponPromptShownIn, db: DbSession) -> dict[str, bool]:
+    """客户端弹窗一亮即调用 → 记一条今日该 App 的 engagement(shown)。
+
+    2026-06-12 频控按 App 为单位(方案文档「一个 app 一天只能弹一次,时机=每天第一次
+    进入」):以"弹出"为频控锚点,用户领/拒/无视都只算这一次;dismiss/claim_started
+    后续只升级同一行的 engage_type。MVP 不鉴权,按 device_id 记。
+    """
+    coupon_repo.mark_engagement(
+        db, payload.device_id, payload.user_id, "shown", payload.package
+    )
+    return {"ok": True}
+
+
 @router.post("/prompt/dismiss", summary="用户拒绝/关闭领券引导窗(记今日已 engage)")
 def coupon_prompt_dismiss(payload: CouponPromptDismissIn, db: DbSession) -> dict[str, bool]:
-    """客户端点关闭引导窗时调用 → 记一条今日 engagement(dismissed),今天不再弹。
+    """客户端点关闭引导窗时调用 → 记一条今日 engagement(dismissed),今天该 App 不再弹。
 
     server 在透传链路里看不到"用户拒绝"(拒绝不发起领券),故必须客户端通知。
-    MVP 不鉴权,按 device_id 记。
+    频控以 /prompt/shown 为主判据,本端点把同一行升级成 dismissed(记录用);
+    旧客户端不带 package → 写 NULL 全局兜底行(旧语义)。MVP 不鉴权,按 device_id 记。
     """
-    coupon_repo.mark_engagement(db, payload.device_id, payload.user_id, "dismissed")
+    coupon_repo.mark_engagement(
+        db, payload.device_id, payload.user_id, "dismissed", payload.package
+    )
     return {"ok": True}
 
 
 @router.get(
     "/prompt/should-show",
     response_model=CouponPromptShouldShowOut,
-    summary="切到外卖 App 时是否还应弹领券引导窗",
+    summary="切到某外卖 App 时是否还应弹领券引导窗(按 App 频控)",
 )
 def coupon_prompt_should_show(
-    device_id: str, db: DbSession
+    device_id: str, db: DbSession, package: str | None = None
 ) -> CouponPromptShouldShowOut:
-    """今天这台设备已 engage(领或拒)过 → should_show=false。客户端据此决定弹不弹
-    (纯后台判据,客户端不再做前台 SP 缓存判断)。"""
+    """should_show = 今天没跑完整轮领券 AND 该 App 今天没弹过。
+
+    2026-06-12 按 App 为单位(产品确认):
+    - 该 App 今天弹过(shown/dismissed/claim_started 任一)→ false;
+    - **其他 App** 弹过/领了一半不影响本 App → 仍 true(没领完进其他平台要再弹);
+    - 今天已跑完整轮(coupon_daily_completion,"彻底领完")→ 全局 false。
+    package 不传 = 旧客户端,退回旧全局语义(任意一行算 engage)+ 同样吃 completion 闸。
+    客户端据此决定弹不弹(纯后台判据,客户端不做前台 SP 缓存判断)。"""
+    if coupon_repo.has_completed_today(db, device_id):
+        return CouponPromptShouldShowOut(should_show=False)
     return CouponPromptShouldShowOut(
-        should_show=not coupon_repo.has_engaged_today(db, device_id)
+        should_show=not coupon_repo.has_engaged_today(db, device_id, package)
     )
 
 
-@router.post("/prompt/reset", summary="重置今日领券引导窗 engagement(开发测频控用)")
+@router.post("/prompt/reset", summary="重置今日领券状态:弹窗 engagement + 完成记录(开发测试用)")
 def coupon_prompt_reset(payload: CouponPromptDismissIn, db: DbSession) -> dict[str, bool]:
-    """删这台设备今天的 engagement → has_engaged_today 变 false,今天又能弹。
+    """删这台设备今天的 engagement + coupon_daily_completion:弹窗又能弹,且首页
+    「去领取」卡/弹窗「一键自动领取」CTA 恢复可点(只删 engagement 的话, 重置后 CTA
+    仍被"今日已跑完整轮"置灰, 2026-06-12)。配合客户端本地重置 = 等效重装。
+    领券记录(coupon_claim_record)是资产沉淀、不参与任何门控判断, 不删。
     开发设置「重置今日领券弹窗状态」按钮调。MVP 不鉴权,按 device_id。"""
     coupon_repo.reset_today_engagement(db, payload.device_id)
+    coupon_repo.reset_today_completion(db, payload.device_id)
     return {"ok": True}
 
 

app/api/v1/device.py

@@ -0,0 +1,66 @@
+"""设备注册 / 心跳 endpoint(无障碍保护存活检测)。
+
+路由前缀 /api/v1/device,需 Bearer 鉴权(设备绑登录用户)。
+  POST /register   注册设备 / 更新 registration_id(App 前台、拿到 push token 时调)
+  POST /heartbeat  上报心跳(无障碍服务存活时周期调,刷新存活)
+
+后端 heartbeat_monitor_worker 据此发现心跳超时的设备并极光推送告警。
+见 spec: spec/accessibility-liveness-push.md。
+"""
+from __future__ import annotations
+
+import logging
+
+from fastapi import APIRouter
+
+from app.api.deps import CurrentUser, DbSession
+from app.repositories import device as device_repo
+from app.schemas.device import (
+    DeviceOut,
+    DeviceRegisterRequest,
+    HeartbeatRequest,
+    OkResponse,
+)
+
+logger = logging.getLogger("shagua.device")
+
+router = APIRouter(prefix="/api/v1/device", tags=["device"])
+
+
+@router.post("/register", response_model=DeviceOut, summary="注册设备/更新推送token")
+def register_device(
+    req: DeviceRegisterRequest,
+    user: CurrentUser,
+    db: DbSession,
+) -> DeviceOut:
+    device = device_repo.register_or_update(
+        db,
+        user_id=user.id,
+        device_id=req.device_id,
+        registration_id=req.registration_id,
+        platform=req.platform,
+        app_version=req.app_version,
+    )
+    logger.info(
+        "device register user_id=%d device_id=%s reg=%s",
+        user.id,
+        req.device_id,
+        bool(req.registration_id),
+    )
+    return DeviceOut.model_validate(device)
+
+
+@router.post("/heartbeat", response_model=OkResponse, summary="上报心跳")
+def report_heartbeat(
+    req: HeartbeatRequest,
+    user: CurrentUser,
+    db: DbSession,
+) -> OkResponse:
+    device_repo.touch_heartbeat(
+        db,
+        user_id=user.id,
+        device_id=req.device_id,
+        accessibility_enabled=req.accessibility_enabled,
+        registration_id=req.registration_id,
+    )
+    return OkResponse()