fix(admin): review 加固——超管防自锁/时区/并发发钱/审计

代码 review 后端运营后台后修复 7 项:
- admins: 降级/禁用 super_admin 前校验仍≥1 个 active 超管,防零超管死局;审计记 before/after
- queries: 时间筛选统一 tz-aware(列为 timestamptz),比较绝对时刻、不再依赖 DB 会话时区
- price_report: approve/reject 加行锁,防并发/连点双倍发奖
- users/wallet: get_or_create_account 增可选 lock 参(默认关,不动 C 端);调金币/现金读余额加行锁防双写错位
- ad_audit: 复算排序补 id 次级键,时间戳并列时顺序确定
- withdraw: health-check 限 finance/super,不暴露密钥路径给全员
- schemas: 调账/拒绝 reason 加 trim 校验,拒纯空白

测试: admin 套件 37 passed,全量 140 passed,无新增失败。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

alembic/versions/coupon_engage_per_package.py

@@ -1,53 +0,0 @@
-"""coupon_prompt_engagement 频控加 package 维度(美团/淘宝/京东各自独立弹)
-
-Revision ID: coupon_engage_per_package
-Revises: store_mapping_jd_cols
-Create Date: 2026-06-14 11:00:00.000000
-
-需求:领券引导窗按 (device, App, 自然日) 频控——在美团弹过/领过,不影响淘宝、京东今天
-仍各弹一次。原表唯一键是 (device_id, engage_date),缺 package → 任一 App 弹过就把整台
-设备当天标记 engage,其余 App 被压住不弹(bug)。
-
-本迁移:
-  1. 加 package 列(NOT NULL,旧行用 server_default "" 填占位,不影响新逻辑判断)。
-  2. 旧唯一约束 (device_id, engage_date) → 新 (device_id, package, engage_date)。
-
-SQLite 不支持直接 drop/add 约束,用 batch_alter_table(建临时表 + 拷数据 + 换名,
-与 store_mapping_* 同款)。
-"""
-from typing import Sequence, Union
-
-from alembic import op
-import sqlalchemy as sa
-
-
-# revision identifiers, used by Alembic.
-revision: str = 'coupon_engage_per_package'
-down_revision: Union[str, Sequence[str], None] = 'store_mapping_jd_cols'
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    with op.batch_alter_table('coupon_prompt_engagement', schema=None) as batch_op:
-        # 加 package 列。旧行(改造前的全局记录)填 "" 占位:它们对应的是"老的全局态",
-        # 新逻辑按 (device, package, 日) 判,占位 "" 不会与真实包名(com.xxx)碰撞。
-        batch_op.add_column(
-            sa.Column('package', sa.String(length=64), nullable=False, server_default='')
-        )
-        # 旧唯一约束 (device_id, engage_date) → 新三元组 (device_id, package, engage_date)。
-        batch_op.drop_constraint('uq_coupon_engage_device_date', type_='unique')
-        batch_op.create_unique_constraint(
-            'uq_coupon_engage_device_pkg_date',
-            ['device_id', 'package', 'engage_date'],
-        )
-
-
-def downgrade() -> None:
-    with op.batch_alter_table('coupon_prompt_engagement', schema=None) as batch_op:
-        batch_op.drop_constraint('uq_coupon_engage_device_pkg_date', type_='unique')
-        batch_op.create_unique_constraint(
-            'uq_coupon_engage_device_date',
-            ['device_id', 'engage_date'],
-        )
-        batch_op.drop_column('package')

app/admin/repositories/ad_audit.py

@@ -50,7 +50,7 @@ def _reward_video_rows(
             AdRewardRecord.reward_date == date,
             AdRewardRecord.reward_scene == "reward_video",
         )
-        .order_by(AdRewardRecord.user_id, AdRewardRecord.created_at)
+        .order_by(AdRewardRecord.user_id, AdRewardRecord.created_at, AdRewardRecord.id)
     )
     if user_id is not None:
         stmt = stmt.where(AdRewardRecord.user_id == user_id)
@@ -127,7 +127,7 @@ def _feed_rows(db: Session, *, date: str, user_id: int | None) -> list[dict]:
     stmt = (
         select(AdFeedRewardRecord)
         .where(AdFeedRewardRecord.reward_date == date)
-        .order_by(AdFeedRewardRecord.user_id, AdFeedRewardRecord.created_at)
+        .order_by(AdFeedRewardRecord.user_id, AdFeedRewardRecord.created_at, AdFeedRewardRecord.id)
     )
     if user_id is not None:
         stmt = stmt.where(AdFeedRewardRecord.user_id == user_id)
@@ -205,7 +205,7 @@ def ad_coin_audit(
         rows.extend(_reward_video_rows(db, date=date, user_id=user_id))
     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)
+    rows.sort(key=lambda r: (r["created_at"], r["record_id"]), reverse=True)
 
     total = len(rows)
     mismatch_count = sum(1 for r in rows if not r["matched"])

app/admin/repositories/queries.py

@@ -57,7 +57,7 @@ def list_users(
     """用户列表(admin 全量)。支持手机号前缀 / 渠道 / 状态 / 昵称模糊 / 注册·最近登录时间范围筛选,
     按 id·注册时间·最近登录排序。**offset 分页**(cursor=offset):任意列排序下游标语义统一,
     代价是翻页期间数据变动可能错位一条——admin 低频场景可接受(同 [list_all_withdraw_orders])。
-    日期入参统一转 UTC naive 比较(User 时间均为 UTC naive,见 _as_utc_naive)。"""
+    日期入参统一转 tz-aware UTC 比较(列为 timestamptz,见 _as_utc)。"""
     stmt = select(User)
     if phone:
         stmt = stmt.where(User.phone.like(f"{phone}%"))  # 前缀匹配
@@ -68,13 +68,13 @@ def list_users(
     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))
+        stmt = stmt.where(User.created_at >= _as_utc(created_from))
     if created_to is not None:
-        stmt = stmt.where(User.created_at <= _as_utc_naive(created_to))
+        stmt = stmt.where(User.created_at <= _as_utc(created_to))
     if last_login_from is not None:
-        stmt = stmt.where(User.last_login_at >= _as_utc_naive(last_login_from))
+        stmt = stmt.where(User.last_login_at >= _as_utc(last_login_from))
     if last_login_to is not None:
-        stmt = stmt.where(User.last_login_at <= _as_utc_naive(last_login_to))
+        stmt = stmt.where(User.last_login_at <= _as_utc(last_login_to))
 
     sort_cols = {
         "id": User.id,
@@ -190,16 +190,16 @@ def list_all_withdraw_orders(
 
     date_col = WithdrawOrder.updated_at if date_field == "updated_at" else WithdrawOrder.created_at
     if date_from is not None:
-        stmt = stmt.where(date_col >= _as_utc_naive(date_from))
+        stmt = stmt.where(date_col >= _as_utc(date_from))
     if date_to is not None:
-        stmt = stmt.where(date_col <= _as_utc_naive(date_to))
+        stmt = stmt.where(date_col <= _as_utc(date_to))
 
-    now = datetime.now(timezone.utc).replace(tzinfo=None)
+    # tz-aware:列为 timestamptz,比较绝对时刻、与 DB 会话时区无关(同 _as_utc / stats.py)
+    now = datetime.now(timezone.utc)
     today_start = (
         datetime.now(ZoneInfo("Asia/Shanghai"))
         .replace(hour=0, minute=0, second=0, microsecond=0)
         .astimezone(timezone.utc)
-        .replace(tzinfo=None)
     )
     if quick_filter == "abnormal":
         stmt = stmt.where(
@@ -254,11 +254,16 @@ def list_all_withdraw_orders(
     return items, next_cursor
 
 
-def _as_utc_naive(value: datetime) -> datetime:
-    """前端传 ISO 时间;DB 当前按 UTC naive 比较最稳(SQLite/本地开发一致)。"""
+def _as_utc(value: datetime) -> datetime:
+    """前端传 ISO 时间 → 统一成 tz-aware UTC 再比较。
+
+    所有时间列均为 `DateTime(timezone=True)`(Postgres timestamptz);用 tz-aware 绑定参数
+    比较的是绝对时刻,与 DB 会话时区无关、恒正确。曾用 naive UTC,正确性依赖会话 TimeZone=UTC,
+    生产会话非 UTC 时筛选边界会整体偏移——故统一 tz-aware(与 stats.py / withdraw_summary 一致)。
+    无时区入参按 UTC 解释。"""
     if value.tzinfo is None:
-        return value
-    return value.astimezone(timezone.utc).replace(tzinfo=None)
+        return value.replace(tzinfo=timezone.utc)
+    return value.astimezone(timezone.utc)
 
 
 def list_feedbacks(
@@ -266,15 +271,41 @@ def list_feedbacks(
     *,
     status: str | None = None,
     user_id: int | None = None,
+    content: str | None = None,
+    created_from: datetime | None = None,
+    created_to: datetime | None = None,
+    sort_by: str = "id",
+    sort_order: str = "desc",
     limit: int = 20,
     cursor: int | None = None,
 ) -> tuple[list[Feedback], int | None]:
+    """反馈工单列表。支持 状态 / 用户ID / 内容模糊 / 提交时间范围 筛选,按 id·提交时间排序。
+    **offset 分页**(cursor=offset):任意列排序下游标语义统一(同 [list_users]),代价是翻页期间
+    数据变动可能错位一条——admin 低频场景可接受。created_at 为 timestamptz,日期入参统一转 tz-aware UTC 比较。"""
     stmt = select(Feedback)
     if status:
         stmt = stmt.where(Feedback.status == status)
     if user_id is not None:
         stmt = stmt.where(Feedback.user_id == user_id)
-    return cursor_paginate(db, stmt, Feedback.id, limit=limit, cursor=cursor)
+    if content and content.strip():
+        stmt = stmt.where(Feedback.content.ilike(f"%{content.strip()}%"))
+    if created_from is not None:
+        stmt = stmt.where(Feedback.created_at >= _as_utc(created_from))
+    if created_to is not None:
+        stmt = stmt.where(Feedback.created_at <= _as_utc(created_to))
+
+    sort_cols = {"id": Feedback.id, "created_at": Feedback.created_at}
+    sort_col = sort_cols.get(sort_by, Feedback.id)
+    order_fn = asc if sort_order == "asc" else desc
+    id_order = asc(Feedback.id) if sort_order == "asc" else desc(Feedback.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 get_withdraw_by_out_bill_no(db: Session, out_bill_no: str) -> WithdrawOrder | None:

app/admin/routers/admins.py

@@ -17,6 +17,12 @@ router = APIRouter(
 )
 
 
+def _active_super_count(db: AdminDb) -> int:
+    return sum(
+        1 for a in admin_repo.list_admins(db) if a.role == "super_admin" and a.status == "active"
+    )
+
+
 @router.get("", response_model=list[AdminOut], summary="管理员列表")
 def list_admins(db: AdminDb) -> list[AdminOut]:
     return [AdminOut.model_validate(a) for a in admin_repo.list_admins(db)]
@@ -48,16 +54,29 @@ def update_admin(
     if admin_id == admin.id and body.status == "disabled":
         raise HTTPException(status_code=400, detail="不能禁用自己")
 
+    # 防自锁:降级 / 禁用某个 super_admin 前,确认操作后仍至少剩 1 个 active super_admin,
+    # 否则会进入「零可用超管」死局——本路由仅 super 可进,只能改库恢复。
+    demotes_super = (
+        target.role == "super_admin"
+        and target.status == "active"
+        and (
+            (body.role is not None and body.role != "super_admin")
+            or body.status == "disabled"
+        )
+    )
+    if demotes_super and _active_super_count(db) <= 1:
+        raise HTTPException(status_code=400, detail="不能降级/禁用最后一个超级管理员")
+
     changes: dict = {}
-    if body.role is not None:
+    if body.role is not None and body.role != target.role:
+        changes["role"] = {"before": target.role, "after": body.role}
         target.role = body.role
-        changes["role"] = body.role
-    if body.status is not None:
+    if body.status is not None and body.status != target.status:
+        changes["status"] = {"before": target.status, "after": body.status}
         target.status = body.status
-        changes["status"] = body.status
     if body.password is not None:
-        target.password_hash = hash_password(body.password)
         changes["password"] = "reset"
+        target.password_hash = hash_password(body.password)
     if not changes:
         raise HTTPException(status_code=400, detail="无任何变更字段")
     db.commit()

app/admin/routers/price_report.py

@@ -60,7 +60,9 @@ def approve_price_report(
     admin: Annotated[AdminUser, Depends(require_role("operator"))],
     db: AdminDb,
 ) -> OkResponse:
-    rep = db.get(PriceReport, report_id)
+    # 行锁(SELECT FOR UPDATE):并发/连点双请求会都读到 pending → 各发一次金币双倍发奖,
+    # 锁住该行串行化,第二个请求拿锁后看到 approved → 走 400。SQLite 下 FOR UPDATE 为 no-op。
+    rep = db.get(PriceReport, report_id, with_for_update=True)
     if rep is None:
         raise HTTPException(status_code=404, detail="上报记录不存在")
     if rep.status != "pending":
@@ -88,7 +90,7 @@ def reject_price_report(
     admin: Annotated[AdminUser, Depends(require_role("operator"))],
     db: AdminDb,
 ) -> OkResponse:
-    rep = db.get(PriceReport, report_id)
+    rep = db.get(PriceReport, report_id, with_for_update=True)  # 行锁,同 approve(防并发重复审核)
     if rep is None:
         raise HTTPException(status_code=404, detail="上报记录不存在")
     if rep.status != "pending":

app/admin/routers/users.py

@@ -126,7 +126,8 @@ def grant_user_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
+        # lock=True:锁账户行,防连点/并发各读同一 before 算同一 delta 双写,余额错位
+        before = wallet_repo.get_or_create_account(db, user_id, commit=False, lock=True).coin_balance
         delta = body.amount - before
         if delta == 0:
             raise HTTPException(status_code=400, detail=f"当前金币已为 {body.amount},无需调整")
@@ -134,9 +135,9 @@ def grant_user_coins(
         if body.amount == 0:
             raise HTTPException(status_code=400, detail="amount 不能为 0")
         delta = body.amount
-        # 负数扣减时不允许扣成负余额(运营误操作保护)
+        # 负数扣减时不允许扣成负余额(运营误操作保护);lock=True 防并发扣穿
         if delta < 0:
-            acc_now = wallet_repo.get_or_create_account(db, user_id, commit=False)
+            acc_now = wallet_repo.get_or_create_account(db, user_id, commit=False, lock=True)
             if acc_now.coin_balance + delta < 0:
                 raise HTTPException(
                     status_code=400, detail=f"扣减后金币为负(当前余额 {acc_now.coin_balance})"
@@ -174,7 +175,10 @@ def grant_user_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
+        # lock=True:锁账户行,防连点/并发各读同一 before 算同一 delta 双写,余额错位
+        before = wallet_repo.get_or_create_account(
+            db, user_id, commit=False, lock=True
+        ).cash_balance_cents
         delta = body.amount_cents - before
         if delta == 0:
             raise HTTPException(
@@ -184,9 +188,9 @@ def grant_user_cash(
         if body.amount_cents == 0:
             raise HTTPException(status_code=400, detail="amount_cents 不能为 0")
         delta = body.amount_cents
-        # 负数扣减时不允许扣成负余额(运营误操作保护)
+        # 负数扣减时不允许扣成负余额(运营误操作保护);lock=True 防并发扣穿
         if delta < 0:
-            acc_now = wallet_repo.get_or_create_account(db, user_id, commit=False)
+            acc_now = wallet_repo.get_or_create_account(db, user_id, commit=False, lock=True)
             if acc_now.cash_balance_cents + delta < 0:
                 raise HTTPException(
                     status_code=400, detail=f"扣减后现金为负(当前余额 {acc_now.cash_balance_cents} 分)"

app/admin/routers/withdraw.py

@@ -87,7 +87,12 @@ def withdraws_summary(db: AdminDb) -> WithdrawSummaryOut:
     return WithdrawSummaryOut(**queries.withdraw_summary(db))
 
 
-@router.get("/health-check", response_model=WxpayHealthCheckOut, summary="提现配置健康检查")
+@router.get(
+    "/health-check",
+    response_model=WxpayHealthCheckOut,
+    summary="提现配置健康检查",
+    dependencies=[Depends(require_role("finance"))],  # 暴露密钥路径/配置,限财务+super
+)
 def withdraw_health_check() -> WxpayHealthCheckOut:
     private_path = wxpay._resolve_config_path(settings.WXPAY_MCH_PRIVATE_KEY_PATH)  # noqa: SLF001
     public_path = wxpay._resolve_config_path(settings.WXPAY_PUBLIC_KEY_PATH)  # noqa: SLF001

app/admin/schemas/price_report.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 
 from datetime import datetime
 
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, field_validator
 
 
 class PriceReportOut(BaseModel):
@@ -36,6 +36,14 @@ class PriceReportOut(BaseModel):
 class PriceReportRejectRequest(BaseModel):
     reason: str = Field(min_length=1, max_length=256, description="拒绝理由,用户端记录页会看到")
 
+    @field_validator("reason")
+    @classmethod
+    def _reason_not_blank(cls, v: str) -> str:
+        # min_length=1 放过纯空白(" "),trim 后再校验非空,避免审计/用户端记录到空理由
+        if not v.strip():
+            raise ValueError("拒绝理由不能为空")
+        return v.strip()
+
 
 class PriceReportSummary(BaseModel):
     """审核台顶部各状态计数。"""

app/admin/schemas/user.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 from datetime import datetime
 from typing import Literal
 
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, field_validator
 
 
 class AdminUserListItem(BaseModel):
@@ -37,6 +37,13 @@ class AdminUserOverview(BaseModel):
     feedback_total: int
 
 
+def _strip_reason(v: str) -> str:
+    # min_length=1 放过纯空白(" "),trim 后再校验非空,避免审计记到空原因
+    if not v.strip():
+        raise ValueError("操作原因不能为空")
+    return v.strip()
+
+
 class GrantCoinsRequest(BaseModel):
     mode: Literal["delta", "set"] = Field(
         "delta", description="delta=增减(amount 为变动量) / set=设为(amount 为目标值,须≥0)"
@@ -47,6 +54,8 @@ class GrantCoinsRequest(BaseModel):
     )
     reason: str = Field(..., min_length=1, max_length=128, description="操作原因(必填,入审计)")
 
+    _v_reason = field_validator("reason")(_strip_reason)
+
 
 class GrantCashRequest(BaseModel):
     mode: Literal["delta", "set"] = Field(
@@ -58,6 +67,8 @@ class GrantCashRequest(BaseModel):
     )
     reason: str = Field(..., min_length=1, max_length=128, description="操作原因(必填,入审计)")
 
+    _v_reason = field_validator("reason")(_strip_reason)
+
 
 class SetUserStatusRequest(BaseModel):
     status: Literal["active", "disabled"] = Field(

app/api/v1/coupon.py

@@ -27,7 +27,6 @@ from app.schemas.coupon_state import (
     CouponCompletedTodayOut,
     CouponPromptDismissIn,
     CouponPromptShouldShowOut,
-    CouponPromptShownIn,
 )
 
 logger = logging.getLogger("shagua.coupon")
@@ -67,11 +66,11 @@ def _extract_coupon_results(resp_json: dict) -> list[dict]:
 
 
 def _mark_engagement_blocking(
-    device_id: str, package: str, user_id: int | None, engage_type: str
+    device_id: str, user_id: int | None, engage_type: str
 ) -> None:
     """独立 session 写 engagement(async 端点经 run_in_threadpool 调,不阻塞事件循环)。"""
     with SessionLocal() as db:
-        coupon_repo.mark_engagement(db, device_id, package, user_id, engage_type)
+        coupon_repo.mark_engagement(db, device_id, user_id, engage_type)
 
 
 def _record_claims_blocking(
@@ -112,17 +111,14 @@ async def coupon_step(
     device_id = meta.get("device_id")
     user_id = _to_int(meta.get("user_id"))  # 登录态才带;判断不靠它,资产留痕用
     trace_id = meta.get("trace_id")
-    # 发起领券时前台 App 包名(step body 带 "package")。频控按 App,这条 engagement 要记到
-    # 对应 App 上。App 内「去领取」发起时 package 可能缺/为空 → 退化为 "" 占位(全局态)。
-    pkg = meta.get("package") or ""
 
     # 领券任务首帧(step=0)= 用户已发起领券 → 记一条今日 engagement(claim_started),
-    # 今天**这个 App** 不再弹引导窗(对齐前台"点一键领取即 markEngaged")。写库失败绝不能
+    # 今天这台设备不再弹引导窗(对齐前台"点一键领取即 markEngaged")。写库失败绝不能
     # 连累领券主流程,整段吞掉。
     if device_id and meta.get("step") == 0:
         try:
             await run_in_threadpool(
-                _mark_engagement_blocking, device_id, pkg, user_id, "claim_started"
+                _mark_engagement_blocking, device_id, user_id, "claim_started"
             )
         except Exception as e:  # noqa: BLE001
             logger.warning("coupon engagement write failed: %s", e)
@@ -192,29 +188,14 @@ async def coupon_step(
     return resp_json
 
 
-@router.post("/prompt/shown", summary="领券引导窗弹出即上报(按 App 记 shown)")
-def coupon_prompt_shown(payload: CouponPromptShownIn, db: DbSession) -> dict[str, bool]:
-    """客户端弹出引导窗那刻调 → 记一条今日 engagement(shown),今天**这个 App** 不再自动弹。
-
-    频控主判据(管跨重装):弹出即占用今天这个 App 的"一次"。用户领/拒/无视都算用掉。
-    后续点领取/拒绝再由 step/dismiss 把 type 升级。按 (device, package, 日) 记。
-    """
-    coupon_repo.mark_engagement(
-        db, payload.device_id, payload.package, payload.user_id, "shown"
-    )
-    return {"ok": True}
-
-
 @router.post("/prompt/dismiss", summary="用户拒绝/关闭领券引导窗(记今日已 engage)")
 def coupon_prompt_dismiss(payload: CouponPromptDismissIn, db: DbSession) -> dict[str, bool]:
-    """客户端点关闭引导窗时调用 → 记一条今日 engagement(dismissed),今天**这个 App** 不再弹。
+    """客户端点关闭引导窗时调用 → 记一条今日 engagement(dismissed),今天不再弹。
 
     server 在透传链路里看不到"用户拒绝"(拒绝不发起领券),故必须客户端通知。
-    频控按 (device, package, 日),各 App 独立。MVP 不鉴权,按 device_id 记。
+    MVP 不鉴权,按 device_id 记。
     """
-    coupon_repo.mark_engagement(
-        db, payload.device_id, payload.package, payload.user_id, "dismissed"
-    )
+    coupon_repo.mark_engagement(db, payload.device_id, payload.user_id, "dismissed")
     return {"ok": True}
 
 
@@ -224,12 +205,12 @@ def coupon_prompt_dismiss(payload: CouponPromptDismissIn, db: DbSession) -> dict
     summary="切到外卖 App 时是否还应弹领券引导窗",
 )
 def coupon_prompt_should_show(
-    device_id: str, db: DbSession, package: str = ""
+    device_id: str, db: DbSession
 ) -> CouponPromptShouldShowOut:
-    """今天这台设备**这个 App** 已 engage(弹/领/拒)过 → should_show=false。各 App 独立:
-    美团弹过不压淘宝/京东。客户端切到目标 App 时带 package 查(老客户端不带 → "" 全局态)。"""
+    """今天这台设备已 engage(领或拒)过 → should_show=false。客户端据此决定弹不弹
+    (纯后台判据,客户端不再做前台 SP 缓存判断)。"""
     return CouponPromptShouldShowOut(
-        should_show=not coupon_repo.has_engaged_today(db, device_id, package)
+        should_show=not coupon_repo.has_engaged_today(db, device_id)
     )
 
 
@@ -255,16 +236,3 @@ def coupon_completed_today(
     return CouponCompletedTodayOut(
         completed=coupon_repo.has_completed_today(db, device_id)
     )
-
-
-@router.post(
-    "/completed-today/reset",
-    summary="重置今日已完成(开发设置全重置用,恢复首页「去领取」卡可点)",
-)
-def coupon_completed_today_reset(
-    payload: CouponPromptDismissIn, db: DbSession
-) -> dict[str, bool]:
-    """删这台设备今天的 completion → has_completed_today 变 false,首页「去领取」卡恢复可点。
-    与 /prompt/reset 配套:开发设置「重置今日领券弹窗状态」一键把今日状态全清。MVP 不鉴权。"""
-    coupon_repo.reset_today_completion(db, payload.device_id)
-    return {"ok": True}

app/models/coupon_state.py

@@ -137,35 +137,25 @@ class CouponDailyCompletion(Base):
 
 
 class CouponPromptEngagement(Base):
-    """按 (device, **App**, 自然日) 记"今天这个 App 是否对领券引导窗表达过意向"——弹窗频控源。
-
-    2026-06-14:频控维度从 (device, 日) 改为 (device, package, 日)。需求是美团/淘宝/京东
-    各自独立——在美团弹过/领过,不影响淘宝、京东今天仍各弹一次。原来缺 package → 任一 App
-    弹过就把整台设备当天标记 engage,其余 App 被压住不弹(bug)。
-    """
+    """按 (device, 自然日) 记"今天是否对领券引导窗表达过意向"——弹窗频控源。"""
 
     __tablename__ = "coupon_prompt_engagement"
     __table_args__ = (
-        # 一台设备、一个 App、一天一条:今天**这个 App** engage 过(领或拒)才不再弹该 App。
+        # 一台设备一天一条:今天 engage 过(领或拒)就不再弹。
         UniqueConstraint(
-            "device_id", "package", "engage_date",
-            name="uq_coupon_engage_device_pkg_date",
+            "device_id", "engage_date",
+            name="uq_coupon_engage_device_date",
         ),
     )
 
     id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
 
     device_id: Mapped[str] = mapped_column(String(64), nullable=False)
-    # 触发弹窗的目标 App 包名(com.sankuai.meituan / com.taobao.taobao / com.jingdong.app.mall)。
-    # 频控维度,各 App 独立。旧行(改造前)无此值 → 迁移用占位 "" 填,不影响新逻辑判断。
-    package: Mapped[str] = mapped_column(
-        String(64), nullable=False, server_default=""
-    )
     user_id: Mapped[int | None] = mapped_column(Integer, index=True, nullable=True)
     # Asia/Shanghai 自然日。
     engage_date: Mapped[date] = mapped_column(Date, nullable=False)
-    # claim_started(点了一键领取)/ dismissed(点了拒绝/关闭)/ shown(自动弹出即记)。
-    # 仅记录区分,判断只看"今天这个 App 有没有这条",type 不影响弹不弹。
+    # claim_started(点了一键领取)/ dismissed(点了拒绝/关闭)。仅记录区分,
+    # 判断只看"今天有没有这条",type 不影响弹不弹。
     engage_type: Mapped[str] = mapped_column(String(16), nullable=False)
 
     created_at: Mapped[datetime] = mapped_column(

app/repositories/coupon_state.py

@@ -31,13 +31,11 @@ def today_cn() -> date:
 
 # ===== 弹窗频控(coupon_prompt_engagement)=====
 
-def has_engaged_today(db: Session, device_id: str, package: str) -> bool:
-    """这台设备今天**这个 App** 是否已对领券引导窗表达过意向(领/拒/弹出)。有 = 该 App 不再弹。
-    频控按 (device, package, 日):美团弹过不影响淘宝/京东今天各自仍弹一次。"""
+def has_engaged_today(db: Session, device_id: str) -> bool:
+    """这台设备今天是否已对领券引导窗表达过意向(领或拒)。有 = 不再弹。"""
     row = db.execute(
         select(CouponPromptEngagement.id).where(
             CouponPromptEngagement.device_id == device_id,
-            CouponPromptEngagement.package == package,
             CouponPromptEngagement.engage_date == today_cn(),
         )
     ).first()
@@ -45,18 +43,13 @@ def has_engaged_today(db: Session, device_id: str, package: str) -> bool:
 
 
 def mark_engagement(
-    db: Session, device_id: str, package: str, user_id: int | None, engage_type: str
+    db: Session, device_id: str, user_id: int | None, engage_type: str
 ) -> None:
-    """记今日意向(shown / claim_started / dismissed)。(device, package, 今天) 唯一,幂等 upsert。
-
-    engage_type 升级口径(同一 (device,package,日) 多次调,只覆盖 type,不新增行):
-    shown(自动弹出)→ claim_started(点一键领取)/ dismissed(点关闭)。判断只看"有没有这条"。
-    """
+    """记今日意向(claim_started / dismissed)。(device, 今天) 唯一,幂等 upsert。"""
     today = today_cn()
     row = db.execute(
         select(CouponPromptEngagement).where(
             CouponPromptEngagement.device_id == device_id,
-            CouponPromptEngagement.package == package,
             CouponPromptEngagement.engage_date == today,
         )
     ).scalar_one_or_none()
@@ -66,20 +59,19 @@ def mark_engagement(
             row.user_id = user_id
     else:
         db.add(CouponPromptEngagement(
-            device_id=device_id, package=package, user_id=user_id,
+            device_id=device_id, user_id=user_id,
             engage_date=today, engage_type=engage_type,
         ))
     try:
         db.commit()
     except IntegrityError:
-        # 并发下另一请求刚插了同 (device, package, 日) → 唯一约束撞,回滚忽略(本就幂等)。
+        # 并发下另一请求刚插了同 (device, 日) → 唯一约束撞,回滚忽略(本就幂等)。
         db.rollback()
 
 
 def reset_today_engagement(db: Session, device_id: str) -> int:
-    """删这台设备今天**所有 App** 的 engagement(开发设置「重置今日领券弹窗状态」调,测频控用)。
-    删后各 App has_engaged_today → false,今天又都能弹。返回删除行数。
-    (不按 package 过滤:重置是"把今天清干净从头测",清全部 App 最符合预期。)"""
+    """删这台设备今天的 engagement(开发设置「重置今日领券弹窗状态」调,测频控用)。
+    删后 has_engaged_today → false,今天又能弹。返回删除行数。"""
     result = db.execute(
         delete(CouponPromptEngagement).where(
             CouponPromptEngagement.device_id == device_id,
@@ -131,19 +123,6 @@ def mark_completed_today(
         db.rollback()
 
 
-def reset_today_completion(db: Session, device_id: str) -> int:
-    """删这台设备今天的"已完成"记录(开发设置「重置今日领券弹窗状态」全重置时调)。
-    删后 has_completed_today → false,首页「去领取」卡恢复可点。返回删除行数。"""
-    result = db.execute(
-        delete(CouponDailyCompletion).where(
-            CouponDailyCompletion.device_id == device_id,
-            CouponDailyCompletion.complete_date == today_cn(),
-        )
-    )
-    db.commit()
-    return result.rowcount or 0
-
-
 # ===== 领券记录(coupon_claim_record)=====
 
 def record_claims(

app/repositories/wallet.py

@@ -78,9 +78,15 @@ class WithdrawNotReviewable(Exception):
     """提现单当前状态不可审核(非 reviewing,可能已被处理过)。"""
 
 
-def get_or_create_account(db: Session, user_id: int, *, commit: bool = True) -> CoinAccount:
-    """取用户金币账户,不存在则建一个空账户。"""
-    acc = db.get(CoinAccount, user_id)
+def get_or_create_account(
+    db: Session, user_id: int, *, commit: bool = True, lock: bool = False
+) -> CoinAccount:
+    """取用户金币账户,不存在则建一个空账户。
+
+    lock=True 时对已存在的账户行加 SELECT FOR UPDATE(读-算-写余额的调用方串行化,防并发
+    双写余额错位,如 admin set 模式连点);默认 False 不改 C 端发奖行为。SQLite 下为 no-op。
+    """
+    acc = db.get(CoinAccount, user_id, with_for_update=True) if lock else db.get(CoinAccount, user_id)
     if acc is None:
         acc = CoinAccount(
             user_id=user_id,

app/schemas/coupon_state.py

@@ -7,30 +7,16 @@ from pydantic import BaseModel
 class CouponPromptDismissIn(BaseModel):
     """客户端拒绝/关闭领券引导窗的通知体。
 
-    server 据此记一条今日 engagement(dismissed)→ 今天**这个 App** 不再弹引导窗。
-    频控按 (device, package, 日):各 App 独立。package 缺省 ""(老客户端兼容,退化为全局态)。
+    server 据此记一条今日 engagement(dismissed)→ 今天这台设备不再弹引导窗。
     MVP 不鉴权,按 device_id 判断;user_id 登录态带上就一并记(资产),可空。
     """
 
     device_id: str
-    package: str = ""
-    user_id: int | None = None
-
-
-class CouponPromptShownIn(BaseModel):
-    """客户端弹出领券引导窗即上报(记 shown)。
-
-    弹出那刻就记一条今日 engagement(shown)→ 今天**这个 App** 不再自动弹(频控主判据,
-    管跨重装;本地 SP 兜后台抖动)。后续用户点领取/拒绝再把 type 升级成 claim_started/dismissed。
-    """
-
-    device_id: str
-    package: str
     user_id: int | None = None
 
 
 class CouponPromptShouldShowOut(BaseModel):
-    """切到外卖 App 时是否还应弹领券引导窗。今天**这个 App** 已 engage(弹/领/拒)过 → false。"""
+    """切到外卖 App 时是否还应弹领券引导窗。今天已 engage(领或拒)过 → false。"""
 
     should_show: bool