feat(ad-revenue): 收益报表按一次比价/领券聚合(trace 合并)+ 微信昵称/签到时间修复 (#103)

- 报表主表改为「单次广告行为」:激励视频=一次观看一行;一次比价/领券=同一 trace_id(整场,
  无 trace 时兜底 ad_session_id)的多条发奖聚成一行,点开看逐条金币复算。中途跳转广告致浮层重弹、
  ad_session_id 变化也能按 trace 归一行。
- 信息流统一 Draw(业务已全切):新增 audit 的 feed_all scene,让「Draw 信息流」筛选覆盖历史误标的
  feed/NULL;聚合行 ad_type 统一 draw;_feed_rows 带出 trace_id 供聚合。
- 父行补 sub_rewards(组内逐条复算明细)、sub_count;row_revenue_yuan=该次发奖广告 eCPM 折算收益之和,
  仅供主表逐行展示、不进合计/趋势(避免与展示侧 total 重复计)。
- 用户 360 概览(AdminUserListItem)返回 wechat_nickname,供收益详情抽屉显示微信昵称。
- 金币记录:签到来自 coin_transaction(存北京 wall-clock),组装时转 UTC 与广告记录统一,修抽屉签到
  时间多 8 小时;签到窗口边界 +8h 对齐;顺带补 _window_conds 引用却从未定义的 _as_utc_naive
  (自定义区间会 NameError)。

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

---------

Co-authored-by: zzhyyyyy <2685922758@qq.com>
Reviewed-on: #103
Co-authored-by: zhuzihao <zhuzihao@wonderable.ai>
Co-committed-by: zhuzihao <zhuzihao@wonderable.ai>

alembic/versions/761ef181ce7c_merge_jd_cps_order_fields_and_coupon_.py

@@ -0,0 +1,26 @@
+"""merge jd_cps_order_fields and coupon_session_origin_package heads
+
+Revision ID: 761ef181ce7c
+Revises: coupon_session_origin_package, jd_cps_order_fields
+Create Date: 2026-07-01 13:52:16.068808
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '761ef181ce7c'
+down_revision: Union[str, Sequence[str], None] = ('coupon_session_origin_package', 'jd_cps_order_fields')
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    pass
+
+
+def downgrade() -> None:
+    pass

app/admin/repositories/ad_audit.py

@@ -136,12 +136,16 @@ def _feed_scene_matches(rec: AdFeedRewardRecord, scene: str | None) -> bool:
     """该信息流记录是否落入请求的展示筛选 scene。
     - scene=="feed":ad_type in ("feed", NULL)(旧数据 NULL 视为 feed,向后兼容)
     - scene=="draw":ad_type=="draw"
+    - scene=="feed_all":所有信息流(feed/draw/NULL 都要)——业务已全切 Draw 信息流,收益报表把「Draw 信息流」
+      当作整个信息流口径(含历史误标 feed/NULL),用它避免筛选漏历史。
     - scene 为 None:不筛(两类都要)。
     """
     if scene == "feed":
         return rec.ad_type in (None, "feed")
     if scene == "draw":
         return rec.ad_type == "draw"
+    if scene == "feed_all":
+        return True
     return True
 
 
@@ -184,6 +188,7 @@ def _feed_rows(
                 "record_id": rec.id,
                 "user_id": rec.user_id,
                 "ad_session_id": rec.ad_session_id,
+                "trace_id": rec.trace_id,
                 "app_env": rec.app_env,
                 "our_code_id": rec.our_code_id,
                 "created_at": rec.created_at,
@@ -209,6 +214,7 @@ def _feed_rows(
                 "record_id": rec.id,
                 "user_id": rec.user_id,
                 "ad_session_id": rec.ad_session_id,
+                "trace_id": rec.trace_id,
                 "app_env": rec.app_env,
                 "our_code_id": rec.our_code_id,
                 "created_at": rec.created_at,
@@ -241,7 +247,7 @@ def audit_rows(
     rows: list[dict] = []
     if scene in (None, "reward_video"):
         rows.extend(_reward_video_rows(db, date=date, user_id=user_id))
-    if scene in (None, "feed", "draw"):
+    if scene in (None, "feed", "draw", "feed_all"):
         rows.extend(_feed_rows(db, date=date, user_id=user_id, scene=scene))
     return rows
 

app/admin/repositories/ad_revenue.py

@@ -3,9 +3,11 @@
 只读。每行 = 一次广告事件(不再按用户聚合):
 - **激励视频**:一次观看 = 1 条展示(ad_ecpm)+ 1 条发奖(ad_reward),按 ad_session_id 合并成一行,
   直接给出 eCPM / 收益 + 状态 / 应发 / 实发 / 一致;点开看该条金币复算因子。
-- **信息流**:轮播每条展示各一行(impressionId 各自独立);整场发奖(ad_feed_reward,client_event_id)
-  与逐条展示无法对应,单独成「纯发奖」行。
-- 兜底:有展示无发奖(中途关 / 未达发奖)、有发奖无展示(未上报 eCPM)都各自成行。
+- **信息流(比价/领券)**:一次比价 / 一次领券 = 一条整场发奖(ad_feed_reward)一行,给出 eCPM /
+  发奖金币 + 应发 / 实发 / 一致;点开看金币复算因子。⚠️ draw 的逐条展示(ad_ecpm,impressionId 各自
+  独立、与整场发奖无公共键、无法归到「哪一次」)**不再单独占行**(2026-07 按「一次比价/领券放一块」调整)——
+  其展示数 / eCPM / 预估收益仍进全量统计(合计 / 趋势 / 分类大盘 / 穿山甲对照),只是主表不逐条铺开。
+- 兜底:激励视频有展示无发奖(中途关 / 未达发奖)、有发奖无展示(未上报 eCPM)仍各自成行。
 
 展示与收益来自 ad_ecpm_record(收益 = eCPM元 ÷ 1000);应发 / 实发金币复用金币审计逐条复算
 (ad_audit.audit_rows,与正式发奖同一公式口径,不另写公式)。合计与对账在全量上统计,
@@ -58,14 +60,6 @@ def _date_range(date_from: str, date_to: str) -> list[str]:
 _AUDIT_SCENES = {"reward_video", "feed", "draw"}
 
 
-def _event_ad_type(row: dict) -> str:
-    """纯发奖事件行的 ad_type:信息流行用 audit 带回的真实 ad_type(feed/draw),回退 feed;
-    激励视频行恒 reward_video。不再用 scene 硬映射,避免把 draw 丢成 feed。"""
-    if row["scene"] == "reward_video":
-        return "reward_video"
-    return row.get("ad_type") or "feed"
-
-
 # 发奖复算明细字段(展开下钻看「金币怎么算出来的」)——从 audit 行原样取这些 key。
 _REWARD_DETAIL_KEYS = (
     "record_id", "created_at", "status", "ecpm", "ecpm_factor", "units",
@@ -108,9 +102,14 @@ def ad_revenue_report(
     #    同时保留全量列表,未被展示合并的成「纯发奖」事件。
     reward_by_session: dict[tuple[int, str], list[dict]] = {}
     all_reward_rows: list[dict] = []
-    # 报表 ad_type 直接当 audit scene 用(取值一致);未知/无效 ad_type 不取发奖行。draw 在此被
-    # 正确传成 scene="draw",audit 会按 ad_type 筛出 Draw 发奖,不再丢成 feed。
-    audit_scene = ad_type if ad_type in _AUDIT_SCENES else None
+    # 报表 ad_type → audit scene:reward_video/feed 直传;**draw(前端「Draw 信息流」)映射成 feed_all**
+    # ——业务已全切 Draw,把「Draw 信息流」当作整个信息流口径(含历史误标 feed/NULL),否则筛选会漏历史。
+    if ad_type == "draw":
+        audit_scene = "feed_all"
+    elif ad_type in _AUDIT_SCENES:
+        audit_scene = ad_type
+    else:
+        audit_scene = None
     if ad_type is None or audit_scene is not None:
         for d in _date_range(date_from, date_to):
             for row in ad_audit.audit_rows(db, date=d, user_id=user_id, scene=audit_scene):
@@ -140,7 +139,10 @@ def ad_revenue_report(
     )
     if user_id is not None:
         stmt = stmt.where(AdEcpmRecord.user_id == user_id)
-    if ad_type is not None:
+    if ad_type == "draw":
+        # draw = 所有信息流展示(业务已全 Draw,含历史误标 feed);展示行只进统计,不占主表行
+        stmt = stmt.where(AdEcpmRecord.ad_type.in_(["draw", "feed"]))
+    elif ad_type is not None:
         stmt = stmt.where(AdEcpmRecord.ad_type == ad_type)
     for rec in db.execute(stmt).scalars():
         rwd = _pop_reward(rec.user_id, rec.ad_session_id)
@@ -165,6 +167,8 @@ def ad_revenue_report(
             ),
             "adn": rec.adn,
             "slot_id": rec.slot_id,
+            "sub_rewards": [],
+            "sub_count": 1,
         }
         if rwd is not None:
             ev.update({
@@ -184,33 +188,88 @@ def ad_revenue_report(
             })
         events.append(ev)
 
-    # 3) 未被展示合并的发奖行 → 「纯发奖」事件(信息流整场发奖 / 有发奖无展示)。
-    #    收益恒 0(收益只算展示侧,避免与展示行重复计)。
+    # 3) 未被展示合并的发奖行 → 事件:
+    #    - 激励视频(reward_video):逐条成「纯发奖」事件(每次一个 ad_session_id;有发奖无展示等)。
+    #    - 信息流(feed/draw):同一次比价/领券的多条广告共享**整场 ad_session_id**(客户端整场复用),
+    #      按 (user_id, ad_session_id) 聚成**一次比价 / 一次领券**父事件;sub_rewards 为组内逐条明细,
+    #      应发/实发取组内合计;业务已全 Draw → 类型统一 "draw"。session 缺失(极少旧数据)各自单独成组。
+    feed_groups: dict[tuple[int, str], list[dict]] = {}
     for row in all_reward_rows:
         if row["record_id"] in used_reward_ids:
             continue
+        if row["scene"] == "reward_video":
+            events.append({
+                "event_key": f"rwd-{row['record_id']}",
+                "report_date": row["_report_date"],
+                "user_id": row["user_id"],
+                "ad_type": "reward_video",
+                "feed_scene": row.get("feed_scene"),
+                "app_env": row.get("app_env"),
+                "our_code_id": row.get("our_code_id"),
+                "created_at": row["created_at"],
+                "hour": _cn_hour(row["created_at"]) if by_hour else None,
+                "has_impression": False,
+                "impressions": 0,
+                "ecpm": row["ecpm"],
+                "revenue_yuan": 0.0,
+                "adn": None,
+                "slot_id": None,
+                "has_reward": True,
+                "status": row["status"],
+                "expected_coin": int(row["expected_coin"]),
+                "actual_coin": int(row["actual_coin"]),
+                "matched": bool(row["matched"]),
+                "reward_detail": _reward_detail(row),
+                "sub_rewards": [],
+                "sub_count": 1,
+            })
+        else:
+            # 聚合单位 = 一次完整比价/领券流程:优先用 trace_id(比价带 comparisonTraceId、领券带 sessionTraceId,
+            # 整个流程不变;即使中途点广告致浮层关闭重弹、ad_session_id 变了,trace_id 仍不变 → 全流程聚成一行)。
+            # 无 trace_id(历史领券未上报 / 旧数据)回退整场 ad_session_id;再无则 record_id 各自成组、不误并。
+            grp_key = row.get("trace_id") or row.get("ad_session_id") or f"_rid-{row['record_id']}"
+            feed_groups.setdefault((row["user_id"], grp_key), []).append(row)
+
+    # 信息流分组 → 「一次比价 / 一次领券」父事件(收益恒 0:收益只算展示侧,避免与展示行重复计)。
+    for (uid, grp_key), group in feed_groups.items():
+        group.sort(key=lambda r: (r["created_at"], r["record_id"]))
+        rep = group[-1]  # 代表条(最新一条):时间/场景/应用/代码位取它
+        expected_sum = sum(int(g["expected_coin"]) for g in group)
+        actual_sum = sum(int(g["actual_coin"]) for g in group)
+        # 父行 eCPM:组内各条 eCPM(分)均值(展示用,各条不同);无有效值则取代表条
+        ecpm_fens = [rewards.parse_ecpm_fen(g["ecpm"]) for g in group if g.get("ecpm")]
+        avg_ecpm = str(round(sum(ecpm_fens) / len(ecpm_fens))) if ecpm_fens else rep.get("ecpm")
+        # 主表逐行显示用:这次发奖广告的预估收益之和(发奖侧 eCPM 折算,钳顶同展示侧)。只放进
+        # row_revenue_yuan 给主表逐行展示,不进 revenue_yuan/合计/趋势——避免与展示侧 total 重复计。
+        row_revenue = round(sum(
+            min(rewards.parse_ecpm_yuan(g["ecpm"]), rewards.AD_ECPM_MAX_FEN / 100.0) / 1000.0
+            for g in group if g.get("ecpm")
+        ), 6)
         events.append({
-            "event_key": f"rwd-{row['record_id']}",
-            "report_date": row["_report_date"],
-            "user_id": row["user_id"],
-            "ad_type": _event_ad_type(row),
-            "feed_scene": row.get("feed_scene"),
-            "app_env": row.get("app_env"),
-            "our_code_id": row.get("our_code_id"),
-            "created_at": row["created_at"],
-            "hour": _cn_hour(row["created_at"]) if by_hour else None,
+            "event_key": f"feedgrp-{uid}-{grp_key}",
+            "report_date": rep["_report_date"],
+            "user_id": uid,
+            "ad_type": "draw",  # 业务已全切 Draw 信息流,聚合行统一 draw
+            "feed_scene": rep.get("feed_scene"),
+            "app_env": rep.get("app_env"),
+            "our_code_id": rep.get("our_code_id"),
+            "created_at": rep["created_at"],
+            "hour": _cn_hour(rep["created_at"]) if by_hour else None,
             "has_impression": False,
             "impressions": 0,
-            "ecpm": row["ecpm"],
+            "ecpm": avg_ecpm,
             "revenue_yuan": 0.0,
+            "row_revenue_yuan": row_revenue,
             "adn": None,
             "slot_id": None,
             "has_reward": True,
-            "status": row["status"],
-            "expected_coin": int(row["expected_coin"]),
-            "actual_coin": int(row["actual_coin"]),
-            "matched": bool(row["matched"]),
-            "reward_detail": _reward_detail(row),
+            "status": rep["status"],  # 代表状态(逐条见展开)
+            "expected_coin": expected_sum,
+            "actual_coin": actual_sum,
+            "matched": all(bool(g["matched"]) for g in group),
+            "reward_detail": None,
+            "sub_rewards": [_reward_detail(g) for g in group],
+            "sub_count": len(group),
         })
 
     # 「场景」作为全局筛选(与 user_id/ad_type 一致):同时作用于明细、合计与 daily/hourly 趋势。
@@ -331,9 +390,20 @@ def ad_revenue_report(
     is_today = date_from == date_to == rewards.cn_today().isoformat()
     dau = admin_stats.today_dau(db) if is_today else None
 
+    # 主表「逐行」= 单次广告行为(2026-07 按「一次比价/领券放一块」聚合):激励视频 = 一次观看一行(展示+发奖
+    # 按 ad_session_id 合并);一次比价 / 一次领券 = 该次整场多条广告按 ad_session_id 聚成一行(展开看逐条)。
+    # 信息流(draw/feed)的逐条展示(ad_ecpm,impressionId 各自独立、与整场发奖无公共键)不再单独占行
+    # ——其展示数 / eCPM / 预估收益已计入上面的全量统计(total_*、daily / hourly、type_stats、穿山甲对照),
+    # 只是主表不逐条铺开;逐条明细在父行展开里看(sub_rewards)。合计 / 趋势 / 分类大盘均基于全量 events,
+    # 不受此过滤影响;total / 分页只作用于主表行。
+    main_rows = [
+        e for e in events
+        if not (e["ad_type"] in ("draw", "feed") and e["has_impression"] and not e["has_reward"])
+    ]
+
     return {
-        "total": len(events),
-        "truncated": len(events) > offset + limit,
+        "total": len(main_rows),
+        "truncated": len(main_rows) > offset + limit,
         "total_impressions": total_impressions,
         "total_revenue_yuan": total_revenue_yuan,
         # 穿山甲后台收益合计(元):预估 revenue + 收益Api;非全量视图(带 user/类型/场景过滤)或无数据为 None。
@@ -347,5 +417,5 @@ def ad_revenue_report(
         "hourly": hourly,
         "type_stats": type_stats,
         "dau": dau,
-        "items": events[offset:offset + limit],
+        "items": main_rows[offset:offset + limit],
     }

app/admin/repositories/queries.py

@@ -806,6 +806,12 @@ def get_user_overview(db: Session, user_id: int) -> dict | None:
     }
 
 
+def _as_utc_naive(value: datetime) -> datetime:
+    """窗口入参 → UTC naive(= _as_utc 去时区),与库里按 naive UTC 存取的 created_at 同口径比较。
+    历史遗留:_window_conds 一直引用本函数却未定义(自定义区间会 NameError),此处补上。"""
+    return _as_utc(value).replace(tzinfo=None)
+
+
 def _window_conds(col, date_from: datetime | None, date_to: datetime | None) -> list:
     """把 [date_from, date_to] 转成对 col(created_at)的过滤条件;都为 None = 全量(注册至今)。"""
     conds = []
@@ -895,6 +901,13 @@ def user_reward_stats(
     }
 
 
+def _cn_wall_to_utc(dt: datetime) -> datetime:
+    """coin_transaction 存的是北京 wall-clock(naive,见 wallet.grant_coins「存北京 wall-clock」),转成 UTC naive,
+    与广告表(func.now() UTC)统一 —— 让本函数按同一绝对时刻排序、且前端 apiTime(把无时区时间当 UTC 再 +8 展示)
+    口径一致;否则签到会比实际多显示 8 小时(北京时间又被 +8)。"""
+    return dt.replace(tzinfo=rewards.CN_TZ).astimezone(timezone.utc).replace(tzinfo=None)
+
+
 def user_coin_records(
     db: Session,
     user_id: int,
@@ -915,6 +928,9 @@ def user_coin_records(
     offset = max(cursor or 0, 0)
     fetch = offset + limit + 1
     rows: list[dict] = []
+    # coin_transaction 存北京 wall-clock(其余表存 UTC);签到窗口边界 +8h 对齐北京,过滤/计数才不偏移 8 小时
+    signin_from = date_from + timedelta(hours=8) if date_from is not None else None
+    signin_to = date_to + timedelta(hours=8) if date_to is not None else None
 
     for rec in db.execute(
         select(AdRewardRecord)
@@ -958,7 +974,7 @@ def user_coin_records(
         .where(
             CoinTransaction.user_id == user_id,
             CoinTransaction.biz_type == "signin",
-            *_window_conds(CoinTransaction.created_at, date_from, date_to),
+            *_window_conds(CoinTransaction.created_at, signin_from, signin_to),
         )
         .order_by(CoinTransaction.created_at.desc())
         .limit(fetch)
@@ -966,7 +982,8 @@ def user_coin_records(
         rows.append({
             "source": "signin",
             "source_label": "签到",
-            "created_at": rec.created_at,
+            # 北京 wall-clock → UTC,与广告记录统一(前端 apiTime 会 +8 回北京展示,不然签到会多 8 小时)
+            "created_at": _cn_wall_to_utc(rec.created_at),
             "ecpm": None,
             "coin": rec.amount,
         })
@@ -992,7 +1009,7 @@ def user_coin_records(
         + _count(
             CoinTransaction, CoinTransaction.user_id == user_id,
             CoinTransaction.biz_type == "signin",
-            *_window_conds(CoinTransaction.created_at, date_from, date_to),
+            *_window_conds(CoinTransaction.created_at, signin_from, signin_to),
         )
     )
     return rows[offset:offset + limit], (offset + limit if has_more else None), total

app/admin/schemas/ad_revenue.py

@@ -94,6 +94,11 @@ class AdRevenueRow(BaseModel):
     impressions: int = Field(..., description="本行展示条数:有展示=1 / 纯发奖=0(供日汇总、趋势图复用)")
     ecpm: str | None = Field(None, description="eCPM 原始值(分/千次);展示行取展示值,纯发奖行取发奖采用值")
     revenue_yuan: float = Field(..., description="本次展示预估收益(元)= eCPM元 ÷ 1000;纯发奖行=0")
+    row_revenue_yuan: float | None = Field(
+        None,
+        description="主表逐行展示用的预估收益(元):一次比价/领券聚合行=该次发奖广告 eCPM 折算之和;"
+        "其它行为空(前端回退取 revenue_yuan)。不进合计/趋势,避免与展示侧重复计",
+    )
     adn: str | None = Field(None, description="实际填充 ADN 子渠道(pangle/gdt…);纯发奖行为空")
     slot_id: str | None = Field(None, description="底层 mediation rit(非我们配置的广告位 ID);纯发奖行为空")
     # ── 发奖侧 ──
@@ -106,6 +111,15 @@ class AdRevenueRow(BaseModel):
         None,
         description="发奖复算明细(eCPM/因子1/份数/LT/因子2/应发/实发/一致);点行展开下钻用,纯展示为空",
     )
+    sub_rewards: list[AdRevenueRecord] = Field(
+        default_factory=list,
+        description="一次比价/领券聚合行的组内逐条发奖明细(同一整场 ad_session_id 的多条广告);"
+        "点行展开渲染多行。激励视频/纯展示行为空(单条看 reward_detail)",
+    )
+    sub_count: int = Field(
+        1,
+        description="本行聚合的发奖条数:一次比价/领券=该次广告条数(≥1);激励视频/纯展示=1",
+    )
 
 
 class AdRevenueReportOut(BaseModel):

app/admin/schemas/user.py

@@ -17,6 +17,7 @@ class AdminUserListItem(BaseModel):
     status: str
     debug_trace_enabled: bool = False
     wechat_openid: str | None = None
+    wechat_nickname: str | None = None
     created_at: datetime
     last_login_at: datetime
 

deploy/pangle-revenue.md

@@ -0,0 +1,67 @@
+# 穿山甲 GroMore 收益拉取 定时任务 — 运维手册
+
+> 对象:维护「每天拉穿山甲后台收益入库」这套定时任务的同事。
+> 🔒 服务器登录信息见**私密交接清单**,不入库。
+
+## 它是什么
+admin「广告收益报表」里的「穿山甲后台收益(T+1)」读的是**本地表 `ad_pangle_daily_revenue` 的快照,不是实时查穿山甲**。穿山甲只通过 GroMore 数据 API 给数、且 **T+1**(次日约 10:00 出昨天的数),所以每天得拉一次入库,报表才会往前走。
+
+- 每天 10:30 跑一轮 `scripts/sync_pangle_revenue.py`,默认 `--days 3` 回补近 3 天。
+- 维度 = 日期 × 应用(site_id)× 广告位(ad_unit_id);指标 = `revenue`(预估)+ `api_revenue`(结算口径)。
+- **幂等 upsert**:同一(日期×应用×代码位)重跑只覆盖、不重复,故回补 / 重跑 / catch-up 都安全。
+- 穿山甲无用户/设备维度 → 只能落「汇总/趋势级」,报表带 user_id 过滤时这块收益置空(显示「-」)。
+
+## 文件
+| 项 | 路径 |
+|---|---|
+| 脚本入口 | `scripts/sync_pangle_revenue.py` |
+| 拉取 / 签名 | `app/integrations/pangle_report.py`(签名=参数字典序拼接+secure_key 后 MD5) |
+| 入库表 | `ad_pangle_daily_revenue`(读写在 `app/repositories/ad_pangle_revenue.py`) |
+| 凭证 | `.env` 的 `PANGLE_REPORT_USER_ID` / `PANGLE_REPORT_ROLE_ID` / `PANGLE_REPORT_SECURITY_KEY` |
+| 应用映射 | `.env` 的 `PANGLE_REPORT_SITE_ID_PROD`(5830519)/ `PANGLE_REPORT_SITE_ID_TEST`(5832303) |
+| systemd 单元 | `deploy/pangle-revenue.{service,timer}` |
+
+## 上线前置(只做一次)
+1. **填凭证**:后台「接入中心 → GroMore-API」领 user_id / role_id / Security Key(`secure_key`,**≠ 发奖 m-key**),填进线上 `.env` 的 `PANGLE_REPORT_*`。三项填齐脚本才工作,缺任一 → no-op 退出。
+2. **子账号要授权**:线上若用子账号(role_id ≠ user_id),需主账号给它授「查看全部数据」,否则接口报 **118**(无权限)。本人自查自己(user_id=role_id)无此问题。
+3. 凭证泄露:后台「重置 key 值」即可,改完同步线上 `.env` 重跑。
+
+## 部署(Linux 服务器,需 root)
+```bash
+sudo cp deploy/pangle-revenue.{service,timer} /etc/systemd/system/
+sudo systemctl daemon-reload && sudo systemctl enable --now pangle-revenue.timer
+systemctl list-timers pangle-revenue.timer   # 确认下次触发时间(应是次日 10:30)
+```
+
+## 怎么看健康 / 手动跑一次
+```bash
+sudo systemctl start pangle-revenue.service     # 立即手动跑一轮(不等 10:30)
+journalctl -u pangle-revenue -n 30 --no-pager   # 看日志:拉取区间 / 入库行数 / 新增更新 / 预估收益合计
+```
+成功日志形如:`✅ 完成:接口 N 行 → 入库 M 行(跳过 x),新增 a / 更新 b;预估收益合计 ¥19.42`。
+> 看不到收益、提示 `PANGLE_REPORT_* 未配置`→ 回「上线前置」补 `.env`;报 118 → 子账号没授「查看全部数据」。
+
+## 本机 Windows 开发(无 systemd)
+直接手动跑:
+```
+.venv\Scripts\python -m scripts.sync_pangle_revenue            # 拉昨天
+.venv\Scripts\python -m scripts.sync_pangle_revenue --days 3   # 回补近 3 天
+.venv\Scripts\python -m scripts.sync_pangle_revenue --date 2026-06-27          # 指定单天
+.venv\Scripts\python -m scripts.sync_pangle_revenue --start 2026-06-01 --end 2026-06-27   # 区间回补
+```
+
+## 脚本参数
+- 无参:拉**昨天**(北京时间)。timer 用的是 `--days 3`。
+- `--days N`:从昨天起往前回补 N 天(含昨天)。
+- `--date YYYY-MM-DD`:指定单天。
+- `--start / --end`:指定闭区间(跨度 ≤ 31 天,接口上限 1 个月,超了报 114)。
+
+## 注意事项
+- **触发时间**:`OnCalendar=*-*-* 10:30:00`。穿山甲 ~10:00 出数,故别早于 10:00 跑(会拉到空/不全)。
+- **catch-up**:`Persistent=true` 补跑错过的那一轮;叠加 `--days 3`,漏一两天重新触发即自愈。
+- **今天 / 今天以前要分开查**:脚本默认只拉昨天及更早,不混查今天(接口约束),无需关心。
+- **join key 是 `ad_unit_id`(我们配的 104xxx)不是 `code_id`**:`code_id` 是底层各 ADN 代码位,对不上口径;`ad_unit_id='-1'` 是未归因桶。改维度时务必注意(详见脚本头注释)。
+- **`api_revenue` 很稀疏**:测试应用 ADN 没配 Reporting → 全 0,仅 prod 个别位有;`revenue`(预估)才是稳的主力。
+- **DB 无关**:sqlite / postgres 均可(upsert 逐行 select-then-write,不像美团 ETL 需要 PG)。
+- **别和别的触发方式双跑**:本 systemd timer 与「手动 cron / 进程内任务」二选一,虽幂等不会重复入库,纯属多余。
+- **改脚本 / 改部署**:走 git + PR,由有 root 的人部署。

deploy/pangle-revenue.service

@@ -0,0 +1,38 @@
+# 每天拉穿山甲 GroMore T+1 天级收益入库 —— 单轮跑,由 pangle-revenue.timer 每天 10:30 触发。
+# 落 ad_pangle_daily_revenue 表,供 admin 广告收益报表的「穿山甲后台收益(T+1)」区块。
+#
+# 仅用于 Linux 服务器;本机 Windows 开发无 systemd,直接手动跑脚本即可:
+#   .venv\Scripts\python -m scripts.sync_pangle_revenue            # 拉昨天(北京时间)
+#   .venv\Scripts\python -m scripts.sync_pangle_revenue --days 3   # 回补近 3 天
+#
+# 部署(服务器):
+#   sudo cp deploy/pangle-revenue.{service,timer} /etc/systemd/system/
+#   sudo systemctl daemon-reload && sudo systemctl enable --now pangle-revenue.timer
+#   # 手动跑一次验证: sudo systemctl start pangle-revenue.service && journalctl -u pangle-revenue -n 30
+#
+# 前置:.env 配好 PANGLE_REPORT_USER_ID / PANGLE_REPORT_ROLE_ID / PANGLE_REPORT_SECURITY_KEY
+#       (后台「接入中心 → GroMore-API」领;子账号需主账号授「查看全部数据」否则接口 118)。
+#       未配齐这三项 → 脚本自动 no-op 退出,免动 timer。
+[Unit]
+Description=Sync Pangle GroMore daily revenue (T+1, one-shot, driven by timer)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=oneshot
+User=root
+WorkingDirectory=/opt/shaguabijia-app-server
+Environment="PATH=/opt/shaguabijia-app-server/.venv/bin:/usr/bin:/bin"
+EnvironmentFile=/opt/shaguabijia-app-server/.env
+# 默认拉昨天;--days 3 回补近 3 天(幂等 upsert,应对偶发漏跑 + 穿山甲对历史数据订正,重跑无害)。
+ExecStart=/opt/shaguabijia-app-server/.venv/bin/python -m scripts.sync_pangle_revenue --days 3
+SyslogIdentifier=pangle-revenue
+# 仅几个 HTTP 请求 + 小批量入库,通常数秒;给 10min 硬超时防穿山甲接口卡死。
+TimeoutStartSec=600
+
+# 与主服务 shaguabijia-app-server.service 同款加固。
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ReadWritePaths=/opt/shaguabijia-app-server
+ProtectHome=true

deploy/pangle-revenue.timer

@@ -0,0 +1,14 @@
+# 每天 10:30 触发一次穿山甲 GroMore T+1 收益拉取入库(Linux 服务器用)。
+# 见 pangle-revenue.service 顶部注释的部署步骤。
+[Unit]
+Description=Run Pangle GroMore daily revenue sync at 10:30
+
+[Timer]
+# 穿山甲 T+1、次日约 10:00 出数;10:30 触发留 30min 余量。要错开整点扎堆可微调到 10:35。
+OnCalendar=*-*-* 10:30:00
+# 服务器宕机/重启后,补跑错过的那一轮(而不是干等次日);叠加 --days 3 回补,漏一两天能自愈。
+Persistent=true
+AccuracySec=1min
+
+[Install]
+WantedBy=timers.target