feat(invite): 发奖口径改为「比价并下单」+ DEV dev-reset 出厂重置接口

- 发奖触发点从「比价成功上报」(compare/record)挪到「实际下单上报」
  (order/report):被邀请人完成比价并真实下单才给邀请人发 2 元邀请奖励金
  (冰 2026-07-02 拍板);仅完成比价不再发奖。幂等闸 compare_reward_granted 不变。
- 新增 POST /api/v1/invite/dev-reset:把固定测试号(TEST_ACCOUNT_PHONE)打回
  出厂态(清邀请关系/奖励金/savings/流水 + 刷 created_at 骗过 72h 新用户闸),
  便于反复当新用户测发奖。双门控:生产 404 + 只认配置的测试号,无鉴权。
- 测试:8 例改为下单驱动 + 新增 2 例覆盖 dev-reset(可反复邀请 / 开关关闭 400)。

.env.example

@@ -58,6 +58,13 @@ MT_CPS_DEFAULT_SID=sgbjia
 # 线上国内服务器留空(=直连)。留空且本机直连失败时 /feed、/coupons、/top-sales 会返回空。
 MT_CPS_PROXY=
 
+# ===== 京东联盟 CPS =====
+# 京东联盟/京东宙斯开放平台创建应用后填写。AUTH_KEY 是工具商授权 key,自有应用可留空。
+JD_UNION_APP_KEY=
+JD_UNION_APP_SECRET=
+JD_UNION_SITE_ID=
+JD_UNION_AUTH_KEY=
+
 # ===== Pricebot 上游 (领券/比价业务透传目标) =====
 # 客户端调本服务的 /api/v1/coupon/step 等,我们透传到 pricebot-backend。
 # 本地开发用 localhost:8000。生产部署改成内网地址(如 http://pricebot.internal:8000)。

.gitignore

@@ -23,14 +23,17 @@ dist/
 *.db-journal
 *.db-shm
 *.db-wal
-# data/ 整体不入库(运行时数据/上传文件/大二进制)。例外:邀请落地页 dl.html——
-# 它既是生产落地页又是本地测试资产,纳入 git 便于同事一致测试
+# data/ 整体不入库(运行时数据/上传文件/大二进制)。例外:邀请落地页 dl.html 及其
+# 引用的静态插画(coupon-page-bg.png 底图 + sb-brand.png logo)——既是生产落地页资产
+# 又是本地测试资产,纳入 git 便于同事一致测试、且随部署进生产 /media(否则线上 404→落地页毛坯)。
 # (见 docs/邀请功能-实现原理与本地测试.md)。其余(avatars/ / *.apk / app.db 等)仍忽略。
 data/*
 !data/media/
 data/media/*
 !data/media/dl.html
 !data/media/taobao_landing.jpg
+!data/media/coupon-page-bg.png
+!data/media/sb-brand.png
 
 secrets/*
 !secrets/.gitkeep

alembic/versions/coupon_session_origin_package.py

@@ -0,0 +1,32 @@
+"""coupon_session 加 origin_package 列(发起来源 App 包名 → admin「发起平台」)
+
+null=App 内(傻瓜比价首页)发起,非空=从美团/淘宝/京东弹券发起。与 trace_url 同理单独成迁移,
+已建表环境靠它补列、全新环境顺序应用,不重复加列。
+
+Revision ID: coupon_session_origin_package
+Revises: coupon_session_trace_url
+Create Date: 2026-06-30 00:00:00.000000
+
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "coupon_session_origin_package"
+down_revision: str | Sequence[str] | None = "coupon_session_trace_url"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    with op.batch_alter_table("coupon_session", schema=None) as batch_op:
+        batch_op.add_column(sa.Column("origin_package", sa.String(length=64), nullable=True))
+
+
+def downgrade() -> None:
+    with op.batch_alter_table("coupon_session", schema=None) as batch_op:
+        batch_op.drop_column("origin_package")

alembic/versions/coupon_session_table.py

@@ -0,0 +1,81 @@
+"""coupon session table(领券任务全程流水 → admin「领券数据」看板数据源)
+
+一次领券一行(trace_id 唯一):客户端 POST /api/v1/coupon/session 两段上报 —— 发起建行
+(status=started)、收尾(completed/failed/abandoned)按 trace_id 更新同一行。记全程耗时
+elapsed_ms + 各平台耗时 platform_elapsed + 机型/ROM,供 admin 算发起/完成数、耗时分位、机型维度。
+
+Revision ID: coupon_session_table
+Revises: feedback_submit_env
+Create Date: 2026-06-30 00:00:00.000000
+
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "coupon_session_table"
+down_revision: str | Sequence[str] | None = "feedback_submit_env"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+# PG 用 JSONB,SQLite(本地/测试)退化为通用 JSON(同 model 的 _JSON variant)。
+_JSON = sa.JSON().with_variant(postgresql.JSONB(), "postgresql")
+
+
+def upgrade() -> None:
+    op.create_table(
+        "coupon_session",
+        sa.Column("id", sa.Integer(), autoincrement=True, nullable=False),
+        sa.Column("trace_id", sa.String(length=64), nullable=False),
+        sa.Column("device_id", sa.String(length=64), nullable=False),
+        sa.Column("user_id", sa.Integer(), nullable=True),
+        sa.Column("status", sa.String(length=16), nullable=False),
+        sa.Column("app_env", sa.String(length=16), nullable=True),
+        sa.Column("platforms", _JSON, nullable=True),
+        sa.Column("device_model", sa.String(length=128), nullable=True),
+        sa.Column("rom", sa.String(length=64), nullable=True),
+        sa.Column("started_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("started_date", sa.Date(), nullable=False),
+        sa.Column("finished_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("elapsed_ms", sa.Integer(), nullable=True),
+        sa.Column("platform_elapsed", _JSON, nullable=True),
+        sa.Column("claimed_count", sa.Integer(), nullable=True),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("(CURRENT_TIMESTAMP)"),
+            nullable=False,
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("(CURRENT_TIMESTAMP)"),
+            nullable=False,
+        ),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint("trace_id", name="uq_coupon_session_trace"),
+    )
+    with op.batch_alter_table("coupon_session", schema=None) as batch_op:
+        batch_op.create_index(
+            batch_op.f("ix_coupon_session_user_id"), ["user_id"], unique=False
+        )
+        batch_op.create_index(
+            batch_op.f("ix_coupon_session_app_env"), ["app_env"], unique=False
+        )
+        # admin 主聚合/筛选:按上海自然日 + 环境。
+        batch_op.create_index(
+            "ix_coupon_session_date_env", ["started_date", "app_env"], unique=False
+        )
+
+
+def downgrade() -> None:
+    with op.batch_alter_table("coupon_session", schema=None) as batch_op:
+        batch_op.drop_index("ix_coupon_session_date_env")
+        batch_op.drop_index(batch_op.f("ix_coupon_session_app_env"))
+        batch_op.drop_index(batch_op.f("ix_coupon_session_user_id"))
+    op.drop_table("coupon_session")

alembic/versions/coupon_session_trace_url.py

@@ -0,0 +1,32 @@
+"""coupon_session 加 trace_url 列(pricebot done 帧公网调试链接)
+
+建表迁移 coupon_session_table 落地后才追加本列,故单独成一个迁移:已建表的环境(本地/已 upgrade 过)
+靠它补列,全新环境则「建表(无 trace_url)→ 本迁移加列」,两条路一致、不重复加列。
+
+Revision ID: coupon_session_trace_url
+Revises: coupon_session_table
+Create Date: 2026-06-30 00:00:00.000000
+
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "coupon_session_trace_url"
+down_revision: str | Sequence[str] | None = "coupon_session_table"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    with op.batch_alter_table("coupon_session", schema=None) as batch_op:
+        batch_op.add_column(sa.Column("trace_url", sa.String(length=512), nullable=True))
+
+
+def downgrade() -> None:
+    with op.batch_alter_table("coupon_session", schema=None) as batch_op:
+        batch_op.drop_column("trace_url")

alembic/versions/jd_cps_order_fields.py

@@ -0,0 +1,56 @@
+"""add jd cps order fields
+
+Revision ID: jd_cps_order_fields
+Revises: 7db22acee504
+Create Date: 2026-06-28 20:30:00.000000
+"""
+from __future__ import annotations
+
+from alembic import op
+import sqlalchemy as sa
+
+
+revision = "jd_cps_order_fields"
+down_revision = "7db22acee504"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    with op.batch_alter_table("cps_order") as batch_op:
+        batch_op.add_column(
+            sa.Column("platform", sa.String(length=20), nullable=False, server_default="meituan")
+        )
+        batch_op.add_column(sa.Column("external_order_id", sa.String(length=128), nullable=True))
+        batch_op.add_column(sa.Column("external_row_id", sa.String(length=128), nullable=True))
+        batch_op.add_column(sa.Column("estimated_commission_cents", sa.Integer(), nullable=True))
+        batch_op.add_column(sa.Column("actual_commission_cents", sa.Integer(), nullable=True))
+        batch_op.add_column(sa.Column("jd_valid_code", sa.String(length=16), nullable=True))
+        batch_op.add_column(sa.Column("settle_month", sa.String(length=16), nullable=True))
+        batch_op.add_column(sa.Column("site_id", sa.String(length=128), nullable=True))
+        batch_op.add_column(sa.Column("position_id", sa.String(length=128), nullable=True))
+        batch_op.add_column(sa.Column("pid", sa.String(length=128), nullable=True))
+        batch_op.add_column(sa.Column("sub_union_id", sa.String(length=128), nullable=True))
+        batch_op.create_index("ix_cps_order_platform", ["platform"])
+        batch_op.create_index("ix_cps_order_external_order_id", ["external_order_id"])
+        batch_op.create_index("ix_cps_order_external_row_id", ["external_row_id"])
+        batch_op.create_index("ix_cps_order_jd_valid_code", ["jd_valid_code"])
+
+
+def downgrade() -> None:
+    with op.batch_alter_table("cps_order") as batch_op:
+        batch_op.drop_index("ix_cps_order_jd_valid_code")
+        batch_op.drop_index("ix_cps_order_external_row_id")
+        batch_op.drop_index("ix_cps_order_external_order_id")
+        batch_op.drop_index("ix_cps_order_platform")
+        batch_op.drop_column("sub_union_id")
+        batch_op.drop_column("pid")
+        batch_op.drop_column("position_id")
+        batch_op.drop_column("site_id")
+        batch_op.drop_column("settle_month")
+        batch_op.drop_column("jd_valid_code")
+        batch_op.drop_column("actual_commission_cents")
+        batch_op.drop_column("estimated_commission_cents")
+        batch_op.drop_column("external_row_id")
+        batch_op.drop_column("external_order_id")
+        batch_op.drop_column("platform")

app/admin/main.py

@@ -21,6 +21,7 @@ from app.admin.routers.audit import router as audit_router
 from app.admin.routers.auth import router as auth_router
 from app.admin.routers.comparison import router as comparison_router
 from app.admin.routers.config import router as config_router
+from app.admin.routers.coupon_data import router as coupon_data_router
 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
@@ -101,6 +102,7 @@ admin_app.include_router(audit_router)
 admin_app.include_router(config_router)
 admin_app.include_router(comparison_router)
 admin_app.include_router(cps_router)
+admin_app.include_router(coupon_data_router)
 admin_app.include_router(ad_audit_router)
 admin_app.include_router(ad_config_router)
 admin_app.include_router(ad_revenue_router)

app/admin/repositories/coupon_data.py

@@ -0,0 +1,225 @@
+"""admin「领券数据」看板聚合:发起/完成数、耗时均值与分位、按天/小时趋势、逐条明细。
+
+数据源 coupon_session(一次领券一行,客户端 /api/v1/coupon/session 两段上报)。量级不大,全量拉
+区间数据后 Python 聚合(分位 SQLite 无 percentile,统一 Python 算,PG 上也一致)。
+- 发起数 = 区间内全部 session(含 started/completed/failed/abandoned),= 流失统计的基数。
+- 完成数 / 耗时均值 / 分位 = 仅 status==completed 子集(成功跑完才有可比的"领券耗时")。
+- summary/daily/hourly/total 在全量上算,不受分页;items 为排序后当前页。
+"""
+from __future__ import annotations
+
+from datetime import UTC, date as _date, datetime
+
+from sqlalchemy import func, or_, select
+from sqlalchemy.orm import Session
+
+from app.core import rewards
+from app.models.coupon_state import CouponSession
+from app.models.user import User
+
+
+def _cn_hour(dt: datetime) -> int:
+    """started_at(UTC 口径)→ 北京时间小时(0–23)。naive 当 UTC(sqlite),tz-aware 直接换算(pg)。"""
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=UTC)
+    return dt.astimezone(rewards.CN_TZ).hour
+
+
+def _percentile(sorted_vals: list[int], q: float) -> int | None:
+    """线性插值分位(q=0..100,numpy 默认法)。sorted_vals 须已升序;空返回 None。"""
+    if not sorted_vals:
+        return None
+    if len(sorted_vals) == 1:
+        return sorted_vals[0]
+    idx = (len(sorted_vals) - 1) * q / 100.0
+    lo = int(idx)
+    hi = min(lo + 1, len(sorted_vals) - 1)
+    frac = idx - lo
+    return round(sorted_vals[lo] * (1 - frac) + sorted_vals[hi] * frac)
+
+
+def _avg(vals: list[int]) -> int | None:
+    return round(sum(vals) / len(vals)) if vals else None
+
+
+def _session_to_row(r, phone: str | None = None, nickname: str | None = None) -> dict:
+    """CouponSession ORM → 明细行 dict(主表「领券数据」与「用户全部领券」抽屉共用)。"""
+    return {
+        "id": r.id,
+        "trace_id": r.trace_id,
+        "user_id": r.user_id,
+        "user_phone": phone,
+        "user_nickname": nickname,
+        "status": r.status,
+        "platforms": r.platforms,
+        "origin_package": r.origin_package,
+        "elapsed_ms": r.elapsed_ms,
+        "platform_elapsed": r.platform_elapsed,
+        "device_model": r.device_model,
+        "rom": r.rom,
+        "app_env": r.app_env,
+        "started_at": r.started_at,
+        "claimed_count": r.claimed_count,
+        "trace_url": r.trace_url,
+    }
+
+
+def _empty_result() -> dict:
+    return {
+        "summary": {
+            "started_count": 0, "completed_count": 0, "avg_elapsed_ms": None,
+            "p5_ms": None, "p50_ms": None, "p95_ms": None, "p99_ms": None,
+        },
+        "daily": [],
+        "hourly": [],
+        "total": 0,
+        "items": [],
+    }
+
+
+def coupon_data_report(
+    db: Session,
+    *,
+    date_from: str,
+    date_to: str,
+    user: str | None = None,
+    app_env: str | None = None,
+    granularity: str = "day",
+    limit: int = 500,
+    offset: int = 0,
+    sort: str = "time",
+) -> dict:
+    """日期区间(北京自然日 started_date,闭区间)领券数据:汇总卡 + 趋势 + 逐条明细。
+
+    - user:手机号/昵称模糊搜(匹配不到任何用户 → 空结果)。
+    - app_env:prod/dev 精确;None=全部。
+    - sort:time=发起时刻倒序(默认) / elapsed=全程耗时倒序(None 末尾)。
+    """
+    by_hour = granularity == "hour"
+    d_from = _date.fromisoformat(date_from)
+    d_to = _date.fromisoformat(date_to)
+
+    # user 模糊 → 先定位匹配用户 id;匹配不到直接空结果(不全表扫)。
+    user_ids: set[int] | None = None
+    if user:
+        like = f"%{user}%"
+        user_ids = set(db.execute(
+            select(User.id).where(or_(User.phone.like(like), User.nickname.like(like)))
+        ).scalars().all())
+        if not user_ids:
+            return _empty_result()
+
+    stmt = select(CouponSession).where(
+        CouponSession.started_date >= d_from,
+        CouponSession.started_date <= d_to,
+    )
+    if app_env is not None:
+        stmt = stmt.where(CouponSession.app_env == app_env)
+    if user_ids is not None:
+        stmt = stmt.where(CouponSession.user_id.in_(user_ids))
+    rows = list(db.execute(stmt).scalars())
+
+    # ── 汇总卡 ──
+    completed_elapsed = sorted(
+        r.elapsed_ms for r in rows if r.status == "completed" and r.elapsed_ms is not None
+    )
+    summary = {
+        "started_count": len(rows),
+        "completed_count": sum(1 for r in rows if r.status == "completed"),
+        "avg_elapsed_ms": _avg(completed_elapsed),
+        "p5_ms": _percentile(completed_elapsed, 5),
+        "p50_ms": _percentile(completed_elapsed, 50),
+        "p95_ms": _percentile(completed_elapsed, 95),
+        "p99_ms": _percentile(completed_elapsed, 99),
+    }
+
+    # ── 按天趋势(柱=发起/完成数,线=平均耗时)──
+    daily_map: dict[str, dict] = {}
+    for r in rows:
+        d = r.started_date.isoformat()
+        b = daily_map.get(d)
+        if b is None:
+            b = {"date": d, "started_count": 0, "completed_count": 0, "_elapsed": []}
+            daily_map[d] = b
+        b["started_count"] += 1
+        if r.status == "completed":
+            b["completed_count"] += 1
+            if r.elapsed_ms is not None:
+                b["_elapsed"].append(r.elapsed_ms)
+    daily = [
+        {
+            "date": b["date"],
+            "started_count": b["started_count"],
+            "completed_count": b["completed_count"],
+            "avg_elapsed_ms": _avg(b["_elapsed"]),
+        }
+        for b in sorted(daily_map.values(), key=lambda x: x["date"])
+    ]
+
+    # ── 按小时趋势(单日 hour 粒度)──
+    hourly: list[dict] = []
+    if by_hour:
+        hour_map: dict[int, dict] = {}
+        for r in rows:
+            h = _cn_hour(r.started_at)
+            b = hour_map.get(h)
+            if b is None:
+                b = {"hour": h, "started_count": 0, "completed_count": 0, "_elapsed": []}
+                hour_map[h] = b
+            b["started_count"] += 1
+            if r.status == "completed":
+                b["completed_count"] += 1
+                if r.elapsed_ms is not None:
+                    b["_elapsed"].append(r.elapsed_ms)
+        hourly = [
+            {
+                "hour": b["hour"],
+                "started_count": b["started_count"],
+                "completed_count": b["completed_count"],
+                "avg_elapsed_ms": _avg(b["_elapsed"]),
+            }
+            for b in sorted(hour_map.values(), key=lambda x: x["hour"])
+        ]
+
+    # ── 明细:排序 + 分页 + 补用户手机号/昵称(批量,防 N+1)──
+    if sort == "elapsed":
+        rows.sort(key=lambda r: (r.elapsed_ms is None, -(r.elapsed_ms or 0)))
+    else:  # time:发起时刻倒序
+        rows.sort(key=lambda r: r.started_at, reverse=True)
+    page = rows[offset:offset + limit]
+
+    uids = {r.user_id for r in page if r.user_id is not None}
+    user_map: dict[int, tuple[str | None, str | None]] = {}
+    if uids:
+        user_map = {
+            uid: (phone, nickname)
+            for uid, phone, nickname in db.execute(
+                select(User.id, User.phone, User.nickname).where(User.id.in_(uids))
+            ).all()
+        }
+    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))
+
+    return {
+        "summary": summary,
+        "daily": daily,
+        "hourly": hourly,
+        "total": len(rows),
+        "items": items,
+    }
+
+
+def coupon_user_records(db: Session, *, user_id: int, limit: int = 100) -> dict:
+    """某用户全部领券记录(点手机号抽屉用):按发起时刻倒序、不限日期,total=该用户领券总次数。"""
+    rows = list(db.execute(
+        select(CouponSession)
+        .where(CouponSession.user_id == user_id)
+        .order_by(CouponSession.started_at.desc())
+        .limit(limit)
+    ).scalars())
+    total = db.execute(
+        select(func.count()).select_from(CouponSession).where(CouponSession.user_id == user_id)
+    ).scalar_one()
+    return {"items": [_session_to_row(r) for r in rows], "total": int(total)}

app/admin/repositories/cps.py

@@ -7,13 +7,14 @@ from __future__ import annotations
 
 from datetime import datetime, timedelta, timezone
 from decimal import Decimal, InvalidOperation
+from typing import Any
 from uuid import uuid4
 
 from sqlalchemy import desc, func, select
 from sqlalchemy.orm import Session
 
 from app.admin.repositories.queries import _as_utc, offset_paginate
-from app.integrations import meituan
+from app.integrations import jd_union, meituan
 from app.repositories import cps_link as cps_link_repo
 from app.models.cps_activity import CpsActivity
 from app.models.cps_group import CpsGroup
@@ -24,6 +25,11 @@ from app.models.cps_wx_user import CpsWxUser
 # 美团订单状态:取消(4)/风控(5)不计佣金;结算(6)为佣金真正到账
 _INVALID_STATUS = {"4", "5"}
 _SETTLED_STATUS = "6"
+_JD_INVALID_CODES = {
+    "2", "3", "4", "5", "6", "7", "8", "9", "11", "13", "14", "19", "20", "21",
+    "22", "23", "25", "26", "27", "28", "29", "30", "31", "34", "35", "36",
+}
+_JD_UNPAID_CODES = {"15"}
 
 # CPS 点击时序按北京时区分桶(运营看的是北京时间)
 _BJ_TZ = timezone(timedelta(hours=8))
@@ -47,6 +53,36 @@ def _ts_to_dt(ts: object) -> datetime | None:
     """秒级时间戳 → tz-aware UTC datetime(绝对时刻,前端按北京展示)。"""
     if not ts:
         return None
+
+
+def _jd_dt_to_utc(value: object) -> datetime | None:
+    """京东时间字符串(北京时间) → UTC aware datetime。"""
+    if value is None:
+        return None
+    s = str(value).strip()
+    if not s:
+        return None
+    for fmt in ("%Y-%m-%d %H:%M:%S", "%Y-%m-%d"):
+        try:
+            dt = datetime.strptime(s, fmt)
+            return dt.replace(tzinfo=_BJ_TZ).astimezone(timezone.utc)
+        except ValueError:
+            continue
+    return None
+
+
+def _text(value: object) -> str | None:
+    if value is None:
+        return None
+    s = str(value).strip()
+    return s or None
+
+
+def _pick(row: dict[str, Any], *keys: str) -> Any:
+    for key in keys:
+        if key in row and row[key] is not None:
+            return row[key]
+    return None
     try:
         return datetime.fromtimestamp(int(ts), tz=timezone.utc)
     except (ValueError, OSError, TypeError):
@@ -249,6 +285,80 @@ def _map_order_fields(r: dict) -> dict:
     }
 
 
+def _jd_order_key(r: dict[str, Any]) -> str | None:
+    row_id = _text(_pick(r, "id", "rowId", "orderRowId"))
+    if row_id:
+        return f"jd:{row_id}"
+    order_id = _text(_pick(r, "orderId", "parentOrderId"))
+    sku_id = _text(_pick(r, "skuId"))
+    if order_id and sku_id:
+        return f"jd:{order_id}:{sku_id}"
+    if order_id:
+        return f"jd:{order_id}"
+    return None
+
+
+def _map_jd_order_fields(r: dict[str, Any]) -> dict:
+    """京东 order.row.query 单条订单行 → CpsOrder 字段。"""
+    sku_name = _text(_pick(r, "skuName", "goodsName", "productName"))
+    if sku_name and len(sku_name) > 500:
+        sku_name = sku_name[:500]
+    valid_code = _text(_pick(r, "validCode", "valid_code"))
+    actual_fee = _yuan_to_cents(_pick(r, "actualFee", "actual_fee"))
+    estimate_fee = _yuan_to_cents(_pick(r, "estimateFee", "estimate_fee"))
+    commission = actual_fee if actual_fee not in (None, 0) else estimate_fee
+    order_time = _jd_dt_to_utc(_pick(r, "orderTime", "order_time"))
+    return {
+        "platform": "jd",
+        "external_order_id": _text(_pick(r, "orderId", "parentOrderId")),
+        "external_row_id": _text(_pick(r, "id", "rowId", "orderRowId")),
+        "sid": _text(_pick(r, "subUnionId", "sub_union_id")),
+        "act_id": None,
+        "biz_line": None,
+        "trade_type": None,
+        "pay_price_cents": _yuan_to_cents(
+            _pick(r, "actualCosPrice", "estimateCosPrice", "price")
+        ),
+        "commission_cents": commission,
+        "commission_rate": _text(_pick(r, "commissionRate", "commission_rate")),
+        "refund_price_cents": None,
+        "refund_profit_cents": None,
+        "estimated_commission_cents": estimate_fee,
+        "actual_commission_cents": actual_fee,
+        "mt_status": None,
+        "jd_valid_code": valid_code,
+        "invalid_reason": None if _is_jd_valid_code(valid_code) else f"validCode={valid_code}",
+        "product_name": sku_name,
+        "settle_month": _text(_pick(r, "payMonth", "settleMonth", "pay_month")),
+        "site_id": _text(_pick(r, "siteId", "site_id")),
+        "position_id": _text(_pick(r, "positionId", "position_id")),
+        "pid": _text(_pick(r, "pid")),
+        "sub_union_id": _text(_pick(r, "subUnionId", "sub_union_id")),
+        "pay_time": order_time,
+        "mt_update_time": _jd_dt_to_utc(_pick(r, "modifyTime", "updateTime", "modify_time"))
+        or order_time,
+        "raw": r,
+    }
+
+
+def _is_jd_valid_code(valid_code: str | None) -> bool:
+    code = str(valid_code).strip() if valid_code is not None else ""
+    return bool(code and code not in _JD_INVALID_CODES and code not in _JD_UNPAID_CODES)
+
+
+def is_jd_order_valid(order: CpsOrder) -> bool:
+    return _is_jd_valid_code(order.jd_valid_code)
+
+
+def effective_commission_cents(order: CpsOrder) -> int:
+    if order.platform == "jd":
+        if order.actual_commission_cents not in (None, 0):
+            return order.actual_commission_cents or 0
+        if order.estimated_commission_cents is not None:
+            return order.estimated_commission_cents or 0
+    return order.commission_cents or 0
+
+
 def reconcile_orders(
     db: Session, *, start_time: int, end_time: int,
     query_time_type: int = 1, sid: str | None = None, max_pages: int = 200,
@@ -274,6 +384,11 @@ def reconcile_orders(
                 continue
             fetched += 1
             fields = _map_order_fields(r)
+            fields.setdefault("platform", "meituan")
+            fields.setdefault("external_order_id", order_id)
+            fields.setdefault("external_row_id", None)
+            fields.setdefault("estimated_commission_cents", fields.get("commission_cents"))
+            fields.setdefault("actual_commission_cents", None)
             existing = db.execute(
                 select(CpsOrder).where(CpsOrder.order_id == order_id)
             ).scalar_one_or_none()
@@ -291,6 +406,56 @@ def reconcile_orders(
     return {"fetched": fetched, "inserted": inserted, "updated": updated, "pages": pages}
 
 
+def reconcile_jd_orders(
+    db: Session, *, start_time: datetime, end_time: datetime,
+    query_time_type: int = 3, max_pages: int = 100,
+) -> dict:
+    """调京东 order.row.query 拉单 → 按订单行 upsert。
+
+    京东单次查询窗口最多 1 小时,这里按北京自然时间切窗并逐页拉取。
+    """
+    fetched = inserted = updated = pages = 0
+    cur = start_time
+    while cur < end_time:
+        win_end = min(cur + timedelta(hours=1), end_time)
+        page = 1
+        while page <= max_pages:
+            resp = jd_union.query_order_rows(
+                start_time=cur,
+                end_time=win_end,
+                query_time_type=query_time_type,
+                page_index=page,
+                page_size=200,
+            )
+            rows = resp.get("rows") or []
+            has_more = bool(resp.get("has_more"))
+            if not rows:
+                break
+            pages += 1
+            for r in rows:
+                order_id = _jd_order_key(r)
+                if not order_id:
+                    continue
+                fetched += 1
+                fields = _map_jd_order_fields(r)
+                existing = db.execute(
+                    select(CpsOrder).where(CpsOrder.order_id == order_id)
+                ).scalar_one_or_none()
+                if existing is None:
+                    db.add(CpsOrder(order_id=order_id, **fields))
+                    inserted += 1
+                else:
+                    for k, v in fields.items():
+                        setattr(existing, k, v)
+                    updated += 1
+            if not has_more or len(rows) < 200:
+                break
+            page += 1
+        cur = win_end
+    db.commit()
+    return {"fetched": fetched, "inserted": inserted, "updated": updated, "pages": pages}
+
+
 def list_orders(
     db: Session, *, sid: str | None = None, mt_status: str | None = None,
     limit: int = 20, cursor: int | None = None,

app/admin/repositories/queries.py

@@ -788,6 +788,7 @@ def get_user_overview(db: Session, user_id: int) -> dict | None:
         "user": user,
         "coin_balance": acc.coin_balance if acc else 0,
         "cash_balance_cents": acc.cash_balance_cents if acc else 0,
+        "invite_cash_balance_cents": acc.invite_cash_balance_cents if acc else 0,
         "total_coin_earned": acc.total_coin_earned if acc else 0,
         "comparison_total": _count(ComparisonRecord, ComparisonRecord.user_id == user_id),
         "comparison_success": _count(

app/admin/repositories/stats.py

@@ -13,6 +13,7 @@ from sqlalchemy.orm import Session
 
 from app.models.ad_feed_reward import AdFeedRewardRecord
 from app.models.ad_reward import AdRewardRecord
+from app.models.analytics_event import AnalyticsEvent
 from app.models.comparison import ComparisonRecord
 from app.models.coupon_state import CouponPromptEngagement
 from app.models.cps_order import CpsOrder
@@ -35,6 +36,13 @@ REGULAR_TASK_EXCLUDED_BIZ_TYPES = (
 )
 MEITUAN_CPS_INVALID_STATUSES = ("4", "5")
 MEITUAN_CPS_SETTLED_STATUS = "6"
+COMPARE_START_EVENT = "real_compare_start"
+COUPON_START_EVENT = "real_coupon_start"
+JD_CPS_INVALID_CODES = {
+    "2", "3", "4", "5", "6", "7", "8", "9", "11", "13", "14", "19", "20", "21",
+    "22", "23", "25", "26", "27", "28", "29", "30", "31", "34", "35", "36",
+}
+JD_CPS_UNPAID_CODES = {"15"}
 
 
 def _beijing_today_start_utc() -> datetime:
@@ -45,14 +53,31 @@ def _beijing_today_start_utc() -> datetime:
 
 
 def today_dau(db: Session) -> int:
-    """今日活跃用户数(DAU):北京时区今天 0 点后登录过(last_login_at)。
+    """今日活跃用户数(DAU):登录 + 开始比价 + 开始领券,按用户去重。
 
     广告收益报表复用这个函数;历史窗口 DAU 由 dashboard_overview 的 period 口径另算。
     """
+    today_bj = datetime.now(_BEIJING).date()
     today_start = _beijing_today_start_utc()
-    return int(
-        db.execute(select(func.count(User.id)).where(User.last_login_at >= today_start)).scalar_one()
+    tomorrow_start = today_start + timedelta(days=1)
+    login_user_ids = _id_set(
+        db,
+        select(User.id).where(User.last_login_at >= today_start, User.last_login_at < tomorrow_start),
     )
+    compare_start_user_ids = _event_user_ids(
+        db, (COMPARE_START_EVENT,), today_start, tomorrow_start
+    )
+    coupon_event_user_ids = _event_user_ids(
+        db, (COUPON_START_EVENT,), today_start, tomorrow_start
+    )
+    coupon_claim_user_ids = _id_set(
+        db,
+        select(CouponPromptEngagement.user_id).where(
+            CouponPromptEngagement.engage_date == today_bj,
+            CouponPromptEngagement.engage_type == "claim_started",
+        ),
+    )
+    return len(login_user_ids | compare_start_user_ids | coupon_event_user_ids | coupon_claim_user_ids)
 
 
 def _default_period_end() -> date:
@@ -91,6 +116,24 @@ def _date_range(date_from: date, date_to: date) -> list[date]:
     return [date_from + timedelta(days=i) for i in range(days + 1)]
 
 
+def _id_set(db: Session, stmt) -> set[int]:
+    return {int(v) for v in db.execute(stmt).scalars().all() if v is not None}
+
+
+def _event_user_ids(
+    db: Session, event_names: tuple[str, ...], start_utc: datetime, end_utc: datetime
+) -> set[int]:
+    return _id_set(
+        db,
+        select(AnalyticsEvent.user_id).where(
+            AnalyticsEvent.user_id.is_not(None),
+            AnalyticsEvent.event.in_(event_names),
+            AnalyticsEvent.created_at >= start_utc,
+            AnalyticsEvent.created_at < end_utc,
+        ),
+    )
+
+
 def _commission_rate_percent(raw: str | None) -> Decimal | None:
     """美团 commissionRate 原值: "300"=3%, "10"=0.1%;也兼容 "3%"。"""
     if raw is None:
@@ -107,6 +150,11 @@ def _commission_rate_percent(raw: str | None) -> Decimal | None:
     return val / Decimal("100")
 
 
+def _jd_valid_order(order: CpsOrder) -> bool:
+    code = str(order.jd_valid_code).strip() if order.jd_valid_code is not None else ""
+    return bool(code and code not in JD_CPS_INVALID_CODES and code not in JD_CPS_UNPAID_CODES)
+
+
 def dashboard_overview(
     db: Session, *, date_from: date | None = None, date_to: date | None = None
 ) -> dict:
@@ -216,17 +264,22 @@ def dashboard_overview(
     login_user_ids = _user_id_set(
         select(User.id).where(User.last_login_at >= start_utc, User.last_login_at < end_utc)
     )
-    compare_user_ids = _user_id_set(
-        select(ComparisonRecord.user_id).where(*period_comparison_conds)
+    compare_start_user_ids = _event_user_ids(
+        db, (COMPARE_START_EVENT,), start_utc, end_utc
     )
-    coupon_user_ids = _user_id_set(
+    coupon_event_user_ids = _event_user_ids(
+        db, (COUPON_START_EVENT,), start_utc, end_utc
+    )
+    coupon_claim_user_ids = _user_id_set(
         select(CouponPromptEngagement.user_id).where(
             CouponPromptEngagement.engage_date >= period_from,
             CouponPromptEngagement.engage_date <= period_to,
             CouponPromptEngagement.engage_type == "claim_started",
         )
     )
-    period_active_user_ids = login_user_ids | compare_user_ids | coupon_user_ids
+    period_active_user_ids = (
+        login_user_ids | compare_start_user_ids | coupon_event_user_ids | coupon_claim_user_ids
+    )
     period_retained_new_user_ids = period_new_user_ids & period_active_user_ids
     period_retention_rate = (
         round(len(period_retained_new_user_ids) / len(period_new_user_ids), 4)
@@ -248,10 +301,13 @@ def dashboard_overview(
                 User.last_login_at < day_end_utc,
             )
         )
-        daily_compare_user_ids = _user_id_set(
-            select(ComparisonRecord.user_id).where(*daily_comparison_conds)
+        daily_compare_start_user_ids = _event_user_ids(
+            db, (COMPARE_START_EVENT,), day_start_utc, day_end_utc
         )
-        daily_coupon_user_ids = _user_id_set(
+        daily_coupon_event_user_ids = _event_user_ids(
+            db, (COUPON_START_EVENT,), day_start_utc, day_end_utc
+        )
+        daily_coupon_claim_user_ids = _user_id_set(
             select(CouponPromptEngagement.user_id).where(
                 CouponPromptEngagement.engage_date == cur_date,
                 CouponPromptEngagement.engage_type == "claim_started",
@@ -261,7 +317,10 @@ def dashboard_overview(
             {
                 "date": cur_date,
                 "active_users": len(
-                    daily_login_user_ids | daily_compare_user_ids | daily_coupon_user_ids
+                    daily_login_user_ids
+                    | daily_compare_start_user_ids
+                    | daily_coupon_event_user_ids
+                    | daily_coupon_claim_user_ids
                 ),
                 "new_users": _count(
                     User,
@@ -317,7 +376,7 @@ def dashboard_overview(
         *period_coin_conds,
         CoinTransaction.biz_type.notin_(REGULAR_TASK_EXCLUDED_BIZ_TYPES),
     )
-    period_meituan_orders = list(
+    period_cps_orders = list(
         db.execute(
             select(CpsOrder).where(
                 CpsOrder.pay_time >= start_utc,
@@ -325,9 +384,17 @@ def dashboard_overview(
             )
         ).scalars()
     )
+    period_meituan_orders = [
+        o for o in period_cps_orders if (o.platform or "meituan") == "meituan"
+    ]
     period_meituan_valid_orders = [
         o for o in period_meituan_orders if o.mt_status not in MEITUAN_CPS_INVALID_STATUSES
     ]
+    period_jd_orders = [o for o in period_cps_orders if o.platform == "jd"]
+    period_jd_valid_orders = [o for o in period_jd_orders if _jd_valid_order(o)]
+    period_jd_invalid_orders = [
+        o for o in period_jd_orders if o.jd_valid_code and not _jd_valid_order(o)
+    ]
     period_meituan_hit_count = 0
     period_meituan_miss_count = 0
     period_meituan_unknown_rate_count = 0
@@ -412,8 +479,8 @@ def dashboard_overview(
                 "retained_new_users": len(period_retained_new_user_ids),
                 "retention_rate": period_retention_rate,
                 "retention_note": (
-                    "近似口径:登录(last_login_at)+已上报比价记录+领券claim_started;"
-                    "尚不包含未完成上报的比价开始事件"
+                    "口径:登录(last_login_at)+开始比价(real_compare_start)+"
+                    "开始领券(real_coupon_start/claim_started),按用户去重"
                 ),
             },
             "comparison": {
@@ -450,7 +517,7 @@ def dashboard_overview(
         },
         "cps": {
             "available": True,
-            "note": "美团 CPS 读 cps_order 对账订单;淘宝/京东佣金暂空",
+            "note": "美团/JD CPS 读 cps_order 对账订单;淘宝佣金暂空",
             "meituan_order_count": len(period_meituan_valid_orders),
             "meituan_commission_cents": sum(
                 o.commission_cents or 0 for o in period_meituan_valid_orders
@@ -459,5 +526,17 @@ def dashboard_overview(
             "meituan_miss_count": period_meituan_miss_count,
             "meituan_unknown_rate_count": period_meituan_unknown_rate_count,
             "meituan_hit_rate": period_meituan_hit_rate,
+            "jd_order_count": len(period_jd_valid_orders),
+            # 数据大盘京东 CPS 只看实际佣金,不再用预估佣金兜底。
+            "jd_commission_cents": sum(
+                o.actual_commission_cents or 0 for o in period_jd_valid_orders
+            ),
+            "jd_actual_commission_cents": sum(
+                o.actual_commission_cents or 0 for o in period_jd_valid_orders
+            ),
+            "jd_estimated_commission_cents": sum(
+                o.estimated_commission_cents or 0 for o in period_jd_valid_orders
+            ),
+            "jd_invalid_count": len(period_jd_invalid_orders),
         },
     }

app/admin/routers/coupon_data.py

@@ -0,0 +1,106 @@
+"""admin「领券数据」看板:发起/完成数 + 领券耗时(均值 + P5/P50/P95/P99)+ 按天趋势 + 逐条明细。
+
+任意已登录 admin 可看(只读)。聚合逻辑在 app/admin/repositories/coupon_data.py。
+数据源 coupon_session(客户端 /api/v1/coupon/session 两段上报)。
+"""
+from __future__ import annotations
+
+from datetime import date as _date
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+
+from app.admin.deps import AdminDb, get_current_admin
+from app.admin.repositories import coupon_data
+from app.admin.schemas.coupon_data import (
+    CouponDataDaily,
+    CouponDataHourly,
+    CouponDataOut,
+    CouponDataRow,
+    CouponDataSummary,
+    CouponUserRecordsOut,
+)
+from app.core.rewards import cn_today
+
+router = APIRouter(
+    prefix="/admin/api/coupon-data",
+    tags=["admin-coupon-data"],
+    dependencies=[Depends(get_current_admin)],
+)
+
+# 区间最大跨度(天);超出拒绝,避免一次拉过多天拖垮接口(对齐广告收益报表)。
+_MAX_RANGE_DAYS = 92
+
+
+def _parse_day(value: str | None, *, field: str, default: _date) -> _date:
+    if value is None:
+        return default
+    try:
+        return _date.fromisoformat(value)
+    except ValueError as e:
+        raise HTTPException(status_code=422, detail=f"{field} 需为 YYYY-MM-DD") from e
+
+
+@router.get(
+    "",
+    response_model=CouponDataOut,
+    summary="领券数据看板(发起/完成数 + 耗时分位 + 按天趋势 + 逐条明细)",
+)
+def get_coupon_data(
+    db: AdminDb,
+    date_from: Annotated[str | None, Query(description="起始日 北京 YYYY-MM-DD,默认今天")] = None,
+    date_to: Annotated[str | None, Query(description="结束日 北京 YYYY-MM-DD,闭区间,默认=date_from")] = None,
+    user: Annotated[str | None, Query(description="用户手机号/昵称模糊搜;不传=全部")] = None,
+    app_env: Annotated[str, Query(description="prod(默认) / dev / all(全部环境)")] = "prod",
+    granularity: Annotated[
+        str, Query(description="day=按天 / hour=按小时(北京);区间>1 天建议 day")
+    ] = "day",
+    limit: Annotated[int, Query(ge=1, le=1000, description="每页条数(分页大小)")] = 500,
+    offset: Annotated[int, Query(ge=0, description="分页偏移(已跳过条数)=(页码-1)×每页条数")] = 0,
+    sort: Annotated[
+        str, Query(description="排序:time=发起时间倒序(默认) / elapsed=耗时倒序")
+    ] = "time",
+) -> CouponDataOut:
+    today = cn_today()
+    d_from = _parse_day(date_from, field="date_from", default=today)
+    d_to = _parse_day(date_to, field="date_to", default=d_from)
+    if d_to < d_from:
+        raise HTTPException(status_code=422, detail="date_to 不能早于 date_from")
+    if (d_to - d_from).days + 1 > _MAX_RANGE_DAYS:
+        raise HTTPException(status_code=422, detail=f"区间最长 {_MAX_RANGE_DAYS} 天")
+
+    # 报表默认只看 prod(对齐广告报表防串台口径);app_env=all 时不过滤、看全部环境。
+    env = None if app_env == "all" else app_env
+    result = coupon_data.coupon_data_report(
+        db, date_from=d_from.isoformat(), date_to=d_to.isoformat(),
+        user=user, app_env=env, granularity=granularity,
+        limit=limit, offset=offset, sort=sort,
+    )
+    return CouponDataOut(
+        date_from=d_from.isoformat(),
+        date_to=d_to.isoformat(),
+        summary=CouponDataSummary(**result["summary"]),
+        daily=[CouponDataDaily(**d) for d in result["daily"]],
+        hourly=[CouponDataHourly(**h) for h in result["hourly"]],
+        total=result["total"],
+        items=[CouponDataRow(**r) for r in result["items"]],
+    )
+
+
+@router.get(
+    "/user-records",
+    response_model=CouponUserRecordsOut,
+    summary="某用户全部领券记录(点手机号抽屉:领券次数 + 记录列表)",
+)
+def get_user_coupon_records(
+    db: AdminDb,
+    user_id: Annotated[int, Query(description="用户 id")],
+    limit: Annotated[int, Query(ge=1, le=500, description="最多返回条数")] = 100,
+    sort_by: Annotated[str, Query(description="兼容 UserRecordsDrawer 参数;固定按发起时间倒序")] = "created_at",
+    sort_order: Annotated[str, Query(description="兼容参数,忽略")] = "desc",
+) -> CouponUserRecordsOut:
+    result = coupon_data.coupon_user_records(db, user_id=user_id, limit=limit)
+    return CouponUserRecordsOut(
+        items=[CouponDataRow(**r) for r in result["items"]],
+        total=result["total"],
+    )

app/admin/routers/cps.py

@@ -1,7 +1,7 @@
-"""admin CPS 分发与对账:群/活动管理 + 生成落地页短链 + 美团订单对账 + 统计。
+"""admin CPS 分发与对账:群/活动管理 + 生成落地页短链 + 联盟订单对账 + 统计。
 
 平台:meituan(actId+sid 转链 + query_order 对账) / taobao(整段淘口令) / jd(链接)。
-淘宝/京东无 API → 只统计点击(咱落地页 PV/UV + 淘宝复制),对账字段显示 "-"。
+淘宝暂未接 API → 只统计点击(咱落地页 PV/UV + 淘宝复制),对账字段显示 "-"。
 群/活动管理 = operator;订单对账(涉佣金) = finance;只读列表/统计 = 登录即可。
 """
 from __future__ import annotations
@@ -34,6 +34,7 @@ from app.admin.schemas.cps import (
 from app.core import media
 from app.core.config import settings
 from app.integrations import meituan
+from app.integrations.jd_union import JdUnionError
 from app.integrations.meituan import MeituanCpsError
 from app.models.admin import AdminUser
 from app.models.cps_activity import CpsActivity
@@ -373,7 +374,22 @@ def _reconcile_range_to_ts(
     return int(start_dt.timestamp()), int(end_dt.timestamp())
 
 
-@router.post("/orders/reconcile", response_model=CpsReconcileResult, summary="拉取美团订单对账")
+def _reconcile_range_to_bj_dt(
+    date_from: _date | None, date_to: _date | None, days: int
+) -> tuple[datetime, datetime]:
+    start_ts, end_ts = _reconcile_range_to_ts(date_from, date_to, days)
+    return (
+        datetime.fromtimestamp(start_ts, tz=_BEIJING),
+        datetime.fromtimestamp(end_ts, tz=_BEIJING),
+    )
+
+
+def _merge_reconcile_result(total: dict, current: dict) -> None:
+    for key in ("fetched", "inserted", "updated", "pages"):
+        total[key] = int(total.get(key, 0)) + int(current.get(key, 0))
+
+
+@router.post("/orders/reconcile", response_model=CpsReconcileResult, summary="拉取联盟订单对账")
 def reconcile_orders(
     request: Request,
     admin: Annotated[AdminUser, Depends(require_role("finance"))],
@@ -382,26 +398,42 @@ def reconcile_orders(
     date_to: Annotated[str | None, Query(description="结束日 YYYY-MM-DD")] = None,
     days: Annotated[int, Query(ge=1, le=90, description="未传日期时默认拉近 N 天")] = 7,
     sid: Annotated[str | None, Query(max_length=64)] = None,
-    query_time_type: Annotated[int, Query(ge=1, le=2)] = 1,
+    query_time_type: Annotated[int, Query(ge=1, le=3)] = 1,
+    platform: Annotated[str, Query(pattern="^(all|meituan|jd)$")] = "all",
 ) -> CpsReconcileResult:
-    start_ts, end_ts = _reconcile_range_to_ts(
-        _parse_day(date_from, field="date_from"),
-        _parse_day(date_to, field="date_to"),
-        days,
-    )
+    parsed_from = _parse_day(date_from, field="date_from")
+    parsed_to = _parse_day(date_to, field="date_to")
+    result = {"fetched": 0, "inserted": 0, "updated": 0, "pages": 0}
     try:
-        result = cps_repo.reconcile_orders(
-            db,
-            start_time=start_ts,
-            end_time=end_ts,
-            query_time_type=query_time_type,
-            sid=sid,
-        )
+        if platform in {"all", "meituan"}:
+            start_ts, end_ts = _reconcile_range_to_ts(parsed_from, parsed_to, days)
+            mt_result = cps_repo.reconcile_orders(
+                db,
+                start_time=start_ts,
+                end_time=end_ts,
+                query_time_type=query_time_type if query_time_type in (1, 2) else 2,
+                sid=sid,
+            )
+            _merge_reconcile_result(result, mt_result)
+        if platform in {"all", "jd"}:
+            if sid:
+                raise HTTPException(status_code=422, detail="京东订单刷新不支持 sid 筛选")
+            start_dt, end_dt = _reconcile_range_to_bj_dt(parsed_from, parsed_to, days)
+            jd_result = cps_repo.reconcile_jd_orders(
+                db,
+                start_time=start_dt,
+                end_time=end_dt,
+                query_time_type=query_time_type,
+            )
+            _merge_reconcile_result(result, jd_result)
     except MeituanCpsError as e:
         raise HTTPException(status_code=502, detail=f"美团拉单失败: {e}") from e
+    except JdUnionError as e:
+        raise HTTPException(status_code=502, detail=f"京东拉单失败: {e}") from e
     write_audit(
         db, admin, action="cps.order.reconcile", target_type="cps_order", target_id=None,
         detail={
+            "platform": platform,
             "date_from": date_from,
             "date_to": date_to,
             "days": days,

app/admin/routers/users.py

@@ -210,22 +210,28 @@ def grant_user_cash(
     db: AdminDb,
 ) -> OkResponse:
     """给指定用户增/减或设值现金(分)。delta:正=发放、负=扣减;set:直接设为目标值。
+    account=coin_cash(金币兑现金)/ invite_cash(邀请奖励金):两本账物理隔离、各调各的。
     主要用于让无现金用户直接测试提现。"""
     user = user_repo.get_user_by_id(db, user_id)
     if user is None:
         raise HTTPException(status_code=404, detail="用户不存在")
-    # set=设为目标值:读当前余额算差值,仍复用 grant_cash 写一笔流水(沿用原子/审计/扣负保护)
+    # 按目标账户选「余额字段 + 变动入口」(grant_invite_cash 与 grant_cash 同构)
+    is_invite = body.account == "invite_cash"
+    balance_attr = "invite_cash_balance_cents" if is_invite else "cash_balance_cents"
+    grant_fn = wallet_repo.grant_invite_cash if is_invite else wallet_repo.grant_cash
+    acct_label = "邀请奖励金" if is_invite else "现金"
+    before: int | None = None
+    # set=设为目标值:读当前余额算差值,仍复用 grant 写一笔流水(沿用原子/审计/扣负保护)
     if body.mode == "set":
         if body.amount_cents < 0:
-            raise HTTPException(status_code=400, detail="目标现金值不能为负")
+            raise HTTPException(status_code=400, detail=f"目标{acct_label}值不能为负")
         # lock=True:锁账户行,防连点/并发各读同一 before 算同一 delta 双写,余额错位
-        before = wallet_repo.get_or_create_account(
-            db, user_id, commit=False, lock=True
-        ).cash_balance_cents
+        acc_locked = wallet_repo.get_or_create_account(db, user_id, commit=False, lock=True)
+        before = getattr(acc_locked, balance_attr)
         delta = body.amount_cents - before
         if delta == 0:
             raise HTTPException(
-                status_code=400, detail=f"当前现金已为 {body.amount_cents} 分,无需调整"
+                status_code=400, detail=f"当前{acct_label}已为 {body.amount_cents} 分,无需调整"
             )
     else:
         if body.amount_cents == 0:
@@ -234,18 +240,20 @@ def grant_user_cash(
         # 负数扣减时不允许扣成负余额(运营误操作保护);lock=True 防并发扣穿
         if delta < 0:
             acc_now = wallet_repo.get_or_create_account(db, user_id, commit=False, lock=True)
-            if acc_now.cash_balance_cents + delta < 0:
+            if getattr(acc_now, balance_attr) + delta < 0:
                 raise HTTPException(
-                    status_code=400, detail=f"扣减后现金为负(当前余额 {acc_now.cash_balance_cents} 分)"
+                    status_code=400,
+                    detail=f"扣减后{acct_label}为负(当前余额 {getattr(acc_now, balance_attr)} 分)",
                 )
     biz_type = "admin_grant" if delta > 0 else "admin_deduct"
-    # grant_cash 只 flush 不 commit;审计同 commit=False;最后一起 commit → 原子(改钱+留痕)
-    acc, _ = wallet_repo.grant_cash(
+    # grant 只 flush 不 commit;审计同 commit=False;最后一起 commit → 原子(改钱+留痕)
+    acc, _ = grant_fn(
         db, user_id, delta, biz_type=biz_type, remark=f"admin:{body.reason}"[:128],
     )
     detail = {
+        "account": body.account,
         "amount_cents": delta,
-        "balance_after_cents": acc.cash_balance_cents,
+        "balance_after_cents": getattr(acc, balance_attr),
         "reason": body.reason,
     }
     if body.mode == "set":

app/admin/schemas/coupon_data.py

@@ -0,0 +1,83 @@
+"""admin「领券数据」看板 schemas:汇总卡 + 按天/小时趋势 + 逐条领券明细。
+
+数据源 coupon_session(一次领券一行)。耗时单位 ms(前端按需折秒);均值/分位只统计 completed。
+"""
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+
+class CouponDataSummary(BaseModel):
+    """汇总卡:发起/完成数 + 耗时均值与分位(P5/P50/P95/P99,基于 completed 的 elapsed_ms)。"""
+
+    started_count: int = Field(..., description="发起数(区间内所有领券 session)")
+    completed_count: int = Field(..., description="完成数(status=completed)")
+    avg_elapsed_ms: int | None = Field(None, description="平均耗时(ms,仅 completed;无数据为空)")
+    p5_ms: int | None = Field(None, description="耗时 5 分位(ms)")
+    p50_ms: int | None = Field(None, description="耗时 50 分位(ms,中位数)")
+    p95_ms: int | None = Field(None, description="耗时 95 分位(ms)")
+    p99_ms: int | None = Field(None, description="耗时 99 分位(ms)")
+
+
+class CouponDataDaily(BaseModel):
+    """按天趋势(全量,不受分页影响):柱=发起/完成数,线=平均耗时。"""
+
+    date: str = Field(..., description="北京时间 YYYY-MM-DD")
+    started_count: int
+    completed_count: int
+    avg_elapsed_ms: int | None = Field(None, description="当天平均耗时(ms,仅 completed)")
+
+
+class CouponDataHourly(BaseModel):
+    """按北京小时(0–23)趋势(单日 granularity=hour 时非空)。"""
+
+    hour: int = Field(..., description="北京时间小时 0–23")
+    started_count: int
+    completed_count: int
+    avg_elapsed_ms: int | None = None
+
+
+class CouponDataRow(BaseModel):
+    """一条领券明细(一次领券任务)。"""
+
+    id: int = Field(..., description="coupon_session 主键(抽屉 rowKey 用)")
+    trace_id: str
+    user_id: int | None = None
+    user_phone: str | None = Field(None, description="手机号(admin 展示;匿名领券/查不到为空)")
+    user_nickname: str | None = Field(None, description="昵称")
+    status: str = Field(..., description="started / completed / failed / abandoned")
+    platforms: list[str] | None = Field(None, description="发起勾选平台")
+    origin_package: str | None = Field(None, description="发起来源 App 包名;null=App 内(傻瓜比价首页)发起")
+    elapsed_ms: int | None = Field(None, description="全程耗时(ms)")
+    platform_elapsed: dict[str, int] | None = Field(
+        None, description="各平台耗时 {meituan-waimai/taobao-shanguang/jd-waimai: ms}"
+    )
+    device_model: str | None = None
+    rom: str | None = None
+    app_env: str | None = None
+    started_at: datetime = Field(..., description="发起时刻(明细「时间」列)")
+    claimed_count: int | None = None
+    trace_url: str | None = Field(None, description="pricebot 公网 trace 链接(仅 completed 有);admin 渲染可点链接,无则显示可复制 trace_id")
+
+
+class CouponDataOut(BaseModel):
+    """领券数据看板响应:汇总卡 + 趋势 + 明细分页。"""
+
+    date_from: str
+    date_to: str
+    summary: CouponDataSummary
+    daily: list[CouponDataDaily] = Field(default_factory=list, description="按天趋势(全量)")
+    hourly: list[CouponDataHourly] = Field(
+        default_factory=list, description="按小时趋势(单日 hour 粒度时非空)"
+    )
+    total: int = Field(..., description="明细总条数(全量,不受分页)")
+    items: list[CouponDataRow] = Field(..., description="逐条领券明细(当前页)")
+
+
+class CouponUserRecordsOut(BaseModel):
+    """某用户全部领券记录(点手机号抽屉用):total=该用户领券总次数,items=记录列表(UserRecordsDrawer 渲染)。"""
+
+    items: list[CouponDataRow]
+    total: int

app/admin/schemas/cps.py

@@ -1,7 +1,7 @@
 """admin CPS 分发与对账 schemas。金额统一「分」(cents),前端 yuan() 展示。
 
-平台:meituan(actId+sid 转链对账) / taobao(淘口令,只统计点击) / jd(链接,只统计点击)。
-对账类字段对淘宝/京东为 None → 前端显示 "-"(无法对账)。
+平台:meituan(actId+sid 转链对账) / taobao(淘口令,只统计点击) / jd(链接 + 订单 API 对账)。
+对账类字段对淘宝为 None → 前端显示 "-"(暂未对账)。
 """
 from __future__ import annotations
 
@@ -116,15 +116,22 @@ class CpsOrderOut(BaseModel):
     model_config = ConfigDict(from_attributes=True)
 
     id: int
+    platform: str = "meituan"
     order_id: str
+    external_order_id: str | None = None
+    external_row_id: str | None = None
     sid: str | None = None
     act_id: str | None = None
     pay_price_cents: int | None = None
     commission_cents: int | None = None
+    estimated_commission_cents: int | None = None
+    actual_commission_cents: int | None = None
     commission_rate: str | None = None
     mt_status: str | None = None
+    jd_valid_code: str | None = None
     invalid_reason: str | None = None
     product_name: str | None = None
+    settle_month: str | None = None
     pay_time: datetime | None = None
 
 

app/admin/schemas/dashboard.py

@@ -103,6 +103,11 @@ class DashboardCps(BaseModel):
     meituan_miss_count: int = 0
     meituan_unknown_rate_count: int = 0
     meituan_hit_rate: float | None = None
+    jd_order_count: int = 0
+    jd_commission_cents: int = 0
+    jd_actual_commission_cents: int = 0
+    jd_estimated_commission_cents: int = 0
+    jd_invalid_count: int = 0
 
 
 class DashboardOverview(BaseModel):

app/admin/schemas/user.py

@@ -29,6 +29,7 @@ class AdminUserOverview(BaseModel):
     user: AdminUserListItem
     coin_balance: int
     cash_balance_cents: int
+    invite_cash_balance_cents: int  # 邀请奖励金余额(与 cash_balance_cents 物理隔离)
     total_coin_earned: int
     comparison_total: int
     comparison_success: int
@@ -88,6 +89,11 @@ class GrantCoinsRequest(BaseModel):
 
 
 class GrantCashRequest(BaseModel):
+    # 目标账户:金币兑换的现金(cash_balance_cents)与邀请奖励金(invite_cash_balance_cents)物理隔离,
+    # 各调各的、不可串。默认 coin_cash 兼容旧调用。
+    account: Literal["coin_cash", "invite_cash"] = Field(
+        "coin_cash", description="目标账户:coin_cash=金币兑现金账户 / invite_cash=邀请奖励金账户"
+    )
     mode: Literal["delta", "set"] = Field(
         "delta", description="delta=增减(amount_cents 为变动量) / set=设为(amount_cents 为目标值,须≥0)"
     )

app/api/v1/compare_record.py

@@ -21,16 +21,15 @@ from app.api.deps import CurrentUser, DbSession
 from app.db.session import SessionLocal
 from app.models.comparison import ComparisonRecord
 from app.repositories import comparison as crud_compare
-from app.repositories import invite as crud_invite
-from app.services.pricebot_llm_calls import fetch_llm_calls
 from app.schemas.compare_record import (
     CompareStatsOut,
     ComparisonRecordCreatedOut,
     ComparisonRecordDetailOut,
     ComparisonRecordIn,
-    ComparisonRecordPage,
     ComparisonRecordOut,
+    ComparisonRecordPage,
 )
+from app.services.pricebot_llm_calls import fetch_llm_calls
 
 logger = logging.getLogger("shagua.compare_record")
 
@@ -53,18 +52,8 @@ def report_record(
     # 任务做,不阻塞上报响应(顺带给 pricebot 落盘留足余量)。upsert 已 commit,后台用
     # 独立 session 按 record id 回填 llm_calls + 派生 llm_call_count/retry_count。
     background_tasks.add_task(_backfill_llm_calls, rec.id, rec.trace_id)
-    # 邀请 v2 发奖:被邀请人完成一次【成功】比价 → 给邀请人发邀请奖励金(幂等,只发一次)。
-    # best-effort:发奖异常不影响比价上报本身(rec 已 commit),只 log;邀请人补偿靠后续对账。
-    if rec.status == "success":
-        try:
-            reward = crud_invite.try_reward_on_compare(db, user.id)
-            if reward.status == "granted":
-                logger.info(
-                    "invite compare reward granted inviter=%s invitee=%s cents=%s",
-                    reward.inviter_user_id, user.id, reward.reward_cents,
-                )
-        except Exception as e:  # noqa: BLE001 best-effort,发奖失败不阻塞上报
-            logger.warning("invite compare reward failed invitee=%s: %s", user.id, e)
+    # 注:邀请发奖已从"比价成功"挪到"实际下单"(见 api/v1/order.py report_order)——
+    # 冰拍板:被邀请人完成比价并实际下单才算邀请成功,仅完成比价不再发奖。
     logger.info(
         "compare record user=%s trace=%s biz=%s status=%s saved=%s (llm_calls backfill queued)",
         user.id,

app/api/v1/coupon.py

@@ -29,6 +29,7 @@ from app.schemas.coupon_state import (
     CouponPromptDismissIn,
     CouponPromptShouldShowOut,
     CouponPromptShownIn,
+    CouponSessionIn,
     CouponStatsOut,
 )
 
@@ -194,6 +195,34 @@ async def coupon_step(
     return resp_json
 
 
+@router.post("/session", summary="领券任务流水上报(admin 领券数据看板数据源)")
+def coupon_session(payload: CouponSessionIn, db: DbSession) -> dict[str, bool]:
+    """客户端两段上报一次领券流水(发起 started / 收尾 completed-failed-abandoned),按 trace_id upsert
+    到 coupon_session。不鉴权(同领券循环 MVP,按 device_id/trace_id);供 admin「领券数据」看板算
+    发起/完成数、耗时分位、机型维度。写库失败不应连累客户端(本就 fire-and-forget),吞掉返回 ok。"""
+    try:
+        coupon_repo.upsert_coupon_session(
+            db,
+            trace_id=payload.trace_id,
+            device_id=payload.device_id,
+            status=payload.status,
+            started_at_ms=payload.started_at_ms,
+            user_id=payload.user_id,
+            platforms=payload.platforms,
+            origin_package=payload.origin_package,
+            device_model=payload.device_model,
+            rom=payload.rom,
+            app_env=payload.app_env,
+            elapsed_ms=payload.elapsed_ms,
+            platform_elapsed=payload.platform_elapsed,
+            claimed_count=payload.claimed_count,
+            trace_url=payload.trace_url,
+        )
+    except Exception as e:  # noqa: BLE001
+        logger.warning("coupon session write failed: %s", e)
+    return {"ok": True}
+
+
 @router.post("/prompt/shown", summary="领券引导窗弹出即上报(按 App 记 shown)")
 def coupon_prompt_shown(payload: CouponPromptShownIn, db: DbSession) -> dict[str, bool]:
     """客户端弹出引导窗那刻调 → 记一条今日 engagement(shown),今天**这个 App** 不再自动弹。

app/api/v1/invite.py

@@ -122,6 +122,57 @@ def my_invitees(
     )
 
 
+@router.post("/seed-fake", summary="[DEV] 给自己塞虚拟好友(测在途/好友列表 UI,仅非生产)")
+def seed_fake_invitees(
+    user: CurrentUser, db: DbSession, pending: int = 3, compared: int = 2
+) -> dict:
+    """造 pending 个未比价 + compared 个已比价的虚拟好友。生产环境(is_prod)直接 404。
+
+    未比价 → 上"在途列表 / 好友列表去提醒";已比价 → 好友列表"邀请成功"、并发真实邀请奖励金
+    (可提现余额/累计提现也有数)。清理见 DELETE /seed-fake。
+    """
+    if settings.is_prod:
+        from fastapi import HTTPException
+        raise HTTPException(status_code=404, detail="Not Found")
+    n = invite_repo.seed_fake_invitees(db, user.id, pending=max(0, pending), compared=max(0, compared))
+    return {"status": "ok", "created": n, "pending": pending, "compared": compared}
+
+
+@router.delete("/seed-fake", summary="[DEV] 清掉自己的虚拟好友(仅非生产)")
+def clear_fake_invitees(user: CurrentUser, db: DbSession) -> dict:
+    if settings.is_prod:
+        from fastapi import HTTPException
+        raise HTTPException(status_code=404, detail="Not Found")
+    n = invite_repo.clear_fake_invitees(db, user.id)
+    return {"status": "ok", "removed": n}
+
+
+@router.post("/dev-reset", summary="[DEV] 把固定测试号打回出厂态,便于反复当新用户测发奖(仅非生产)")
+def dev_reset(db: DbSession) -> dict:
+    """把 TEST_ACCOUNT_PHONE 这个固定测试号清成"从没被邀请/没下过单"的新用户态。
+
+    ⚠️ 无需鉴权(它只按配置里的测试号操作,不依赖登录态,方便测试脚本第一步直接调)。
+    双重门控:生产环境(is_prod)404;测试号总开关(TEST_ACCOUNT_PHONE)没配置 → 400。
+    故它永远只能动那一个配置好的测试号,动不了任意真实用户。
+
+    清什么见 repositories/invite.dev_reset_test_account(全清 + 刷 created_at 骗过 72h 闸)。
+    调完该测试号即可再次绑定 + 下单上报,重新触发一次邀请发奖。
+    """
+    from fastapi import HTTPException
+
+    if settings.is_prod:
+        raise HTTPException(status_code=404, detail="Not Found")
+    phone = settings.test_account_phone
+    if not phone:
+        raise HTTPException(
+            status_code=400,
+            detail="测试号未启用:请在 .env 配 TEST_ACCOUNT_PHONE=11111111111 并重启服务",
+        )
+    cleared = invite_repo.dev_reset_test_account(db, phone)
+    logger.info("invite dev-reset phone=%s cleared=%s", phone, cleared)
+    return {"status": "ok", "phone": phone, "cleared": cleared}
+
+
 @router.post(
     "/landing-track",
     response_model=LandingTrackOut,

app/api/v1/order.py

@@ -1,9 +1,14 @@
+import logging
+
 from fastapi import APIRouter
 
 from app.api.deps import CurrentUser, DbSession
+from app.repositories import invite as crud_invite
 from app.repositories import savings as crud_savings
 from app.schemas.order import OrderReportOut, OrderReportRequest
 
+logger = logging.getLogger("shagua.order")
+
 router = APIRouter(prefix="/api/v1/order", tags=["order"])
 
 
@@ -15,6 +20,20 @@ router = APIRouter(prefix="/api/v1/order", tags=["order"])
 def report_order(req: OrderReportRequest, user: CurrentUser, db: DbSession) -> OrderReportOut:
     # 记账唯一真相表是 savings_record(source='compare')。
     rec, duplicated = crud_savings.create_from_report(db, user.id, req)
+    # 邀请 v2 发奖:被邀请人【实际下单】(而非仅完成比价)才给邀请人发邀请奖励金(幂等,只发一次)。
+    # 触发点从"比价成功上报"挪到这里(冰:完成比价并实际下单才算成功)。仅首次真实上报触发,
+    # 重复上报(duplicated)跳过。best-effort:发奖异常不影响订单上报本身(rec 已 commit),只 log;
+    # try_reward_on_compare 自带 compare_reward_granted 幂等闸,漏发靠后续对账补。
+    if not duplicated:
+        try:
+            reward = crud_invite.try_reward_on_compare(db, user.id)
+            if reward.status == "granted":
+                logger.info(
+                    "invite order reward granted inviter=%s invitee=%s cents=%s",
+                    reward.inviter_user_id, user.id, reward.reward_cents,
+                )
+        except Exception as e:  # noqa: BLE001 best-effort,发奖失败不阻塞订单上报
+            logger.warning("invite order reward failed invitee=%s: %s", user.id, e)
     return OrderReportOut(
         id=rec.id,
         platform=rec.platform or req.platform,

app/api/v1/wallet.py

@@ -202,6 +202,9 @@ def withdraw(req: WithdrawRequest, user: CurrentUser, db: DbSession) -> Withdraw
         order = crud_wallet.create_withdraw(
             db, user.id, req.amount_cents, source=req.source,
             user_name=req.user_name, out_bill_no=req.out_bill_no,
+            # 0.01 元调试提现:放行低于最低额的小额。双闸——客户端仅 debug 包在「0.01 元提现」开关开时
+            # 连同 skip_review 一起下发;服务端仅非 prod 才认。生产恒 False,最低额校验照常。
+            allow_sub_min=(req.skip_review and not settings.is_prod),
         )
     except crud_wallet.InvalidWithdrawAmountError as e:
         raise HTTPException(

app/core/config.py

@@ -113,6 +113,21 @@ class Settings(BaseSettings):
         """美团 CPS 凭证齐全(缺则接口返空,而非 502)。"""
         return bool(self.MT_CPS_APP_KEY and self.MT_CPS_APP_SECRET)
 
+    # ===== 京东联盟 CPS =====
+    # app_key/app_secret 来自京东联盟应用;site_id 是推广管理里的 APP/网站 ID;
+    # auth_key 是工具商授权 key,自有应用查询可留空。
+    JD_UNION_APP_KEY: str = ""
+    JD_UNION_APP_SECRET: str = ""
+    JD_UNION_SITE_ID: str = ""
+    JD_UNION_AUTH_KEY: str = ""
+    JD_UNION_GATEWAY: str = "https://api.jd.com/routerjson"
+    JD_UNION_TIMEOUT_SEC: int = 15
+
+    @property
+    def jd_union_configured(self) -> bool:
+        """京东联盟订单查询凭证齐全。"""
+        return bool(self.JD_UNION_APP_KEY and self.JD_UNION_APP_SECRET)
+
     # ===== 微信服务号(网页授权) =====
     # CPS 落地页在微信内拿用户 openid(base 静默)/昵称头像(userinfo),做用户级群统计。
     # ⚠️ 区别于 WECHAT_APP_ID(那是 App 移动应用,用于微信支付);这是【已认证服务号】。

app/integrations/jd_union.py

@@ -0,0 +1,163 @@
+"""京东联盟 OpenAPI 客户端。
+
+当前只接数据大盘需要的订单明细接口:
+`jd.union.open.order.row.query`。京东要求订单查询时间窗最长 1 小时,
+调用方负责切窗分页。
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+from datetime import datetime, timedelta, timezone
+from typing import Any
+
+import httpx
+
+from app.core.config import settings
+
+logger = logging.getLogger(__name__)
+
+_BEIJING = timezone(timedelta(hours=8))
+
+
+class JdUnionError(RuntimeError):
+    """京东联盟 API 调用失败。"""
+
+
+def _parse_json_maybe(value: Any) -> Any:
+    if not isinstance(value, str):
+        return value
+    text = value.strip()
+    if not text:
+        return value
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        return value
+
+
+def _sign(params: dict[str, Any], secret: str) -> str:
+    pieces = [secret]
+    for key in sorted(k for k in params if k != "sign"):
+        value = params[key]
+        if value is None:
+            continue
+        pieces.append(f"{key}{value}")
+    pieces.append(secret)
+    raw = "".join(pieces)
+    return hashlib.md5(raw.encode("utf-8")).hexdigest().upper()
+
+
+def _unwrap_response(data: dict[str, Any]) -> dict[str, Any]:
+    if "error_response" in data:
+        err = data["error_response"] or {}
+        msg = err.get("zh_desc") or err.get("en_desc") or err.get("msg") or err
+        raise JdUnionError(f"京东 API 错误: {msg}")
+
+    body: Any = data
+    for key, value in data.items():
+        if key.endswith("_responce") or key.endswith("_response"):
+            body = value
+            break
+
+    body = _parse_json_maybe(body)
+    if not isinstance(body, dict):
+        raise JdUnionError("京东 API 返回格式异常")
+
+    result = body.get("queryResult", body.get("result", body))
+    result = _parse_json_maybe(result)
+    if not isinstance(result, dict):
+        raise JdUnionError("京东 API 业务结果格式异常")
+
+    code = str(result.get("code", result.get("resultCode", "200")))
+    if code not in {"0", "200"}:
+        msg = result.get("message") or result.get("msg") or result.get("resultMsg") or result
+        raise JdUnionError(f"京东 API 业务错误: {msg}")
+    return result
+
+
+def call(method: str, payload: dict[str, Any], *, version: str = "1.0") -> dict[str, Any]:
+    if not settings.jd_union_configured:
+        raise JdUnionError("京东联盟凭证未配置")
+
+    biz_json = json.dumps(payload, ensure_ascii=False, separators=(",", ":"))
+    params: dict[str, Any] = {
+        "method": method,
+        "app_key": settings.JD_UNION_APP_KEY,
+        "timestamp": datetime.now(_BEIJING).strftime("%Y-%m-%d %H:%M:%S"),
+        "format": "json",
+        "v": version,
+        "sign_method": "md5",
+        "360buy_param_json": biz_json,
+    }
+    params["sign"] = _sign(params, settings.JD_UNION_APP_SECRET)
+
+    try:
+        with httpx.Client(timeout=settings.JD_UNION_TIMEOUT_SEC, trust_env=False) as client:
+            resp = client.post(settings.JD_UNION_GATEWAY, data=params)
+            resp.raise_for_status()
+            data = resp.json()
+    except httpx.HTTPError as e:
+        raise JdUnionError(f"京东 API 网络错误: {e}") from e
+    except json.JSONDecodeError as e:
+        raise JdUnionError("京东 API 返回非 JSON") from e
+
+    return _unwrap_response(data)
+
+
+def _extract_rows(result: dict[str, Any]) -> tuple[list[dict[str, Any]], bool]:
+    payload = _parse_json_maybe(result.get("data", result.get("result", result)))
+    has_more = bool(result.get("hasMore") or result.get("has_more"))
+
+    if isinstance(payload, dict):
+        for key in ("orderRowResp", "orderRows", "orderList", "orders", "list", "rows"):
+            rows = _parse_json_maybe(payload.get(key))
+            if isinstance(rows, list):
+                return [r for r in rows if isinstance(r, dict)], bool(
+                    payload.get("hasMore") or payload.get("has_more") or has_more
+                )
+        return [], bool(payload.get("hasMore") or payload.get("has_more") or has_more)
+    if isinstance(payload, list):
+        return [r for r in payload if isinstance(r, dict)], has_more
+    return [], has_more
+
+
+def query_order_rows(
+    *,
+    start_time: datetime,
+    end_time: datetime,
+    query_time_type: int = 3,
+    page_index: int = 1,
+    page_size: int = 200,
+) -> dict[str, Any]:
+    """查询京东 CPS 订单行。
+
+    query_time_type: 1 下单时间, 2 完成时间, 3 更新时间。
+    start_time/end_time 用北京时间展示给京东;调用方需保证窗口不超过 1 小时。
+    """
+    start_bj = start_time.astimezone(_BEIJING)
+    end_bj = end_time.astimezone(_BEIJING)
+    if end_bj <= start_bj:
+        return {"rows": [], "has_more": False}
+    if end_bj - start_bj > timedelta(hours=1):
+        raise JdUnionError("京东订单查询单次时间窗不能超过 1 小时")
+
+    order_req: dict[str, Any] = {
+        "pageIndex": page_index,
+        "pageSize": min(max(page_size, 1), 200),
+        "type": query_time_type,
+        "startTime": start_bj.strftime("%Y-%m-%d %H:%M:%S"),
+        "endTime": end_bj.strftime("%Y-%m-%d %H:%M:%S"),
+    }
+    if settings.JD_UNION_AUTH_KEY:
+        order_req["key"] = settings.JD_UNION_AUTH_KEY
+    result = call("jd.union.open.order.row.query", {"orderReq": order_req})
+    rows, has_more = _extract_rows(result)
+    logger.info(
+        "jd.union.open.order.row.query fetched rows=%s page=%s has_more=%s",
+        len(rows),
+        page_index,
+        has_more,
+    )
+    return {"rows": rows, "has_more": has_more, "raw": result}

app/main.py

@@ -2,18 +2,23 @@
 
 通过 `uvicorn app.main:app --reload` 启动。
 """
+
 from __future__ import annotations
 
 import logging
 from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
-
 from pathlib import Path
 
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse
 from fastapi.staticfiles import StaticFiles
 
+from app.api.internal.app_version import router as internal_app_version_router
+from app.api.internal.launch_confirm import router as internal_launch_confirm_router
+from app.api.internal.price import router as internal_price_router
+from app.api.internal.store import router as internal_store_router
 from app.api.v1.ad import router as ad_router
 from app.api.v1.analytics import router as analytics_router
 from app.api.v1.auth import router as auth_router
@@ -21,12 +26,8 @@ from app.api.v1.compare import router as compare_router
 from app.api.v1.compare_milestone import router as compare_milestone_router
 from app.api.v1.compare_record import router as compare_record_router
 from app.api.v1.coupon import router as coupon_router
-from app.api.v1.device import router as device_router
 from app.api.v1.cps_redirect import router as cps_redirect_router
-from app.api.internal.app_version import router as internal_app_version_router
-from app.api.internal.launch_confirm import router as internal_launch_confirm_router
-from app.api.internal.price import router as internal_price_router
-from app.api.internal.store import router as internal_store_router
+from app.api.v1.device import router as device_router
 from app.api.v1.feedback import router as feedback_router
 from app.api.v1.invite import router as invite_router
 from app.api.v1.meituan import router as meituan_router
@@ -40,14 +41,14 @@ from app.api.v1.user import router as user_router
 from app.api.v1.wallet import router as wallet_router
 from app.api.v1.wxpay import router as wxpay_router
 from app.core.config import settings
-from app.core.heartbeat_monitor_worker import (
-    start_heartbeat_monitor,
-    stop_heartbeat_monitor,
-)
 from app.core.daily_exchange_worker import (
     start_daily_exchange_worker,
     stop_daily_exchange_worker,
 )
+from app.core.heartbeat_monitor_worker import (
+    start_heartbeat_monitor,
+    stop_heartbeat_monitor,
+)
 from app.core.logging import setup_logging
 from app.core.pricebot_client import aclose_pricebot_client, get_pricebot_client
 from app.core.withdraw_reconcile_worker import (
@@ -137,6 +138,30 @@ app.include_router(cps_redirect_router)
 # 用户上传文件(头像)静态服务。生产可改由 nginx 直接 serve MEDIA_ROOT。
 _media_root = Path(settings.MEDIA_ROOT)
 _media_root.mkdir(parents=True, exist_ok=True)
+
+
+# 官网下载的 APK 直链(落地页 dl.html「官网下载」按钮指向 /media/shaguabijia.apk)。
+# 必须在 StaticFiles 挂载【之前】注册,否则被静态挂载吃掉。
+# StaticFiles 给 .apk 的 Content-Type 不对、且无 attachment 头 → 部分国产浏览器不触发下载、转甩应用市场;
+# 这里显式回 application/vnd.android.package-archive + Content-Disposition:attachment 强制浏览器下载。
+# 文件由 scripts/publish_apk.sh 编 release 包后放到 data/media/shaguabijia.apk(*.apk 不入 git,需部署时放)。
+_APK_PATH = _media_root / "shaguabijia.apk"
+
+
+@app.get(f"{settings.MEDIA_URL_PREFIX}/shaguabijia.apk", tags=["meta"], include_in_schema=False)
+def download_apk() -> FileResponse:
+    if not _APK_PATH.is_file():
+        from fastapi import HTTPException
+
+        raise HTTPException(status_code=404, detail="安装包未就绪")
+    return FileResponse(
+        _APK_PATH,
+        media_type="application/vnd.android.package-archive",
+        filename="shaguabijia.apk",
+        headers={"Content-Disposition": 'attachment; filename="shaguabijia.apk"'},
+    )
+
+
 app.mount(
     settings.MEDIA_URL_PREFIX,
     StaticFiles(directory=str(_media_root)),

app/models/__init__.py

@@ -19,6 +19,7 @@ from app.models.coupon_state import (  # noqa: F401
     CouponClaimRecord,
     CouponDailyCompletion,
     CouponPromptEngagement,
+    CouponSession,
 )
 from app.models.feedback import Feedback  # noqa: F401
 from app.models.invite import InviteRelation  # noqa: F401

app/models/coupon_state.py

@@ -181,3 +181,79 @@ class CouponPromptEngagement(Base):
             f"<CouponPromptEngagement device={self.device_id} "
             f"date={self.engage_date} type={self.engage_type}>"
         )
+
+
+class CouponSession(Base):
+    """一次领券任务的全程流水(admin「领券数据」看板数据源,2026-06-30)。
+
+    与 coupon_claim_record(按券一天一条去重)、coupon_daily_completion(按设备一天一条)都不同:
+    本表**一次领券一条**(trace_id 唯一),记从发起(started)到收尾(completed/failed/abandoned)的
+    全程耗时 + 各平台耗时 + 机型/ROM。客户端 POST /api/v1/coupon/session 两段上报:发起建行、
+    收尾按 trace_id 更新同一行。发起即落库 → admin 可算「发起数」与中途流失(started 无终态=未完成)。
+
+    口径:elapsed_ms 由客户端全程计时(点发起→收尾)、权威;started_at/finished_at 为时刻留痕。
+    started_date = started_at 的 Asia/Shanghai 自然日,供 admin 按天聚合 / 日期筛选(索引)。
+    """
+
+    __tablename__ = "coupon_session"
+    __table_args__ = (
+        # 一次领券一行:trace_id 幂等 upsert(发起建、收尾更新同一行)。
+        UniqueConstraint("trace_id", name="uq_coupon_session_trace"),
+        # admin 主聚合/筛选:按上海自然日 + 环境(报表默认只看 prod,避免测试数据串台)。
+        Index("ix_coupon_session_date_env", "started_date", "app_env"),
+    )
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+
+    # 一次领券唯一 id(客户端 UUID,全程贯穿),upsert 键。
+    trace_id: Mapped[str] = mapped_column(String(64), nullable=False)
+    device_id: Mapped[str] = mapped_column(String(64), nullable=False)
+    # 登录态才带(admin join 用户表出手机号/昵称);匿名领券为空。
+    user_id: Mapped[int | None] = mapped_column(Integer, index=True, nullable=True)
+
+    # started / completed / failed / abandoned。started 无终态 = 中途流失(未完成)。
+    status: Mapped[str] = mapped_column(String(16), nullable=False)
+    # prod / dev(客户端 BuildConfig.DEBUG)。admin 报表默认只看 prod(对齐广告报表防串台口径)。
+    app_env: Mapped[str | None] = mapped_column(String(16), index=True, nullable=True)
+
+    # 发起勾选平台 ["meituan-waimai", ...](空=全领)。
+    platforms: Mapped[list | None] = mapped_column(_JSON, nullable=True)
+    # 发起来源外卖 App 包名;null=App 内(傻瓜比价首页)发起,非空=从美团/淘宝/京东弹券发起。
+    # admin「发起平台」列据此区分(空→傻瓜比价,包名→对应平台)。
+    origin_package: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    # 机型(Build.MANUFACTURER + MODEL)与 ROM(OemDetector,如 "ColorOS 14")。明细「机型/ROM」列 + 维度筛选。
+    device_model: Mapped[str | None] = mapped_column(String(128), nullable=True)
+    rom: Mapped[str | None] = mapped_column(String(64), nullable=True)
+
+    # 发起时刻(客户端墙钟):明细「时间」列、趋势 X 轴。
+    started_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    # 发起的 Asia/Shanghai 自然日:按天聚合 / 日期范围筛选(索引)。
+    started_date: Mapped[date] = mapped_column(Date, nullable=False)
+    # 收尾时刻(服务端 now);未收尾(流失)为空。
+    finished_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+
+    # 全程耗时(ms,客户端点发起→收尾):平均 / 分位都基于它(只统计 completed)。
+    elapsed_ms: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    # 各平台领券耗时 {"meituan-waimai":3200,...}(ms)。明细美团/淘宝/京东耗时列。
+    platform_elapsed: Mapped[dict | None] = mapped_column(_JSON, nullable=True)
+    # 领到总张数(收尾帧带)。
+    claimed_count: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    # pricebot done 帧回传的公网调试链接(price.shaguabijia.com/traces/{dir});含落盘时分秒、拼不出,只能存
+    # (同 ComparisonRecord.trace_url)。admin「领券数据」明细据此渲染可点 trace 链接;未到 done(failed/abandoned)为空。
+    trace_url: Mapped[str | None] = mapped_column(String(512), nullable=True)
+
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), nullable=False
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), onupdate=func.now(),
+        nullable=False,
+    )
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return (
+            f"<CouponSession trace={self.trace_id} status={self.status} "
+            f"elapsed_ms={self.elapsed_ms}>"
+        )

app/models/cps_order.py

@@ -1,11 +1,13 @@
 """CPS 对账订单(cps_order)。
 
-从美团联盟 query_order 按时间窗拉回、按 sid 归群的订单明细。字段对齐 query_order
+从联盟 API 按时间窗拉回、按平台落库的 CPS 订单明细。字段最初对齐美团 query_order,
+后续兼容京东订单报表:
 实测返回:
   - payPrice / profit 是「元」字符串 → 入库统一转「分」(与全站口径一致)
   - payTime / updateTime 是秒级时间戳 → 入库转 tz-aware datetime
   - status: 2付款 3完成 4取消 5风控 6结算(取消/风控不计佣金)
-order_id 全局唯一,reconcile 按它 upsert(订单状态会变,重复拉则更新)。
+order_id 全局唯一,reconcile 按它 upsert(订单状态会变,重复拉则更新)。京东订单用
+`jd:<row_id>` 前缀避免与美团订单号碰撞。
 """
 from __future__ import annotations
 
@@ -22,8 +24,13 @@ class CpsOrder(Base):
     __tablename__ = "cps_order"
 
     id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
-    # 美团订单号(加密串),全局唯一,upsert 幂等键。
+    # 平台:meituan / jd。历史数据迁移默认 meituan。
+    platform: Mapped[str] = mapped_column(String(20), default="meituan", index=True, nullable=False)
+    # 平台订单号/行号包装后的全局唯一键,upsert 幂等。
     order_id: Mapped[str] = mapped_column(String(64), unique=True, index=True, nullable=False)
+    # 平台原始订单号/行号。京东一笔订单多 SKU 时可按行号区分。
+    external_order_id: Mapped[str | None] = mapped_column(String(128), index=True, nullable=True)
+    external_row_id: Mapped[str | None] = mapped_column(String(128), index=True, nullable=True)
     # 渠道追踪位 = 群 sid(历史无 sid 订单为空)。按它归群聚合。
     sid: Mapped[str | None] = mapped_column(String(64), index=True, nullable=True)
     act_id: Mapped[str | None] = mapped_column(String(64), index=True, nullable=True)
@@ -35,11 +42,21 @@ class CpsOrder(Base):
     commission_rate: Mapped[str | None] = mapped_column(String(16), nullable=True)  # "300"=3% "10"=0.1%
     refund_price_cents: Mapped[int | None] = mapped_column(Integer, nullable=True)
     refund_profit_cents: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    # 通用佣金拆分。美团只有预估 profit;京东有预估/实际佣金。
+    estimated_commission_cents: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    actual_commission_cents: Mapped[int | None] = mapped_column(Integer, nullable=True)
 
     # 美团订单状态: 2付款 3完成 4取消 5风控 6结算
     mt_status: Mapped[str | None] = mapped_column(String(8), index=True, nullable=True)
+    # 京东订单有效码(validCode),用于判断是否有效/已完成。
+    jd_valid_code: Mapped[str | None] = mapped_column(String(16), index=True, nullable=True)
     invalid_reason: Mapped[str | None] = mapped_column(String(128), nullable=True)
     product_name: Mapped[str | None] = mapped_column(String(512), nullable=True)
+    settle_month: Mapped[str | None] = mapped_column(String(16), nullable=True)
+    site_id: Mapped[str | None] = mapped_column(String(128), nullable=True)
+    position_id: Mapped[str | None] = mapped_column(String(128), nullable=True)
+    pid: Mapped[str | None] = mapped_column(String(128), nullable=True)
+    sub_union_id: Mapped[str | None] = mapped_column(String(128), nullable=True)
 
     pay_time: Mapped[datetime | None] = mapped_column(
         DateTime(timezone=True), index=True, nullable=True
@@ -59,5 +76,6 @@ class CpsOrder(Base):
     def __repr__(self) -> str:  # pragma: no cover
         return (
             f"<CpsOrder id={self.id} order_id={self.order_id!r} "
-            f"sid={self.sid!r} status={self.mt_status} profit_cents={self.commission_cents}>"
+            f"platform={self.platform!r} sid={self.sid!r} "
+            f"status={self.mt_status or self.jd_valid_code} profit_cents={self.commission_cents}>"
         )

app/repositories/coupon_state.py

@@ -6,7 +6,7 @@
 from __future__ import annotations
 
 import logging
-from datetime import date, datetime
+from datetime import date, datetime, timezone
 from zoneinfo import ZoneInfo
 
 from sqlalchemy import delete, func, select
@@ -17,6 +17,7 @@ from app.models.coupon_state import (
     CouponClaimRecord,
     CouponDailyCompletion,
     CouponPromptEngagement,
+    CouponSession,
 )
 
 logger = logging.getLogger("shagua.coupon_state")
@@ -232,3 +233,91 @@ def sum_claimed_count(db: Session, user_id: int) -> int:
         )
     ).scalar_one()
     return int(total or 0)
+
+
+# ===== 领券任务流水(coupon_session,admin「领券数据」看板数据源)=====
+
+def upsert_coupon_session(
+    db: Session,
+    *,
+    trace_id: str,
+    device_id: str,
+    status: str,
+    started_at_ms: int,
+    user_id: int | None = None,
+    platforms: list[str] | None = None,
+    origin_package: str | None = None,
+    device_model: str | None = None,
+    rom: str | None = None,
+    app_env: str | None = None,
+    elapsed_ms: int | None = None,
+    platform_elapsed: dict | None = None,
+    claimed_count: int | None = None,
+    trace_url: str | None = None,
+) -> None:
+    """一条领券流水按 trace_id 幂等 upsert(发起 started 建行、收尾终态更新同一行)。
+
+    - 乱序/重复兜底:终态(completed/failed/abandoned)先到也建行;started 重复到不覆盖已有终态
+      (状态只前进,不降级)。
+    - started_at 由客户端墙钟毫秒转;started_date 取其 Asia/Shanghai 自然日(admin 按天聚合/筛选)。
+    - 终态帧补 finished_at=服务端 now;各字段非空才写(避免 started 帧的 None 抹掉收尾值,反之亦然)。
+    并发 IntegrityError 回滚忽略(本就幂等)。
+    """
+    started_at = datetime.fromtimestamp(started_at_ms / 1000, tz=timezone.utc)
+    started_date = started_at.astimezone(_CN_TZ).date()
+    is_terminal = status in ("completed", "failed", "abandoned")
+
+    row = db.execute(
+        select(CouponSession).where(CouponSession.trace_id == trace_id)
+    ).scalar_one_or_none()
+
+    if row is None:
+        db.add(CouponSession(
+            trace_id=trace_id,
+            device_id=device_id,
+            user_id=user_id,
+            status=status,
+            app_env=app_env,
+            platforms=platforms,
+            origin_package=origin_package,
+            device_model=device_model,
+            rom=rom,
+            started_at=started_at,
+            started_date=started_date,
+            finished_at=datetime.now(timezone.utc) if is_terminal else None,
+            elapsed_ms=elapsed_ms,
+            platform_elapsed=platform_elapsed,
+            claimed_count=claimed_count,
+            trace_url=trace_url,
+        ))
+    else:
+        # 状态只前进:started 帧重复到(如 START_STICKY 重启)不把已有终态降级回 started。
+        if not (status == "started" and row.status in ("completed", "failed", "abandoned")):
+            row.status = status
+        if is_terminal:
+            row.finished_at = datetime.now(timezone.utc)
+        if user_id is not None:
+            row.user_id = user_id
+        if platforms is not None:
+            row.platforms = platforms
+        if origin_package is not None:
+            row.origin_package = origin_package
+        if device_model is not None:
+            row.device_model = device_model
+        if rom is not None:
+            row.rom = rom
+        if app_env is not None:
+            row.app_env = app_env
+        if elapsed_ms is not None:
+            row.elapsed_ms = elapsed_ms
+        if platform_elapsed is not None:
+            row.platform_elapsed = platform_elapsed
+        if claimed_count is not None:
+            row.claimed_count = claimed_count
+        if trace_url is not None:
+            row.trace_url = trace_url
+    try:
+        db.commit()
+    except IntegrityError:
+        # 并发下另一请求刚插了同 trace_id → 唯一约束撞,回滚忽略(本就幂等)。
+        db.rollback()

app/repositories/invite.py

@@ -216,13 +216,21 @@ def try_reward_on_compare(db: Session, invitee_user_id: int) -> CompareRewardRes
 def get_stats(db: Session, inviter_id: int) -> tuple[int, int]:
     """返回 (已成功邀请人数, 累计从邀请获得的金币)。
 
+    "已邀请好友数"口径 = 完成一次比价(已触发邀请奖励金)的被邀请人数,即 compare_reward_granted=True。
+    不再数"仅绑定未比价"的关系——否则会出现"已邀请 1、可提现余额 0"(好友下载登录但没比价),
+    与产品口径"已邀请好友数 × 2元 = 累计提现 + 可提现余额"对不上。过滤后该恒等式天然成立
+    (每个计入的好友都恰好发过 1 笔 2 元,钱要么在余额要么已提现)。
+
     金币口径(inviter_coin 之和)自 v3 起恒 0(邀请人收益改走邀请奖励金,见 get_reward_stats /
     try_reward_on_compare);保留返回位兼容旧响应字段 coins_earned。
     """
     count = db.execute(
         select(func.count())
         .select_from(InviteRelation)
-        .where(InviteRelation.inviter_user_id == inviter_id)
+        .where(
+            InviteRelation.inviter_user_id == inviter_id,
+            InviteRelation.compare_reward_granted.is_(True),
+        )
     ).scalar_one()
     coins = db.execute(
         select(func.coalesce(func.sum(InviteRelation.inviter_coin), 0))
@@ -296,11 +304,186 @@ def get_invitees(
             "avatar_url": u.avatar_url or u.wechat_avatar_url or None,
             "coins": rel.inviter_coin,      # v3 起恒 0(邀请人收益改走邀请奖励金)
             "invited_at": rel.created_at,
+            # 是否已完成过一次比价(= 已发过邀请奖励金)。客户端据此:好友列表分"去提醒/邀请成功"、
+            # 在途列表只取未比价(is_compared=False)、算在途好友数与在途收益(未比价数×2元)。
+            "is_compared": bool(rel.compare_reward_granted),
         })
     has_more = offset + len(rows) < int(total)
     return items, int(total), has_more
 
 
+# ===== 开发用:塞虚拟好友(仅非生产,方便真机测在途/好友列表 UI)=====
+
+def seed_fake_invitees(db: Session, inviter_id: int, *, pending: int = 3, compared: int = 2) -> int:
+    """给 inviter 造 pending 个"未比价"+ compared 个"已比价"的虚拟被邀请好友(仅测试用)。
+
+    造真实 User(随机手机号/昵称/头像)+ InviteRelation;已比价的顺带发邀请奖励金(走真实入账,
+    这样"可提现余额/累计"也有数)。仅非生产环境开放(endpoint 层用 is_prod 挡)。返回新建好友数。
+    """
+    from datetime import datetime, timedelta, timezone
+
+    from app.repositories import user as user_repo
+
+    # 造点像样的中文昵称 + 打包进 APK 的真人头像(asset://,客户端转 file:///android_asset/ 本地加载,
+    # 离线必显、不依赖外网,避免 dicebear 这类国外图在国内加载失败成空白)。头像图见客户端
+    # app/src/main/assets/avatars/fake/p0..p7.jpg,按序号轮询分配。
+    names = ["小满同学", "一罐可乐Colour", "草原上感受宁静者", "晴天小豆", "momo", "隔壁老王",
+             "爱吃辣的猫", "月半子", "阿柴", "橘子汽水"]
+    FAKE_AVATAR_COUNT = 8  # 与客户端 assets/avatars/fake/ 图数一致
+    created = 0
+    total = pending + compared
+    now = datetime.now(timezone.utc)
+    for i in range(total):
+        is_compared = i >= pending
+        # 唯一手机号:99 开头 + 9 位随机(避开真实号段,不与真人撞)
+        phone = "99" + "".join(secrets.choice("0123456789") for _ in range(9))
+        nickname = names[i % len(names)] + secrets.choice(["", "", "_", str(secrets.randbelow(99))])
+        u = User(
+            phone=phone,
+            username=user_repo._gen_unique_username(db),
+            nickname=nickname,
+            register_channel="fake_seed",
+            avatar_url=f"asset://avatars/fake/p{i % FAKE_AVATAR_COUNT}.jpg",  # 打包头像,轮询分配
+            status="active",
+        )
+        db.add(u)
+        db.flush()  # 拿 u.id
+        rel = InviteRelation(
+            inviter_user_id=inviter_id,
+            invitee_user_id=u.id,
+            channel="fake_seed",
+            status="effective",
+            inviter_coin=0,
+            invitee_coin=0,
+            # 邀请时间错开,便于看"时间近→远"排序
+            created_at=(now - timedelta(hours=i * 6)).replace(tzinfo=None),
+        )
+        if is_compared:
+            # 已比价 → 走真实"好友比价发奖"链路:标记 + 真发 ¥2 进邀请奖励金账户(invite_cash),
+            # 让"可提现余额/累计/人数/流水/提现记录"全链路真实变化,可验证功能正确。
+            # (钱只进 invite_cash,不碰金币现金账户;清理 DELETE /seed-fake 会原路退回。)
+            rel.compare_reward_granted = True
+            rel.compare_reward_cents = rewards.INVITE_COMPARE_REWARD_CENTS
+            rel.compare_rewarded_at = now
+        db.add(rel)
+        db.flush()
+        if is_compared:
+            crud_wallet.grant_invite_cash(
+                db, inviter_id, rewards.INVITE_COMPARE_REWARD_CENTS,
+                biz_type="invite_reward", ref_id=str(u.id), remark="虚拟好友比价奖励(测试)",
+            )
+        created += 1
+    db.commit()
+    return created
+
+
+def clear_fake_invitees(db: Session, inviter_id: int) -> int:
+    """删掉该 inviter 名下所有 channel=fake_seed 的虚拟好友关系 + 对应虚拟 User(测试收尾)。
+
+    ⚠️已发过邀请奖励金的假关系(compare_reward_granted),删除时必须把当初 grant 的钱**原路退回**
+    (负数 grant_invite_cash),否则假好友清掉了、发进钱包的奖励金却残留 → invite_cash 余额脏账。
+    """
+    rels = db.execute(
+        select(InviteRelation).where(
+            InviteRelation.inviter_user_id == inviter_id,
+            InviteRelation.channel == "fake_seed",
+        )
+    ).scalars().all()
+    n = 0
+    for rel in rels:
+        # 先退钱:该关系当初发过奖励金 → 反向扣回同额,钱包不留残
+        if rel.compare_reward_granted and rel.compare_reward_cents:
+            crud_wallet.grant_invite_cash(
+                db, inviter_id, -rel.compare_reward_cents,
+                biz_type="invite_reward", ref_id=str(rel.invitee_user_id),
+                remark="虚拟好友清理·奖励金退回(测试)",
+            )
+        u = db.get(User, rel.invitee_user_id)
+        db.delete(rel)
+        if u is not None and u.register_channel == "fake_seed":
+            db.delete(u)
+        n += 1
+    db.commit()
+    return n
+
+
+def dev_reset_test_account(db: Session, phone: str) -> dict:
+    """[DEV] 把固定测试号打回"从没被邀请/没下过单"的出厂态,以便反复当新用户测发奖。
+
+    清理范围(全清,冰 2026-07-02 拍板):该 user 的
+      - invite_relation(作为被邀请人的那条 = 解 already_bound;作为邀请人的那些)
+      - invite_cash_transaction / coin_account 三个余额归零(invite_cash / coin / cash)
+      - savings_record(= 解 order/report 的 duplicated 幂等)
+      - invite_fingerprint(作为邀请人落的指纹)
+      - coin_transaction / cash_transaction / withdraw_order(彻底出厂)
+    并把 user.created_at 刷成 now(UTC)—— 骗过 bind 的"新用户 72h 窗口"闸(_is_new_user),
+    否则该号第一次跑之后 created_at 固定、过 72h 即使清了关系也会 not_eligible。
+
+    仅供 dev-reset 端点调用(端点已 is_prod→404 + 只认配置的测试号)。返回各表清理条数。
+    user 不存在(还没登录过)→ 返回全 0,不报错(下一步登录会新建,天然新号)。
+    """
+    from datetime import datetime, timezone
+
+    from app.models.invite_fingerprint import InviteFingerprint
+    from app.models.savings import SavingsRecord
+    from app.models.wallet import (
+        CashTransaction,
+        CoinAccount,
+        CoinTransaction,
+        InviteCashTransaction,
+        WithdrawOrder,
+    )
+
+    user = db.execute(select(User).where(User.phone == phone)).scalar_one_or_none()
+    if user is None:
+        return {"user_found": False}
+    uid = user.id
+
+    def _del(model, whereclause) -> int:
+        rows = db.execute(select(model).where(whereclause)).scalars().all()
+        for r in rows:
+            db.delete(r)
+        return len(rows)
+
+    cleared = {
+        "user_found": True,
+        "user_id": uid,
+        "invite_relation_as_invitee": _del(
+            InviteRelation, InviteRelation.invitee_user_id == uid
+        ),
+        "invite_relation_as_inviter": _del(
+            InviteRelation, InviteRelation.inviter_user_id == uid
+        ),
+        "invite_cash_transaction": _del(
+            InviteCashTransaction, InviteCashTransaction.user_id == uid
+        ),
+        "coin_transaction": _del(CoinTransaction, CoinTransaction.user_id == uid),
+        "cash_transaction": _del(CashTransaction, CashTransaction.user_id == uid),
+        "withdraw_order": _del(WithdrawOrder, WithdrawOrder.user_id == uid),
+        "invite_fingerprint": _del(
+            InviteFingerprint, InviteFingerprint.inviter_user_id == uid
+        ),
+        "savings_record": _del(SavingsRecord, SavingsRecord.user_id == uid),
+    }
+
+    # 余额账户归零(保留行,只清三个余额;没有账户行则跳过)
+    acc = db.get(CoinAccount, uid)
+    if acc is not None:
+        acc.invite_cash_balance_cents = 0
+        acc.coin_balance = 0
+        acc.cash_balance_cents = 0
+        cleared["coin_account_zeroed"] = True
+    else:
+        cleared["coin_account_zeroed"] = False
+
+    # 刷 created_at 骗过 72h 新用户闸(存 naive UTC,与登录新建 user 的写法一致)
+    user.created_at = datetime.now(timezone.utc).replace(tzinfo=None)
+    cleared["created_at_refreshed"] = True
+
+    db.commit()
+    return cleared
+
+
 # ===== 指纹归因(剪贴板兜底,见 [[invite-three-tasks]] 任务 3)=====
 
 def record_fingerprint(

app/repositories/wallet.py

@@ -296,6 +296,9 @@ def daily_auto_exchange(db: Session) -> dict:
     - **逐用户独立事务**:单个用户异常 rollback 不影响其他人;exchange_coins_to_cash 内部按用户 commit。
     返回统计 dict(scanned/converted/skipped_done/skipped_dust/failed/total_cents)。
     """
+    # ⚠️「今天」写死北京时(rewards.cn_today() = datetime.now(CN_TZ).date(), CN_TZ=+8),与服务器/用户
+    #   时区无关(用户 2026-07-01 硬约束:兑换一律北京 0 点日切)。**禁止**改成 date.today() / 裸
+    #   datetime.now().date()——那会跟随进程本地时区,服务器非 CST 时会在错误的"天"兑/重复兑。
     today = rewards.cn_today()
     stats = {
         "scanned": 0, "converted": 0, "skipped_done": 0,
@@ -610,6 +613,7 @@ def create_withdraw(
     source: str = "coin_cash",
     user_name: str | None = None,
     out_bill_no: str | None = None,
+    allow_sub_min: bool = False,
 ) -> WithdrawOrder:
     """发起提现:原子扣款 + 建单 reviewing(待人工审核),**不打款**。
 
@@ -619,8 +623,13 @@ def create_withdraw(
        重复发起多笔提现(审核拒绝再退回)。
     #2 out_bill_no 客户端幂等键:同号重试返回该单现状(reviewing 等审核),不重复扣款建单。
     实名 user_name 在此存下(WithdrawOrder.user_name),供异步审核打款时传给微信(达额需实名)。
+
+    allow_sub_min:放行低于"提现最低额"的小额(用于 0.01 元调试提现)。仅由 endpoint 在
+    `skip_review and not is_prod`(debug 包 + 非生产双闸)时置 True;仍受 schema gt=0 与 max 上限约束。
+    生产恒为 False → 最低额校验照常,绝不可能提 0.01。
     """
-    if amount_cents < rewards.get_withdraw_min_cents(db) or amount_cents > rewards.get_withdraw_max_cents(db):
+    min_c = 0 if allow_sub_min else rewards.get_withdraw_min_cents(db)
+    if amount_cents < min_c or amount_cents > rewards.get_withdraw_max_cents(db):
         raise InvalidWithdrawAmountError
 
     # 提现即要求已绑微信:否则审核通过也打不了款,提前拦更友好

app/schemas/coupon_state.py

@@ -49,3 +49,28 @@ class CouponStatsOut(BaseModel):
     """
 
     coupon_count: int
+
+
+class CouponSessionIn(BaseModel):
+    """客户端领券流水上报体(admin「领券数据」看板数据源,POST /api/v1/coupon/session)。
+
+    一次领券两段上报,按 trace_id upsert 到 coupon_session:
+    - 发起(status=started):带勾选平台 + 机型/ROM/app_env + started_at_ms(发起墙钟毫秒)。
+    - 收尾(completed/failed/abandoned):带 elapsed_ms(全程耗时)+ platform_elapsed(各平台耗时)+ claimed_count。
+    不鉴权(同领券循环 MVP,按 device_id/trace_id),user_id 登录态带上做留痕(可空)。
+    """
+
+    trace_id: str
+    device_id: str
+    status: str  # started / completed / failed / abandoned
+    started_at_ms: int  # 发起墙钟毫秒(客户端 System.currentTimeMillis)
+    user_id: int | None = None
+    platforms: list[str] | None = None
+    origin_package: str | None = None
+    device_model: str | None = None
+    rom: str | None = None
+    app_env: str | None = None
+    elapsed_ms: int | None = None
+    platform_elapsed: dict[str, int] | None = None
+    claimed_count: int | None = None
+    trace_url: str | None = None

app/schemas/invite.py

@@ -69,6 +69,7 @@ class InviteeItem(BaseModel):
     avatar_url: str | None = None   # 头像 URL;null = 前端画默认色块
     coins: int                      # 这次邀请给我(邀请人)发的金币
     invited_at: datetime            # 邀请绑定时间(前端转"今天/3天前")
+    is_compared: bool = False       # 该好友是否已完成过一次比价(好友列表分"去提醒/邀请成功";在途列表只取 False)
 
 
 class InviteeListOut(BaseModel):

data/media/dl.html

@@ -198,7 +198,7 @@
       选择「<span class="guide-highlight">在浏览器打开</span>」
       <span class="guide-final">在浏览器里按提示<span class="guide-target">去应用商店下载</span></span>
     </h2>
-    <div class="guide-dismiss" id="wxGuideDismiss">我知道了 ✕</div>
+    <!-- <div class="guide-dismiss" id="wxGuideDismiss">我知道了 ✕</div> -->
   </div>
 
   <div class="toast" id="toast" role="status" aria-live="polite"></div>
@@ -263,7 +263,7 @@
   var wxGuide = document.getElementById("wxGuide");
   function showWxGuide() { wxGuide.classList.add("show"); }
   function hideWxGuide() { wxGuide.classList.remove("show"); }
-  document.getElementById("wxGuideDismiss").addEventListener("click", hideWxGuide);
+  // document.getElementById("wxGuideDismiss").addEventListener("click", hideWxGuide);  // 「我知道了 ✕」已注释隐藏
   if (isWeChat) showWxGuide();   // 微信里一进页面就提示去浏览器（微信内下载必被拦）
 
   function showToast(text) {
@@ -273,15 +273,24 @@
     showToast.timer = setTimeout(function () { toast.classList.remove("show"); }, 1400);
   }
 
-  // ===== 下载按钮：微信内引导去浏览器；iOS 提示；安卓写邀请码 + 跳应用商店 =====
+  // ===== 应用商店下载：微信内引导去浏览器；iOS 提示；安卓写邀请码 + 跳应用商店 =====
   function handleDownload() {
     if (isWeChat) { showWxGuide(); return; }
     if (isIOS)    { alert("iOS 版即将上线，请前往 App Store 搜索「傻瓜比价」"); return; }
     copyInviteCode();   // 先把邀请码写进剪贴板（供 App 首启归因），链路丢了还有 landing-track 指纹兜底
     openStore();
   }
+  // ===== 官网下载：微信/iOS 同上引导；安卓直接跳 APK 直链 → 弹系统下载弹窗 =====
+  // APK_URL 跟随页面 host：本地走 LAN、生产走 app-api.shaguabijia.com（见邀请功能文档约定）。
+  var APK_URL = location.origin + "/media/shaguabijia.apk";
+  function handleWebsiteDownload() {
+    if (isWeChat) { showWxGuide(); return; }
+    if (isIOS)    { alert("iOS 版即将上线，请前往 App Store 搜索「傻瓜比价」"); return; }
+    copyInviteCode();   // 同样先写邀请码进剪贴板（供 App 首启归因）
+    window.location.href = APK_URL;
+  }
   document.getElementById("dlbtn").addEventListener("click", handleDownload);
-  document.getElementById("dlbtn2").addEventListener("click", handleDownload);
+  document.getElementById("dlbtn2").addEventListener("click", handleWebsiteDownload);
 </script>
 </body>
 </html>

deploy/daily-exchange.service

@@ -19,6 +19,9 @@ Type=oneshot
 User=root
 WorkingDirectory=/opt/shaguabijia-app-server
 Environment="PATH=/opt/shaguabijia-app-server/.venv/bin:/usr/bin:/bin"
+# 写死北京时:兑换的"当天/0 点"一律按北京时,不随服务器 OS 时区漂(用户 2026-07-01 硬约束)。
+# 脚本内的日期判断本就走 rewards.cn_today()(CN_TZ=+8),这里再把进程 TZ 也钉成北京,双保险。
+Environment="TZ=Asia/Shanghai"
 EnvironmentFile=/opt/shaguabijia-app-server/.env
 ExecStart=/opt/shaguabijia-app-server/.venv/bin/python -m scripts.daily_auto_exchange --once
 SyslogIdentifier=daily-exchange

deploy/daily-exchange.timer

@@ -4,8 +4,10 @@
 Description=Run daily auto-exchange coins->cash at midnight
 
 [Timer]
-# 每天 0 点跑。客户端文案已注明「可能存在延迟」,可按需改 00:05 错开整点扎堆。
-OnCalendar=*-*-* 00:00:00
+# 每天【北京时】0 点跑,写死时区(用户 2026-07-01 硬约束:兑换一律北京 0 点,不随服务器本地时区漂)。
+# systemd OnCalendar 支持尾缀时区;不写时区会按服务器 OS 本地时区触发 → 服务器非 CST 时会在错误时刻兑。
+# 客户端文案已注明「可能存在延迟」,可按需改 00:05 错开整点扎堆。
+OnCalendar=*-*-* 00:00:00 Asia/Shanghai
 # 服务器宕机/重启后,补跑错过的那一轮(而不是干等次日)。
 Persistent=true
 AccuracySec=1min

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

scripts/invite_reward_e2e.ps1

@@ -0,0 +1,141 @@
+# 邀请发奖真环境验证脚本(方案①:纯后端)—— PowerShell 版 ·【192 局域网 debug 环境】
+# ==============================================================================
+# 证明:好友 B 实际下单(POST /api/v1/order/report)→ 邀请人 A 到账 2 元(invite_cash),
+#       且「只绑定不下单不发」「重复不重发」「无关系不发」;并证明固定测试号 B 经
+#       dev-reset 后可【反复】当新用户,再次触发发奖。
+# 不用真下单 / 不用付钱 / 不用无障碍 / 不用第二台设备。
+#
+# 打的是本地局域网 debug 环境(默认 http://192.168.0.144:8770 = 本机 LAN IP)。
+# 两个前提:① SMS_MOCK=true(默认) → 任意 6 位验证码通过;② .env 配了
+# TEST_ACCOUNT_PHONE=11111111111 并【重启过】app-server(B 靠它免验证码 + dev-reset)。
+#
+# 用法(PowerShell):
+#   .\invite_reward_e2e.ps1                                    # 默认 192.168.0.144:8770
+#   .\invite_reward_e2e.ps1 -BaseUrl http://127.0.0.1:8770
+# ==============================================================================
+param(
+    # 目标环境:本地局域网 debug :8770(默认本机 LAN IP)
+    [string]$BaseUrl = "http://192.168.0.144:8770"
+)
+
+$ErrorActionPreference = "Stop"
+$BaseUrl = $BaseUrl.TrimEnd('/')
+
+# B 固定用测试号(免验证码 + 可 dev-reset 反复当新用户)。必须与 .env 的 TEST_ACCOUNT_PHONE 一致。
+$phoneB = "11111111111"
+# A(邀请人)/ X(无关系)用带时间戳的新号。
+$stamp  = [int][double]::Parse((Get-Date -UFormat %s))
+$suffix = ($stamp % 100000000)
+$phoneX = "139" + ("{0:D8}" -f $suffix)
+
+$expectCents = 200   # = INVITE_COMPARE_REWARD_CENTS(2 元)
+
+Write-Host "======================================================================"
+Write-Host " 邀请发奖·192 局域网 debug 验证   BASE_URL=$BaseUrl"
+Write-Host " B(固定测试号·被邀请人)=$phoneB   X(无关系·下单)=$phoneX"
+Write-Host "======================================================================"
+
+# ---- HTTP 小工具(Invoke-RestMethod 自动解析 JSON)---------------------------
+function Invoke-Api {
+    param([string]$Method, [string]$Path, $Body, [string]$Token)
+    $headers = @{ "Content-Type" = "application/json; charset=utf-8" }
+    if ($Token) { $headers["Authorization"] = "Bearer $Token" }
+    $req = @{ Method = $Method; Uri = "$BaseUrl$Path"; Headers = $headers }
+    if ($null -ne $Body) {
+        # 用 UTF8 字节发,保证「美团」等中文不乱码
+        $json = ($Body | ConvertTo-Json -Compress)
+        $req["Body"] = [System.Text.Encoding]::UTF8.GetBytes($json)
+    }
+    return Invoke-RestMethod @req
+}
+
+# 登录:发码(mock 不真发)→ 用 123456 登录 → 回 access_token
+# 唯一 device_id 避开「device_id+IP 每小时 5 次」限流(测试号 B 本不受限,统一带上无害)。
+function Login {
+    param([string]$Phone)
+    $dev = "e2e-$Phone-$stamp"
+    Invoke-Api POST "/api/v1/auth/sms/send"  @{ phone = $Phone; device_id = $dev } | Out-Null
+    $r = Invoke-Api POST "/api/v1/auth/sms/login" @{ phone = $Phone; code = "123456"; device_id = $dev }
+    if (-not $r.access_token) { throw "登录失败 phone=$Phone" }
+    return $r.access_token
+}
+
+# 把固定测试号 B 打回出厂态(清绑定/发奖/savings + 刷 created_at 骗过 72h 闸)。无需鉴权。
+function Reset-TestAccount {
+    try {
+        $r = Invoke-Api POST "/api/v1/invite/dev-reset" @{}
+    } catch {
+        throw "dev-reset 失败:$($_.Exception.Message)  (检查 app-server 是否用最新代码重启?.env 是否配了 TEST_ACCOUNT_PHONE 并重启?)"
+    }
+    if ($r.status -ne "ok") { throw "dev-reset 返回非 ok:$($r | ConvertTo-Json -Compress)" }
+}
+
+function Get-Reward   { param([string]$Tok) (Invoke-Api GET "/api/v1/invite/me" $null $Tok).reward_balance_cents }
+function Get-MyCode   { param([string]$Tok) (Invoke-Api GET "/api/v1/invite/me" $null $Tok).invite_code }
+function Bind-To      { param([string]$Tok,[string]$Code) Invoke-Api POST "/api/v1/invite/bind" @{ invite_code = $Code } $Tok }
+function Report-Order {
+    param([string]$Tok,[string]$EventId)
+    Invoke-Api POST "/api/v1/order/report" @{
+        client_event_id     = $EventId
+        platform            = "美团"
+        pay_channel         = "wechat"
+        compared_price_cents = 2016
+        paid_amount_cents    = 2016
+    } $Tok | Out-Null
+}
+
+# ---- 断言 -------------------------------------------------------------------
+$script:pass = 0; $script:fail = 0
+function Assert-Eq {
+    param($Expected, $Actual, [string]$Desc)
+    if ("$Expected" -eq "$Actual") { Write-Host "  ✓ $Desc (=$Actual)"; $script:pass++ }
+    else { Write-Host "  ✗ $Desc  期望=$Expected 实得=$Actual" -ForegroundColor Red; $script:fail++ }
+}
+
+# ---- 一轮完整发奖验证:reset B → 新 A 绑定 → B 下单 → A 到账 -----------------
+function Invoke-RewardCycle {
+    param([int]$Tag)
+    $phoneA = "138" + ("{0:D8}" -f (($suffix + $Tag) % 100000000))
+    Write-Host "`n===== 第 $Tag 轮:A=$phoneA 邀请固定号 B=$phoneB ====="
+
+    Reset-TestAccount                               # 把 B 打回新用户态
+    $tokA = Login $phoneA
+    $tokB = Login $phoneB
+    $codeA = Get-MyCode $tokA
+    Write-Host "  A 邀请码=$codeA;B 已 dev-reset 回新用户"
+
+    Assert-Eq 0 (Get-Reward $tokA) "[$Tag] 发奖前 A.invite_cash"
+
+    $bind = Bind-To $tokB $codeA
+    Write-Host "  bind → status=$($bind.status)(期望 success)"
+    Assert-Eq 0 (Get-Reward $tokA) "[$Tag] 仅绑定后 A.invite_cash(绑定不发)"
+
+    Report-Order $tokB "evt-$stamp-$Tag-1"
+    Assert-Eq $expectCents (Get-Reward $tokA) "[$Tag] B 首单后 A.invite_cash(下单才发)"
+
+    Report-Order $tokB "evt-$stamp-$Tag-1"   # 重复同 event
+    Report-Order $tokB "evt-$stamp-$Tag-2"   # 不同 event 第二笔
+    Assert-Eq $expectCents (Get-Reward $tokA) "[$Tag] B 重复/多次上报后 A.invite_cash(只发一次)"
+}
+
+# ============================== 开跑 =========================================
+# 第 1、2 轮:同一个固定号 B 反复当新用户各拿一次发奖(证明 dev-reset 让它可反复用)。
+Invoke-RewardCycle 1
+Invoke-RewardCycle 2
+
+# 无关系用户下单 → 不发奖
+Write-Host "`n===== 无关系校验:X 没绑定任何人,下单不应发奖 ====="
+$tokX = Login $phoneX
+Report-Order $tokX "evt-$stamp-x"
+Assert-Eq 0 (Get-Reward $tokX) "无邀请关系 X 下单后 X.invite_cash(不发)"
+
+# ============================== 结果 =========================================
+Write-Host "`n======================================================================"
+if ($script:fail -eq 0) {
+    Write-Host " ✅ 全部通过($script:pass 项):下单才发奖 / 绑定不发 / 重复不重发 / 无关系不发" -ForegroundColor Green
+    Write-Host "    且固定号 B 经 dev-reset 后【反复】当新用户两轮均发奖成功。" -ForegroundColor Green
+    exit 0
+} else {
+    Write-Host " ❌ 有 $($script:fail) 项未通过(通过 $($script:pass) 项)。看上面 ✗ 行。" -ForegroundColor Red
+    exit 1
+}

scripts/invite_reward_e2e.sh

@@ -0,0 +1,160 @@
+#!/usr/bin/env bash
+# 邀请发奖真环境验证脚本(方案①:纯后端 curl)——【192 局域网 debug 包环境】
+# ------------------------------------------------------------------------------
+# 证明:好友 B 实际下单(POST /api/v1/order/report)→ 邀请人 A 到账 2 元(invite_cash),
+#       且「只绑定不下单不发」「重复上报不重发」「无邀请关系不发」;
+#       并证明固定测试号 B 经 dev-reset 后可【反复】当新用户,再次触发发奖。
+# 不用真下单 / 不用付钱 / 不用无障碍 / 不用第二台设备。
+#
+# 打的是本地局域网 debug 环境(默认 http://192.168.0.144:8770 = 本机 LAN IP)。
+# 两个前提(不满足脚本白跑):
+#   ① SMS_MOCK=true(默认即是)→ /sms/login 放行任意 6 位验证码,故用 123456 拿 token。
+#   ② .env 里配了 TEST_ACCOUNT_PHONE=11111111111 并【重启过】app-server —— B 用它免验证码
+#      登录,且脚本靠 POST /invite/dev-reset 每轮把它打回新用户态。
+#
+# 用法:
+#   ./invite_reward_e2e.sh                              # 用默认 192.168.0.144:8770
+#   ./invite_reward_e2e.sh http://192.168.0.144:8770   # 位置参数传 base
+#   BASE_URL=http://127.0.0.1:8770 ./invite_reward_e2e.sh
+# 依赖:仅 curl(JSON 用 grep/sed 抽字段,不依赖 python/jq —— Windows Git Bash 里
+#       python3 常是 WindowsApps 假 stub,故意不用)。
+# ==============================================================================
+set -euo pipefail
+
+# ---- 目标环境:本地局域网 debug :8770(改成你的开发机内网 IP)------------------
+BASE_URL="${1:-${BASE_URL:-http://192.168.0.144:8770}}"
+BASE_URL="${BASE_URL%/}"   # 去掉结尾多余的 /
+
+# B 固定用测试号(免验证码 + 可 dev-reset 反复当新用户)。必须与 .env 的 TEST_ACCOUNT_PHONE 一致。
+PHONE_B="11111111111"
+
+# A(邀请人)/ X(无关系)每轮用带时间戳的新号:A 需从 0 余额验起、X 只要没关系即可。
+STAMP="$(date +%s)"
+SUFFIX="${STAMP: -8}"
+PHONE_X="139${SUFFIX}"
+
+EXPECT_CENTS=200   # = INVITE_COMPARE_REWARD_CENTS(2 元)
+
+echo "======================================================================"
+echo " 邀请发奖·192 局域网 debug 验证   BASE_URL=$BASE_URL"
+echo " B(固定测试号·被邀请人)=$PHONE_B   X(无关系·下单)=$PHONE_X"
+echo "======================================================================"
+
+# ---- 小工具:从 JSON 取字段(纯 grep/sed,不依赖 python/jq)------------------
+# 用法:  echo "$json" | jget access_token
+# 支持字符串值("key":"val")与数字值("key":123);只取顶层首个匹配,够本脚本用。
+jget() {
+  local key="$1" body; body="$(cat)"
+  local v
+  v="$(printf '%s' "$body" | grep -o "\"$key\"[[:space:]]*:[[:space:]]*\"[^\"]*\"" | head -1 | sed -E "s/.*:[[:space:]]*\"([^\"]*)\"/\1/")"
+  if [ -n "$v" ]; then printf '%s' "$v"; return; fi
+  printf '%s' "$body" | grep -o "\"$key\"[[:space:]]*:[[:space:]]*-\?[0-9]\+" | head -1 | sed -E "s/.*:[[:space:]]*(-?[0-9]+)/\1/"
+}
+
+# ---- POST JSON:body 走 stdin + --data-binary,不内联 -d --------------------
+# ⚠️ Windows Git Bash 里内联 -d "{...美团...}" 会把中文 UTF-8 字节搞乱 → 后端
+#    "error parsing the body"。把 body 从 stdin 以原始字节喂进去可避开。
+post_json() {
+  local path="$1" token="$2"
+  local auth=()
+  [ -n "$token" ] && auth=(-H "Authorization: Bearer $token")
+  curl -sS -X POST "$BASE_URL$path" \
+       -H 'Content-Type: application/json' "${auth[@]}" \
+       --data-binary @-
+}
+
+# ---- 登录:发码(mock 不真发)→ 用 123456 登录 → 回 access_token -----------
+# 每个号带唯一 device_id(=phone+stamp):登录/发码限流是「device_id+IP 每小时 5 次」,
+# 空 device_id 会让本机所有请求挤同一桶,自己把自己限流掉。给唯一 id 各走各的桶。
+# (测试号 B 本就不受该限流约束,但带上 device_id 无害、统一处理。)
+login() {
+  local phone="$1"
+  local dev="e2e-${phone}-${STAMP}"
+  post_json /api/v1/auth/sms/send "" <<< "{\"phone\":\"$phone\",\"device_id\":\"$dev\"}" >/dev/null
+  local resp
+  resp="$(post_json /api/v1/auth/sms/login "" <<< "{\"phone\":\"$phone\",\"code\":\"123456\",\"device_id\":\"$dev\"}")"
+  local tok; tok="$(printf '%s' "$resp" | jget access_token)"
+  if [ -z "$tok" ]; then
+    echo "✗ 登录失败 phone=$phone,响应:$resp" >&2
+    exit 1
+  fi
+  printf '%s' "$tok"
+}
+
+# 把固定测试号 B 打回出厂态(清绑定/发奖/savings + 刷 created_at 骗过 72h 闸)。无需鉴权。
+dev_reset() {
+  local resp; resp="$(post_json /api/v1/invite/dev-reset "" <<< '{}')"
+  if [ "$(printf '%s' "$resp" | jget status)" != "ok" ]; then
+    echo "✗ dev-reset 失败,响应:$resp" >&2
+    echo "  (检查:app-server 是否已用最新代码重启?.env 是否配了 TEST_ACCOUNT_PHONE 并重启?)" >&2
+    exit 1
+  fi
+}
+
+# GET /invite/me 的某个字段(邀请码 / 奖励金余额都从这里读)
+invite_me() { curl -sS "$BASE_URL/api/v1/invite/me" -H "Authorization: Bearer $1"; }
+my_code()   { invite_me "$1" | jget invite_code; }
+reward()    { invite_me "$1" | jget reward_balance_cents; }
+
+bind_to()   { post_json /api/v1/invite/bind "$1" <<< "{\"invite_code\":\"$2\"}"; }
+report_order() {
+  post_json /api/v1/order/report "$1" <<< "{\"client_event_id\":\"$2\",\"platform\":\"美团\",\"pay_channel\":\"wechat\",\"compared_price_cents\":2016,\"paid_amount_cents\":2016}"
+}
+
+# ---- 断言 -------------------------------------------------------------------
+PASS=0; FAIL=0
+assert_eq() { # 期望 实得 说明
+  if [ "$1" = "$2" ]; then echo "  ✓ $3 (=$2)"; PASS=$((PASS+1));
+  else echo "  ✗ $3  期望=$1 实得=$2"; FAIL=$((FAIL+1)); fi
+}
+
+# ---- 一轮完整发奖验证:reset B → 新 A 绑定 → B 下单 → A 到账 -----------------
+# $1=轮次标签(用于 event_id 唯一 + 展示)。A 每轮用不同新号(从 0 验起)。
+run_reward_cycle() {
+  local tag="$1"
+  local phone_a="138$(printf '%08d' $(( (10#$SUFFIX + tag) % 100000000 )) )"
+  echo; echo "===== 第 $tag 轮:A=$phone_a 邀请固定号 B=$PHONE_B ====="
+
+  dev_reset                                            # 把 B 打回新用户态
+  local tok_a tok_b code_a
+  tok_a="$(login "$phone_a")"
+  tok_b="$(login "$PHONE_B")"
+  code_a="$(my_code "$tok_a")"
+  echo "  A 邀请码=$code_a;B 已 dev-reset 回新用户"
+
+  assert_eq 0 "$(reward "$tok_a")" "[$tag] 发奖前 A.invite_cash"
+
+  local bind_resp; bind_resp="$(bind_to "$tok_b" "$code_a")"
+  echo "  bind → status=$(printf '%s' "$bind_resp" | jget status)(期望 success)"
+  assert_eq 0 "$(reward "$tok_a")" "[$tag] 仅绑定后 A.invite_cash(绑定不发)"
+
+  report_order "$tok_b" "evt-$STAMP-$tag-1" >/dev/null
+  assert_eq "$EXPECT_CENTS" "$(reward "$tok_a")" "[$tag] B 首单后 A.invite_cash(下单才发)"
+
+  report_order "$tok_b" "evt-$STAMP-$tag-1" >/dev/null   # 重复同 event
+  report_order "$tok_b" "evt-$STAMP-$tag-2" >/dev/null   # 不同 event 的第二笔
+  assert_eq "$EXPECT_CENTS" "$(reward "$tok_a")" "[$tag] B 重复/多次上报后 A.invite_cash(只发一次)"
+}
+
+# ============================== 开跑 =========================================
+# 第 1、2 轮:同一个固定号 B 反复当新用户各拿一次发奖(证明 dev-reset 让它可反复用)。
+run_reward_cycle 1
+run_reward_cycle 2
+
+# 无关系用户下单 → 不发奖
+echo; echo "===== 无关系校验:X 没绑定任何人,下单不应发奖 ====="
+TOK_X="$(login "$PHONE_X")"
+report_order "$TOK_X" "evt-$STAMP-x" >/dev/null
+assert_eq 0 "$(reward "$TOK_X")" "无邀请关系 X 下单后 X.invite_cash(不发)"
+
+# ============================== 结果 =========================================
+echo
+echo "======================================================================"
+if [ "$FAIL" -eq 0 ]; then
+  echo " ✅ 全部通过($PASS 项):下单才发奖 / 绑定不发 / 重复不重发 / 无关系不发"
+  echo "    且固定号 B 经 dev-reset 后【反复】当新用户两轮均发奖成功。"
+  exit 0
+else
+  echo " ❌ 有 $FAIL 项未通过(通过 $PASS 项)。看上面 ✗ 行。"
+  exit 1
+fi

scripts/publish_apk.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# 编 release 正式包并发布到官网下载位 data/media/shaguabijia.apk。
+#
+# 背景:落地页 dl.html「官网下载」按钮指向 /media/shaguabijia.apk(见 app/main.py download_apk 路由)。
+# 该 apk 不入 git(.gitignore 忽略 *.apk),也没有 CI 自动放 —— 以前全靠手动 cp,常忘/放成 debug 包。
+# 本脚本把"编 release + 放到位"固化成一条命令。发版时跑一次即可。
+#
+# 用法:  bash scripts/publish_apk.sh
+# 产物:  <app-server>/data/media/shaguabijia.apk(release 签名、指向生产后端的正式包)
+#
+# 注意:① 需要 app/jishisongfu-release.jks 存在(release 签名,仅 CTO 持有);缺失会编译失败。
+#       ② 服务器部署不在本脚本职责内 —— 它只把 apk 放到本仓 data/media/;上线由部署流程把
+#          data/media/ 同步到生产(或 nginx serve 同目录)。
+set -euo pipefail
+
+# 路径全部相对脚本位置算,跟 CWD 无关。
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SERVER_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+ANDROID_DIR="$(cd "$SERVER_DIR/../shaguabijia-app-android" && pwd)"
+DEST="$SERVER_DIR/data/media/shaguabijia.apk"
+APK_OUT="$ANDROID_DIR/app/build/outputs/apk/release/app-release.apk"
+
+# Android Studio 自带 JBR(本机构建环境约定)。已设 JAVA_HOME 则尊重现有值。
+export JAVA_HOME="${JAVA_HOME:-D:/android-studio/jbr}"
+
+echo "[publish_apk] Android 工程: $ANDROID_DIR"
+if [ ! -f "$ANDROID_DIR/app/jishisongfu-release.jks" ]; then
+  echo "[publish_apk] ✗ 缺 app/jishisongfu-release.jks(release 签名),无法出正式包。" >&2
+  exit 1
+fi
+
+echo "[publish_apk] 编 release 包(assembleRelease,R8+release 签名,BASE_URL=生产)…"
+( cd "$ANDROID_DIR" && ./gradlew :app:assembleRelease )
+
+if [ ! -f "$APK_OUT" ]; then
+  echo "[publish_apk] ✗ 没找到产物 $APK_OUT" >&2
+  exit 1
+fi
+
+mkdir -p "$(dirname "$DEST")"
+cp "$APK_OUT" "$DEST"
+SIZE_MB=$(( $(wc -c < "$DEST") / 1024 / 1024 ))
+echo "[publish_apk] ✓ 已发布 → $DEST (${SIZE_MB}MB)"
+echo "[publish_apk]   官网下载链接(生产):https://app-api.shaguabijia.com/media/shaguabijia.apk"
+echo "[publish_apk]   部署:把 data/media/ 同步到生产服务器(本脚本不负责上线)。"

tests/test_admin_read.py

@@ -66,6 +66,7 @@ def test_dashboard_overview(admin_client: TestClient, admin_token: str) -> None:
     assert "success_rate" in data["comparison"]
     assert data["cps"]["available"] is True
     assert "meituan_order_count" in data["cps"]
+    assert "jd_order_count" in data["cps"]
 
 
 def test_user_list_and_detail(admin_client: TestClient, admin_token: str) -> None:

tests/test_cps_admin.py

@@ -11,6 +11,7 @@ from app.admin.repositories import admin_user as admin_repo
 from app.admin.repositories import cps as cps_repo
 from app.db.session import SessionLocal
 from app.models.cps_link import CpsClick
+from app.models.cps_order import CpsOrder
 from app.models.cps_wx_user import CpsWxUser
 from app.repositories import cps_link as cps_link_repo
 
@@ -180,3 +181,73 @@ def test_day_users_cross_year(admin_client: TestClient, admin_token: str) -> Non
     assert len(users) == 1
     assert users[0]["openid"] == openid
     assert users[0]["visit_count"] == 5  # 次年 01-01 那条被时间窗排除
+
+
+def test_jd_reconcile_updates_dashboard(
+    admin_client: TestClient, admin_token: str, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """京东拉单:按订单行入库;大盘只统计有效 validCode 的佣金。"""
+
+    def fake_query_order_rows(**kwargs):
+        start = kwargs["start_time"].astimezone(_BJ)
+        if start.hour != 10 or kwargs["page_index"] != 1:
+            return {"rows": [], "has_more": False}
+        return {
+            "rows": [
+                {
+                    "id": "pytest-jd-row-valid",
+                    "orderId": "pytest-jd-order-1",
+                    "skuId": "sku-1",
+                    "skuName": "京东测试商品",
+                    "orderTime": "2026-06-25 10:10:00",
+                    "modifyTime": "2026-06-25 10:20:00",
+                    "validCode": "16",
+                    "estimateCosPrice": "19.90",
+                    "estimateFee": "1.23",
+                    "actualFee": "2.34",
+                    "commissionRate": "10.00",
+                },
+                {
+                    "id": "pytest-jd-row-invalid",
+                    "orderId": "pytest-jd-order-2",
+                    "skuId": "sku-2",
+                    "skuName": "京东无效订单",
+                    "orderTime": "2026-06-25 10:15:00",
+                    "modifyTime": "2026-06-25 10:25:00",
+                    "validCode": "4",
+                    "estimateCosPrice": "9.90",
+                    "estimateFee": "0.50",
+                    "commissionRate": "5.00",
+                },
+            ],
+            "has_more": False,
+        }
+
+    monkeypatch.setattr("app.integrations.jd_union.query_order_rows", fake_query_order_rows)
+    r = admin_client.post(
+        "/admin/api/cps/orders/reconcile",
+        params={
+            "platform": "jd",
+            "date_from": "2026-06-25",
+            "date_to": "2026-06-25",
+            "query_time_type": 1,
+        },
+        headers=_auth(admin_token),
+    )
+    assert r.status_code == 200, r.text
+    assert r.json()["fetched"] == 2
+
+    with SessionLocal() as db:
+        rows = db.query(CpsOrder).filter(CpsOrder.platform == "jd").all()
+        assert len([o for o in rows if o.order_id.startswith("jd:pytest-jd-row")]) == 2
+
+    overview = admin_client.get(
+        "/admin/api/stats/overview",
+        params={"date_from": "2026-06-25", "date_to": "2026-06-25"},
+        headers=_auth(admin_token),
+    )
+    assert overview.status_code == 200, overview.text
+    cps = overview.json()["cps"]
+    assert cps["jd_order_count"] >= 1
+    assert cps["jd_commission_cents"] >= 234
+    assert cps["jd_invalid_count"] >= 1

tests/test_daily_exchange_timezone.py

@@ -0,0 +1,82 @@
+"""金币→现金「每日自动兑」时区回归测试。
+
+用户 2026-07-01 硬约束:不管服务器 / 用户设成什么时区,兑换一律按【北京时 0 点】日切。
+本测试锁死这个行为,防以后有人把 rewards.cn_today() 改回 date.today() / 裸 datetime.now()
+(那会跟随进程本地时区,服务器非 CST 时在错误的"天"兑或重复兑)。
+"""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from app.core import rewards
+from app.core.rewards import COIN_PER_CENT
+from app.db.session import SessionLocal
+from app.repositories import wallet as crud_wallet
+from app.repositories.user import get_user_by_phone
+
+
+def _login(client, phone: str) -> str:
+    client.post("/api/v1/auth/sms/send", json={"phone": phone})
+    r = client.post("/api/v1/auth/sms/login", json={"phone": phone, "code": "123456"})
+    assert r.status_code == 200, r.text
+    return r.json()["access_token"]
+
+
+def test_cn_today_is_beijing_date_regardless_of_utc_offset() -> None:
+    """cn_today() 恒等于北京时的日期,与 UTC / 进程本地时区无关。
+
+    取一个 UTC 与北京跨天的时刻(北京已是次日 0 点后、UTC 还在前一天)验证:
+    2026-07-01 15:30 UTC = 2026-07-01 23:30 北京(同一天);
+    2026-07-01 17:30 UTC = 2026-07-02 01:30 北京(北京已跨天)。
+    """
+    cst = timezone(rewards.CN_TZ.utcoffset(None))
+    # UTC 17:30 → 北京次日 01:30:北京日期应是 07-02
+    moment_utc = datetime(2026, 7, 1, 17, 30, tzinfo=timezone.utc)
+    assert moment_utc.astimezone(cst).date().isoformat() == "2026-07-02"
+    # 反过来 UTC 23:30 → 北京 07:30 次日:北京日期 07-02(证明 +8 偏移生效)
+    moment_utc2 = datetime(2026, 7, 1, 23, 30, tzinfo=timezone.utc)
+    assert moment_utc2.astimezone(cst).date().isoformat() == "2026-07-02"
+    # cn_today() 的实现就是 datetime.now(CN_TZ).date():与 UTC now 的北京投影一致
+    assert rewards.cn_today() == datetime.now(timezone.utc).astimezone(cst).date()
+
+
+def test_daily_auto_exchange_idempotent_within_same_beijing_day(client) -> None:
+    """同一北京日内多次触发只兑一次(幂等键 = 当天是否已有 exchange_in 北京日流水)。"""
+    token = _login(client, "13800007701")
+    assert token
+    with SessionLocal() as db:
+        user = get_user_by_phone(db, "13800007701")
+        assert user is not None
+        # 给 200 金币(= 2 分),够到分兑换
+        crud_wallet.grant_coins(db, user.id, 200, biz_type="test_grant")
+        db.commit()
+
+        first = crud_wallet.daily_auto_exchange(db)
+        assert first["converted"] == 1, first
+        assert first["total_cents"] == 2, first
+
+        # 当天再进账 200 金币,再触发一轮:因当天已有 exchange_in(北京日幂等键)→ 跳过,
+        # 不重复兑(这 200 留到次日北京 0 点)。若幂等键被改成本地时区,服务器非 CST 时这里会误兑。
+        crud_wallet.grant_coins(db, user.id, 200, biz_type="test_grant")
+        db.commit()
+        second = crud_wallet.daily_auto_exchange(db)
+        assert second["converted"] == 0, second
+        assert second["skipped_done"] >= 1, second
+
+
+def test_has_exchange_in_on_keyed_on_given_beijing_day(client) -> None:
+    """_has_exchange_in_on 以传入的北京日为界比较 [当天0点, 次日0点)。"""
+    token = _login(client, "13800007702")
+    assert token
+    with SessionLocal() as db:
+        user = get_user_by_phone(db, "13800007702")
+        assert user is not None
+        crud_wallet.grant_coins(db, user.id, 200, biz_type="test_grant")
+        db.commit()
+        crud_wallet.daily_auto_exchange(db)
+
+        today = rewards.cn_today()
+        assert crud_wallet._has_exchange_in_on(db, user.id, today) is True
+        # 昨天(北京日)不该命中今天兑的流水
+        yesterday = today.fromordinal(today.toordinal() - 1)
+        assert crud_wallet._has_exchange_in_on(db, user.id, yesterday) is False

tests/test_invite.py

@@ -73,9 +73,11 @@ def test_bind_flow_no_coins_either_side(client) -> None:
     assert _coin_balance(client, b) == 0
     assert _coin_balance(client, a) == 0
 
-    # A 的战绩:已邀 1 人;金币口径收益恒 0(邀请人收益走邀请奖励金,见 try_reward_on_compare)
+    # A 的战绩:此时 invited_count=0 —— 口径 = "完成过一次比价的好友数"(compare_reward_granted=True),
+    # 仅绑定未比价不计入(否则会出现"已邀 1、可提现余额 0",与产品口径"已邀×2=累计提现+余额"对不上;
+    # 见 get_stats 注释 + 需求 spec"邀请好友人数=邀请的完成一次比价的新用户数量")。金币口径收益恒 0。
     r = client.get("/api/v1/invite/me", headers=_auth(a))
-    assert r.json()["invited_count"] == 1
+    assert r.json()["invited_count"] == 0
     assert r.json()["coins_earned"] == 0
 
 
@@ -322,6 +324,8 @@ def test_invitees_basic(client) -> None:
     assert all(it["avatar_url"] is None for it in body["items"])
     # v2:绑定时邀请人那份为 0(收益改"好友比价才发奖"),故每条 coins 字段=0
     assert all(it["coins"] == 0 for it in body["items"])
+    # 刚绑定还没比价 → is_compared 全 False(客户端据此:在途列表取这些、好友列表按钮"去提醒")
+    assert all(it["is_compared"] is False for it in body["items"])
 
 
 def test_invitees_order_desc(client) -> None:

tests/test_invite_compare_reward.py

@@ -1,5 +1,8 @@
-"""邀请 v3 比价发奖测试:好友完成成功比价 → 邀请人得邀请奖励金(独立账户),幂等只发一次,
+"""邀请 v3 发奖测试:好友完成比价【并实际下单】→ 邀请人得邀请奖励金(独立账户),幂等只发一次,
 账户隔离不串金币/现金。被邀请人绑定不得任何奖励由 test_invite.py 覆盖。
+
+⚠️ 触发口径(冰拍板):被邀请人仅完成比价【不】发奖,须实际下单(客户端归因后 POST
+/api/v1/order/report)才发。故本文件用下单上报驱动发奖,而非比价上报。
 """
 from __future__ import annotations
 
@@ -30,10 +33,17 @@ def _bind(client, token: str, code: str):
     return client.post("/api/v1/invite/bind", json={"invite_code": code}, headers=_auth(token))
 
 
-def _report_compare(client, token: str, trace_id: str, status: str = "success"):
+def _report_order(client, token: str, event_id: str):
+    """上报一笔归因订单(视为实际下单)→ 触发邀请发奖。event_id 为幂等键。"""
     return client.post(
-        "/api/v1/compare/record",
-        json={"trace_id": trace_id, "status": status},
+        "/api/v1/order/report",
+        json={
+            "client_event_id": event_id,
+            "platform": "美团",
+            "pay_channel": "wechat",
+            "compared_price_cents": 2016,
+            "paid_amount_cents": 2016,
+        },
         headers=_auth(token),
     )
 
@@ -46,58 +56,80 @@ def _invite_cash(phone: str) -> int:
         return acc.invite_cash_balance_cents if acc else 0
 
 
-def test_compare_reward_granted_to_inviter(client) -> None:
-    """B 被 A 邀请后完成一次成功比价 → A 得邀请奖励金 2 元(独立账户),B 不得该奖。"""
+def test_order_reward_granted_to_inviter(client) -> None:
+    """B 被 A 邀请后实际下单一笔 → A 得邀请奖励金 2 元(独立账户),B 不得该奖。"""
     a = _login(client, "13800003001")
     b = _login(client, "13800003002")
     _bind(client, b, _my_code(client, a))
 
     assert _invite_cash("13800003001") == 0                            # 发奖前
 
-    r = _report_compare(client, b, "trace-reward-1")
+    r = _report_order(client, b, "evt-reward-1")
     assert r.status_code == 200, r.text
 
     assert _invite_cash("13800003001") == INVITE_COMPARE_REWARD_CENTS  # 邀请人到账
     assert _invite_cash("13800003002") == 0                            # 被邀请人不得此奖
 
 
-def test_compare_reward_idempotent(client) -> None:
-    """好友比价多次 → 只发一次(compare_reward_granted 幂等)。"""
+def test_order_reward_idempotent(client) -> None:
+    """好友下单多次 → 只发一次(compare_reward_granted 幂等)。"""
     a = _login(client, "13800003003")
     b = _login(client, "13800003004")
     _bind(client, b, _my_code(client, a))
 
-    _report_compare(client, b, "trace-idem-1")
-    _report_compare(client, b, "trace-idem-2")    # 第二次比价(不同 trace)
-    _report_compare(client, b, "trace-idem-1")    # 重复上报同 trace
+    _report_order(client, b, "evt-idem-1")
+    _report_order(client, b, "evt-idem-2")    # 第二笔下单(不同 event)
+    _report_order(client, b, "evt-idem-1")    # 重复上报同 event
 
     assert _invite_cash("13800003003") == INVITE_COMPARE_REWARD_CENTS  # 仍只发一次
 
 
-def test_compare_no_relation_no_reward(client) -> None:
-    """没有邀请关系的人比价 → 不发奖(没人是他的邀请人)。"""
+def test_invitees_is_compared_flag_flips_after_order(client) -> None:
+    """好友列表 is_compared:好友下单前 False(在途/去提醒)、下单后 True(邀请成功)。"""
+    a = _login(client, "13800003021")
+    b = _login(client, "13800003022")
+    _bind(client, b, _my_code(client, a))
+    with SessionLocal() as db:
+        b_name = get_user_by_phone(db, "13800003022").nickname
+
+    def _b_item():
+        items = client.get("/api/v1/invite/invitees", headers=_auth(a)).json()["items"]
+        return next(it for it in items if it["display_name"] == b_name)
+
+    assert _b_item()["is_compared"] is False           # 下单前:未完成(在途 / 去提醒)
+    _report_order(client, b, "evt-flag-1")              # B 实际下单一笔
+    assert _b_item()["is_compared"] is True            # 下单后:已完成(邀请成功)
+
+
+def test_order_no_relation_no_reward(client) -> None:
+    """没有邀请关系的人下单 → 不发奖(没人是他的邀请人)。"""
     x = _login(client, "13800003005")
-    r = _report_compare(client, x, "trace-norel-1")
+    r = _report_order(client, x, "evt-norel-1")
     assert r.status_code == 200, r.text
     assert _invite_cash("13800003005") == 0
 
 
-def test_compare_failed_no_reward(client) -> None:
-    """失败的比价(status=failed)不触发发奖。"""
+def test_compare_alone_no_reward(client) -> None:
+    """仅完成比价、未下单 → 不触发发奖(新口径:比价不再发奖)。"""
     a = _login(client, "13800003006")
     b = _login(client, "13800003007")
     _bind(client, b, _my_code(client, a))
 
-    _report_compare(client, b, "trace-fail-1", status="failed")
-    assert _invite_cash("13800003006") == 0
+    r = client.post(
+        "/api/v1/compare/record",
+        json={"trace_id": "trace-noorder-1", "status": "success"},
+        headers=_auth(b),
+    )
+    assert r.status_code == 200, r.text
+    assert _invite_cash("13800003006") == 0            # 只比价没下单:不发奖
 
 
-def test_compare_reward_isolated_from_coin_cash(client) -> None:
+def test_order_reward_isolated_from_coin_cash(client) -> None:
     """账户隔离:邀请奖励金进 invite_cash,不串 cash_balance_cents;流水落 invite_cash_transaction。"""
     a = _login(client, "13800003008")
     b = _login(client, "13800003009")
     _bind(client, b, _my_code(client, a))
-    _report_compare(client, b, "trace-iso-1")
+    _report_order(client, b, "evt-iso-1")
 
     with SessionLocal() as db:
         ua = get_user_by_phone(db, "13800003008")
@@ -112,3 +144,48 @@ def test_compare_reward_isolated_from_coin_cash(client) -> None:
         ).scalars().all()
         assert len(txns) == 1
         assert txns[0].amount_cents == INVITE_COMPARE_REWARD_CENTS
+
+
+def test_dev_reset_makes_test_account_fresh_again(client, monkeypatch) -> None:
+    """dev-reset 让固定测试号 B 可【反复】当新用户:发奖 → reset → 换个邀请人再发奖成功。
+
+    验证 POST /api/v1/invite/dev-reset(方案 B)把 B 的 invite_relation / invite_cash /
+    savings 清掉并刷 created_at,于是它能再次绑定 + 下单触发第二次发奖(第一次的 already_bound /
+    savings 幂等 / 72h 闸都被 reset 解除)。
+    """
+    from app.core.config import settings
+
+    test_phone = "11111111111"
+    # 端点按 settings.test_account_phone 认号 → 用 monkeypatch 在本用例内启用该测试号
+    monkeypatch.setattr(settings, "TEST_ACCOUNT_PHONE", test_phone)
+
+    a1 = _login(client, "13800003101")
+    b = _login(client, test_phone)
+
+    # 第一轮:B 绑 A1 → 下单 → A1 得奖
+    assert _bind(client, b, _my_code(client, a1)).json()["status"] == "success"
+    _report_order(client, b, "evt-reset-r1")
+    assert _invite_cash("13800003101") == INVITE_COMPARE_REWARD_CENTS
+    assert _invite_cash(test_phone) == 0                      # 被邀请人 B 不得此奖
+
+    # dev-reset:把 B 打回出厂态(无需鉴权)
+    r = client.post("/api/v1/invite/dev-reset")
+    assert r.status_code == 200, r.text
+    body = r.json()
+    assert body["status"] == "ok" and body["phone"] == test_phone
+    assert body["cleared"]["invite_relation_as_invitee"] == 1  # 上一轮那条被邀请关系被清
+
+    # 第二轮:同一个 B 绑【另一个】邀请人 A2 → 下单 → A2 也得奖(证明 B 又是新用户了)
+    a2 = _login(client, "13800003102")
+    assert _bind(client, b, _my_code(client, a2)).json()["status"] == "success"  # 不再 already_bound
+    _report_order(client, b, "evt-reset-r2")
+    assert _invite_cash("13800003102") == INVITE_COMPARE_REWARD_CENTS  # 第二个邀请人到账
+
+
+def test_dev_reset_blocked_when_test_account_disabled(client, monkeypatch) -> None:
+    """测试号总开关没配(TEST_ACCOUNT_PHONE 空)→ dev-reset 返回 400(功能未启用)。"""
+    from app.core.config import settings
+
+    monkeypatch.setattr(settings, "TEST_ACCOUNT_PHONE", "")
+    r = client.post("/api/v1/invite/dev-reset")
+    assert r.status_code == 400, r.text