feat(admin): 返回领券点位明细

## 改动
- eCPM 上报新增可选 exposure_ms，兼容旧客户端
- exposure_ms < 1000 时保留展示记录并强制有效 eCPM 为 0
- 失败领券任务允许保留短曝光零收益 trace，后台显示 0 而不是未填充
- 其他失败后的迟到曝光仍按原规则解绑 trace

## 验证
- 相关 pytest：10 passed
- Ruff：通过
- compileall：通过

依赖：先合并 Server #149。

---------

Co-authored-by: unknown <798648091@qq.com>
Reviewed-on: #150
Co-authored-by: linkeyu <linkeyu@wonderable.ai>
Co-committed-by: linkeyu <linkeyu@wonderable.ai>

alembic/versions/analytics_active_idx_active_composite_index.py

@@ -5,8 +5,10 @@ Revises: 135e79414fd0
 Create Date: 2026-07-18 17:35:00.000000
 
 给 analytics_event 加活跃口径热点复合索引 (event, page, user_id, created_at):
-activity.active_event_condition 按 (event=show & page=home) ∪ 比价 ∪ 领券 过滤后
-group by user_id、max(created_at)。覆盖索引让该聚合走 index-only,避免高频 show 事件全表扫。
+activity.active_event_condition 按 event IN (home_visible ∪ 比价 ∪ 领券) 过滤后
+group by user_id、max(created_at)。覆盖索引让该聚合走 index-only,避免高频活跃事件全表扫。
+(历史:早期首页可见用 event=show+page=home 组合,故索引含 page 列;现改单一 home_visible、
+不再按 page 过滤 → page 列成冗余,索引仍靠 event 前缀生效;如需更优可后续新迁移瘦成 (event,user_id,created_at)。)
 
 ⚠️ 本分支迁移树有**既有多头**:135e79414fd0(不活跃两表)与 phone_rebind_log 同从
 comparison_llm_cost 分叉,`alembic upgrade head` 会多头报错。本迁移挂在 135e79414fd0

app/admin/repositories/coupon_data.py

@@ -22,6 +22,10 @@ from app.repositories import ad_ecpm as crud_ecpm
 from app.repositories.coupon_state import DEFAULT_PLATFORMS, coupon_id_to_platform
 
 
+_SLOT_OK = ("success", "already_claimed")
+_SLOT_TRIED = ("success", "already_claimed", "failed")
+
+
 def _cn_hour(dt: datetime) -> int:
     """started_at(UTC 口径)→ 北京时间小时(0–23)。naive 当 UTC(sqlite),tz-aware 直接换算(pg)。"""
     if dt.tzinfo is None:
@@ -86,7 +90,13 @@ def _success_rates(rows: list) -> dict:
     }
 
 
-def _session_to_row(r, phone: str | None = None, nickname: str | None = None, ad_revenue_yuan: float = 0.0) -> dict:
+def _session_to_row(
+    r,
+    phone: str | None = None,
+    nickname: str | None = None,
+    ad_revenue_yuan: float = 0.0,
+    point_stats: dict | None = None,
+) -> dict:
     """CouponSession ORM → 明细行 dict(主表「领券数据」与「用户全部领券」抽屉共用)。"""
     return {
         "id": r.id,
@@ -104,11 +114,47 @@ def _session_to_row(r, phone: str | None = None, nickname: str | None = None, ad
         "app_env": r.app_env,
         "started_at": r.started_at,
         "claimed_count": r.claimed_count,
+        "point_success_count": point_stats["succeeded"] if point_stats and point_stats["tried"] else None,
+        "point_total_count": point_stats["tried"] if point_stats and point_stats["tried"] else None,
+        "point_details": point_stats["details"] if point_stats else [],
         "trace_url": r.trace_url,
         "ad_revenue_yuan": ad_revenue_yuan,
     }
 
 
+def _point_stats_by_trace(db: Session, trace_ids: list[str]) -> dict[str, dict]:
+    """一次查询批量返回逐场点位分数和逐券明细。"""
+    if not trace_ids:
+        return {}
+    rows = db.execute(
+        select(
+            CouponClaimRecord.trace_id,
+            CouponClaimRecord.coupon_id,
+            CouponClaimRecord.coupon_name,
+            CouponClaimRecord.status,
+            CouponClaimRecord.reason,
+        )
+        .where(CouponClaimRecord.trace_id.in_(trace_ids))
+        .order_by(CouponClaimRecord.trace_id, CouponClaimRecord.id)
+    ).all()
+    result: dict[str, dict] = {}
+    for trace_id, coupon_id, coupon_name, status, reason in rows:
+        if trace_id is None:
+            continue
+        stats = result.setdefault(trace_id, {"succeeded": 0, "tried": 0, "details": []})
+        if status in _SLOT_TRIED:
+            stats["tried"] += 1
+            if status in _SLOT_OK:
+                stats["succeeded"] += 1
+        stats["details"].append({
+            "coupon_id": coupon_id,
+            "coupon_name": coupon_name,
+            "status": status,
+            "reason": reason,
+        })
+    return result
+
+
 def _empty_result() -> dict:
     return {
         "summary": {
@@ -249,10 +295,17 @@ def coupon_data_report(
             ).all()
         }
     rev_map = crud_ecpm.revenue_yuan_by_trace(db, [r.trace_id for r in page])
+    point_stats_map = _point_stats_by_trace(db, [r.trace_id for r in page])
     items = []
     for r in page:
         phone, nickname = user_map.get(r.user_id, (None, None)) if r.user_id is not None else (None, None)
-        items.append(_session_to_row(r, phone, nickname, ad_revenue_yuan=rev_map.get(r.trace_id, 0.0)))
+        items.append(_session_to_row(
+            r,
+            phone,
+            nickname,
+            ad_revenue_yuan=rev_map.get(r.trace_id, 0.0),
+            point_stats=point_stats_map.get(r.trace_id),
+        ))
 
     return {
         "summary": summary,
@@ -275,16 +328,20 @@ def coupon_user_records(db: Session, *, user_id: int, limit: int = 100) -> dict:
         select(func.count()).select_from(CouponSession).where(CouponSession.user_id == user_id)
     ).scalar_one()
     rev_map = crud_ecpm.revenue_yuan_by_trace(db, [r.trace_id for r in rows])
+    point_stats_map = _point_stats_by_trace(db, [r.trace_id for r in rows])
     return {
-        "items": [_session_to_row(r, ad_revenue_yuan=rev_map.get(r.trace_id, 0.0)) for r in rows],
+        "items": [
+            _session_to_row(
+                r,
+                ad_revenue_yuan=rev_map.get(r.trace_id, 0.0),
+                point_stats=point_stats_map.get(r.trace_id),
+            )
+            for r in rows
+        ],
         "total": int(total),
     }
 
 
-_SLOT_OK = ("success", "already_claimed")
-_SLOT_TRIED = ("success", "already_claimed", "failed")
-
-
 def coupon_slot_report(
     db: Session, *, date_from: str, date_to: str, app_env: str | None = None
 ) -> dict:

app/admin/repositories/queries.py

@@ -145,7 +145,7 @@ def list_users(
     代价是翻页期间数据变动可能错位一条——admin 低频场景可接受(同 [list_all_withdraw_orders])。
     日期入参统一转 tz-aware UTC 比较(列为 timestamptz,见 _as_utc)。"""
     # 最近活跃 = max(注册时间, 最近行为事件, 最近领券发起)。baseline 由 last_login_at 改为 created_at
-    #(登录不代表在用 App;口径统一到 activity.py,含 home_view + 比价 + 领券,见 activity.ACTIVE_EVENTS)。
+    #(登录不代表在用 App;口径统一到 activity.py,含 home_visible + 比价 + 领券,见 activity.ACTIVE_EVENTS)。
     # 未命中侧 coalesce 到 created_at(恒非空基线)。派生表 1:1,outerjoin 不放大行数。
     ev_agg, eng_agg = activity.last_active_subqueries(db)
     last_active = activity.last_active_expr(

app/admin/schemas/coupon_data.py

@@ -49,6 +49,15 @@ class CouponDataHourly(BaseModel):
     avg_elapsed_ms: int | None = None
 
 
+class CouponPointDetail(BaseModel):
+    """一次领券任务中的单券点位结果。"""
+
+    coupon_id: str
+    coupon_name: str | None = None
+    status: str = Field(..., description="success / already_claimed / failed / skipped")
+    reason: str | None = None
+
+
 class CouponDataRow(BaseModel):
     """一条领券明细(一次领券任务)。"""
 
@@ -69,6 +78,15 @@ class CouponDataRow(BaseModel):
     app_env: str | None = None
     started_at: datetime = Field(..., description="发起时刻(明细「时间」列)")
     claimed_count: int | None = None
+    point_success_count: int | None = Field(
+        None, description="本次成功券点位数(success+already_claimed);无逐券埋点为空"
+    )
+    point_total_count: int | None = Field(
+        None, description="本次尝试券点位数(success+already_claimed+failed,不含 skipped);无逐券埋点为空"
+    )
+    point_details: list[CouponPointDetail] = Field(
+        default_factory=list, description="本次逐券点位结果，用于后台点击分数查看成功/失败明细"
+    )
     trace_url: str | None = Field(None, description="pricebot 公网 trace 链接(仅 completed 有);admin 渲染可点链接,无则显示可复制 trace_id")
     ad_revenue_yuan: float = Field(
         0.0, description="本次领券看的信息流广告预估收益(元);按 trace_id 聚合 ad_ecpm_record"

app/api/v1/ad.py

@@ -281,7 +281,10 @@ def ecpm_report(payload: EcpmReportIn, user: CurrentUser, db: DbSession) -> Ecpm
     丢一两条不影响业务(穿山甲后台报表是结算权威)。eCPM 与发奖(S2S)是两条独立流,不逐条关联。
     """
     attributed_trace_id = crud_ecpm.attributable_trace_id(
-        db, feed_scene=payload.feed_scene, trace_id=payload.trace_id
+        db,
+        feed_scene=payload.feed_scene,
+        trace_id=payload.trace_id,
+        exposure_ms=payload.exposure_ms,
     )
     if payload.trace_id and attributed_trace_id is None:
         logger.info(
@@ -296,11 +299,12 @@ def ecpm_report(payload: EcpmReportIn, user: CurrentUser, db: DbSession) -> Ecpm
         feed_scene=payload.feed_scene,
         trace_id=attributed_trace_id,
         app_env=payload.app_env, our_code_id=payload.our_code_id,
+        exposure_ms=payload.exposure_ms,
     )
     logger.info(
-        "ad ecpm report user_id=%d type=%s scene=%s session=%s ecpm=%s adn=%s slot=%s app=%s code=%s",
+        "ad ecpm report user_id=%d type=%s scene=%s session=%s ecpm=%s exposure_ms=%s adn=%s slot=%s app=%s code=%s",
         user.id, payload.ad_type, payload.feed_scene, payload.ad_session_id, payload.ecpm,
-        payload.adn, payload.slot_id, payload.app_env, payload.our_code_id,
+        payload.exposure_ms, payload.adn, payload.slot_id, payload.app_env, payload.our_code_id,
     )
     return EcpmReportOut(ok=True)
 

app/models/analytics_event.py

@@ -25,8 +25,9 @@ class AnalyticsEvent(Base):
     __tablename__ = "analytics_event"
     __table_args__ = (
         # 活跃口径聚合热点(activity.active_event_condition + last_active_subqueries):
-        # 按 (event,page) 过滤 首页可见(show/home)∪比价∪领券,再 group by user_id 取
-        # max(created_at)。覆盖索引 → 该聚合走 index-only,避免高频 show 事件全表扫。
+        # 按 event IN (home_visible∪比价∪领券) 过滤,再 group by user_id 取 max(created_at)。
+        # 覆盖索引 → 该聚合走 index-only。注:page 列是早期 show+home 组合的遗留,现不再按 page
+        # 过滤(索引靠 event 前缀仍生效);后续可新迁移瘦成 (event,user_id,created_at)。
         Index("ix_analytics_event_active", "event", "page", "user_id", "created_at"),
     )
 

app/repositories/activity.py

@@ -1,6 +1,6 @@
 """活跃口径唯一真源:worker(不活跃清零)与 admin(最近活跃/DAU)共用,防两处漂移。
 
-口径 = max(User.created_at, AnalyticsEvent[首页可见 show/home + 比价 + 领券], CouponPromptEngagement[claim_started])。
+口径 = max(User.created_at, AnalyticsEvent[首页可见 home_visible + 比价 + 领券], CouponPromptEngagement[claim_started])。
 **不含 last_login_at**(登录/re-login 不代表在用 App);created_at 为恒非空基线。
 清零/预警按北京自然日 0 点对齐(见 reset_cutoff)。
 """
@@ -8,7 +8,7 @@ from __future__ import annotations
 
 from datetime import date, datetime, timedelta, timezone
 
-from sqlalchemy import and_, func, or_, select
+from sqlalchemy import func, select
 from sqlalchemy.orm import Session
 
 from app.core.rewards import CN_TZ, cn_today
@@ -16,24 +16,18 @@ from app.models.analytics_event import AnalyticsEvent
 from app.models.coupon_state import CouponPromptEngagement
 
 # —— 活跃口径事件(与"用户管理"口径一致)——
-# 首页可见:前端埋点 event=show + page=home(组合判定,单个 event 名不足以区分,见
-# active_event_condition);其余为纯 event 名。
-HOME_VIEW_EVENT = "show"
-HOME_VIEW_PAGE = "home"
+# 首页可见:前端埋点确认 event=home_visible(首页进入可视区时触发,单一 event 名即可判定)。
+HOME_VISIBLE_EVENT = "home_visible"
 COMPARE_START_EVENT = "real_compare_start"   # 发起比价(含浮窗触发)
 COUPON_START_EVENT = "real_coupon_start"     # 发起领券
-# 纯 event 名即可判定的活跃事件(首页可见是 event+page 组合、不在此列)
-ACTIVE_EVENTS = (COMPARE_START_EVENT, COUPON_START_EVENT)
+ACTIVE_EVENTS = (HOME_VISIBLE_EVENT, COMPARE_START_EVENT, COUPON_START_EVENT)
 ACTIVE_ENGAGE_TYPE = "claim_started"         # coupon_prompt_engagement 一键领取
 
 
 def active_event_condition():
-    """analytics_event 中算"活跃"的行为过滤:首页可见(event=show & page=home)
+    """analytics_event 中算"活跃"的行为过滤:首页可见(event=home_visible)
     ∪ 发起比价 ∪ 发起领券。worker 子查询与 admin 展示共用,单一真源。"""
-    return or_(
-        and_(AnalyticsEvent.event == HOME_VIEW_EVENT, AnalyticsEvent.page == HOME_VIEW_PAGE),
-        AnalyticsEvent.event.in_(ACTIVE_EVENTS),
-    )
+    return AnalyticsEvent.event.in_(ACTIVE_EVENTS)
 
 
 def as_utc(value: datetime) -> datetime:

app/repositories/ad_ecpm.py

@@ -15,9 +15,22 @@ from app.core.rewards import cn_today
 from app.models.ad_ecpm import AdEcpmRecord
 from app.models.coupon_state import CouponSession
 
+MIN_REVENUE_EXPOSURE_MS = 1000
+
+
+def effective_ecpm_raw(ecpm_raw: str, exposure_ms: int | None) -> str:
+    """曝光不足一秒时保留展示记录，但把该条有效 eCPM 归零。"""
+    if exposure_ms is not None and exposure_ms < MIN_REVENUE_EXPOSURE_MS:
+        return "0"
+    return ecpm_raw
+
 
 def attributable_trace_id(
-    db: Session, *, feed_scene: str | None, trace_id: str | None
+    db: Session,
+    *,
+    feed_scene: str | None,
+    trace_id: str | None,
+    exposure_ms: int | None = None,
 ) -> str | None:
     """返回广告展示允许归属的业务 trace。
 
@@ -31,7 +44,12 @@ def attributable_trace_id(
     session_status = db.execute(
         select(CouponSession.status).where(CouponSession.trace_id == trace_id)
     ).scalar_one_or_none()
-    return None if session_status in {"failed", "abandoned"} else trace_id
+    if session_status not in {"failed", "abandoned"}:
+        return trace_id
+    # 已真实上墙但不足一秒的曝光要在终态明细中明确显示 0，而不是被误判成“未填充”。
+    if exposure_ms is not None and exposure_ms < MIN_REVENUE_EXPOSURE_MS:
+        return trace_id
+    return None
 
 
 def create_ecpm_record(
@@ -47,6 +65,7 @@ def create_ecpm_record(
     trace_id: str | None = None,
     app_env: str | None = None,
     our_code_id: str | None = None,
+    exposure_ms: int | None = None,
 ) -> AdEcpmRecord:
     """落一条 eCPM 上报记录。report_date 用北京时间当天,供按天聚合。
 
@@ -67,7 +86,7 @@ def create_ecpm_record(
         trace_id=trace_id,
         app_env=app_env,
         our_code_id=our_code_id,
-        ecpm_raw=ecpm_raw,
+        ecpm_raw=effective_ecpm_raw(ecpm_raw, exposure_ms),
         report_date=cn_today().isoformat(),
     )
     db.add(rec)

app/schemas/ad.py

@@ -69,6 +69,12 @@ class EcpmReportIn(BaseModel):
         description="本次比价/领券 trace_id(信息流场景带上):把这条展示收益归属到对应比价/领券,"
         "供领券数据/比价记录看板聚合本场广告收益;激励视频/福利为空",
     )
+    exposure_ms: int | None = Field(
+        None,
+        ge=0,
+        le=86_400_000,
+        description="本条广告真实在屏曝光毫秒数；小于 1000ms 时收益强制按 0 计算。旧客户端不传则保持原口径",
+    )
     app_env: str | None = Field(
         None, max_length=16, description="我们的穿山甲应用环境:prod(傻瓜比价正式) / test(测试应用)"
     )

docs/superpowers/specs/2026-07-16-inactivity-reset-design.md

@@ -38,8 +38,8 @@
 
 | 决策点 | 结论 | 理由 |
 |---|---|---|
-| **活跃口径** | 与"用户管理"一致：`max(首页可见 show/home, 比价, 领券)`，**不含 last_login_at**；无任何信号时以 `created_at` 为非空基线 | 比价可从**浮窗**触发、不进首页；`last_login_at` 只在登录/换绑动作更新（re-login 也算），代表不了"在用 App"，故彻底排除 |
-| **"进首页"信号落地** | **方案 A：前端上报 `home_view` 埋点**（复用 `/analytics/events`），非新接口 | 三个活跃信号统一为同类埋点事件；零新接口零新列；与 admin 口径天然一致。B（鉴权接口 + 列）"更权威"的优势是假的——比价/领券仍是端上报事件，最弱环决定整体可信度 |
+| **活跃口径** | 与"用户管理"一致：`max(首页可见 home_visible, 比价, 领券)`，**不含 last_login_at**；无任何信号时以 `created_at` 为非空基线 | 比价可从**浮窗**触发、不进首页；`last_login_at` 只在登录/换绑动作更新（re-login 也算），代表不了"在用 App"，故彻底排除 |
+| **"进首页"信号落地** | **方案 A：前端上报 `home_visible` 埋点**（复用 `/analytics/events`），非新接口 | 三个活跃信号统一为同类埋点事件；零新接口零新列；与 admin 口径天然一致。B（鉴权接口 + 列）"更权威"的优势是假的——比价/领券仍是端上报事件，最弱环决定整体可信度 |
 | **清零范围** | **金币 + 折算现金**（**邀请现金不清**——产品红线，仅快照入审计） | 对应"账户里的金币和现金"；邀请奖励金与金币现金物理隔离、不可累加，见 `wallet.CoinAccount` 注释 |
 | **预警推送** | **可插拔通知器 + 日志占位**（v1），后续接 JPush/短信 | 现状无真实推送能力；先把清零主流程 + 审计做扎实，不阻塞 |
 | **预警时机** | **完全可配置**（提前天数列表 + 次数 + 执行点 + 通道） | R5 |
@@ -76,7 +76,7 @@ last_active = max(
 ### 模块内容
 
 - 常量：
-  - **首页可见活跃信号已定名：`event=show` + `page=home`**（前端确认，原占位 `home_view`；下文出现的 `home_view` 均指此信号）。活跃行为过滤见 `activity.active_event_condition()`：首页可见 ∪ 比价 `real_compare_start` ∪ 领券 `real_coupon_start`；`ACTIVE_EVENTS` 仅含后两个纯 event 名（首页可见是 event+page 组合、单列）。
+  - **首页可见活跃信号已定名：`event=home_visible`**（前端最终确认；曾用过渡期 `show`+`page=home` 组合，已废弃）。活跃行为过滤见 `activity.active_event_condition()`：首页可见 `home_visible` ∪ 比价 `real_compare_start` ∪ 领券 `real_coupon_start`——三者均为纯 event 名，全部收进 `ACTIVE_EVENTS`。
   - `ACTIVE_ENGAGE_TYPE = "claim_started"`
 - `last_active_subqueries(db)` —— 复刻现 admin `queries._last_active_parts()`：两个按 `user_id` 的 `GROUP BY max(created_at)` 聚合子查询。
 - `last_active_expr(base_col, ev_sub, eng_sub, dialect)` —— 生成 `greatest`/`max`（PG `func.greatest`／SQLite `func.max`）；子聚合缺失时 `coalesce(子聚合, User.created_at)` 兜底（注册基线恒非空，**替代原 last_login_at**）。
@@ -210,7 +210,7 @@ INACTIVITY_RESET_CHECK_INTERVAL_SEC = 1800  # worker 唤醒间隔（可复用现
 
 ## 9. 幂等与重新活跃
 
-- **重新活跃自动退出**：`inactive_days` 由 §4 口径**实时算**。用户一有 `home_view`/比价/领券（**登录本身不算**），`last_active` 前移，自动移出预警与清零队列。**无需**显式"重置标记"。
+- **重新活跃自动退出**：`inactive_days` 由 §4 口径**实时算**。用户一有 `home_visible`/比价/领券（**登录本身不算**），`last_active` 前移，自动移出预警与清零队列。**无需**显式"重置标记"。
 - **预警去重**：`inactivity_notification_log` 中存在 `stage==k 且 created_at > last_active` 的行 ⟹ 本 streak 已推过档 `k`，不重推。用户回归后 `last_active` 前移，旧预警行自然"失效"，开启新 streak。
 - **清零幂等**：阶段 B 只处理三桶非全 0 者；清完 = 0，次日不再匹配。worker 重启 / 多次唤醒 / 补跑均安全，不产生重复清零或重复流水。
 - **稳健补发**：worker 漏跑数天后，某用户可能同时满足多档；只补发**最紧急的未推档**（最小 `k`），避免一次刷屏。
@@ -221,7 +221,7 @@ INACTIVITY_RESET_CHECK_INTERVAL_SEC = 1800  # worker 唤醒间隔（可复用现
 
 | 场景 | 处理 |
 |---|---|
-| 新用户 | `created_at` 作活跃基线（恒非空）→ 注册即"第 1 日活跃"；注册后连续 15 天无 home_view/比价/领券 才清 |
+| 新用户 | `created_at` 作活跃基线（恒非空）→ 注册即"第 1 日活跃"；注册后连续 15 天无 home_visible/比价/领券 才清 |
 | 在途提现 | 提现申请时现金已扣入 `WithdrawOrder`，当前余额已不含在途；只清当前余额、不动提现单。提现失败退款到已清账户 = 用户的钱，正常 |
 | 与 `daily_auto_exchange` 并存 | 各自逐用户幂等；金币多已日结折现金，三桶全清正好覆盖 |
 | 时区/日界 | 统一北京（`rewards.cn_today()`/`CN_TZ`）；**清零/预警按北京自然日 0 点对齐**（末次活跃记为第 1 日 → 第 16 日 0 点清零，见 §4），非滚动 24h；流水 `created_at` 沿用北京 wall-clock naive |
@@ -229,11 +229,11 @@ INACTIVITY_RESET_CHECK_INTERVAL_SEC = 1800  # worker 唤醒间隔（可复用现
 
 ---
 
-## 11. 前端依赖：`home_view` 埋点（跨仓 — Android）
+## 11. 前端依赖：`home_visible` 埋点（跨仓 — Android）
 
-- **Android 端**（`shaguabijia-app-android`）需在**首页可见**（`onResume`/Tab 切入）时，向现有 `POST /api/v1/analytics/events` 批量上报里加一条 `event=<首页可见事件名>`（名称明天加埋点时定，暂记 `"home_view"`） 的事件，**携带登录后的 `user_id`**。
+- **Android 端**（`shaguabijia-app-android`）需在**首页可见**（`onResume`/Tab 切入）时，向现有 `POST /api/v1/analytics/events` 批量上报里加一条 `event=home_visible`（前端已定名）的事件，**携带登录后的 `user_id`**。
 - 客户端按会话/前台去重即可（服务端只取 `max(created_at)`，多报无害）。
-- **上线顺序依赖**：`home_view` 全量覆盖前，"进首页"信号缺失，只有比价/领券能推进活跃、其余落到 `created_at` 基线（"只开首页不操作"且注册满 15 天的用户会被误清）—— 故**开真清（`ENABLED=true`）必须待 `home_view` 铺满后再开**（§13）；dry-run 只记名单不动钱、可先开着看。
+- **上线顺序依赖**：`home_visible` 全量覆盖前，"进首页"信号缺失，只有比价/领券能推进活跃、其余落到 `created_at` 基线（"只开首页不操作"且注册满 15 天的用户会被误清）—— 故**开真清（`ENABLED=true`）必须待 `home_visible` 铺满后再开**（§13）；dry-run 只记名单不动钱、可先开着看。
 
 ---
 
@@ -241,25 +241,25 @@ INACTIVITY_RESET_CHECK_INTERVAL_SEC = 1800  # worker 唤醒间隔（可复用现
 
 - `app/admin/repositories/queries.py`：删本地 `_ACTIVE_EVENTS`/`_last_active_parts()`，改用 `activity.py` 的常量与子查询构造；`list_users` 的 `greatest(...)` 排序/筛选、`_attach_last_active` 均改走共享构造器。
 - `app/admin/repositories/stats.py`：`COMPARE_START_EVENT`/`COUPON_START_EVENT`/活跃用户集（`:138-146`）改用共享常量与口径。
-- **行为变化（预期内、需产品知会）**：admin 的"最近活跃 / DAU"口径变化——**移除 `last_login_at`（登录不再计为活跃）、以 `created_at` 为基线、纳入 `home_view`**。net：`home_view` 铺满后更准（真正把"开首页"算进活跃）；铺满前"只登录不操作"的用户活跃度会下降。
-- **回归底线**：现有 admin 用户列表 / stats 测试按新口径**更新预期**（last_login_at 移除 + created_at 基线 + home_view 纳入）；非活跃口径部分行为不变。
+- **行为变化（预期内、需产品知会）**：admin 的"最近活跃 / DAU"口径变化——**移除 `last_login_at`（登录不再计为活跃）、以 `created_at` 为基线、纳入 `home_visible`**。net：`home_visible` 铺满后更准（真正把"开首页"算进活跃）；铺满前"只登录不操作"的用户活跃度会下降。
+- **回归底线**：现有 admin 用户列表 / stats 测试按新口径**更新预期**（last_login_at 移除 + created_at 基线 + home_visible 纳入）；非活跃口径部分行为不变。
 
 ---
 
 ## 13. 灰度与上线顺序（安全优先）
 
 1. **后端先行**：合入共享模块 + 两表 + worker + 通知器，`INACTIVITY_RESET_ENABLED=False`；活跃口径以 `created_at` 为非空基线、**不含 last_login_at**。
-2. **Android 发版**：上报 `home_view`；观察 analytics 覆盖率。
+2. **Android 发版**：上报 `home_visible`；观察 analytics 覆盖率。
 3. **dry-run 灰度（默认即是）**：`INACTIVITY_RESET_ENABLED=False` 时 worker 常驻只写审计名单（`reason=inactive_Nd_dryrun`）、不动钱、不预警；核对名单准确。
 4. **开真清**：确认无误后置 `INACTIVITY_RESET_ENABLED=True`（转为真清 + 预警）。
-5. **收尾/监控**：持续观察 `home_view` 覆盖率与预警/清零名单；发现"活跃却被判不活跃"的漏报即回查埋点覆盖（口径已不含 last_login_at，登录不再兜底）。
+5. **收尾/监控**：持续观察 `home_visible` 覆盖率与预警/清零名单；发现"活跃却被判不活跃"的漏报即回查埋点覆盖（口径已不含 last_login_at，登录不再兜底）。
 
 ---
 
 ## 14. 测试计划
 
-- **活跃口径（共享模块）**：`home_view`/比价/领券 各单独命中都算活跃；**纯登录不算**；无信号用户以 `created_at` 计；`max` 取最新；naive/aware 混算不崩。
-- **admin 回归**：用户列表 / stats 按新口径更新预期（移除 last_login_at + created_at 基线 + home_view）。
+- **活跃口径（共享模块）**：`home_visible`/比价/领券 各单独命中都算活跃；**纯登录不算**；无信号用户以 `created_at` 计；`max` 取最新；naive/aware 混算不崩。
+- **admin 回归**：用户列表 / stats 按新口径更新预期（移除 last_login_at + created_at 基线 + home_visible）。
 - **不活跃判定**：`last_active` 分别 `<15d / =15d / >15d` × 有/无余额 的命中矩阵。
 - **清零**：三桶归零；`inactivity_reset_log` 清前值正确；三条流水 `biz_type=inactivity_reset`、`balance_after=0`、`ref_id=log.id`；`total_coin_earned` 不变。
 - **预警**：命中窗口调 notifier + 写 `notification_log`；同 streak 不重推；回归后 `last_active` 前移可再次预警；漏跑补发最紧急档。

scripts/seed_inactivity_cases.py

@@ -33,6 +33,7 @@ from app.models.wallet import (  # noqa: E402
     CoinTransaction,
     InviteCashTransaction,
 )
+from app.repositories import activity  # noqa: E402
 from app.repositories import wallet as wallet_repo  # noqa: E402
 
 MARK = "vcase"  # username 前缀,用于清理
@@ -47,7 +48,7 @@ CASES = [
     ("6 只有现金",        30,   0, 200,   0, None, "清 cash;审计1行+1流水"),
     ("7 只有邀请(红线)",  30,   0,   0, 300, None, "不选中/不清/无审计/无流水;invite=300 原封"),
     ("8 预警窗(10天)",    10,  50,  60,  70, None, "不清;发 T-7 预警;notification_log 1行;余额不动"),
-    ("9 活跃兜底",        30, 100, 200, 300,    1, "昨日 home_view→last_active 近→不清不警"),
+    ("9 活跃兜底",        30, 100, 200, 300,    1, "昨日 home_visible→last_active 近→不清不警"),
     ("10 新用户(3天)",     3, 100, 200,   0, None, "created_at 近→不清不警"),
 ]
 
@@ -86,8 +87,8 @@ def seed(db) -> None:
         acc.coin_balance, acc.cash_balance_cents, acc.invite_cash_balance_cents = coin, cash, invite
         acc.total_coin_earned = coin
         if ev_days is not None:
-            db.add(AnalyticsEvent(  # 首页可见 = event=show + page=home
-                event="show", page="home", device_id=MARK, user_id=u.id,
+            db.add(AnalyticsEvent(  # 首页可见 = event=home_visible(单一 event 名,见 activity.ACTIVE_EVENTS)
+                event=activity.HOME_VISIBLE_EVENT, device_id=MARK, user_id=u.id,
                 client_ts=0, created_at=now - timedelta(days=ev_days),
             ))
         db.flush()

tests/test_ad_ecpm_trace_revenue.py

@@ -58,6 +58,32 @@ def test_revenue_yuan_by_trace_empty() -> None:
         db.close()
 
 
+def test_short_exposure_keeps_record_with_zero_revenue() -> None:
+    """不足一秒仍落展示记录，以便后台显示 0 而不是未填充。"""
+    db = SessionLocal()
+    try:
+        rec = crud_ecpm.create_ecpm_record(
+            db, 1, ad_type="draw", ecpm_raw="350",
+            ad_session_id="sess-short-exposure", feed_scene="coupon",
+            trace_id="trace-short-exposure", exposure_ms=999,
+        )
+        assert rec.ecpm_raw == "0"
+        assert crud_ecpm.revenue_yuan_by_trace(db, ["trace-short-exposure"]) == {
+            "trace-short-exposure": 0.0
+        }
+    finally:
+        db.execute(delete(AdEcpmRecord).where(
+            AdEcpmRecord.ad_session_id == "sess-short-exposure"
+        ))
+        db.commit()
+        db.close()
+
+
+def test_one_second_exposure_keeps_original_ecpm() -> None:
+    assert crud_ecpm.effective_ecpm_raw("350", 1000) == "350"
+    assert crud_ecpm.effective_ecpm_raw("350", None) == "350"
+
+
 def test_terminal_coupon_trace_is_not_attributable_to_late_impression() -> None:
     """领券失败或被放弃后才到达的广告展示保留收益记录，但不再关联死亡 trace。"""
     db = SessionLocal()
@@ -80,6 +106,12 @@ def test_terminal_coupon_trace_is_not_attributable_to_late_impression() -> None:
         assert crud_ecpm.attributable_trace_id(
             db, feed_scene="coupon", trace_id="abandoned-before-ad"
         ) is None
+        assert crud_ecpm.attributable_trace_id(
+            db, feed_scene="coupon", trace_id="failed-before-ad", exposure_ms=999
+        ) == "failed-before-ad"
+        assert crud_ecpm.attributable_trace_id(
+            db, feed_scene="coupon", trace_id="abandoned-before-ad", exposure_ms=999
+        ) == "abandoned-before-ad"
         assert crud_ecpm.attributable_trace_id(
             db, feed_scene="comparison", trace_id="failed-before-ad"
         ) == "failed-before-ad"

tests/test_coupon_point_score.py

@@ -0,0 +1,61 @@
+"""admin 领券明细逐场点位分数。"""
+from datetime import date
+
+from app.admin.repositories.coupon_data import _point_stats_by_trace
+from app.db.session import SessionLocal
+from app.models.coupon_state import CouponClaimRecord
+
+
+def test_point_scores_by_trace() -> None:
+    """已领算成功、失败算尝试、跳过不进分母。"""
+    db = SessionLocal()
+    trace = "point-score-trace"
+    try:
+        db.add_all([
+            CouponClaimRecord(
+                device_id="score-device",
+                coupon_id=f"mt-score-{status}",
+                claim_date=date(2020, 1, 2),
+                status=status,
+                coupon_name=f"测试点位-{status}",
+                reason="测试失败" if status == "failed" else None,
+                trace_id=trace,
+            )
+            for status in ("success", "already_claimed", "failed", "skipped")
+        ])
+        db.flush()
+
+        stats = _point_stats_by_trace(db, [trace])[trace]
+        assert stats["succeeded"] == 2
+        assert stats["tried"] == 3
+        assert [item["status"] for item in stats["details"]] == [
+            "success", "already_claimed", "failed", "skipped"
+        ]
+        assert stats["details"][2]["reason"] == "测试失败"
+    finally:
+        db.rollback()
+        db.close()
+
+
+def test_point_stats_keep_skipped_detail_without_faking_score() -> None:
+    """仅有 skipped 时保留明细，但分数仍为 0/0，由 schema 层展示为空。"""
+    db = SessionLocal()
+    trace = "point-score-skipped"
+    try:
+        db.add(CouponClaimRecord(
+            device_id="score-device-skipped",
+            coupon_id="mt-score-skipped-only",
+            claim_date=date(2020, 1, 2),
+            status="skipped",
+            trace_id=trace,
+        ))
+        db.flush()
+
+        stats = _point_stats_by_trace(db, [trace, "missing-trace"])
+        assert stats[trace]["succeeded"] == 0
+        assert stats[trace]["tried"] == 0
+        assert stats[trace]["details"][0]["status"] == "skipped"
+        assert "missing-trace" not in stats
+    finally:
+        db.rollback()
+        db.close()

tests/test_inactivity_reset.py

@@ -42,9 +42,9 @@ def test_reset_cutoff_is_cn_midnight_of_today_minus_days_minus_1() -> None:
 
 
 def test_active_event_constants() -> None:
-    # 首页可见 = event=show + page=home 组合,不在纯 event 名集合里
-    assert activity.HOME_VIEW_EVENT == "show" and activity.HOME_VIEW_PAGE == "home"
-    assert activity.HOME_VIEW_EVENT not in activity.ACTIVE_EVENTS
+    # 首页可见:前端埋点确认 event=home_visible,单一 event 名,在 ACTIVE_EVENTS 中
+    assert activity.HOME_VISIBLE_EVENT == "home_visible"
+    assert activity.HOME_VISIBLE_EVENT in activity.ACTIVE_EVENTS
     assert "real_compare_start" in activity.ACTIVE_EVENTS
     assert "real_coupon_start" in activity.ACTIVE_EVENTS
     assert activity.ACTIVE_ENGAGE_TYPE == "claim_started"
@@ -133,15 +133,15 @@ def test_last_active_expr_takes_max_of_baseline_and_events() -> None:
         db.close()
 
 
-def test_home_signal_uses_show_event_on_home_page() -> None:
-    """首页可见活跃口径 = event=show + page=home 组合;show 但非 home 页不算活跃。"""
+def test_home_signal_uses_home_visible_event() -> None:
+    """首页可见活跃口径 = event=home_visible(单一事件名,前端埋点已确认);其他事件不算活跃。"""
     from sqlalchemy import select
     db = SessionLocal()
     try:
         base = datetime(2026, 1, 1, tzinfo=timezone.utc)
-        seen = _new_user(db, created_at=base)      # show/home → 活跃
-        _add_event(db, seen, "show", datetime(2026, 1, 10, tzinfo=timezone.utc), page="home")
-        other = _new_user(db, created_at=base)     # show/其他页 → 不算活跃
+        seen = _new_user(db, created_at=base)      # home_visible → 活跃
+        _add_event(db, seen, "home_visible", datetime(2026, 1, 10, tzinfo=timezone.utc))
+        other = _new_user(db, created_at=base)     # 其他事件 → 不算活跃
         _add_event(db, other, "show", datetime(2026, 1, 10, tzinfo=timezone.utc), page="coupon")
         db.commit()
 
@@ -156,8 +156,8 @@ def test_home_signal_uses_show_event_on_home_page() -> None:
                     .where(User.id == uid))
             return activity.norm_utc(db.execute(stmt).scalar_one())
 
-        assert last_active(seen) == datetime(2026, 1, 10, tzinfo=timezone.utc)  # show/home 算
-        assert last_active(other) == base                                       # show/其他页 不算
+        assert last_active(seen) == datetime(2026, 1, 10, tzinfo=timezone.utc)  # home_visible 算
+        assert last_active(other) == base                                       # 其他事件不算
     finally:
         db.rollback()
         db.close()
@@ -194,9 +194,9 @@ def test_run_reset_clears_coin_and_cash_but_preserves_invite_cash() -> None:
         # 末次活跃 = created_at 基线 = 1/10(距 today 22 天 → 应清)
         old = _new_user(db, created_at=datetime(2026, 1, 10, tzinfo=timezone.utc),
                         coin=100, cash=200, invite=300)
-        # 活跃用户:昨天有 home_view → 不清
+        # 活跃用户:昨天有 home_visible → 不清
         fresh = _new_user(db, created_at=datetime(2026, 1, 1, tzinfo=timezone.utc), coin=50)
-        _add_event(db, fresh, "show", datetime(2026, 1, 31, tzinfo=timezone.utc), page="home")
+        _add_event(db, fresh, "home_visible", datetime(2026, 1, 31, tzinfo=timezone.utc))
         db.commit()
 
         stats = inactivity.run_reset_once(db, reset_days=15, today=today)