feat(store-mapping): JD 缓存 deeplink 失效标记(对标淘宝)

store_mapping 加 jd_deeplink_invalid_at 列 + 迁移(down_revision=store_mapping_tb_dl_invalid);
mark_jd_deeplink_invalid 按 id_jd 标记 + lookup_nearest 过滤已失效 JD 候选;
/internal/store-mapping/invalidate 接 jd 分支。配 pricebot 京东缓存 deeplink 失效回退。

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

alembic/versions/coupon_engage_per_package.py

@@ -0,0 +1,53 @@
+"""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')

alembic/versions/store_mapping_jd_dl_invalid.py

@@ -0,0 +1,32 @@
+"""store_mapping 加京东 deeplink 失效标记列 jd_deeplink_invalid_at
+
+Revision ID: store_mapping_jd_dl_invalid
+Revises: store_mapping_tb_dl_invalid
+Create Date: 2026-06-15 00:00:00.000000
+
+京东同淘宝: 缓存的店内搜索 deeplink 会失效(打开是"当前门店超出配送范围"页)。pricebot 比价撞到
+失效页时回退正常搜店, 并 server→server 通知把该 storeId 的 deeplink 标记失效。本列记失效时刻
+(NULL=有效); lookup 反查时过滤掉已失效的京东候选, 不再返回坏 deeplink。
+与淘宝 taobao_deeplink_invalid_at 对称; 用时间戳而非布尔: 留痕可审计、可统计失效率, 不销毁原 deeplink。
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'store_mapping_jd_dl_invalid'
+down_revision: Union[str, Sequence[str], None] = 'store_mapping_tb_dl_invalid'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    with op.batch_alter_table('store_mapping', schema=None) as batch_op:
+        batch_op.add_column(sa.Column('jd_deeplink_invalid_at', sa.DateTime(timezone=True), nullable=True))
+
+
+def downgrade() -> None:
+    with op.batch_alter_table('store_mapping', schema=None) as batch_op:
+        batch_op.drop_column('jd_deeplink_invalid_at')

alembic/versions/store_mapping_tb_dl_invalid.py

@@ -0,0 +1,33 @@
+"""store_mapping 加淘宝 deeplink 失效标记列 taobao_deeplink_invalid_at
+
+Revision ID: store_mapping_tb_dl_invalid
+Revises: coupon_engage_per_package
+Create Date: 2026-06-15 00:00:00.000000
+
+缓存的淘宝店内搜索 deeplink 会失效(打开是"页面出错了"降级页)。pricebot 比价撞到错误页时
+回退正常搜店, 并 server→server 通知把该 shopId 的 deeplink 标记失效。本列记失效时刻
+(NULL=有效); lookup 反查时过滤掉已失效的淘宝候选, 不再返回坏 deeplink。
+只加淘宝一列(当前只接淘宝); 用时间戳而非布尔: 留痕可审计、可统计失效率, 且不销毁原 deeplink。
+无需索引: 过滤总叠在 name_taobao== 之后, 候选集已小。
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'store_mapping_tb_dl_invalid'
+down_revision: Union[str, Sequence[str], None] = 'coupon_engage_per_package'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    with op.batch_alter_table('store_mapping', schema=None) as batch_op:
+        batch_op.add_column(sa.Column('taobao_deeplink_invalid_at', sa.DateTime(timezone=True), nullable=True))
+
+
+def downgrade() -> None:
+    with op.batch_alter_table('store_mapping', schema=None) as batch_op:
+        batch_op.drop_column('taobao_deeplink_invalid_at')

app/api/internal/store.py

@@ -17,7 +17,12 @@ from fastapi import APIRouter, Header
 from app.api.deps import DbSession
 from app.api.internal.price import _check_secret
 from app.repositories import store_mapping as repo
-from app.schemas.store_mapping import StoreMappingIn, StoreMappingOut
+from app.schemas.store_mapping import (
+    StoreMappingIn,
+    StoreMappingInvalidateIn,
+    StoreMappingInvalidateOut,
+    StoreMappingOut,
+)
 
 logger = logging.getLogger("shagua.internal.store")
 
@@ -77,3 +82,29 @@ def report_store_mapping(
         payload.source_device_id, payload.source_user_id,
     )
     return StoreMappingOut(inserted=created, row_id=row_id)
+
+
+@router.post(
+    "/store-mapping/invalidate",
+    response_model=StoreMappingInvalidateOut,
+    summary="标记某平台 shopId 的缓存 deeplink 失效(pricebot 撞错误页回退时上报,lookup 不再返回)",
+)
+def invalidate_store_mapping(
+    payload: StoreMappingInvalidateIn,
+    db: DbSession,
+    x_internal_secret: Annotated[str | None, Header()] = None,
+) -> StoreMappingInvalidateOut:
+    _check_secret(x_internal_secret)
+    if payload.platform == "taobao":
+        affected = repo.mark_taobao_deeplink_invalid(db, payload.shop_id)
+    elif payload.platform == "jd":
+        affected = repo.mark_jd_deeplink_invalid(db, payload.shop_id)
+    else:
+        # 当前只接淘宝/京东; 其它平台先 no-op(affected=0), 不报错 — 向后兼容 pricebot 将来扩展。
+        logger.info("store_mapping invalidate 跳过: platform=%s 暂不支持", payload.platform)
+        return StoreMappingInvalidateOut(ok=True, affected=0)
+    logger.info(
+        "store_mapping invalidate platform=%s shop_id=%s → 标记失效 %d 行",
+        payload.platform, payload.shop_id, affected,
+    )
+    return StoreMappingInvalidateOut(ok=True, affected=affected)

app/api/v1/coupon.py

@@ -27,6 +27,7 @@ from app.schemas.coupon_state import (
     CouponCompletedTodayOut,
     CouponPromptDismissIn,
     CouponPromptShouldShowOut,
+    CouponPromptShownIn,
 )
 
 logger = logging.getLogger("shagua.coupon")
@@ -66,11 +67,11 @@ def _extract_coupon_results(resp_json: dict) -> list[dict]:
 
 
 def _mark_engagement_blocking(
-    device_id: str, user_id: int | None, engage_type: str
+    device_id: str, package: 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, user_id, engage_type)
+        coupon_repo.mark_engagement(db, device_id, package, user_id, engage_type)
 
 
 def _record_claims_blocking(
@@ -111,14 +112,17 @@ 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),
-    # 今天这台设备不再弹引导窗(对齐前台"点一键领取即 markEngaged")。写库失败绝不能
+    # 今天**这个 App** 不再弹引导窗(对齐前台"点一键领取即 markEngaged")。写库失败绝不能
     # 连累领券主流程,整段吞掉。
     if device_id and meta.get("step") == 0:
         try:
             await run_in_threadpool(
-                _mark_engagement_blocking, device_id, user_id, "claim_started"
+                _mark_engagement_blocking, device_id, pkg, user_id, "claim_started"
             )
         except Exception as e:  # noqa: BLE001
             logger.warning("coupon engagement write failed: %s", e)
@@ -188,14 +192,29 @@ 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),今天不再弹。
+    """客户端点关闭引导窗时调用 → 记一条今日 engagement(dismissed),今天**这个 App** 不再弹。
 
     server 在透传链路里看不到"用户拒绝"(拒绝不发起领券),故必须客户端通知。
-    MVP 不鉴权,按 device_id 记。
+    频控按 (device, package, 日),各 App 独立。MVP 不鉴权,按 device_id 记。
     """
-    coupon_repo.mark_engagement(db, payload.device_id, payload.user_id, "dismissed")
+    coupon_repo.mark_engagement(
+        db, payload.device_id, payload.package, payload.user_id, "dismissed"
+    )
     return {"ok": True}
 
 
@@ -205,12 +224,12 @@ def coupon_prompt_dismiss(payload: CouponPromptDismissIn, db: DbSession) -> dict
     summary="切到外卖 App 时是否还应弹领券引导窗",
 )
 def coupon_prompt_should_show(
-    device_id: str, db: DbSession
+    device_id: str, db: DbSession, package: str = ""
 ) -> CouponPromptShouldShowOut:
-    """今天这台设备已 engage(领或拒)过 → should_show=false。客户端据此决定弹不弹
-    (纯后台判据,客户端不再做前台 SP 缓存判断)。"""
+    """今天这台设备**这个 App** 已 engage(弹/领/拒)过 → should_show=false。各 App 独立:
+    美团弹过不压淘宝/京东。客户端切到目标 App 时带 package 查(老客户端不带 → "" 全局态)。"""
     return CouponPromptShouldShowOut(
-        should_show=not coupon_repo.has_engaged_today(db, device_id)
+        should_show=not coupon_repo.has_engaged_today(db, device_id, package)
     )
 
 
@@ -236,3 +255,16 @@ 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,25 +137,35 @@ class CouponDailyCompletion(Base):
 
 
 class CouponPromptEngagement(Base):
-    """按 (device, 自然日) 记"今天是否对领券引导窗表达过意向"——弹窗频控源。"""
+    """按 (device, **App**, 自然日) 记"今天这个 App 是否对领券引导窗表达过意向"——弹窗频控源。
+
+    2026-06-14:频控维度从 (device, 日) 改为 (device, package, 日)。需求是美团/淘宝/京东
+    各自独立——在美团弹过/领过,不影响淘宝、京东今天仍各弹一次。原来缺 package → 任一 App
+    弹过就把整台设备当天标记 engage,其余 App 被压住不弹(bug)。
+    """
 
     __tablename__ = "coupon_prompt_engagement"
     __table_args__ = (
-        # 一台设备一天一条:今天 engage 过(领或拒)就不再弹。
+        # 一台设备、一个 App、一天一条:今天**这个 App** engage 过(领或拒)才不再弹该 App。
         UniqueConstraint(
-            "device_id", "engage_date",
-            name="uq_coupon_engage_device_date",
+            "device_id", "package", "engage_date",
+            name="uq_coupon_engage_device_pkg_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(点了拒绝/关闭)。仅记录区分,
-    # 判断只看"今天有没有这条",type 不影响弹不弹。
+    # claim_started(点了一键领取)/ dismissed(点了拒绝/关闭)/ shown(自动弹出即记)。
+    # 仅记录区分,判断只看"今天这个 App 有没有这条",type 不影响弹不弹。
     engage_type: Mapped[str] = mapped_column(String(16), nullable=False)
 
     created_at: Mapped[datetime] = mapped_column(

app/models/store_mapping.py

@@ -86,6 +86,9 @@ class StoreMapping(Base):
     taobao_share_url: Mapped[str | None] = mapped_column(String(256), nullable=True)   # m.tb.cn 短链
     taobao_resolved_url: Mapped[str | None] = mapped_column(Text, nullable=True)        # 解析出的目标 URL(含 shopId)
     taobao_deeplink: Mapped[str | None] = mapped_column(Text, nullable=True)            # 拼好的 et-store/search deeplink
+    # 淘宝 deeplink 失效标记:比价撞"页面出错了"降级页时被置(pricebot server→server invalidate),
+    # NULL=有效。lookup 反查过滤掉非 NULL 的淘宝候选,不再返回坏 deeplink(重搜会写新行覆盖)。
+    taobao_deeplink_invalid_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
 
     # ===== 美团原料(同淘宝;dpurl.cn 短链 → 302 反查 poi_id_str → imeituan:// deeplink)=====
     # ⚠️ poi_id_str 每次分享重新加密、非稳定主键(调研文档 §八), 故单列存"可复跳的一次性票据",
@@ -102,6 +105,8 @@ class StoreMapping(Base):
     jd_share_url: Mapped[str | None] = mapped_column(String(256), nullable=True)         # 3.cn 短链
     jd_resolved_url: Mapped[str | None] = mapped_column(Text, nullable=True)             # 反查出的目标 openapp.jdmobile:// deeplink
     jd_deeplink: Mapped[str | None] = mapped_column(Text, nullable=True)                 # 拼好的 pages/search 店内搜索 deeplink
+    # 京东 deeplink 失效标记(同 taobao_deeplink_invalid_at):撞"当前门店超出配送范围"页时被置,NULL=有效。
+    jd_deeplink_invalid_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
 
     # 灵活字段兜底(免得加字段就迁移)
     attrs: Mapped[dict | None] = mapped_column(_JSON, nullable=True)

app/repositories/coupon_state.py

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

@@ -15,7 +15,7 @@ from __future__ import annotations
 import logging
 import math
 
-from sqlalchemy import select
+from sqlalchemy import func, select, update
 from sqlalchemy.exc import IntegrityError
 from sqlalchemy.orm import Session
 
@@ -107,6 +107,40 @@ def upsert(db: Session, payload: StoreMappingIn) -> tuple[int, int | None]:
     return 0, existing.id
 
 
+def mark_taobao_deeplink_invalid(db: Session, shop_id: str) -> int:
+    """把所有 id_taobao=shop_id 的行标记淘宝 deeplink 失效(置 invalid_at=now)。返回本次新标记的行数。
+
+    按 shopId 标记**所有**行 —— 同一个坏 shopId(撞淘宝"页面出错了"降级页)可能散在多次比价的
+    多行里, 全标掉才能让后续 lookup 不再返回它。幂等: 已标记的行(invalid_at 非 NULL)跳过。"""
+    result = db.execute(
+        update(StoreMapping)
+        .where(
+            StoreMapping.id_taobao == shop_id,
+            StoreMapping.taobao_deeplink_invalid_at.is_(None),
+        )
+        .values(taobao_deeplink_invalid_at=func.now())
+    )
+    db.commit()
+    return result.rowcount or 0
+
+
+def mark_jd_deeplink_invalid(db: Session, store_id: str) -> int:
+    """把所有 id_jd=store_id 的行标记京东 deeplink 失效(置 invalid_at=now)。返回本次新标记的行数。
+
+    同 mark_taobao_deeplink_invalid:按 storeId 标记**所有**行(撞京东"当前门店超出配送范围"页),
+    全标掉才能让后续 lookup 不再返回它。幂等:已标记的行(invalid_at 非 NULL)跳过。"""
+    result = db.execute(
+        update(StoreMapping)
+        .where(
+            StoreMapping.id_jd == store_id,
+            StoreMapping.jd_deeplink_invalid_at.is_(None),
+        )
+        .values(jd_deeplink_invalid_at=func.now())
+    )
+    db.commit()
+    return result.rowcount or 0
+
+
 # ============================================================
 # 缓存查询: 比价前按"源平台店名"反查已沉淀的各目标平台店铺 id, 命中就让 pricebot 直接
 # deeplink 跳店内搜索, 省掉"开平台→进店→分享反查"整段。
@@ -161,6 +195,12 @@ def lookup_nearest(
         if tgt == src_key:
             continue  # 不返回源平台自己
         cands = [r for r in rows if getattr(r, id_attr)]
+        if tgt == "taobao":
+            # 失效的淘宝 deeplink(撞过错误页被 invalidate)整条排除 = 当没缓存, pricebot 走正常搜店。
+            cands = [r for r in cands if r.taobao_deeplink_invalid_at is None]
+        elif tgt == "jd":
+            # 同上:失效的京东 deeplink(撞"当前门店超出配送范围"被 invalidate)整条排除。
+            cands = [r for r in cands if r.jd_deeplink_invalid_at is None]
         if not cands:
             continue
         best = _pick_best(cands, lat, lng)

app/schemas/coupon_state.py

@@ -7,16 +7,30 @@ from pydantic import BaseModel
 class CouponPromptDismissIn(BaseModel):
     """客户端拒绝/关闭领券引导窗的通知体。
 
-    server 据此记一条今日 engagement(dismissed)→ 今天这台设备不再弹引导窗。
+    server 据此记一条今日 engagement(dismissed)→ 今天**这个 App** 不再弹引导窗。
+    频控按 (device, package, 日):各 App 独立。package 缺省 ""(老客户端兼容,退化为全局态)。
     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 时是否还应弹领券引导窗。今天已 engage(领或拒)过 → false。"""
+    """切到外卖 App 时是否还应弹领券引导窗。今天**这个 App** 已 engage(弹/领/拒)过 → false。"""
 
     should_show: bool
 

app/schemas/store_mapping.py

@@ -60,3 +60,17 @@ class StoreMappingOut(BaseModel):
 
     inserted: int
     row_id: int | None = None
+
+
+class StoreMappingInvalidateIn(BaseModel):
+    """标记某平台某 shopId 的缓存 deeplink 失效(pricebot 撞错误页回退时上报)。"""
+
+    platform: str  # 目前只支持 "taobao"
+    shop_id: str  # 失效的店铺 id(淘宝 = shopId = id_taobao)
+
+
+class StoreMappingInvalidateOut(BaseModel):
+    """标记结果。affected = 本次新标记失效的行数(按 shopId 标记所有匹配行)。"""
+
+    ok: bool
+    affected: int

tests/test_store_mapping_invalidate.py

@@ -0,0 +1,156 @@
+"""淘宝 deeplink 失效标记 + lookup 过滤 + invalidate 端点测试。
+
+覆盖:按 shopId 标记所有行(幂等)、lookup 过滤失效淘宝候选、失效后新行仍可命中、
+invalidate 端点鉴权(503 未配 / 401 头错 / 200)、端到端标记后 lookup MISS、非淘宝 no-op。
+"""
+from __future__ import annotations
+
+import pytest
+
+from app.core.config import settings
+from app.db.session import SessionLocal
+from app.models.store_mapping import StoreMapping
+from app.repositories import store_mapping as repo
+
+_SECRET = "test-internal-secret-only-for-pytest"
+
+
+def _mk_row(db, *, trace_id, name_meituan=None, name_taobao=None,
+            id_taobao=None, deeplink=None, lat=None, lng=None,
+            name_jd=None, id_jd=None, jd_deeplink=None):
+    row = StoreMapping(
+        trace_id=trace_id, business_type="food",
+        name_meituan=name_meituan, name_taobao=name_taobao,
+        id_taobao=id_taobao, taobao_deeplink=deeplink, lat=lat, lng=lng,
+        name_jd=name_jd, id_jd=id_jd, jd_deeplink=jd_deeplink,
+    )
+    db.add(row)
+    db.commit()
+    db.refresh(row)
+    return row
+
+
+@pytest.fixture()
+def db():
+    """每个用例前后清空 store_mapping(表由 conftest 的 create_all 建好,session 级共享)。"""
+    s = SessionLocal()
+    s.query(StoreMapping).delete()
+    s.commit()
+    yield s
+    s.query(StoreMapping).delete()
+    s.commit()
+    s.close()
+
+
+# ---------- repo 层 ----------
+
+def test_mark_invalid_marks_all_rows_with_shop_id(db):
+    # 同一个坏 shopId 散在两行(两次比价),另一行不同 shopId
+    _mk_row(db, trace_id="t1", name_meituan="绝味鸭脖", name_taobao="绝味鸭脖", id_taobao="BAD1", deeplink="dl_a")
+    _mk_row(db, trace_id="t2", name_meituan="绝味鸭脖", name_taobao="绝味鸭脖", id_taobao="BAD1", deeplink="dl_b")
+    _mk_row(db, trace_id="t3", name_meituan="绝味鸭脖", name_taobao="绝味鸭脖", id_taobao="GOOD9", deeplink="dl_g")
+
+    # 按 shopId 标记所有行
+    assert repo.mark_taobao_deeplink_invalid(db, "BAD1") == 2
+    # 幂等:已标记的不重复
+    assert repo.mark_taobao_deeplink_invalid(db, "BAD1") == 0
+
+    rows = {r.trace_id: r for r in db.query(StoreMapping).all()}
+    assert rows["t1"].taobao_deeplink_invalid_at is not None
+    assert rows["t2"].taobao_deeplink_invalid_at is not None
+    assert rows["t3"].taobao_deeplink_invalid_at is None  # 不同 shopId 不动
+
+
+def test_lookup_filters_invalid_taobao(db):
+    _mk_row(db, trace_id="t1", name_meituan="绝味鸭脖", name_taobao="绝味鸭脖", id_taobao="BAD1", deeplink="dl")
+    # 标记前命中
+    assert repo.lookup_nearest(db, "meituan", "绝味鸭脖")["taobao"]["shop_id"] == "BAD1"
+    # 标记失效后淘宝候选被过滤 → MISS(仅此一条淘宝)
+    repo.mark_taobao_deeplink_invalid(db, "BAD1")
+    assert "taobao" not in repo.lookup_nearest(db, "meituan", "绝味鸭脖")
+
+
+def test_lookup_picks_new_valid_row_after_invalidate(db):
+    # 失效旧行 + 重搜写的新行(新 shopId,invalid_at=NULL)共存 → lookup 选到新行
+    _mk_row(db, trace_id="t1", name_meituan="店A", name_taobao="店A", id_taobao="BAD1", deeplink="dl_bad")
+    repo.mark_taobao_deeplink_invalid(db, "BAD1")
+    _mk_row(db, trace_id="t2", name_meituan="店A", name_taobao="店A", id_taobao="NEW2", deeplink="dl_new")
+    assert repo.lookup_nearest(db, "meituan", "店A")["taobao"]["shop_id"] == "NEW2"
+
+
+# ---------- invalidate 端点 ----------
+
+def test_invalidate_endpoint_secret_unset_503(client, monkeypatch):
+    monkeypatch.setattr(settings, "INTERNAL_API_SECRET", "")  # 未配 = 端点关闭
+    r = client.post("/internal/store-mapping/invalidate",
+                    json={"platform": "taobao", "shop_id": "X"})
+    assert r.status_code == 503
+
+
+def test_invalidate_endpoint_auth(client, monkeypatch):
+    monkeypatch.setattr(settings, "INTERNAL_API_SECRET", _SECRET)
+    body = {"platform": "taobao", "shop_id": "X"}
+    assert client.post("/internal/store-mapping/invalidate", json=body).status_code == 401
+    assert client.post("/internal/store-mapping/invalidate", json=body,
+                       headers={"X-Internal-Secret": "wrong"}).status_code == 401
+    r = client.post("/internal/store-mapping/invalidate", json=body,
+                    headers={"X-Internal-Secret": _SECRET})
+    assert r.status_code == 200 and r.json()["ok"] is True
+
+
+def test_invalidate_endpoint_marks_and_lookup_miss(client, db, monkeypatch):
+    monkeypatch.setattr(settings, "INTERNAL_API_SECRET", _SECRET)
+    _mk_row(db, trace_id="t1", name_meituan="店B", name_taobao="店B", id_taobao="BADX", deeplink="dl")
+    _mk_row(db, trace_id="t2", name_meituan="店B", name_taobao="店B", id_taobao="BADX", deeplink="dl2")
+    r = client.post("/internal/store-mapping/invalidate",
+                    json={"platform": "taobao", "shop_id": "BADX"},
+                    headers={"X-Internal-Secret": _SECRET})
+    assert r.status_code == 200 and r.json()["affected"] == 2
+    lk = client.get("/internal/store-mapping/lookup",
+                    params={"source_platform": "meituan", "name": "店B"},
+                    headers={"X-Internal-Secret": _SECRET})
+    assert "taobao" not in lk.json()
+
+
+def test_invalidate_endpoint_unsupported_platform_noop(client, monkeypatch):
+    # 当前支持 taobao/jd;其它平台(如 meituan)no-op 返 affected=0
+    monkeypatch.setattr(settings, "INTERNAL_API_SECRET", _SECRET)
+    r = client.post("/internal/store-mapping/invalidate",
+                    json={"platform": "meituan", "shop_id": "X"},
+                    headers={"X-Internal-Secret": _SECRET})
+    assert r.status_code == 200 and r.json()["affected"] == 0
+
+
+# ---------- 京东(对称淘宝)----------
+
+def test_mark_jd_invalid_marks_all_rows_with_store_id(db):
+    _mk_row(db, trace_id="j1", name_meituan="兰州拉面", name_jd="兰州拉面", id_jd="JBAD", jd_deeplink="dl_a")
+    _mk_row(db, trace_id="j2", name_meituan="兰州拉面", name_jd="兰州拉面", id_jd="JBAD", jd_deeplink="dl_b")
+    _mk_row(db, trace_id="j3", name_meituan="兰州拉面", name_jd="兰州拉面", id_jd="JGOOD", jd_deeplink="dl_g")
+    assert repo.mark_jd_deeplink_invalid(db, "JBAD") == 2
+    assert repo.mark_jd_deeplink_invalid(db, "JBAD") == 0  # 幂等
+    rows = {r.trace_id: r for r in db.query(StoreMapping).all()}
+    assert rows["j1"].jd_deeplink_invalid_at is not None
+    assert rows["j2"].jd_deeplink_invalid_at is not None
+    assert rows["j3"].jd_deeplink_invalid_at is None  # 不同 storeId 不动
+
+
+def test_lookup_filters_invalid_jd(db):
+    _mk_row(db, trace_id="j1", name_meituan="兰州拉面", name_jd="兰州拉面", id_jd="JBAD", jd_deeplink="dl")
+    assert repo.lookup_nearest(db, "meituan", "兰州拉面")["jd"]["store_id"] == "JBAD"
+    repo.mark_jd_deeplink_invalid(db, "JBAD")
+    assert "jd" not in repo.lookup_nearest(db, "meituan", "兰州拉面")
+
+
+def test_invalidate_endpoint_jd_marks_and_lookup_miss(client, db, monkeypatch):
+    monkeypatch.setattr(settings, "INTERNAL_API_SECRET", _SECRET)
+    _mk_row(db, trace_id="j1", name_meituan="店J", name_jd="店J", id_jd="JBADX", jd_deeplink="dl")
+    _mk_row(db, trace_id="j2", name_meituan="店J", name_jd="店J", id_jd="JBADX", jd_deeplink="dl2")
+    r = client.post("/internal/store-mapping/invalidate",
+                    json={"platform": "jd", "shop_id": "JBADX"},
+                    headers={"X-Internal-Secret": _SECRET})
+    assert r.status_code == 200 and r.json()["affected"] == 2
+    lk = client.get("/internal/store-mapping/lookup",
+                    params={"source_platform": "meituan", "name": "店J"},
+                    headers={"X-Internal-Secret": _SECRET})
+    assert "jd" not in lk.json()