fix(marquee): 首页轮播脱敏名改为按 user_id 恒定 + 去 Faker 依赖 (#49)

Co-authored-by: OuYingJun1024 <1034284404@qq.com> Reviewed-on: #49 Co-authored-by: ouzhou <ouzhou@wonderable.ai> Co-committed-by: ouzhou <ouzhou@wonderable.ai>
2026-06-13 23:44:57 +08:00
parent 8d7b91219a
commit cce3a01de1
21 changed files with 673 additions and 162 deletions
@@ -1,16 +1,18 @@
 """看广告金币审计:复算 expected_coin 并与实发对比。

 只读。复用 [app.core.rewards] 的公式函数(不另写公式,避免与正式发奖口径漂移):
- 看视频:每条 granted = 1 份,第 N 份 = 当日该用户 granted 的 reward_video 顺序号
-  (与 ad_reward.grant_ad_reward 里 `_granted_today + 1` 一致)。
- 信息流:每条按 unit_count 份逐份累加,LT 序号 = 当日该用户已 granted 份数累计
-  (与 ad_feed_reward._unit_reward_total 的 existing_units 一致)。
+- 看视频:每条 granted = 1 份,第 N 份 = 该用户 granted 的 reward_video **账号累计**顺序号
+  (与 ad_reward.grant_ad_reward 里 `_granted_cumulative + 1` 一致;LT 因子不按天重置,
+  故复算时要把当日序号叠加上该用户在本日**之前**的累计已发份数)。
+- 信息流:每条按 unit_count 份逐份累加,LT 序号 = 该用户 granted 份数**账号累计**
+  (与 ad_feed_reward._unit_reward_total 的 existing_units 一致;同样不按天重置,
+  复算需叠加本日之前的累计份数)。

 非 granted(capped/ecpm_missing)不占用份序号、应发恒 0,据此校验闸口是否确实没发。
 """
 from __future__ import annotations

-from sqlalchemy import select
+from sqlalchemy import func, select
 from sqlalchemy.orm import Session

 from app.core import rewards
@@ -19,10 +21,29 @@ from app.models.ad_reward import AdRewardRecord
 from app.repositories.ad_feed_reward import FEED_REWARD_UNIT_SECONDS


+def _prior_granted_counts(
+    db: Session, *, date: str, user_id: int | None
+) -> dict[int, int]:
+    """各用户在 date **之前**已发奖的 reward_video 累计份数,作为当日复算的 LT 序号起点。
+    LT 因子改账号累计后,当日第 1 份并非全局第 1 份,需叠加历史累计。"""
+    stmt = (
+        select(AdRewardRecord.user_id, func.count())
+        .where(
+            AdRewardRecord.reward_date < date,
+            AdRewardRecord.reward_scene == "reward_video",
+            AdRewardRecord.status == "granted",
+        )
+        .group_by(AdRewardRecord.user_id)
+    )
+    if user_id is not None:
+        stmt = stmt.where(AdRewardRecord.user_id == user_id)
+    return {uid: n for uid, n in db.execute(stmt).all()}
+
+
 def _reward_video_rows(
    db: Session, *, date: str, user_id: int | None
 ) -> list[dict]:
-    """看视频记录复算。按 (user_id, created_at) 升序还原当日第 N 份。"""
+    """看视频记录复算。按 (user_id, created_at) 升序还原账号累计第 N 份(含本日之前的累计)。"""
    stmt = (
        select(AdRewardRecord)
        .where(
@@ -34,7 +55,8 @@ def _reward_video_rows(
    if user_id is not None:
        stmt = stmt.where(AdRewardRecord.user_id == user_id)

-    granted_n: dict[int, int] = {}  # user_id -> 已 granted 份数
+    # 用本日之前的累计份数做起点,当日 granted 在其上继续递增 → 与 _granted_cumulative+1 对齐
+    granted_n: dict[int, int] = _prior_granted_counts(db, date=date, user_id=user_id)
    rows: list[dict] = []
    for rec in db.execute(stmt).scalars():
        if rec.status == "granted":
@@ -80,8 +102,28 @@ def _reward_video_rows(
    return rows


+def _feed_prior_granted_units(
+    db: Session, *, date: str, user_id: int | None
+) -> dict[int, int]:
+    """各用户在 date **之前** granted 的信息流份数累计,作为当日复算的 LT 序号起点。"""
+    stmt = (
+        select(
+            AdFeedRewardRecord.user_id,
+            func.coalesce(func.sum(AdFeedRewardRecord.unit_count), 0),
+        )
+        .where(
+            AdFeedRewardRecord.reward_date < date,
+            AdFeedRewardRecord.status == "granted",
+        )
+        .group_by(AdFeedRewardRecord.user_id)
+    )
+    if user_id is not None:
+        stmt = stmt.where(AdFeedRewardRecord.user_id == user_id)
+    return {uid: int(n) for uid, n in db.execute(stmt).all()}
+
+
 def _feed_rows(db: Session, *, date: str, user_id: int | None) -> list[dict]:
-    """信息流记录复算。granted 记录逐份累加,LT 序号沿用当日累计份数。"""
+    """信息流记录复算。granted 记录逐份累加,LT 序号沿用账号累计份数(含本日之前)。"""
    stmt = (
        select(AdFeedRewardRecord)
        .where(AdFeedRewardRecord.reward_date == date)
@@ -90,7 +132,8 @@ def _feed_rows(db: Session, *, date: str, user_id: int | None) -> list[dict]:
    if user_id is not None:
        stmt = stmt.where(AdFeedRewardRecord.user_id == user_id)

-    granted_units: dict[int, int] = {}  # user_id -> 已 granted 份数累计
+    # 本日之前的累计份数做起点,与 _unit_reward_total 的 existing_units(累计)对齐
+    granted_units: dict[int, int] = _feed_prior_granted_units(db, date=date, user_id=user_id)
    rows: list[dict] = []
    for rec in db.execute(stmt).scalars():
        if rec.status == "granted":
@@ -142,12 +185,20 @@ def _feed_rows(db: Session, *, date: str, user_id: int | None) -> list[dict]:


 def ad_coin_audit(
-    db: Session, *, date: str, user_id: int | None, scene: str | None, limit: int
-) -> list[dict]:
-    """返回当日发奖复算明细,按 created_at 倒序(最新在前)截断到 limit。
+    db: Session,
+    *,
+    date: str,
+    user_id: int | None,
+    scene: str | None,
+    limit: int,
+    only_mismatch: bool = False,
+) -> dict:
+    """当日发奖复算。返回 {total, mismatch_count, truncated, items}。

-    scene: None=两类都要 / "reward_video" / "feed"。
-    份序号在截断前已基于全天数据算好,故 limit 只影响展示条数、不影响 expected 复算正确性。
+    scene: None=两类都要 / "reward_video" / "feed";only_mismatch=True 只展示不一致(✗)行。
+    关键:`total` 与 `mismatch_count` 在**全量**(截断前)上统计,故对账数字始终可信,不受 limit
+    影响;`items` 才是展示集(only_mismatch 时只取 ✗ 行)按 created_at 倒序截断到 limit。
+    份序号在全天数据上已算好,limit 只影响展示条数、不影响 expected 复算正确性。
    """
    rows: list[dict] = []
    if scene in (None, "reward_video"):
@@ -155,7 +206,16 @@ def ad_coin_audit(
    if scene in (None, "feed"):
        rows.extend(_feed_rows(db, date=date, user_id=user_id))
    rows.sort(key=lambda r: r["created_at"], reverse=True)
-    return rows[:limit]
+
+    total = len(rows)
+    mismatch_count = sum(1 for r in rows if not r["matched"])
+    display = [r for r in rows if not r["matched"]] if only_mismatch else rows
+    return {
+        "total": total,
+        "mismatch_count": mismatch_count,
+        "truncated": len(display) > limit,
+        "items": display[:limit],
+    }


 def formula_snapshot() -> dict:
@@ -44,9 +44,20 @@ def list_users(
    phone: str | None = None,
    register_channel: str | None = None,
    status: str | None = None,
+    nickname: str | None = None,
+    created_from: datetime | None = None,
+    created_to: datetime | None = None,
+    last_login_from: datetime | None = None,
+    last_login_to: datetime | None = None,
+    sort_by: str = "id",
+    sort_order: str = "desc",
    limit: int = 20,
    cursor: int | None = None,
 ) -> tuple[list[User], int | None]:
+    """用户列表(admin 全量)。支持手机号前缀 / 渠道 / 状态 / 昵称模糊 / 注册·最近登录时间范围筛选,
+    按 id·注册时间·最近登录排序。**offset 分页**(cursor=offset):任意列排序下游标语义统一,
+    代价是翻页期间数据变动可能错位一条——admin 低频场景可接受(同 [list_all_withdraw_orders])。
+    日期入参统一转 UTC naive 比较(User 时间均为 UTC naive,见 _as_utc_naive)。"""
    stmt = select(User)
    if phone:
        stmt = stmt.where(User.phone.like(f"{phone}%"))  # 前缀匹配
@@ -54,7 +65,33 @@ def list_users(
        stmt = stmt.where(User.register_channel == register_channel)
    if status:
        stmt = stmt.where(User.status == status)
-    return cursor_paginate(db, stmt, User.id, limit=limit, cursor=cursor)
+    if nickname and nickname.strip():
+        stmt = stmt.where(User.nickname.ilike(f"%{nickname.strip()}%"))
+    if created_from is not None:
+        stmt = stmt.where(User.created_at >= _as_utc_naive(created_from))
+    if created_to is not None:
+        stmt = stmt.where(User.created_at <= _as_utc_naive(created_to))
+    if last_login_from is not None:
+        stmt = stmt.where(User.last_login_at >= _as_utc_naive(last_login_from))
+    if last_login_to is not None:
+        stmt = stmt.where(User.last_login_at <= _as_utc_naive(last_login_to))
+
+    sort_cols = {
+        "id": User.id,
+        "created_at": User.created_at,
+        "last_login_at": User.last_login_at,
+    }
+    sort_col = sort_cols.get(sort_by, User.id)
+    order_fn = asc if sort_order == "asc" else desc
+    id_order = asc(User.id) if sort_order == "asc" else desc(User.id)
+    stmt = stmt.order_by(order_fn(sort_col), id_order)
+
+    offset = max(cursor or 0, 0)
+    rows = list(db.execute(stmt.offset(offset).limit(limit + 1)).scalars().all())
+    has_more = len(rows) > limit
+    items = rows[:limit]
+    next_cursor = offset + limit if has_more else None
+    return items, next_cursor


 def list_onboarding_devices(db: Session, *, limit: int = 500) -> list[dict]:
@@ -29,16 +29,20 @@ def get_ad_coin_audit(
        str | None, Query(description="reward_video / feed;不传=两类都要")
    ] = None,
    limit: Annotated[int, Query(ge=1, le=500)] = 100,
+    only_mismatch: Annotated[
+        bool, Query(description="只看不一致(✗)行;统计数仍按全量,不受影响")
+    ] = False,
 ) -> AdCoinAuditOut:
    audit_date = date or cn_today().isoformat()
-    rows = ad_audit.ad_coin_audit(
+    result = ad_audit.ad_coin_audit(
        db, date=audit_date, user_id=user_id, scene=scene, limit=limit,
+        only_mismatch=only_mismatch,
    )
-    items = [AdCoinAuditRow(**r) for r in rows]
    return AdCoinAuditOut(
        date=audit_date,
        formula=AdCoinFormulaOut(**ad_audit.formula_snapshot()),
-        total=len(items),
-        mismatch_count=sum(1 for it in items if not it.matched),
-        items=items,
+        total=result["total"],
+        mismatch_count=result["mismatch_count"],
+        truncated=result["truncated"],
+        items=[AdCoinAuditRow(**r) for r in result["items"]],
    )
@@ -1,6 +1,7 @@
 """admin 用户管理:列表 + 360 详情(读)+ 封禁/解封 + 手动调金币(写,带审计)。"""
 from __future__ import annotations

+from datetime import datetime
 from typing import Annotated

 from fastapi import APIRouter, Depends, HTTPException, Query, Request
@@ -28,18 +29,27 @@ router = APIRouter(
 )


-@router.get("", response_model=CursorPage[AdminUserListItem], summary="用户列表(筛选+分页)")
+@router.get("", response_model=CursorPage[AdminUserListItem], summary="用户列表(筛选+排序+分页)")
 def list_users(
    db: AdminDb,
    phone: Annotated[str | None, Query()] = None,
    register_channel: Annotated[str | None, Query()] = None,
    status: Annotated[str | None, Query()] = None,
+    nickname: Annotated[str | None, Query(max_length=100)] = None,
+    created_from: Annotated[datetime | None, Query()] = None,
+    created_to: Annotated[datetime | None, Query()] = None,
+    last_login_from: Annotated[datetime | None, Query()] = None,
+    last_login_to: Annotated[datetime | None, Query()] = None,
+    sort_by: Annotated[str, Query(pattern="^(id|created_at|last_login_at)$")] = "id",
+    sort_order: Annotated[str, Query(pattern="^(asc|desc)$")] = "desc",
    limit: Annotated[int, Query(ge=1, le=100)] = 20,
    cursor: Annotated[int | None, Query()] = None,
 ) -> CursorPage[AdminUserListItem]:
    items, next_cursor = queries.list_users(
        db, phone=phone, register_channel=register_channel, status=status,
-        limit=limit, cursor=cursor,
+        nickname=nickname, created_from=created_from, created_to=created_to,
+        last_login_from=last_login_from, last_login_to=last_login_to,
+        sort_by=sort_by, sort_order=sort_order, limit=limit, cursor=cursor,
    )
    return CursorPage(
        items=[AdminUserListItem.model_validate(u) for u in items],
@@ -101,7 +111,7 @@ def set_user_debug_trace(
    return OkResponse()


-@router.post("/{user_id}/coins", response_model=OkResponse, summary="手动增减金币(带审计)")
+@router.post("/{user_id}/coins", response_model=OkResponse, summary="手动增减/设值金币(带审计)")
 def grant_user_coins(
    user_id: int,
    body: GrantCoinsRequest,
@@ -109,33 +119,45 @@ def grant_user_coins(
    admin: Annotated[AdminUser, Depends(require_role("finance"))],
    db: AdminDb,
 ) -> OkResponse:
-    if body.amount == 0:
-        raise HTTPException(status_code=400, detail="amount 不能为 0")
    user = user_repo.get_user_by_id(db, user_id)
    if user is None:
        raise HTTPException(status_code=404, detail="用户不存在")
-    # 负数扣减时不允许扣成负余额(运营误操作保护)
-    if body.amount < 0:
-        acc_now = wallet_repo.get_or_create_account(db, user_id, commit=False)
-        if acc_now.coin_balance + body.amount < 0:
-            raise HTTPException(
-                status_code=400, detail=f"扣减后金币为负(当前余额 {acc_now.coin_balance})"
-            )
-    biz_type = "admin_grant" if body.amount > 0 else "admin_deduct"
+    # set=设为目标值:读当前余额算出要写的差值,仍复用 grant_coins 写一笔流水(沿用原子/审计/扣负保护)
+    if body.mode == "set":
+        if body.amount < 0:
+            raise HTTPException(status_code=400, detail="目标金币值不能为负")
+        before = wallet_repo.get_or_create_account(db, user_id, commit=False).coin_balance
+        delta = body.amount - before
+        if delta == 0:
+            raise HTTPException(status_code=400, detail=f"当前金币已为 {body.amount},无需调整")
+    else:
+        if body.amount == 0:
+            raise HTTPException(status_code=400, detail="amount 不能为 0")
+        delta = body.amount
+        # 负数扣减时不允许扣成负余额(运营误操作保护)
+        if delta < 0:
+            acc_now = wallet_repo.get_or_create_account(db, user_id, commit=False)
+            if acc_now.coin_balance + delta < 0:
+                raise HTTPException(
+                    status_code=400, detail=f"扣减后金币为负(当前余额 {acc_now.coin_balance})"
+                )
+    biz_type = "admin_grant" if delta > 0 else "admin_deduct"
    # grant_coins 只 flush 不 commit;审计同 commit=False;最后一起 commit → 原子(改钱+留痕)
    acc, _ = wallet_repo.grant_coins(
-        db, user_id, body.amount, biz_type=biz_type, remark=f"admin:{body.reason}"[:128],
+        db, user_id, delta, biz_type=biz_type, remark=f"admin:{body.reason}"[:128],
    )
+    detail = {"amount": delta, "balance_after": acc.coin_balance, "reason": body.reason}
+    if body.mode == "set":
+        detail.update({"mode": "set", "target": body.amount, "before": before})
    write_audit(
        db, admin, action="user.coins.grant", target_type="user", target_id=user_id,
-        detail={"amount": body.amount, "balance_after": acc.coin_balance, "reason": body.reason},
-        ip=get_client_ip(request), commit=False,
+        detail=detail, ip=get_client_ip(request), commit=False,
    )
    db.commit()
    return OkResponse()


-@router.post("/{user_id}/cash", response_model=OkResponse, summary="手动增减现金(带审计)")
+@router.post("/{user_id}/cash", response_model=OkResponse, summary="手动增减/设值现金(带审计)")
 def grant_user_cash(
    user_id: int,
    body: GrantCashRequest,
@@ -143,32 +165,47 @@ def grant_user_cash(
    admin: Annotated[AdminUser, Depends(require_role("finance"))],
    db: AdminDb,
 ) -> OkResponse:
-    """给指定用户增/减现金(分)。正=发放、负=扣减;主要用于让无现金用户直接测试提现。"""
-    if body.amount_cents == 0:
-        raise HTTPException(status_code=400, detail="amount_cents 不能为 0")
+    """给指定用户增/减或设值现金(分)。delta:正=发放、负=扣减;set:直接设为目标值。
+    主要用于让无现金用户直接测试提现。"""
    user = user_repo.get_user_by_id(db, user_id)
    if user is None:
        raise HTTPException(status_code=404, detail="用户不存在")
-    # 负数扣减时不允许扣成负余额(运营误操作保护)
-    if body.amount_cents < 0:
-        acc_now = wallet_repo.get_or_create_account(db, user_id, commit=False)
-        if acc_now.cash_balance_cents + body.amount_cents < 0:
+    # set=设为目标值:读当前余额算差值,仍复用 grant_cash 写一笔流水(沿用原子/审计/扣负保护)
+    if body.mode == "set":
+        if body.amount_cents < 0:
+            raise HTTPException(status_code=400, detail="目标现金值不能为负")
+        before = wallet_repo.get_or_create_account(db, user_id, commit=False).cash_balance_cents
+        delta = body.amount_cents - before
+        if delta == 0:
            raise HTTPException(
-                status_code=400, detail=f"扣减后现金为负(当前余额 {acc_now.cash_balance_cents} 分)"
+                status_code=400, detail=f"当前现金已为 {body.amount_cents} 分,无需调整"
            )
-    biz_type = "admin_grant" if body.amount_cents > 0 else "admin_deduct"
+    else:
+        if body.amount_cents == 0:
+            raise HTTPException(status_code=400, detail="amount_cents 不能为 0")
+        delta = body.amount_cents
+        # 负数扣减时不允许扣成负余额(运营误操作保护)
+        if delta < 0:
+            acc_now = wallet_repo.get_or_create_account(db, user_id, commit=False)
+            if acc_now.cash_balance_cents + delta < 0:
+                raise HTTPException(
+                    status_code=400, detail=f"扣减后现金为负(当前余额 {acc_now.cash_balance_cents} 分)"
+                )
+    biz_type = "admin_grant" if delta > 0 else "admin_deduct"
    # grant_cash 只 flush 不 commit;审计同 commit=False;最后一起 commit → 原子(改钱+留痕)
    acc, _ = wallet_repo.grant_cash(
-        db, user_id, body.amount_cents, biz_type=biz_type, remark=f"admin:{body.reason}"[:128],
+        db, user_id, delta, biz_type=biz_type, remark=f"admin:{body.reason}"[:128],
    )
+    detail = {
+        "amount_cents": delta,
+        "balance_after_cents": acc.cash_balance_cents,
+        "reason": body.reason,
+    }
+    if body.mode == "set":
+        detail.update({"mode": "set", "target_cents": body.amount_cents, "before_cents": before})
    write_audit(
        db, admin, action="user.cash.grant", target_type="user", target_id=user_id,
-        detail={
-            "amount_cents": body.amount_cents,
-            "balance_after_cents": acc.cash_balance_cents,
-            "reason": body.reason,
-        },
-        ip=get_client_ip(request), commit=False,
+        detail=detail, ip=get_client_ip(request), commit=False,
    )
    db.commit()
    return OkResponse()
@@ -48,10 +48,15 @@ class AdCoinFormulaOut(BaseModel):


 class AdCoinAuditOut(BaseModel):
-    """审计响应:公式参照 + 命中条数 + 明细。"""
+    """审计响应:公式参照 + 全量统计 + 明细。"""

    date: str = Field(..., description="审计日期(北京时间 YYYY-MM-DD)")
    formula: AdCoinFormulaOut
-    total: int = Field(..., description="返回的明细条数")
-    mismatch_count: int = Field(..., description="其中 matched=false 的条数(=0 说明公式全部生效)")
-    items: list[AdCoinAuditRow]
+    total: int = Field(..., description="该筛选下复算总条数(全量,不受 limit/only_mismatch 影响)")
+    mismatch_count: int = Field(
+        ..., description="全量不一致条数(=0 说明公式全部生效;在截断前统计,可信)"
+    )
+    truncated: bool = Field(
+        ..., description="展示集是否被 limit 截断(true=还有未返回的明细,请缩小范围或调大 limit)"
+    )
+    items: list[AdCoinAuditRow] = Field(..., description="展示明细;only_mismatch=true 时只含 ✗ 行")
@@ -38,12 +38,24 @@ class AdminUserOverview(BaseModel):


 class GrantCoinsRequest(BaseModel):
-    amount: int = Field(..., description="金币变动:正=增加,负=扣减(不可为 0)")
+    mode: Literal["delta", "set"] = Field(
+        "delta", description="delta=增减(amount 为变动量) / set=设为(amount 为目标值,须≥0)"
+    )
+    amount: int = Field(
+        ...,
+        description="delta 模式:金币变动(正=增加,负=扣减,不可为 0);set 模式:目标金币值(须≥0)",
+    )
    reason: str = Field(..., min_length=1, max_length=128, description="操作原因(必填,入审计)")


 class GrantCashRequest(BaseModel):
-    amount_cents: int = Field(..., description="现金变动(分):正=增加,负=扣减(不可为 0)")
+    mode: Literal["delta", "set"] = Field(
+        "delta", description="delta=增减(amount_cents 为变动量) / set=设为(amount_cents 为目标值,须≥0)"
+    )
+    amount_cents: int = Field(
+        ...,
+        description="delta 模式:现金变动(分,正=增加,负=扣减,不可为 0);set 模式:目标现金值(分,须≥0)",
+    )
    reason: str = Field(..., min_length=1, max_length=128, description="操作原因(必填,入审计)")