合并 main 并解决 API 文档冲突

app/integrations/notifier.py

@@ -0,0 +1,43 @@
+"""不活跃预警通知器(可插拔)。
+
+v1 仅日志占位(LogNotifier):现状无真实推送能力(极光只用于一键登录解密 + 设备心跳告警,
+心跳 worker 也只打印),先把清零主流程 + 审计做扎实。后续实现同协议的 JPushNotifier /
+SmsNotifier 即可替换,worker/repo 不改。
+"""
+from __future__ import annotations
+
+import logging
+from typing import Protocol
+
+logger = logging.getLogger("shagua.inactivity")
+
+
+class InactivityNotifier(Protocol):
+    channel: str
+
+    def warn(self, *, user_id: int, coin: int, cash_cents: int,
+             stage: int, days_until_reset: int) -> str:
+        """发预警(只涉及会被清的金币 + 折算现金;邀请现金不清、不预警)。
+        返回状态:'sent' / 'failed' / 'placeholder'。"""
+        ...
+
+
+class LogNotifier:
+    """占位实现:只打印,不真推。参照 heartbeat_monitor_worker「本期先不接推送」先例。"""
+
+    channel = "log"
+
+    def warn(self, *, user_id: int, coin: int, cash_cents: int,
+             stage: int, days_until_reset: int) -> str:
+        logger.warning(
+            "[inactivity-warn] user=%s coin=%s cash_cents=%s stage=T-%s days_until_reset=%s",
+            user_id, coin, cash_cents, stage, days_until_reset,
+        )
+        return "placeholder"
+
+
+def get_notifier(channel: str) -> InactivityNotifier:
+    """按配置返回通知器。未实现的通道(jpush/sms)暂回退 LogNotifier 占位。"""
+    # 后续:if channel == "jpush": return JPushNotifier()
+    #       if channel == "sms":   return SmsNotifier()
+    return LogNotifier()

app/integrations/sms.py

@@ -8,15 +8,17 @@
     校验)→ 鉴权复用极光一键登录的 `JG_APP_KEY`/`JG_MASTER_SECRET`(同一极光应用)。
 
 验证码存储:**进程内存**(单 worker uvicorn 够用)。重启丢失(用户重发即可)。多
-worker / 多机时内存不共享 → 冷却、每日上限、校验都会失效,届时迁移到 DB/Redis。
+worker / 多机时内存不共享 → 冷却、校验都会失效,届时迁移到 DB/Redis。
 见 docs/待办与技术债.md。
 
-防刷三层(短信花钱 + `/sms/send` 在登录前无法 JWT 鉴权):
+防刷两层(短信花钱 + `/sms/send` 在登录前无法 JWT 鉴权):
   1. 单号 `SMS_SEND_INTERVAL_SEC` 冷却(本文件)
-  2. 单号每日 `SMS_DAILY_LIMIT_PER_PHONE` 条上限(本文件)
-  3. 单设备(device_id)每小时频控(api 层 auth.sms_send 内 enforce_rate_limit)+ 极光控制台 IP 白名单/防轰炸(运维侧)。
+  2. 单设备(device_id)+ IP 每小时 / 每天频控(api 层 auth.sms_send 的 check/record_rate_limits,
+     **只按成功发码计数** —— 被本文件单号冷却挡下的重发不占额度)+ 极光控制台 IP 白名单/防轰炸(运维侧)。
      ⚠️ 原「单 IP 频控(rate_limit 依赖)」2026-06-26 按产品要求删除、改设备维度;但 device_id 客户端可伪造/轮换,
         脚本轮换 id 能绕过本层 → 挡脚本狂发主要靠极光控制台侧(+ 可选 nginx 限流)。
+     ⚠️ 原「单号每日上限」2026-07-03 按精简要求删除(mentor 定:登录风控只留单号冷却 + 单设备频控);
+        单号维度现仅剩 60s 冷却,「换号轰炸」由单设备频控封顶。
 另:单码校验失败 `SMS_MAX_VERIFY_ATTEMPTS` 次即作废(防爆破),验过即作废(一次性)。
 """
 from __future__ import annotations
@@ -26,7 +28,6 @@ import logging
 import secrets
 import time
 from dataclasses import dataclass
-from datetime import datetime
 from threading import Lock
 
 import httpx
@@ -56,22 +57,17 @@ class _CodeRecord:
 # 进程内存(单 worker 有效;多 worker 不共享,见模块 docstring)
 _codes: dict[str, _CodeRecord] = {}            # phone -> 当前有效验证码
 _last_sent: dict[str, float] = {}              # phone -> 上次发送 epoch(冷却)
-_daily_count: dict[str, tuple[str, int]] = {}  # phone -> (date_str, 当日发送数)
 _lock = Lock()
 _GC_THRESHOLD = 10000  # 任一内存 dict 超此阈值,send 时顺手清过期项(防无限增长,仿 ratelimit)
 
 
-def _today() -> str:
-    return datetime.now().strftime("%Y-%m-%d")
-
-
 def _gen_code() -> str:
     """生成 N 位数字验证码(用 secrets 而非 random;允许前导 0)。"""
     return "".join(secrets.choice("0123456789") for _ in range(settings.SMS_CODE_LENGTH))
 
 
 def _gc(now: float) -> None:
-    """顺手清理过期内存项,防三个 dict 无限增长。仅在持锁时调用,且某 dict 超
+    """顺手清理过期内存项,防两个 dict 无限增长。仅在持锁时调用,且某 dict 超
     _GC_THRESHOLD 才扫它(低频,开销可忽略)。"""
     if len(_codes) > _GC_THRESHOLD:
         for p in [p for p, r in _codes.items() if now > r.expires_at]:
@@ -80,10 +76,6 @@ def _gc(now: float) -> None:
         cutoff = now - settings.SMS_SEND_INTERVAL_SEC
         for p in [p for p, ts in _last_sent.items() if ts < cutoff]:
             _last_sent.pop(p, None)
-    if len(_daily_count) > _GC_THRESHOLD:
-        today = _today()
-        for p in [p for p, (d, _c) in _daily_count.items() if d != today]:
-            _daily_count.pop(p, None)
 
 
 def send_code(phone: str) -> int:
@@ -102,17 +94,9 @@ def send_code(phone: str) -> int:
             remain = int(settings.SMS_SEND_INTERVAL_SEC - elapsed)
             raise SmsError(f"发送过于频繁,请 {remain}s 后再试")
 
-        today = _today()
-        day, cnt = _daily_count.get(phone, ("", 0))
-        if day != today:
-            cnt = 0
-        if cnt >= settings.SMS_DAILY_LIMIT_PER_PHONE:
-            raise SmsError("今日验证码发送次数已达上限,请明天再试")
-
         code = _gen_code()
-        # 预占:先记冷却/计数/存码,释放锁后再发网络(发失败保留冷却+计数,见下)
+        # 预占:先记冷却/存码,释放锁后再发网络(发失败保留冷却,见下)
         _last_sent[phone] = now
-        _daily_count[phone] = (today, cnt + 1)
         _codes[phone] = _CodeRecord(code=code, expires_at=now + settings.SMS_CODE_TTL_SEC)
 
     # --- lock 外:真正发送(网络 IO 不持锁)---
@@ -123,7 +107,7 @@ def send_code(phone: str) -> int:
             _send_via_jiguang(phone, code)
             logger.info("[SMS] sent to %s****", phone[:3])
     except Exception as e:
-        # 发送失败:**保留冷却 + 每日计数**(失败也限速,挡住余额不足/签名失效时
+        # 发送失败:**保留冷却**(失败也限速,挡住余额不足/签名失效时
         # 前端重试狂打极光),只清掉没发出去的码(用户收不到,留着无意义且占内存)。
         with _lock:
             _codes.pop(phone, None)