feat(ad): 广告收益支持环境与业务代码位筛选

## 改动
- 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/ad_revenue.py

@@ -33,7 +33,29 @@ from app.admin.repositories import stats as admin_stats
 from app.core import rewards
 from app.models.ad_ecpm import AdEcpmRecord
 from app.models.user import User
-from app.repositories import ad_pangle_revenue
+from app.repositories import ad_pangle_revenue, app_config
+
+# 已上线过的正式业务代码位要永久保留，避免运营切换当前配置后，历史报表把旧业务位误判成测试流量。
+_KNOWN_PROD_BUSINESS_CODE_IDS = frozenset({"104098712", "104099389"})
+
+# 测试应用中实际承载业务链路的代码位。广告测试 demo 的插屏/半屏/信息流测试位不在这里，
+# 避免“业务口径”把开发诊断曝光混进客户端与穿山甲对账。
+_TEST_BUSINESS_CODE_IDS = frozenset({"104127529", "104127626", "104137445"})
+
+
+def _business_code_ids(db: Session, app_env: str | None) -> set[str]:
+    """返回指定应用环境下可用于业务收益对账的 GroMore 聚合代码位。"""
+    prod_config = app_config.get_ad_config(db)
+    prod_ids = set(_KNOWN_PROD_BUSINESS_CODE_IDS) | {
+        str(prod_config.get(key) or "").strip()
+        for key in ("reward_code_id", "compare_draw_code_id", "coupon_draw_code_id")
+    }
+    prod_ids.discard("")
+    if app_env == "prod":
+        return prod_ids
+    if app_env == "test":
+        return set(_TEST_BUSINESS_CODE_IDS)
+    return prod_ids | set(_TEST_BUSINESS_CODE_IDS)
 
 
 def _cn_hour(dt: datetime) -> int:
@@ -82,6 +104,7 @@ def ad_revenue_report(
     ad_type: str | None = None,
     feed_scene: str | None = None,
     app_env: str | None = None,
+    revenue_scope: str = "all",
     granularity: str = "day",
     limit: int = 500,
     offset: int = 0,
@@ -277,14 +300,18 @@ def ad_revenue_report(
     if feed_scene is not None:
         events = [e for e in events if e.get("feed_scene") == feed_scene]
 
-    # app_env 过滤(2026-06-29 新增能力,修隐患:测试应用上报的假 eCPM 如 ¥678 CPM 会污染正式收益合计/平均):
-    # 显式传 "prod"/"test" 只看该环境;不传=全部(维持现状)。**不擅自把默认改成排除 test**——本地 dev 库多为
-    # test 数据、默认排除会使本地报表空,且「正式报表是否含 test」属产品口径。建议前端报表页加 app_env 筛选器
-    # (默认选 prod),或产品确认后再把默认改成排除 test。注:穿山甲后台收益列(total_pangle_*)暂未联动此过滤
-    # (它是独立对照列,且 pangle 的 test 是真实小额、非客户端那种假值)。
+    # app_env 过滤:显式传 "prod"/"test" 只看该环境;不传=全部。该参数也会传给下方穿山甲聚合，
+    # 保证客户端预估与 GroMore 汇总使用同一应用环境口径。
     if app_env is not None:
         events = [e for e in events if e.get("app_env") == app_env]
 
+    # 业务口径仅保留正式配置/测试业务链路实际使用的代码位。穿山甲“全量”还包含广告测试
+    # demo、插屏等没有客户端收益上报的曝光，两边直接比较会天然产生假差额。
+    business_code_ids: set[str] | None = None
+    if revenue_scope == "business":
+        business_code_ids = _business_code_ids(db, app_env)
+        events = [e for e in events if e.get("our_code_id") in business_code_ids]
+
     # 排序:time=按时间倒序(新→旧);ecpm=按 eCPM 数值倒序(eCPM 原值是字符串「分」,转数值排;
     # 纯发奖行用其发奖采用的 eCPM,缺失/非法计 0 排末尾)。
     if sort == "ecpm":
@@ -336,7 +363,13 @@ def ad_revenue_report(
     total_pangle_revenue_yuan: float | None = None
     total_pangle_api_revenue_yuan: float | None = None
     if pangle_filterable:
-        pangle_aggs = ad_pangle_revenue.aggregate_by_date(db, date_from=date_from, date_to=date_to)
+        pangle_aggs = ad_pangle_revenue.aggregate_by_date(
+            db,
+            date_from=date_from,
+            date_to=date_to,
+            app_env=app_env,
+            our_code_ids=business_code_ids,
+        )
         if pangle_aggs:
             by_date = {a["date"]: a for a in pangle_aggs}
             for d in daily:

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/routers/ad_revenue.py

@@ -5,7 +5,7 @@
 from __future__ import annotations
 
 from datetime import date as _date
-from typing import Annotated
+from typing import Annotated, Literal
 
 from fastapi import APIRouter, Depends, HTTPException, Query
 
@@ -63,6 +63,13 @@ def get_ad_revenue_report(
             "建议正式收益报表选 prod,避免测试应用的假 eCPM 污染收益合计/平均"
         ),
     ] = None,
+    revenue_scope: Annotated[
+        Literal["business", "all"],
+        Query(
+            description="business=仅业务代码位（用于客户端与穿山甲同口径对账）/ "
+            "all=穿山甲应用全部代码位（包含广告测试等非业务曝光）"
+        ),
+    ] = "all",
     granularity: Annotated[
         str, Query(description="day=按天 / hour=按小时(北京时间);区间>1 天建议用 day")
     ] = "day",
@@ -83,6 +90,7 @@ def get_ad_revenue_report(
     result = ad_revenue.ad_revenue_report(
         db, date_from=d_from.isoformat(), date_to=d_to.isoformat(),
         user_id=user_id, ad_type=ad_type, feed_scene=feed_scene, app_env=app_env,
+        revenue_scope=revenue_scope,
         granularity=granularity, limit=limit, offset=offset, sort=sort,
     )
     return AdRevenueReportOut(

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_pangle_revenue.py

@@ -6,6 +6,7 @@
 """
 from __future__ import annotations
 
+from collections.abc import Collection
 from typing import Any, TypedDict
 
 from sqlalchemy import func, select
@@ -73,6 +74,7 @@ def aggregate_by_date(
     date_to: str,
     app_env: str | None = None,
     our_code_id: str | None = None,
+    our_code_ids: Collection[str] | None = None,
 ) -> list[PangleDateAgg]:
     """按日期汇总穿山甲收益(闭区间,北京时间),供报表趋势 + 合计。
 
@@ -97,6 +99,8 @@ def aggregate_by_date(
         stmt = stmt.where(AdPangleDailyRevenue.app_env == app_env)
     if our_code_id is not None:
         stmt = stmt.where(AdPangleDailyRevenue.our_code_id == our_code_id)
+    if our_code_ids is not None:
+        stmt = stmt.where(AdPangleDailyRevenue.our_code_id.in_(our_code_ids))
 
     out: list[PangleDateAgg] = []
     for report_date, rev, api_rev, imp in db.execute(stmt).all():

docs/api/admin/ad/admin-ad-revenue-report.md

@@ -28,6 +28,8 @@
   | `user_id` | int | 全部 | 只看某用户;不传=所有用户 |
   | `ad_type` | string | 全部 | `reward_video` / `feed` / `draw`;不传=全部类型 |
   | `feed_scene` | string | 全部 | `comparison`(比价)/ `coupon`(领券)/ `welfare`(福利);**全局筛选**,同时作用于明细 / 合计 / `daily`·`hourly` 趋势;不传=全部场景 |
+  | `app_env` | string | 全部 | `prod`=正式应用 / `test`=测试应用;同时过滤客户端预估与穿山甲汇总 |
+  | `revenue_scope` | string | `all` | `business`=仅业务代码位,用于同口径对账 / `all`=应用全部代码位,包含广告测试等非业务曝光 |
   | `granularity` | string | `day` | `day`=按天 / `hour`=按小时(聚合键再加北京时间小时 0–23);**区间>1 天建议用 day** |
   | `limit` | int(1~1000) | 500 | **每页条数**(分页大小);`total`/`total_*`/`daily`/`hourly` 按全量统计不受分页影响 |
   | `offset` | int(≥0) | 0 | 分页偏移(已跳过条数)=(页码−1)×`limit` |
@@ -131,5 +133,5 @@
 - **历史 Draw 不可拆**:迁移(Draw→普通信息流)前,Draw 发奖混在 `ad_feed_reward_record` 且无类型标记,金币侧统一记 `feed`;迁移后 Draw 不再产生新数据。展示侧 `ad_type` 由客户端上报区分,故 `draw` 桶基本为空。
 - **来源字段从上线起齐全**:`app_env`/`our_code_id` 是本期新增列,历史记录为 NULL(报表来源列留空)。
 - **逐条/明细的收益是预估**:`items[].revenue_yuan` 基于客户端上报的 eCPM 折算,非穿山甲后台结算值。
-- **穿山甲后台收益(汇总/趋势级)**:`total_pangle_revenue_yuan`(预估 `revenue`)与 `total_pangle_api_revenue_yuan`(收益Api `api_revenue`,更接近结算)来自穿山甲 **GroMore 数据 API**(`integrations/pangle_report` + `scripts/sync_pangle_revenue` 按天 T+1 拉取入 [ad_pangle_daily_revenue](../database/ad_pangle_daily_revenue.md))。穿山甲**不提供分用户/设备/类型/场景维度**(官方明确),最细到 日期×应用×代码位,故只用于汇总与按天趋势的对照,**不挂到逐条事件行**;且仅在全量视图(未按 user/类型/场景过滤)展示。配置见 `.env` 的 `PANGLE_REPORT_*`。
+- **穿山甲后台收益(汇总/趋势级)**:`total_pangle_revenue_yuan`(预估 `revenue`)与 `total_pangle_api_revenue_yuan`(收益Api `api_revenue`,更接近结算)来自穿山甲 **GroMore 数据 API**(`integrations/pangle_report` + `scripts/sync_pangle_revenue` 按天 T+1 拉取入 [ad_pangle_daily_revenue](../database/ad_pangle_daily_revenue.md))。穿山甲**不提供分用户/设备/类型/场景维度**(官方明确),最细到 日期×应用×代码位,故只用于汇总与按天趋势的对照,**不挂到逐条事件行**;且仅在未按 user/类型/场景过滤时展示。`app_env` 与 `revenue_scope` 会同时过滤客户端和穿山甲数据，其中 `business` 排除广告测试等非业务代码位。配置见 `.env` 的 `PANGLE_REPORT_*`。
 - **对账聚合级 + 逐条下钻**:行级 `matched` 给出该组(用户×类型×应用×代码位)应发是否==实发;**展开 `records` 即可看该组逐条明细**(eCPM/因子1/份数/LT/因子2/应发/实发/一致)定位到具体记录。独立逐条审计接口 [admin-ad-coin-audit](./admin-ad-coin-audit.md) 仍保留(同一复算口径,可全局按场景/只看不符筛选)。

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_admin_ad_revenue_scope.py

@@ -0,0 +1,129 @@
+"""广告收益报表的环境与业务代码位口径。"""
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from sqlalchemy import delete
+
+from app.admin.repositories import ad_revenue
+from app.db.session import SessionLocal
+from app.models.ad_ecpm import AdEcpmRecord
+from app.models.ad_pangle_revenue import AdPangleDailyRevenue
+from app.models.user import User
+
+REPORT_DATE = "2040-02-03"
+
+
+def test_business_scope_filters_client_and_pangle_by_env_and_code(monkeypatch) -> None:
+    db = SessionLocal()
+    try:
+        user = User(
+            phone="18800009991",
+            username="29999999991",
+            register_channel="sms",
+        )
+        db.add(user)
+        db.flush()
+        db.add_all([
+            AdEcpmRecord(
+                user_id=user.id, ad_type="reward_video", ad_session_id="scope-prod-business",
+                app_env="prod", our_code_id="prod-reward", ecpm_raw="10000",
+                report_date=REPORT_DATE, created_at=datetime(2040, 2, 3, tzinfo=UTC),
+            ),
+            AdEcpmRecord(
+                user_id=user.id, ad_type="draw", ad_session_id="scope-prod-demo",
+                app_env="prod", our_code_id="prod-demo", ecpm_raw="20000",
+                report_date=REPORT_DATE, created_at=datetime(2040, 2, 3, tzinfo=UTC),
+            ),
+            AdEcpmRecord(
+                user_id=user.id, ad_type="draw", ad_session_id="scope-prod-known-business",
+                app_env="prod", our_code_id="104098712", ecpm_raw="40000",
+                report_date=REPORT_DATE, created_at=datetime(2040, 2, 3, tzinfo=UTC),
+            ),
+            AdEcpmRecord(
+                user_id=user.id, ad_type="reward_video", ad_session_id="scope-test-business",
+                app_env="test", our_code_id="104127529", ecpm_raw="30000",
+                report_date=REPORT_DATE, created_at=datetime(2040, 2, 3, tzinfo=UTC),
+            ),
+            AdPangleDailyRevenue(
+                report_date=REPORT_DATE, app_env="prod", our_code_id="prod-reward",
+                adn="", revenue_yuan=1.5, api_revenue_yuan=1.2, impressions=10,
+            ),
+            AdPangleDailyRevenue(
+                report_date=REPORT_DATE, app_env="prod", our_code_id="prod-demo",
+                adn="", revenue_yuan=8.0, api_revenue_yuan=7.0, impressions=40,
+            ),
+            AdPangleDailyRevenue(
+                report_date=REPORT_DATE, app_env="prod", our_code_id="104098712",
+                adn="", revenue_yuan=2.5, api_revenue_yuan=2.0, impressions=20,
+            ),
+            AdPangleDailyRevenue(
+                report_date=REPORT_DATE, app_env="test", our_code_id="104127529",
+                adn="", revenue_yuan=9.0, api_revenue_yuan=8.0, impressions=50,
+            ),
+        ])
+        db.commit()
+        monkeypatch.setattr(
+            ad_revenue.app_config,
+            "get_ad_config",
+            lambda _db: {
+                "reward_code_id": "prod-reward",
+                "compare_draw_code_id": "prod-draw",
+                "coupon_draw_code_id": "prod-draw",
+            },
+        )
+
+        business = ad_revenue.ad_revenue_report(
+            db,
+            date_from=REPORT_DATE,
+            date_to=REPORT_DATE,
+            app_env="prod",
+            revenue_scope="business",
+        )
+        assert business["total_impressions"] == 2
+        assert business["total_revenue_yuan"] == 0.5
+        assert business["total_pangle_revenue_yuan"] == 4.0
+        assert business["total_pangle_api_revenue_yuan"] == 3.2
+
+        all_codes = ad_revenue.ad_revenue_report(
+            db,
+            date_from=REPORT_DATE,
+            date_to=REPORT_DATE,
+            app_env="prod",
+            revenue_scope="all",
+        )
+        assert all_codes["total_impressions"] == 3
+        assert all_codes["total_revenue_yuan"] == 0.7
+        assert all_codes["total_pangle_revenue_yuan"] == 12.0
+        assert all_codes["total_pangle_api_revenue_yuan"] == 10.2
+
+        test_business = ad_revenue.ad_revenue_report(
+            db,
+            date_from=REPORT_DATE,
+            date_to=REPORT_DATE,
+            app_env="test",
+            revenue_scope="business",
+        )
+        assert test_business["total_impressions"] == 1
+        assert test_business["total_revenue_yuan"] == 0.3
+        assert test_business["total_pangle_revenue_yuan"] == 9.0
+        assert test_business["total_pangle_api_revenue_yuan"] == 8.0
+
+        all_env_business = ad_revenue.ad_revenue_report(
+            db,
+            date_from=REPORT_DATE,
+            date_to=REPORT_DATE,
+            app_env=None,
+            revenue_scope="business",
+        )
+        assert all_env_business["total_impressions"] == 3
+        assert all_env_business["total_revenue_yuan"] == 0.8
+        assert all_env_business["total_pangle_revenue_yuan"] == 13.0
+        assert all_env_business["total_pangle_api_revenue_yuan"] == 11.2
+    finally:
+        db.rollback()
+        db.execute(delete(AdPangleDailyRevenue).where(AdPangleDailyRevenue.report_date == REPORT_DATE))
+        db.execute(delete(AdEcpmRecord).where(AdEcpmRecord.report_date == REPORT_DATE))
+        db.execute(delete(User).where(User.phone == "18800009991"))
+        db.commit()
+        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)