Merge branch 'main' of https://gitea.shaguabijia.com/WonderableAI/shaguabijia-app-server into feat/analytics-success-rate

## 改动
`grant_feed_reward` 按 `feed_scene` 落不同 `biz_type`/`remark`,让收益明细里比价等候期看的广告与领券时看的广告文案分开:

- `comparison` → `feed_ad_reward_comparison`(比价奖励)
- `coupon` → `feed_ad_reward_coupon`(领券奖励)
- 其余(welfare / 空 / 旧端不传)→ 维持通用 `feed_ad_reward`(信息流广告奖励)

客户端按 `biz_type` 直显固定文案(见 android 侧 `CoinHistoryViewModel.coinTitle`),`remark` 仅作后台留痕/兜底。

## 附:验收脚手架
`scripts/seed_coinhistory_labels_test.py`(dev-only):往测试号 `11111111111` 塞每种 bizType 各一条金币流水(`ref_id` 前缀 `TESTDOC`),一屏核对收益明细全部新文案;`--clean` 按前缀精确清理,不污染真实数据。

## 联动
客户端配套改动:`shaguabijia-app-android` 同名分支 `7-6ljh`。

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: no_gen_mu <liujianhishen@gmail.com>
Reviewed-on: #124
Co-authored-by: liujiahui <liujiahui@wonderable.ai>
Co-committed-by: liujiahui <liujiahui@wonderable.ai>

alembic/versions/11c44afbea58_analytics_selfstat_tables.py

@@ -0,0 +1,72 @@
+"""analytics_selfstat tables
+
+Revision ID: 11c44afbea58
+Revises: admin_user_plain_password
+Create Date: 2026-07-08 16:32:49.351817
+
+"""
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+
+from alembic import op
+
+
+# revision identifiers, used by Alembic.
+revision: str = '11c44afbea58'
+down_revision: str | Sequence[str] | None = 'admin_user_plain_password'
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        'analytics_selfstat',
+        sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
+        sa.Column('device_id', sa.String(length=64), nullable=False),
+        sa.Column('epoch_id', sa.String(length=64), nullable=False),
+        sa.Column('app_ver', sa.String(length=32), nullable=True),
+        sa.Column('oem', sa.String(length=32), nullable=True),
+        sa.Column('os', sa.String(length=32), nullable=True),
+        sa.Column('batches_attempted', sa.BigInteger(), nullable=False, server_default='0'),
+        sa.Column('batches_ok', sa.BigInteger(), nullable=False, server_default='0'),
+        sa.Column('batches_fail', sa.BigInteger(), nullable=False, server_default='0'),
+        sa.Column('retries', sa.BigInteger(), nullable=False, server_default='0'),
+        sa.Column('queue_depth', sa.Integer(), nullable=False, server_default='0'),
+        sa.Column('sent_at', sa.BigInteger(), nullable=True),
+        sa.Column('created_at', sa.DateTime(timezone=True),
+                  server_default=sa.text('(CURRENT_TIMESTAMP)'), nullable=False),
+        sa.PrimaryKeyConstraint('id'),
+    )
+    with op.batch_alter_table('analytics_selfstat', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_analytics_selfstat_created_at'), ['created_at'], unique=False)
+        batch_op.create_index(batch_op.f('ix_analytics_selfstat_device_id'), ['device_id'], unique=False)
+        batch_op.create_index(batch_op.f('ix_analytics_selfstat_epoch_id'), ['epoch_id'], unique=False)
+
+    op.create_table(
+        'analytics_selfstat_event',
+        sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
+        sa.Column('snapshot_id', sa.Integer(), nullable=False),
+        sa.Column('event', sa.String(length=64), nullable=False),
+        sa.Column('attempted', sa.BigInteger(), nullable=False, server_default='0'),
+        sa.Column('drop_capture', sa.BigInteger(), nullable=False, server_default='0'),
+        sa.Column('delivered', sa.BigInteger(), nullable=False, server_default='0'),
+        sa.Column('drop_undelivered', sa.BigInteger(), nullable=False, server_default='0'),
+        sa.ForeignKeyConstraint(['snapshot_id'], ['analytics_selfstat.id'], ),
+        sa.PrimaryKeyConstraint('id'),
+    )
+    with op.batch_alter_table('analytics_selfstat_event', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_analytics_selfstat_event_event'), ['event'], unique=False)
+        batch_op.create_index(batch_op.f('ix_analytics_selfstat_event_snapshot_id'), ['snapshot_id'], unique=False)
+
+
+def downgrade() -> None:
+    with op.batch_alter_table('analytics_selfstat_event', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_analytics_selfstat_event_snapshot_id'))
+        batch_op.drop_index(batch_op.f('ix_analytics_selfstat_event_event'))
+    op.drop_table('analytics_selfstat_event')
+    with op.batch_alter_table('analytics_selfstat', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_analytics_selfstat_epoch_id'))
+        batch_op.drop_index(batch_op.f('ix_analytics_selfstat_device_id'))
+        batch_op.drop_index(batch_op.f('ix_analytics_selfstat_created_at'))
+    op.drop_table('analytics_selfstat')

app/admin/main.py

@@ -26,6 +26,7 @@ from app.admin.routers.cps import router as cps_router
 from app.admin.routers.dashboard import router as dashboard_router
 from app.admin.routers.device_liveness import router as device_liveness_router
 from app.admin.routers.ops_stat_config import router as ops_stat_config_router
+from app.admin.routers.analytics_health import router as analytics_health_router
 from app.admin.routers.event_logs import router as event_logs_router
 from app.admin.routers.feedback import router as feedback_router
 from app.admin.routers.feedback_qr import router as feedback_qr_router
@@ -97,6 +98,7 @@ admin_app.include_router(withdraw_router)
 admin_app.include_router(price_report_router)
 admin_app.include_router(feedback_router)
 admin_app.include_router(event_logs_router)
+admin_app.include_router(analytics_health_router)
 admin_app.include_router(feedback_qr_router)
 admin_app.include_router(admins_router)
 admin_app.include_router(roles_router)

app/admin/repositories/analytics_health.py

@@ -0,0 +1,146 @@
+"""埋点健康度聚合(埋点成功率 / 上报成功率)。
+
+只存原始累计快照,查询时在 Python 侧差分聚合(admin 低频、量级小,跨 PG/SQLite 无方言坑;
+与 cps.py / coupon_data.py 同款约定)。差分按 (device_id, epoch_id, event) 分区、created_at
+升序,相邻做差、负值夹 0;每增量按其快照 created_at 归入北京天桶。
+"""
+from __future__ import annotations
+
+from collections import defaultdict
+from datetime import UTC, datetime
+
+from sqlalchemy import func, select
+from sqlalchemy.orm import Session
+
+from app.core import rewards
+from app.models.analytics_selfstat import AnalyticsSelfStat as H
+from app.models.analytics_selfstat import AnalyticsSelfStatEvent as E
+
+_COUNTS = ("attempted", "drop_capture", "delivered", "drop_undelivered")
+
+
+def diff_snapshots(rows: list[dict]) -> list[dict]:
+    """累计快照行 → 每快照增量行(纯逻辑)。
+
+    rows 每行含 device_id/epoch_id/event/created_at/app_ver/oem/os + 四个累计计数。
+    返回每行含 dims + created_at + 四个增量 d_*(分区首行增量=累计值;负值夹 0)。
+    """
+    parts: dict[tuple, list[dict]] = defaultdict(list)
+    for r in rows:
+        parts[(r["device_id"], r["epoch_id"], r["event"])].append(r)
+
+    out: list[dict] = []
+    for group in parts.values():
+        group.sort(key=lambda r: (r["created_at"], r.get("id", 0)))
+        prev = {k: 0 for k in _COUNTS}
+        for r in group:
+            deltas = {f"d_{k}": max(0, int(r[k]) - prev[k]) for k in _COUNTS}
+            out.append({
+                "device_id": r["device_id"], "epoch_id": r["epoch_id"], "event": r["event"],
+                "created_at": r["created_at"], "app_ver": r["app_ver"],
+                "oem": r["oem"], "os": r["os"], **deltas,
+            })
+            prev = {k: int(r[k]) for k in _COUNTS}
+    return out
+
+
+def _cn_day(dt: datetime) -> str:
+    """created_at(UTC 口径)→ 北京日期字符串 YYYY-MM-DD。naive 当 UTC,tz-aware 直接换算。"""
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=UTC)
+    return dt.astimezone(rewards.CN_TZ).date().isoformat()
+
+
+def _rates(sums: dict) -> dict:
+    """由四个增量和派生两段率(分母 0 → None)。"""
+    persisted_denom = sums["attempted"]
+    report_denom = sums["delivered"] + sums["drop_undelivered"]
+    return {
+        **sums,
+        "track_success_rate": (
+            (sums["attempted"] - sums["drop_capture"]) / persisted_denom
+            if persisted_denom else None
+        ),
+        "report_success_rate": (
+            sums["delivered"] / report_denom if report_denom else None
+        ),
+    }
+
+
+def _sum_deltas(deltas: list[dict]) -> dict:
+    return {k: sum(d[f"d_{k}"] for d in deltas) for k in _COUNTS}
+
+
+def _fetch_rows(db: Session, date_from: datetime, date_to: datetime) -> list[dict]:
+    """取 [from, to) 区间行 + 每分区在 from 左侧的最后一条基线行(供第一条区间增量做差)。"""
+    cols = (
+        H.id, H.device_id, H.epoch_id, E.event, H.created_at,
+        H.app_ver, H.oem, H.os,
+        E.attempted, E.drop_capture, E.delivered, E.drop_undelivered,
+    )
+    in_range = db.execute(
+        select(*cols).join(E, E.snapshot_id == H.id)
+        .where(H.created_at >= date_from, H.created_at < date_to)
+    ).mappings().all()
+
+    # 注:基线子查询无下界扫 from 左侧全量(spec §7 已接受的取舍;量级变大再上物化 rollup)。
+    # 用 max(id) 而非 max(created_at) 选"最新一条":id 严格单调,避免 SQLite 秒级时间戳撞车时选歧义。
+    sub = (
+        select(H.device_id, H.epoch_id, E.event, func.max(H.id).label("max_id"))
+        .join(E, E.snapshot_id == H.id)
+        .where(H.created_at < date_from)
+        .group_by(H.device_id, H.epoch_id, E.event)
+        .subquery()
+    )
+    baseline = db.execute(
+        select(*cols).join(E, E.snapshot_id == H.id).join(
+            sub, sub.c.max_id == H.id
+        )
+    ).mappings().all()
+
+    return [dict(r) for r in list(baseline) + list(in_range)]
+
+
+def _in_range_deltas(db: Session, date_from: datetime, date_to: datetime) -> list[dict]:
+    """差分后只保留 created_at ∈ [from, to) 的增量(基线行被差分用后丢弃)。
+
+    Python 侧过滤需对齐 tz 口径:SQLite 返回 naive UTC,PG 返回 aware UTC。
+    统一转成 naive UTC 再比较,兼容两种后端。
+    """
+    def _to_naive_utc(dt: datetime) -> datetime:
+        if dt.tzinfo is not None:
+            return dt.astimezone(UTC).replace(tzinfo=None)
+        return dt
+
+    from_naive = _to_naive_utc(date_from)
+    to_naive = _to_naive_utc(date_to)
+    deltas = diff_snapshots(_fetch_rows(db, date_from, date_to))
+    return [d for d in deltas if from_naive <= _to_naive_utc(d["created_at"]) < to_naive]
+
+
+def overview(db: Session, date_from: datetime, date_to: datetime) -> dict:
+    deltas = _in_range_deltas(db, date_from, date_to)
+    return _rates(_sum_deltas(deltas))
+
+
+def trend(db: Session, date_from: datetime, date_to: datetime) -> list[dict]:
+    deltas = _in_range_deltas(db, date_from, date_to)
+    by_day: dict[str, list[dict]] = defaultdict(list)
+    for d in deltas:
+        by_day[_cn_day(d["created_at"])].append(d)
+    return [
+        {"day": day, **_rates(_sum_deltas(items))}
+        for day, items in sorted(by_day.items())
+    ]
+
+
+def breakdown(db: Session, date_from: datetime, date_to: datetime, dim: str) -> list[dict]:
+    if dim not in ("event", "app_ver", "oem"):
+        raise ValueError(f"invalid dim: {dim!r}")
+    deltas = _in_range_deltas(db, date_from, date_to)
+    by_key: dict[str, list[dict]] = defaultdict(list)
+    for d in deltas:
+        by_key[d.get(dim) or "(unknown)"].append(d)
+    rows = [{"key": key, **_rates(_sum_deltas(items))} for key, items in by_key.items()]
+    rows.sort(key=lambda r: (r["report_success_rate"] is None, r["report_success_rate"] or 0.0))
+    return rows

app/admin/routers/analytics_health.py

@@ -0,0 +1,49 @@
+"""admin 埋点健康度:埋点成功率 / 上报成功率 总览 + 趋势 + 下钻(只读)。"""
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, Query
+
+from app.admin.deps import AdminDb, get_current_admin
+from app.admin.repositories import analytics_health as repo
+from app.admin.schemas.analytics_health import (
+    HealthBreakdownRow,
+    HealthMetrics,
+    HealthTrendPoint,
+)
+
+router = APIRouter(
+    prefix="/admin/api/analytics-health",
+    tags=["admin-analytics-health"],
+    dependencies=[Depends(get_current_admin)],
+)
+
+
+@router.get("/overview", response_model=HealthMetrics, summary="两段成功率总览")
+def overview(
+    db: AdminDb,
+    date_from: Annotated[datetime, Query()],
+    date_to: Annotated[datetime, Query()],
+) -> HealthMetrics:
+    return HealthMetrics(**repo.overview(db, date_from, date_to))
+
+
+@router.get("/trend", response_model=list[HealthTrendPoint], summary="按北京天趋势")
+def trend(
+    db: AdminDb,
+    date_from: Annotated[datetime, Query()],
+    date_to: Annotated[datetime, Query()],
+) -> list[HealthTrendPoint]:
+    return [HealthTrendPoint(**p) for p in repo.trend(db, date_from, date_to)]
+
+
+@router.get("/breakdown", response_model=list[HealthBreakdownRow], summary="按维度下钻")
+def breakdown(
+    db: AdminDb,
+    date_from: Annotated[datetime, Query()],
+    date_to: Annotated[datetime, Query()],
+    dim: Annotated[str, Query(pattern="^(event|app_ver|oem)$")] = "event",
+) -> list[HealthBreakdownRow]:
+    return [HealthBreakdownRow(**r) for r in repo.breakdown(db, date_from, date_to, dim)]

app/admin/schemas/analytics_health.py

@@ -0,0 +1,21 @@
+"""埋点健康度 admin 响应 schema。"""
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class HealthMetrics(BaseModel):
+    attempted: int
+    drop_capture: int
+    delivered: int
+    drop_undelivered: int
+    track_success_rate: float | None
+    report_success_rate: float | None
+
+
+class HealthTrendPoint(HealthMetrics):
+    day: str
+
+
+class HealthBreakdownRow(HealthMetrics):
+    key: str

app/api/v1/analytics.py

@@ -6,13 +6,18 @@ POST /api/v1/analytics/events — 批量接收新手引导(及后续)埋点,appe
 """
 from __future__ import annotations
 
-from fastapi import APIRouter, Request
+import logging
+
+from fastapi import APIRouter, HTTPException, Request
 
 from app.api.deps import DbSession
 from app.repositories import analytics as analytics_repo
+from app.repositories import analytics_selfstat as selfstat_repo
 from app.schemas.analytics import AnalyticsBatchIn, AnalyticsIngestOut
+from app.schemas.analytics_selfstat import SelfStatBatchIn, SelfStatIngestOut
 
 router = APIRouter(prefix="/api/v1/analytics", tags=["analytics"])
+logger = logging.getLogger("shagua.analytics")
 
 
 def _client_ip(request: Request) -> str:
@@ -29,3 +34,13 @@ def ingest_events(
 ) -> AnalyticsIngestOut:
     n = analytics_repo.record_batch(db, batch, client_ip=_client_ip(request))
     return AnalyticsIngestOut(received=n)
+
+
+@router.post("/selfstat", response_model=SelfStatIngestOut, summary="上报自报计数快照")
+def ingest_selfstat(batch: SelfStatBatchIn, db: DbSession) -> SelfStatIngestOut:
+    try:
+        snap_id = selfstat_repo.record_selfstat(db, batch)
+    except Exception:  # noqa: BLE001 — 计数链路要稳,落库失败不裸奔 500,记日志回明确错误
+        logger.exception("selfstat ingest failed device=%s epoch=%s", batch.device_id, batch.epoch_id)
+        raise HTTPException(status_code=503, detail="selfstat ingest failed") from None
+    return SelfStatIngestOut(snapshot_id=snap_id)

app/models/__init__.py

@@ -7,6 +7,10 @@ from app.models.ad_watch_log import AdWatchLog  # noqa: F401
 from app.models.admin import AdminAuditLog, AdminUser  # noqa: F401
 from app.models.admin_role import AdminRole  # noqa: F401
 from app.models.analytics_event import AnalyticsEvent  # noqa: F401
+from app.models.analytics_selfstat import (  # noqa: F401
+    AnalyticsSelfStat,
+    AnalyticsSelfStatEvent,
+)
 from app.models.app_config import AppConfig  # noqa: F401
 from app.models.comparison import ComparisonRecord  # noqa: F401
 from app.models.cps_activity import CpsActivity  # noqa: F401

app/models/analytics_selfstat.py

@@ -0,0 +1,59 @@
+"""埋点/上报成功率自报计数快照表(append-only)。
+
+客户端周期上报「自 epoch 起算的累计计数」;服务端只存原始快照,查询时在 Python 侧差分聚合
+(见 app/admin/repositories/analytics_health.py)。与既有 analytics_event 表完全独立。
+
+- analytics_selfstat        :一快照一行(快照头 + 设备维度 + 设备级诊断量)
+- analytics_selfstat_event  :一 event 一行(四类累计计数),外键指向快照头
+"""
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import BigInteger, DateTime, ForeignKey, Integer, String, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db.base import Base
+
+
+class AnalyticsSelfStat(Base):
+    __tablename__ = "analytics_selfstat"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    device_id: Mapped[str] = mapped_column(String(64), index=True, nullable=False)
+    epoch_id: Mapped[str] = mapped_column(String(64), index=True, nullable=False)
+    # 设备维度(每设备固定,下钻用)
+    app_ver: Mapped[str | None] = mapped_column(String(32), nullable=True)
+    oem: Mapped[str | None] = mapped_column(String(32), nullable=True)
+    os: Mapped[str | None] = mapped_column(String(32), nullable=True)
+    # 设备级诊断量(累计;queue_depth 是瞬时 gauge)
+    batches_attempted: Mapped[int] = mapped_column(BigInteger, nullable=False, default=0)
+    batches_ok: Mapped[int] = mapped_column(BigInteger, nullable=False, default=0)
+    batches_fail: Mapped[int] = mapped_column(BigInteger, nullable=False, default=0)
+    retries: Mapped[int] = mapped_column(BigInteger, nullable=False, default=0)
+    queue_depth: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    sent_at: Mapped[int | None] = mapped_column(BigInteger, nullable=True)  # 端上报时刻 epoch ms
+    # 服务端接收时间(权威,用于时间分桶与分区排序)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), index=True, nullable=False
+    )
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return f"<AnalyticsSelfStat id={self.id} device={self.device_id} epoch={self.epoch_id}>"
+
+
+class AnalyticsSelfStatEvent(Base):
+    __tablename__ = "analytics_selfstat_event"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    snapshot_id: Mapped[int] = mapped_column(
+        ForeignKey("analytics_selfstat.id"), index=True, nullable=False
+    )
+    event: Mapped[str] = mapped_column(String(64), index=True, nullable=False)
+    attempted: Mapped[int] = mapped_column(BigInteger, nullable=False, default=0)
+    drop_capture: Mapped[int] = mapped_column(BigInteger, nullable=False, default=0)
+    delivered: Mapped[int] = mapped_column(BigInteger, nullable=False, default=0)
+    drop_undelivered: Mapped[int] = mapped_column(BigInteger, nullable=False, default=0)
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return f"<AnalyticsSelfStatEvent snap={self.snapshot_id} event={self.event}>"

app/repositories/ad_feed_reward.py

@@ -176,10 +176,19 @@ def grant_feed_reward(
         )
         return _commit_record(db, rec, client_event_id)
 
+    # 按点位场景拆流水文案(2026-07):比价等候期看的广告 vs 领券时看的广告,在收益明细里分开显示。
+    # feed_scene=comparison→比价奖励 / coupon→领券奖励;其它(welfare/空/旧端不带)维持通用「信息流广告奖励」。
+    # 客户端按此 biz_type 直显固定文案(见 CoinHistoryViewModel.coinTitle),故 remark 只作后台留痕/兜底。
+    if feed_scene == "comparison":
+        reward_biz, reward_remark = "feed_ad_reward_comparison", "比价奖励"
+    elif feed_scene == "coupon":
+        reward_biz, reward_remark = "feed_ad_reward_coupon", "领券奖励"
+    else:
+        reward_biz, reward_remark = "feed_ad_reward", "信息流广告奖励"
     crud_wallet.grant_coins(
         db, user_id, coin,
-        biz_type="feed_ad_reward", ref_id=client_event_id,
-        remark="信息流广告奖励",
+        biz_type=reward_biz, ref_id=client_event_id,
+        remark=reward_remark,
     )
     rec = AdFeedRewardRecord(
         client_event_id=client_event_id,

app/repositories/analytics_selfstat.py

@@ -0,0 +1,38 @@
+"""自报计数快照落库。一次事务:插 1 条快照头 + N 条 event 行,返回快照 id。"""
+from __future__ import annotations
+
+from sqlalchemy.orm import Session
+
+from app.models.analytics_selfstat import AnalyticsSelfStat, AnalyticsSelfStatEvent
+from app.schemas.analytics_selfstat import SelfStatBatchIn
+
+
+def record_selfstat(db: Session, batch: SelfStatBatchIn) -> int:
+    snap = AnalyticsSelfStat(
+        device_id=batch.device_id,
+        epoch_id=batch.epoch_id,
+        app_ver=batch.app_ver,
+        oem=batch.oem,
+        os=batch.os,
+        batches_attempted=batch.batches_attempted,
+        batches_ok=batch.batches_ok,
+        batches_fail=batch.batches_fail,
+        retries=batch.retries,
+        queue_depth=batch.queue_depth,
+        sent_at=batch.sent_at,
+    )
+    db.add(snap)
+    db.flush()  # 拿到 snap.id
+    db.add_all([
+        AnalyticsSelfStatEvent(
+            snapshot_id=snap.id,
+            event=e.event,
+            attempted=e.attempted,
+            drop_capture=e.drop_capture,
+            delivered=e.delivered,
+            drop_undelivered=e.drop_undelivered,
+        )
+        for e in batch.events
+    ])
+    db.commit()
+    return snap.id

app/schemas/analytics_selfstat.py

@@ -0,0 +1,34 @@
+"""自报计数上报 schema。字段名对齐客户端 payload(snake_case),累计值语义。"""
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class SelfStatEventIn(BaseModel):
+    event: str = Field(max_length=64)
+    attempted: int = 0
+    drop_capture: int = 0
+    delivered: int = 0
+    drop_undelivered: int = 0
+
+
+class SelfStatBatchIn(BaseModel):
+    device_id: str = Field(max_length=64)
+    epoch_id: str = Field(max_length=64)
+    sent_at: int | None = None
+    app_ver: str | None = Field(default=None, max_length=32)
+    oem: str | None = Field(default=None, max_length=32)
+    os: str | None = Field(default=None, max_length=32)
+    batches_attempted: int = 0
+    batches_ok: int = 0
+    batches_fail: int = 0
+    retries: int = 0
+    queue_depth: int = 0
+    # 允许空列表:某次快照只上报设备级计数(batches_*/retries/queue_depth)、无 event 细分时也合法
+    # (与 AnalyticsBatchIn 的 min_length=1 有意不同——那是行为事件、必须至少一条)。
+    events: list[SelfStatEventIn] = Field(default_factory=list, max_length=200)
+
+
+class SelfStatIngestOut(BaseModel):
+    ok: bool = True
+    snapshot_id: int

scripts/seed_coinhistory_labels_test.py

@@ -0,0 +1,166 @@
+"""收益明细「金币记录」文案验证脚手架(2026-07 文案改版验收用)。
+
+问题:客户端按 bizType 显示固定文案(路线B,强制覆盖后端 remark),但账号若没有对应
+bizType 的流水,收益明细页就空着,无从验证。本脚本往指定测试用户塞每种 bizType 各一条
+流水,让你在手机收益明细页一屏核对全部新文案;验收完 --clean 一键删除,不污染数据。
+
+⚠️ 仅 dev 库用(APP_ENV=dev 时才允许 --seed/--clean)。所有测试流水 ref_id 前缀 TESTDOC,
+按前缀精确清理,不会误删真实流水。
+
+用法(pricebot env 直调,见项目 CLAUDE.md):
+  D:/miniconda/envs/pricebot/python.exe scripts/seed_coinhistory_labels_test.py --show
+  D:/miniconda/envs/pricebot/python.exe scripts/seed_coinhistory_labels_test.py --seed
+  D:/miniconda/envs/pricebot/python.exe scripts/seed_coinhistory_labels_test.py --clean
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+
+from app.core.config import settings
+from app.core.rewards import CN_TZ
+from datetime import datetime
+
+from app.db.session import SessionLocal
+from app.models.user import User
+from app.models.wallet import CoinAccount, CoinTransaction
+
+TEST_PHONE = "11111111111"
+REF_PREFIX = "TESTDOC"  # 所有本脚本造的流水都带这个 ref_id 前缀,便于精确清理
+
+# 每条 = (bizType, 故意写错/留空的 remark, 金币数)。
+# remark 故意填「错的」→ 若客户端仍显示新文案 = 证明路线B强制覆盖生效(无视后端 remark)。
+# task_ 一条留空 remark → 走客户端兜底映射。顺序即手机上从新到旧的展示顺序(后塞的在最上)。
+CASES: list[tuple[str, str, int]] = [
+    ("signin", "每日签到 第99天(旧文案,应被覆盖)", 220),
+    ("signin_boost", "签到膨胀 第99天", 3000),
+    ("reward_video", "看视频奖励金币(旧文案,应被覆盖)", 200),
+    ("feed_ad_reward_comparison", "", 50),   # 后端新拆:比价场景 → 比价奖励
+    ("feed_ad_reward_coupon", "", 50),       # 后端新拆:领券场景 → 领券奖励
+    ("feed_ad_reward", "信息流广告奖励(welfare/旧数据兜底)", 50),
+    ("price_report_reward", "上报更低价审核通过(旧文案,应被覆盖)", 1000),
+    ("feedback_reward", "意见反馈被采纳(旧文案,应被覆盖)", 10000),
+    ("task_enable_notification", "", 750),   # remark 留空 → 客户端「打开消息提醒奖励」
+    # 下两条现实中不会进金币记录(invite 发现金进邀请钱包 / compare_milestone 后端死代码不发钱),
+    # 仅用于验证「杀掉好友比价奖励 + 兜底改任务奖励」:两条都应显示「任务奖励」(remark 被强制无视)。
+    ("invite", "好友比价奖励(旧文案,应被杀→任务奖励)", 200),
+    ("compare_milestone", "", 120),
+]
+
+
+def _client_coin_title(biz_type: str, remark: str | None) -> str:
+    """复刻 CoinHistoryViewModel.coinTitle 的最新逻辑(路线B),用于 --show 预览。
+
+    ⚠️ 必须与客户端保持一致;客户端改了这里也要同步,否则预览会骗人。
+    """
+    fixed = {
+        "exchange_out": "金币兑换现金",
+        "signin": "每日签到奖励",
+        "signin_boost": "签到膨胀奖励",
+        "reward_video": "看视频赚金币",
+        "ad_reward": "看视频赚金币",
+        "feed_ad_reward_comparison": "比价奖励",
+        "feed_ad_reward_coupon": "领券奖励",
+        "feed_ad_reward": "信息流广告奖励",
+        "price_report_reward": "爆料奖励",
+        "feedback_reward": "反馈奖励",
+        "invite": "任务奖励",  # 杀掉"好友比价奖励",归兜底
+    }
+    if biz_type in fixed:
+        return fixed[biz_type]
+    if remark:
+        return remark
+    if biz_type == "task_enable_notification":
+        return "打开消息提醒奖励"
+    return "任务奖励"
+
+
+def _get_user(db) -> User:
+    u = db.query(User).filter(User.phone == TEST_PHONE).first()
+    if not u:
+        print(f"✗ 库里没有测试号 {TEST_PHONE} —— 先在手机上用这个号登录一次再跑本脚本。")
+        sys.exit(1)
+    return u
+
+
+def cmd_show() -> None:
+    """只打印:每种 bizType 经客户端映射后会显示成什么(不写库)。"""
+    print("bizType 造流水后,收益明细页预期显示的文案:\n")
+    print(f"  {'bizType':32} {'后端remark(故意填的)':32} → 手机显示")
+    print("  " + "-" * 90)
+    for biz, remark, _coin in CASES:
+        shown = _client_coin_title(biz, remark or None)
+        rk = (remark or "(空)")
+        print(f"  {biz:32} {rk:32} → {shown}")
+    print("\n注:remark 列是故意填的『旧/错』文案;'手机显示'若为新文案 = 强制覆盖生效。")
+    print("invite / compare_milestone 已从客户端映射删除:invite 有 remark 故显示原样,")
+    print("compare_milestone remark 空故落兜底『奖励』—— 两者都不再有专属新文案(符合『去掉』)。")
+
+
+def cmd_seed() -> None:
+    if settings.APP_ENV != "dev":
+        print(f"✗ 拒绝:APP_ENV={settings.APP_ENV},本脚本只在 dev 库造测试数据。")
+        sys.exit(1)
+    db = SessionLocal()
+    u = _get_user(db)
+    acc = db.query(CoinAccount).filter(CoinAccount.user_id == u.id).first()
+    if acc is None:
+        acc = CoinAccount(user_id=u.id, coin_balance=0, cash_balance_cents=0)
+        db.add(acc)
+        db.flush()
+    now = datetime.now(CN_TZ).replace(tzinfo=None)
+    made = 0
+    for i, (biz, remark, coin) in enumerate(CASES):
+        ref = f"{REF_PREFIX}:{biz}:{i}"
+        exists = db.query(CoinTransaction).filter(CoinTransaction.ref_id == ref).first()
+        if exists:
+            continue
+        acc.coin_balance += coin
+        db.add(CoinTransaction(
+            user_id=u.id, amount=coin, balance_after=acc.coin_balance,
+            biz_type=biz, ref_id=ref, remark=remark or None, created_at=now,
+        ))
+        made += 1
+    db.commit()
+    print(f"✓ 已给 user_id={u.id}({TEST_PHONE})造 {made} 条测试流水,当前金币余额 {acc.coin_balance}。")
+    print("  → 打开手机 App「收益明细 / 金币记录」下拉刷新,逐条核对文案。")
+    print("  → 验收完跑 --clean 删除这些测试流水。")
+
+
+def cmd_clean() -> None:
+    if settings.APP_ENV != "dev":
+        print(f"✗ 拒绝:APP_ENV={settings.APP_ENV}。")
+        sys.exit(1)
+    db = SessionLocal()
+    u = _get_user(db)
+    rows = db.query(CoinTransaction).filter(
+        CoinTransaction.user_id == u.id,
+        CoinTransaction.ref_id.like(f"{REF_PREFIX}:%"),
+    ).all()
+    total = sum(r.amount for r in rows)
+    for r in rows:
+        db.delete(r)
+    acc = db.query(CoinAccount).filter(CoinAccount.user_id == u.id).first()
+    if acc is not None:
+        acc.coin_balance -= total  # 把造流水时加的余额扣回,还原
+    db.commit()
+    print(f"✓ 已删除 {len(rows)} 条 TESTDOC 测试流水,余额回扣 {total},当前 {acc.coin_balance if acc else 0}。")
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="收益明细金币文案验证脚手架")
+    g = ap.add_mutually_exclusive_group(required=True)
+    g.add_argument("--show", action="store_true", help="只打印每种 bizType 的预期显示文案,不写库")
+    g.add_argument("--seed", action="store_true", help="往测试号造每种 bizType 各一条流水")
+    g.add_argument("--clean", action="store_true", help="删除本脚本造的所有测试流水")
+    args = ap.parse_args()
+    if args.show:
+        cmd_show()
+    elif args.seed:
+        cmd_seed()
+    elif args.clean:
+        cmd_clean()
+
+
+if __name__ == "__main__":
+    main()

tests/test_analytics_health.py

@@ -0,0 +1,160 @@
+"""埋点健康度聚合:纯差分函数 + admin 端点。"""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from app.admin.repositories.analytics_health import _cn_day, _rates, diff_snapshots
+
+
+def _row(device, epoch, event, ts, **cum) -> dict:
+    base = {"attempted": 0, "drop_capture": 0, "delivered": 0, "drop_undelivered": 0}
+    base.update(cum)
+    return {
+        "device_id": device, "epoch_id": epoch, "event": event,
+        "created_at": datetime(2026, 7, 1, ts, 0, tzinfo=timezone.utc),
+        "app_ver": "0.2.12(62)", "oem": "ColorOS", "os": "Android 14",
+        **base,
+    }
+
+
+def test_diff_first_row_is_full_cumulative() -> None:
+    rows = [_row("d", "e", "video_play", 1, attempted=100, delivered=90)]
+    out = diff_snapshots(rows)
+    assert len(out) == 1
+    assert out[0]["d_attempted"] == 100
+    assert out[0]["d_delivered"] == 90
+
+
+def test_diff_consecutive_delta() -> None:
+    rows = [
+        _row("d", "e", "video_play", 1, attempted=100, delivered=90),
+        _row("d", "e", "video_play", 2, attempted=150, delivered=140),
+    ]
+    out = sorted(diff_snapshots(rows), key=lambda r: r["created_at"])
+    assert out[1]["d_attempted"] == 50
+    assert out[1]["d_delivered"] == 50
+
+
+def test_diff_epoch_reset_new_partition() -> None:
+    rows = [
+        _row("d", "e1", "video_play", 1, attempted=100),
+        _row("d", "e2", "video_play", 2, attempted=5),
+    ]
+    out = {(r["epoch_id"]): r["d_attempted"] for r in diff_snapshots(rows)}
+    assert out["e1"] == 100
+    assert out["e2"] == 5
+
+
+def test_diff_clamps_negative_on_reorder() -> None:
+    rows = [
+        _row("d", "e", "video_play", 1, attempted=100),
+        _row("d", "e", "video_play", 2, attempted=80),
+    ]
+    out = sorted(diff_snapshots(rows), key=lambda r: r["created_at"])
+    assert out[1]["d_attempted"] == 0
+
+
+def test_rates_computes_both_formulas() -> None:
+    out = _rates({"attempted": 150, "drop_capture": 0, "delivered": 140, "drop_undelivered": 10})
+    assert out["track_success_rate"] == 1.0
+    assert out["report_success_rate"] == 140 / 150
+
+
+def test_rates_zero_denominator_yields_none() -> None:
+    out = _rates({"attempted": 0, "drop_capture": 0, "delivered": 0, "drop_undelivered": 0})
+    assert out["track_success_rate"] is None
+    assert out["report_success_rate"] is None
+
+
+def test_cn_day_beijing_boundary() -> None:
+    # UTC 15:59 → 北京 23:59 同日;UTC 16:00 → 北京 次日 00:00
+    assert _cn_day(datetime(2026, 7, 1, 15, 59, tzinfo=timezone.utc)) == "2026-07-01"
+    assert _cn_day(datetime(2026, 7, 1, 16, 0, tzinfo=timezone.utc)) == "2026-07-02"
+
+
+def test_diff_same_timestamp_ordered_by_id() -> None:
+    ts = datetime(2026, 7, 1, 1, 0, tzinfo=timezone.utc)
+    # 相同 created_at,乱序传入(id=2 在前);应按 id 排序 → id=1(cum100) 在前
+    rows = [
+        {"id": 2, "device_id": "d", "epoch_id": "e", "event": "vp", "created_at": ts,
+         "app_ver": "v", "oem": "o", "os": "s",
+         "attempted": 150, "drop_capture": 0, "delivered": 0, "drop_undelivered": 0},
+        {"id": 1, "device_id": "d", "epoch_id": "e", "event": "vp", "created_at": ts,
+         "app_ver": "v", "oem": "o", "os": "s",
+         "attempted": 100, "drop_capture": 0, "delivered": 0, "drop_undelivered": 0},
+    ]
+    out = diff_snapshots(rows)
+    assert out[0]["d_attempted"] == 100  # id=1 sorts first → its cumulative
+    assert out[1]["d_attempted"] == 50   # id=2 second → 150-100
+
+
+import pytest
+from fastapi.testclient import TestClient
+
+from app.admin.main import admin_app
+from app.admin.repositories import admin_user as admin_repo
+from app.db.session import SessionLocal
+
+
+@pytest.fixture()
+def admin_client() -> TestClient:
+    return TestClient(admin_app)
+
+
+@pytest.fixture()
+def admin_token() -> str:
+    db = SessionLocal()
+    try:
+        if admin_repo.get_by_username(db, "health_admin") is None:
+            admin_repo.create_admin(db, username="health_admin", password="pw", role="super_admin")
+    finally:
+        db.close()
+    c = TestClient(admin_app)
+    r = c.post("/admin/api/auth/login", json={"username": "health_admin", "password": "pw"})
+    return r.json()["access_token"]
+
+
+def _auth(t: str) -> dict:
+    return {"Authorization": f"Bearer {t}"}
+
+
+def _seed_two_snapshots(client: TestClient) -> None:
+    for attempted, delivered in ((100, 90), (150, 140)):
+        client.post("/api/v1/analytics/selfstat", json={
+            "device_id": "d-health", "epoch_id": "e-health",
+            "app_ver": "0.2.12(62)", "oem": "ColorOS", "os": "Android 14",
+            "events": [{"event": "video_play", "attempted": attempted,
+                        "drop_capture": 0, "delivered": delivered, "drop_undelivered": 0}],
+        })
+
+
+def test_health_overview_requires_auth(admin_client: TestClient) -> None:
+    r = admin_client.get("/admin/api/analytics-health/overview",
+                         params={"date_from": "2026-07-01T00:00:00Z", "date_to": "2030-01-01T00:00:00Z"})
+    assert r.status_code == 401
+
+
+def test_health_overview(client: TestClient, admin_client: TestClient, admin_token: str) -> None:
+    _seed_two_snapshots(client)  # 播种走公开 app(ingest 端点在 app,不在 admin_app)
+    r = admin_client.get(
+        "/admin/api/analytics-health/overview",
+        params={"date_from": "2026-07-01T00:00:00Z", "date_to": "2030-01-01T00:00:00Z"},
+        headers=_auth(admin_token),
+    )
+    assert r.status_code == 200, r.text
+    data = r.json()
+    # 两快照累计 100→150,差分后 attempted 总 150(首快照 100 + 增量 50)
+    assert data["attempted"] == 150
+    assert data["track_success_rate"] == 1.0
+
+
+def test_health_breakdown(client: TestClient, admin_client: TestClient, admin_token: str) -> None:
+    _seed_two_snapshots(client)  # 播种走公开 app
+    r = admin_client.get(
+        "/admin/api/analytics-health/breakdown",
+        params={"date_from": "2026-07-01T00:00:00Z", "date_to": "2030-01-01T00:00:00Z", "dim": "event"},
+        headers=_auth(admin_token),
+    )
+    assert r.status_code == 200, r.text
+    rows = r.json()
+    assert any(row["key"] == "video_play" for row in rows)

tests/test_analytics_selfstat.py

@@ -0,0 +1,43 @@
+"""自报计数上报端点测试。"""
+from __future__ import annotations
+
+from fastapi.testclient import TestClient
+
+
+def _payload(**over) -> dict:
+    base = {
+        "device_id": "dev-1", "epoch_id": "ep-1", "sent_at": 1700000000000,
+        "app_ver": "0.2.12(62)", "oem": "ColorOS", "os": "Android 14",
+        "batches_attempted": 10, "batches_ok": 9, "batches_fail": 1,
+        "retries": 1, "queue_depth": 2,
+        "events": [
+            {"event": "video_play", "attempted": 100, "drop_capture": 1,
+             "delivered": 95, "drop_undelivered": 2},
+        ],
+    }
+    base.update(over)
+    return base
+
+
+def test_selfstat_ingest_ok(client: TestClient) -> None:
+    r = client.post("/api/v1/analytics/selfstat", json=_payload())
+    assert r.status_code == 200, r.text
+    body = r.json()
+    assert body["ok"] is True
+    assert isinstance(body["snapshot_id"], int)
+
+
+def test_selfstat_ingest_empty_events(client: TestClient) -> None:
+    r = client.post("/api/v1/analytics/selfstat", json=_payload(events=[]))
+    assert r.status_code == 200, r.text
+    assert r.json()["ok"] is True
+
+
+def test_selfstat_ingest_db_error_returns_503(client: TestClient, monkeypatch) -> None:
+    """落库异常时端点回 503(计数链路稳定性守卫),不裸奔 500。"""
+    def _boom(*_args, **_kwargs):
+        raise RuntimeError("db gone")
+
+    monkeypatch.setattr("app.repositories.analytics_selfstat.record_selfstat", _boom)
+    r = client.post("/api/v1/analytics/selfstat", json=_payload())
+    assert r.status_code == 503, r.text