feat(dev): ensure_pg 加显式 SQLite 逃生舱 + 修 Docker 检测/项目名撞名;新增 run8771 起 admin

- ensure_pg: 无 Docker 时【显式】降级 SQLite(带醒目降级横幅),不再硬失败(反转设计 D4) - ensure_pg: _docker_cli_ok 改用 `docker --version`(纯客户端),修「装了 Docker 但没启动」被 `docker version`(要连 daemon)误判成「没装 CLI」而绕过自动拉起(需求②) - ensure_pg: 钉死 COMPOSE_PROJECT_NAME=shaguabijia + 清「同名但非本项目」残留容器, 修跨目录/worktree 切换时 container_name 撞名 + pgdata 卷分裂 - run8771.bat: 新增 admin 后端(:8771)启动脚本,跑 app.admin.main:admin_app(run.bat 对等版) - 设计文档 §10 记录以上 D4 反转与三处修复 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
docs(dev): 记录本地 Docker PostgreSQL 用法,区分生产原生 PG 路径
2026-07-27 19:12:29 +08:00 · 2026-07-08 19:13:51 +08:00 · 2026-07-08 18:49:46 +08:00 · 2026-07-08 18:46:07 +08:00 · 2026-07-08 18:38:59 +08:00 · 2026-07-08 18:38:09 +08:00
42 changed files with 3779 additions and 156 deletions
@@ -6,8 +6,11 @@ APP_NAME=shaguabijia-app-server
 APP_DEBUG=true

 # ===== 数据库 =====
-# SQLite 本地文件路径。生产环境用 /opt/shaguabijia-app-server/data.db
-DATABASE_URL=sqlite:///./data/app.db
+# 本地开发/测试统一用 Docker PostgreSQL:run.bat/run.sh 会自动拉起容器
+# (docker-compose.yml + scripts/ensure_pg.py)。详见 docs/database/postgres-migration.md。
+# 生产用原生 PG,由 scripts/init_postgres.py 写入强随机密码的连接串。
+# ⚠️ scheme 必须是 postgresql+psycopg://(psycopg3);不要写成 postgresql://(会去找未装的 psycopg2)。
+DATABASE_URL=postgresql+psycopg://shaguabijia_app:shaguabijia_dev_pw@localhost:5432/shaguabijia

 # ===== JWT =====
 # 生产部署务必改成随机长字符串,可用:python -c "import secrets; print(secrets.token_urlsafe(64))"
@@ -48,3 +48,15 @@ secrets/*
 # 运行日志(run.sh 输出, 不入库)
 *.log
 logs/
+
+# Claude Code 自动持久化的权限 allowlist / 个人本地设置(会话专属,不入库)。
+# 需要团队共享的 Claude 配置(commands/ 等)可单独 git add -f,不受此忽略影响。
+.claude/settings.json
+.claude/settings.local.json
+tests/meituan_coupon_bj.tsv
+tests/meituan_coupon_data.tsv
+tests/meituan_coupon_fz.tsv
+tests/meituan_coupon_xm.tsv
+
+# git worktrees (superpowers 隔离工作区)
+.worktrees/
@@ -76,8 +76,8 @@ Endpoints under `app/api/internal/` are for server-to-server communication (pric

 ## Database

- **Dev**: SQLite (`sqlite:///./data/app.db`), `check_same_thread=False`, no connection pool.
- **Prod**: PostgreSQL — just change `DATABASE_URL` in `.env`. Pool size 10 + max overflow 20, pool_recycle 3600.
+- **Dev/Test**: Docker PostgreSQL 16 — `run.sh`/`run.bat` auto-start it via `scripts/ensure_pg.py` + `docker-compose.yml`; `.env.example` ships the PG URL by default; pytest uses the same container's `shaguabijia_test` DB. **Local no longer uses SQLite** (the SQLite branch in `db/session.py` is retained as a fallback only).
+- **Prod**: native PostgreSQL — bootstrap with `scripts/init_postgres.py` (no Docker). Pool size 10 + max overflow 20, pool_recycle 3600.
 - **Migrations**: Alembic with `render_as_batch` for SQLite compatibility. ~60+ migration files in `alembic/versions/` (filenames are descriptive, not hex prefixes). Migration chain uses `down_revision` within each file.
 - **New models**: Define in `app/models/`, import in `app/models/__init__.py`, then run `alembic revision --autogenerate`.

@@ -89,7 +89,7 @@ All config via `pydantic-settings` in `app/core/config.py`. Single `Settings` cl

 ## Testing

- `tests/conftest.py`: Sets env vars BEFORE imports, creates temp SQLite file, builds all tables with `Base.metadata.create_all()`, tears down with `drop_all()` + unlink.
+- `tests/conftest.py`: Sets env vars BEFORE imports, ensures the Docker PG `shaguabijia_test` DB via `scripts/ensure_pg.py`, builds all tables with `Base.metadata.create_all()` (drop+create for a clean start), tears down with `drop_all()`.
 - External integrations are monkeypatched in tests (e.g., WeChat Pay, Jiguang, Pangle callbacks) — tests never make real HTTP calls.
 - `TestClient` from FastAPI is used for all tests. Rate limiting is disabled globally in tests.

@@ -385,10 +385,33 @@ def ad_revenue_report(
        for k, v in type_map.items()
    }

-    # DAU:复用大盘「今日活跃」口径(stats.today_dau,last_login_at)。该口径只能算今日,
-    # 故仅当查询=今日单天时给值;历史 / 多天区间返回 None,前端显示「-」。
-    is_today = date_from == date_to == rewards.cn_today().isoformat()
-    dau = admin_stats.today_dau(db) if is_today else None
+    # 分场景小计(按 feed_scene:展示条数 + 预估收益),同 type_stats 基于全量 events——
+    # 供数据大盘「领券广告 / 比价广告」卡用。此前大盘是在分页 items 里按 feed_scene 现算,
+    # 2026-07-02 起信息流逐条展示行(唯一带收益 + 场景的行)不再进主表 items,现算恒为 0;
+    # 改为服务端在全量上聚合下发(也顺带不受 limit 分页截断影响)。feed_scene 为空(激励视频 /
+    # 旧数据)不计入任何场景桶。
+    scene_map: dict[str, dict] = {}
+    for e in events:
+        sc = e.get("feed_scene")
+        if not sc:
+            continue
+        s = scene_map.get(sc)
+        if s is None:
+            s = {"impressions": 0, "revenue_yuan": 0.0}
+            scene_map[sc] = s
+        s["impressions"] += e["impressions"]
+        s["revenue_yuan"] += e["revenue_yuan"]
+    scene_stats = {
+        k: {"impressions": v["impressions"], "revenue_yuan": round(v["revenue_yuan"], 6)}
+        for k, v in scene_map.items()
+    }
+
+    # DAU:复用数据大盘活跃用户口径(登录 + 开始比价 + 开始领券,按用户去重),按所选日期区间
+    # 统计(含今日),历史 / 多天区间同样有值。ARPU = 区间预估收益 ÷ 区间活跃用户。全局口径,
+    # 不随 user / ad_type / feed_scene / app_env 筛选变化(活跃用户口径无这些维度)。
+    dau = admin_stats.period_active_dau(
+        db, _date.fromisoformat(date_from), _date.fromisoformat(date_to)
+    )

    # 主表「逐行」= 单次广告行为(2026-07 按「一次比价/领券放一块」聚合):激励视频 = 一次观看一行(展示+发奖
    # 按 ad_session_id 合并);一次比价 / 一次领券 = 该次整场多条广告按 ad_session_id 聚成一行(展开看逐条)。
@@ -416,6 +439,7 @@ def ad_revenue_report(
        "daily": daily,
        "hourly": hourly,
        "type_stats": type_stats,
+        "scene_stats": scene_stats,
        "dau": dau,
        "items": main_rows[offset:offset + limit],
    }
@@ -51,7 +51,27 @@ def _yuan_to_cents(v: object) -> int | None:

 def _ts_to_dt(ts: object) -> datetime | None:
    """秒级时间戳 → tz-aware UTC datetime(绝对时刻,前端按北京展示)。"""
-    if not ts:
+    if ts is None:
+        return None
+    if isinstance(ts, datetime):
+        return ts if ts.tzinfo else ts.replace(tzinfo=_BJ_TZ).astimezone(timezone.utc)
+    s = str(ts).strip()
+    if not s or s.lower() == "null":
+        return None
+    try:
+        seconds = float(Decimal(s))
+    except (InvalidOperation, ValueError):
+        return None
+    if seconds == 0:
+        return None
+    # 美团文档是秒级时间戳，这里顺手兼容毫秒/微秒，避免上游格式变化导致时间再次落空。
+    if abs(seconds) > 10_000_000_000_000:
+        seconds /= 1_000_000
+    elif abs(seconds) > 10_000_000_000:
+        seconds /= 1_000
+    try:
+        return datetime.fromtimestamp(seconds, tz=timezone.utc)
+    except (OverflowError, OSError, ValueError):
        return None


@@ -83,10 +103,6 @@ def _pick(row: dict[str, Any], *keys: str) -> Any:
        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):
-        return None


 # ───────────── 群 ─────────────
@@ -11,6 +11,7 @@ from zoneinfo import ZoneInfo
 from sqlalchemy import Select, asc, case, desc, func, or_, select
 from sqlalchemy.orm import Session

+from app.admin.repositories.stats import COMPARE_START_EVENT, COUPON_START_EVENT
 from app.core import rewards
 from app.core.config import settings
 from app.models.ad_feed_reward import AdFeedRewardRecord
@@ -18,12 +19,22 @@ from app.models.ad_reward import AdRewardRecord
 from app.models.admin import AdminAuditLog
 from app.models.analytics_event import AnalyticsEvent
 from app.models.comparison import ComparisonRecord
+from app.models.coupon_state import CouponPromptEngagement
 from app.models.device import DeviceLiveness
 from app.models.feedback import Feedback
 from app.models.onboarding import OnboardingCompletion
 from app.models.price_report import PriceReport
 from app.models.user import User
-from app.models.wallet import CashTransaction, CoinAccount, CoinTransaction, WithdrawOrder
+from app.models.wallet import (
+    CashTransaction,
+    CoinAccount,
+    CoinTransaction,
+    InviteCashTransaction,
+    WithdrawOrder,
+)
+
+# 「最近活跃」计入的行为事件(与大盘 DAU/留存活跃口径一致:开始比价 + 开始领券)
+_ACTIVE_EVENTS = (COMPARE_START_EVENT, COUPON_START_EVENT)

 # 折算成可提现现金时,非广告金币来源的排除集(广告单独统计、人工调整不算"赚取")
 _NON_TASK_BIZ_TYPES = ("reward_video", "feed_ad_reward", "admin_grant", "admin_deduct")
@@ -76,6 +87,86 @@ def offset_paginate(
    return items, next_cursor, total


+def _last_active_parts():
+    """「最近活跃」的两个按 user_id 预聚合派生表(最近开始比价/领券事件、最近领券发起)。
+
+    活跃口径与大盘 DAU/留存一致(2026-07-05 产品定:进入 App≈登录 last_login_at +
+    发起比价 real_compare_start + 发起领券 real_coupon_start/claim_started)。
+    用 LEFT JOIN 预聚合而非相关标量子查询:后者在 PG 上对 users 每行各跑一个 SubPlan
+    (排序键、range 筛选、offset_paginate 的 count 三处叠加),埋点表大了会拖垮列表接口;
+    预聚合借 analytics_event.event 索引只扫两类 start 事件,每次查询聚合一次。
+    """
+    ev_agg = (
+        select(
+            AnalyticsEvent.user_id.label("user_id"),
+            func.max(AnalyticsEvent.created_at).label("last_at"),
+        )
+        .where(
+            AnalyticsEvent.user_id.is_not(None),
+            AnalyticsEvent.event.in_(_ACTIVE_EVENTS),
+        )
+        .group_by(AnalyticsEvent.user_id)
+        .subquery()
+    )
+    eng_agg = (
+        select(
+            CouponPromptEngagement.user_id.label("user_id"),
+            func.max(CouponPromptEngagement.created_at).label("last_at"),
+        )
+        .where(
+            CouponPromptEngagement.user_id.is_not(None),
+            CouponPromptEngagement.engage_type == "claim_started",
+        )
+        .group_by(CouponPromptEngagement.user_id)
+        .subquery()
+    )
+    return ev_agg, eng_agg
+
+
+def _norm_utc(dt: datetime | None) -> datetime | None:
+    """naive 视为 UTC 补 tzinfo(SQLite 读回 naive、PG 读回 aware,混着 max() 会 TypeError)。"""
+    if dt is None:
+        return None
+    return dt if dt.tzinfo is not None else dt.replace(tzinfo=timezone.utc)
+
+
+def _attach_last_active(db: Session, users: list[User]) -> None:
+    """给本页用户瞬态挂 last_active_at(非 DB 列,供 AdminUserListItem from_attributes 读)。
+
+    口径同 [_last_active_expr];按本页 user_id 批量两次 GROUP BY,防 N+1。
+    """
+    uids = [u.id for u in users]
+    if not uids:
+        return
+    ev_map = dict(
+        db.execute(
+            select(AnalyticsEvent.user_id, func.max(AnalyticsEvent.created_at))
+            .where(
+                AnalyticsEvent.user_id.in_(uids),
+                AnalyticsEvent.event.in_(_ACTIVE_EVENTS),
+            )
+            .group_by(AnalyticsEvent.user_id)
+        ).all()
+    )
+    eng_map = dict(
+        db.execute(
+            select(CouponPromptEngagement.user_id, func.max(CouponPromptEngagement.created_at))
+            .where(
+                CouponPromptEngagement.user_id.in_(uids),
+                CouponPromptEngagement.engage_type == "claim_started",
+            )
+            .group_by(CouponPromptEngagement.user_id)
+        ).all()
+    )
+    for u in users:
+        candidates = [
+            _norm_utc(u.last_login_at),
+            _norm_utc(ev_map.get(u.id)),
+            _norm_utc(eng_map.get(u.id)),
+        ]
+        u.last_active_at = max((c for c in candidates if c is not None), default=None)
+
+
 def list_users(
    db: Session,
    *,
@@ -87,16 +178,34 @@ def list_users(
    created_to: datetime | None = None,
    last_login_from: datetime | None = None,
    last_login_to: datetime | None = None,
+    last_active_from: datetime | None = None,
+    last_active_to: datetime | None = None,
    sort_by: str = "id",
    sort_order: str = "desc",
    limit: int = 20,
    cursor: int | None = None,
 ) -> tuple[list[User], int | None, int]:
-    """用户列表(admin 全量)。支持手机号前缀 / 渠道 / 状态 / 昵称模糊 / 注册·最近登录时间范围筛选,
-    按 id·注册时间·最近登录排序。**offset 分页**(cursor=offset):任意列排序下游标语义统一,
+    """用户列表(admin 全量)。支持手机号前缀 / 渠道 / 状态 / 昵称模糊 / 注册·最近登录·最近活跃
+    时间范围筛选,按 id·注册时间·最近登录·最近活跃排序;每页附带计算列 last_active_at
+    (口径见 [_last_active_expr])。**offset 分页**(cursor=offset):任意列排序下游标语义统一,
    代价是翻页期间数据变动可能错位一条——admin 低频场景可接受(同 [list_all_withdraw_orders])。
    日期入参统一转 tz-aware UTC 比较(列为 timestamptz,见 _as_utc)。"""
-    stmt = select(User)
+    # 最近活跃 = max(最近登录, 最近行为事件, 最近领券发起)。PG 用 GREATEST;SQLite 标量 max()
+    # 任一参数 NULL 即返回 NULL,故 LEFT JOIN 未命中侧 coalesce 到 last_login_at 兜底
+    # (注册即登录,该列恒非空)。派生表 1:1(按 user_id 聚合),outerjoin 不会放大行数,
+    # offset_paginate 的 count 不受影响。
+    ev_agg, eng_agg = _last_active_parts()
+    greatest = func.greatest if db.get_bind().dialect.name == "postgresql" else func.max
+    last_active = greatest(
+        User.last_login_at,
+        func.coalesce(ev_agg.c.last_at, User.last_login_at),
+        func.coalesce(eng_agg.c.last_at, User.last_login_at),
+    )
+    stmt = (
+        select(User)
+        .outerjoin(ev_agg, ev_agg.c.user_id == User.id)
+        .outerjoin(eng_agg, eng_agg.c.user_id == User.id)
+    )
    if phone:
        stmt = stmt.where(User.phone.like(f"{phone}%"))  # 前缀匹配
    if register_channel:
@@ -113,16 +222,25 @@ def list_users(
        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(last_login_to))
+    if last_active_from is not None:
+        stmt = stmt.where(last_active >= _as_utc(last_active_from))
+    if last_active_to is not None:
+        stmt = stmt.where(last_active <= _as_utc(last_active_to))

    sort_cols = {
        "id": User.id,
        "created_at": User.created_at,
        "last_login_at": User.last_login_at,
+        "last_active_at": last_active,
    }
    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)
-    return offset_paginate(db, stmt, (order_fn(sort_col), id_order), limit=limit, cursor=cursor)
+    items, next_cursor, total = offset_paginate(
+        db, stmt, (order_fn(sort_col), id_order), limit=limit, cursor=cursor
+    )
+    _attach_last_active(db, items)
+    return items, next_cursor, total


 def _attach_user_info(db: Session, records: list[ComparisonRecord | Feedback | PriceReport]) -> None:
@@ -734,26 +852,19 @@ def withdraw_risk_flags(
    return flags, score


-def withdraw_ledger_check(db: Session) -> dict:
-    cash_balance_total = int(
-        db.execute(select(func.coalesce(func.sum(CoinAccount.cash_balance_cents), 0))).scalar_one()
-    )
-    cash_txn_total = int(
-        db.execute(select(func.coalesce(func.sum(CashTransaction.amount_cents), 0))).scalar_one()
-    )
+def _check_withdraw_ledger_side(
+    orders: list[WithdrawOrder], txns: list, *, withdraw_biz: str, refund_biz: str
+) -> dict:
+    """对某一本账(普通现金 / 邀请奖励金)做提现单 ↔ 流水的交叉校验。

-    orders = list(db.execute(select(WithdrawOrder)).scalars().all())
-    cash_txns = list(
-        db.execute(
-            select(CashTransaction).where(
-                CashTransaction.biz_type.in_(("withdraw", "withdraw_refund"))
-            )
-        ).scalars().all()
-    )
-    withdraw_refs = {txn.ref_id for txn in cash_txns if txn.biz_type == "withdraw"}
+    orders 已按 source 过滤到本账;txns 是本账流水表里 withdraw_biz/refund_biz 两类流水。
+    规则:每单发起应有一条扣款流水(ref_id=out_bill_no);失败/拒绝单应有且仅一条退款流水;
+    非退款终态不应出现退款流水。四个计数全为 0 即本账自洽。
+    """
+    withdraw_refs = {txn.ref_id for txn in txns if txn.biz_type == withdraw_biz}
    refund_counts: dict[str, int] = {}
-    for txn in cash_txns:
-        if txn.biz_type == "withdraw_refund" and txn.ref_id:
+    for txn in txns:
+        if txn.biz_type == refund_biz and txn.ref_id:
            refund_counts[txn.ref_id] = refund_counts.get(txn.ref_id, 0) + 1

    missing_withdraw = 0
@@ -768,24 +879,95 @@ def withdraw_ledger_check(db: Session) -> dict:
        if has_refund and order.status not in {"failed", "rejected"}:
            refund_on_non_terminal += 1

-    duplicate_refund = sum(1 for count in refund_counts.values() if count > 1)
-    diff = cash_balance_total - cash_txn_total
+    return {
+        "missing_withdraw": missing_withdraw,
+        "missing_refund": missing_refund,
+        "duplicate_refund": sum(1 for count in refund_counts.values() if count > 1),
+        "refund_on_non_terminal": refund_on_non_terminal,
+    }
+
+
+def withdraw_ledger_check(db: Session) -> dict:
+    """现金账本校验:两本物理隔离的账各自对账(产品红线:coin_cash / invite_cash 不串)。
+
+    普通现金:CoinAccount.cash_balance_cents ↔ cash_transaction(withdraw/withdraw_refund);
+    邀请奖励金:CoinAccount.invite_cash_balance_cents ↔ invite_cash_transaction
+              (invite_withdraw/invite_withdraw_refund)。
+    提现单按 source 分流到对应账核对——邀请提现的流水写在 invite_cash_transaction 表,
+    绝不能拿去和普通现金流水比(否则每笔邀请提现单都会被误报「缺扣款/缺退款流水」)。
+    分流口径与 create_withdraw 一致:仅 source==invite_cash 走邀请账,其余(含历史空值)归普通现金。
+    """
+    orders = list(db.execute(select(WithdrawOrder)).scalars().all())
+    coin_orders = [o for o in orders if o.source != "invite_cash"]
+    invite_orders = [o for o in orders if o.source == "invite_cash"]
+
+    # —— 普通现金账(coin_cash) ——
+    cash_balance_total = int(
+        db.execute(select(func.coalesce(func.sum(CoinAccount.cash_balance_cents), 0))).scalar_one()
+    )
+    cash_txn_total = int(
+        db.execute(select(func.coalesce(func.sum(CashTransaction.amount_cents), 0))).scalar_one()
+    )
+    cash_txns = list(
+        db.execute(
+            select(CashTransaction).where(
+                CashTransaction.biz_type.in_(("withdraw", "withdraw_refund"))
+            )
+        ).scalars().all()
+    )
+    coin = _check_withdraw_ledger_side(
+        coin_orders, cash_txns, withdraw_biz="withdraw", refund_biz="withdraw_refund"
+    )
+    cash_diff = cash_balance_total - cash_txn_total
+
+    # —— 邀请奖励金账(invite_cash,独立账户 + 独立流水表) ——
+    invite_balance_total = int(
+        db.execute(
+            select(func.coalesce(func.sum(CoinAccount.invite_cash_balance_cents), 0))
+        ).scalar_one()
+    )
+    invite_txn_total = int(
+        db.execute(
+            select(func.coalesce(func.sum(InviteCashTransaction.amount_cents), 0))
+        ).scalar_one()
+    )
+    invite_txns = list(
+        db.execute(
+            select(InviteCashTransaction).where(
+                InviteCashTransaction.biz_type.in_(("invite_withdraw", "invite_withdraw_refund"))
+            )
+        ).scalars().all()
+    )
+    invite = _check_withdraw_ledger_side(
+        invite_orders, invite_txns,
+        withdraw_biz="invite_withdraw", refund_biz="invite_withdraw_refund",
+    )
+    invite_diff = invite_balance_total - invite_txn_total
+
    ok = (
-        diff == 0
-        and missing_withdraw == 0
-        and missing_refund == 0
-        and duplicate_refund == 0
-        and refund_on_non_terminal == 0
+        cash_diff == 0
+        and invite_diff == 0
+        and all(v == 0 for v in coin.values())
+        and all(v == 0 for v in invite.values())
    )
    return {
        "ok": ok,
+        # 普通现金账(coin_cash:金币兑换的现金)
        "cash_balance_total_cents": cash_balance_total,
        "cash_transaction_total_cents": cash_txn_total,
-        "balance_diff_cents": diff,
-        "missing_withdraw_txn_count": missing_withdraw,
-        "missing_refund_txn_count": missing_refund,
-        "duplicate_refund_txn_count": duplicate_refund,
-        "refund_txn_on_non_terminal_count": refund_on_non_terminal,
+        "balance_diff_cents": cash_diff,
+        "missing_withdraw_txn_count": coin["missing_withdraw"],
+        "missing_refund_txn_count": coin["missing_refund"],
+        "duplicate_refund_txn_count": coin["duplicate_refund"],
+        "refund_txn_on_non_terminal_count": coin["refund_on_non_terminal"],
+        # 邀请奖励金账(invite_cash:与普通现金物理隔离,各自对账)
+        "invite_cash_balance_total_cents": invite_balance_total,
+        "invite_cash_transaction_total_cents": invite_txn_total,
+        "invite_balance_diff_cents": invite_diff,
+        "invite_missing_withdraw_txn_count": invite["missing_withdraw"],
+        "invite_missing_refund_txn_count": invite["missing_refund"],
+        "invite_duplicate_refund_txn_count": invite["duplicate_refund"],
+        "invite_refund_txn_on_non_terminal_count": invite["refund_on_non_terminal"],
    }


@@ -5,17 +5,23 @@ user.last_login_at / comparison_record.status / withdraw_order.status)要加索
 """
 from __future__ import annotations

+from collections import Counter
 from datetime import date, datetime, time, timedelta, timezone
 from decimal import Decimal, InvalidOperation

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

+from app.admin.repositories.coupon_data import _percentile
 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.coupon_state import (
+    CouponClaimRecord,
+    CouponPromptEngagement,
+    CouponSession,
+)
 from app.models.cps_order import CpsOrder
 from app.models.feedback import Feedback
 from app.models.savings import SavingsRecord
@@ -55,29 +61,10 @@ def _beijing_today_start_utc() -> datetime:
 def today_dau(db: Session) -> int:
    """今日活跃用户数(DAU):登录 + 开始比价 + 开始领券,按用户去重。

-    广告收益报表复用这个函数;历史窗口 DAU 由 dashboard_overview 的 period 口径另算。
+    = period_active_dau(今天, 今天);历史 / 多天窗口用 period_active_dau 传区间(广告收益报表复用)。
    """
    today_bj = datetime.now(_BEIJING).date()
-    today_start = _beijing_today_start_utc()
-    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)
+    return period_active_dau(db, today_bj, today_bj)


 def _default_period_end() -> date:
@@ -134,6 +121,56 @@ def _event_user_ids(
    )


+def _period_active_user_ids(
+    db: Session,
+    *,
+    start_utc: datetime,
+    end_utc: datetime,
+    period_from: date,
+    period_to: date,
+) -> set[int]:
+    """区间去重活跃用户 id 集合:登录(last_login_at)+ 开始比价(real_compare_start)+
+    开始领券(real_coupon_start / claim_started)。
+
+    user / analytics_event 用 UTC aware 边界 [start_utc, end_utc);coupon_prompt_engagement
+    的 engage_date 是北京自然日 date 列,用 [period_from, period_to] 闭区间。今日 / 历史 / 多天通用。
+    """
+    login_user_ids = _id_set(
+        db,
+        select(User.id).where(User.last_login_at >= start_utc, User.last_login_at < end_utc),
+    )
+    compare_start_user_ids = _event_user_ids(db, (COMPARE_START_EVENT,), start_utc, end_utc)
+    coupon_event_user_ids = _event_user_ids(db, (COUPON_START_EVENT,), start_utc, end_utc)
+    coupon_claim_user_ids = _id_set(
+        db,
+        select(CouponPromptEngagement.user_id).where(
+            CouponPromptEngagement.engage_date >= period_from,
+            CouponPromptEngagement.engage_date <= period_to,
+            CouponPromptEngagement.engage_type == "claim_started",
+        ),
+    )
+    return login_user_ids | compare_start_user_ids | coupon_event_user_ids | coupon_claim_user_ids
+
+
+def period_active_dau(db: Session, date_from: date, date_to: date) -> int:
+    """任意北京自然日区间 [date_from, date_to] 的去重活跃用户数。
+
+    与数据大盘 period.users.active 同口径(登录 + 开始比价 + 开始领券);广告收益报表按所选
+    日期区间(含今日)复用,ARPU = 区间预估收益 ÷ 本数。全局口径,不随用户 / 类型 / 场景筛选变化。
+    """
+    period_from, period_to = _normalize_period(date_from, date_to)
+    start_utc, end_utc, _start_local, _end_local = _period_bounds(period_from, period_to)
+    return len(
+        _period_active_user_ids(
+            db,
+            start_utc=start_utc,
+            end_utc=end_utc,
+            period_from=period_from,
+            period_to=period_to,
+        )
+    )
+
+
 def _commission_rate_percent(raw: str | None) -> Decimal | None:
    """美团 commissionRate 原值: "300"=3%, "10"=0.1%;也兼容 "3%"。"""
    if raw is None:
@@ -261,31 +298,19 @@ def dashboard_overview(
    period_new_user_ids = _user_id_set(
        select(User.id).where(User.created_at >= start_utc, User.created_at < end_utc)
    )
-    login_user_ids = _user_id_set(
-        select(User.id).where(User.last_login_at >= start_utc, User.last_login_at < end_utc)
-    )
-    compare_start_user_ids = _event_user_ids(
-        db, (COMPARE_START_EVENT,), start_utc, end_utc
-    )
-    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_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)
-        if period_new_user_ids
-        else None
+    period_active_user_ids = _period_active_user_ids(
+        db,
+        start_utc=start_utc,
+        end_utc=end_utc,
+        period_from=period_from,
+        period_to=period_to,
    )
+    # 留存口径(2026-07-05 产品改):次日留存——窗口内每天 D,取 **D-1 日(前日)新增**用户,
+    # 统计其 D 日活跃(登录/开始比价/开始领券)比例,逐日累加。默认窗口=昨日单天,即
+    # 「前日新增用户的昨日留存」。原口径(窗口内新增∩窗口内活跃)在单日窗口下≈100% 无意义
+    # (注册即登录,当天新增必然当天活跃)。逐日 cohort 在下方 trend 循环内顺带累计。
+    retention_cohort_total = 0
+    retention_retained_total = 0
    trend_points: list[dict] = []
    for cur_date in _date_range(period_from, period_to):
        day_start_utc, day_end_utc, day_start_local, day_end_local = _period_bounds(
@@ -295,33 +320,26 @@ def dashboard_overview(
            ComparisonRecord.created_at >= day_start_local,
            ComparisonRecord.created_at < day_end_local,
        )
-        daily_login_user_ids = _user_id_set(
+        daily_active_user_ids = _period_active_user_ids(
+            db,
+            start_utc=day_start_utc,
+            end_utc=day_end_utc,
+            period_from=cur_date,
+            period_to=cur_date,
+        )
+        # 次日留存:cohort = 前一日(D-1)新增用户,留存 = 其中当日(D)活跃者(口径见上)。
+        cohort_ids = _user_id_set(
            select(User.id).where(
-                User.last_login_at >= day_start_utc,
-                User.last_login_at < day_end_utc,
-            )
-        )
-        daily_compare_start_user_ids = _event_user_ids(
-            db, (COMPARE_START_EVENT,), day_start_utc, day_end_utc
-        )
-        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",
+                User.created_at >= day_start_utc - timedelta(days=1),
+                User.created_at < day_end_utc - timedelta(days=1),
            )
        )
+        retention_cohort_total += len(cohort_ids)
+        retention_retained_total += len(cohort_ids & daily_active_user_ids)
        trend_points.append(
            {
                "date": cur_date,
-                "active_users": len(
-                    daily_login_user_ids
-                    | daily_compare_start_user_ids
-                    | daily_coupon_event_user_ids
-                    | daily_coupon_claim_user_ids
-                ),
+                "active_users": len(daily_active_user_ids),
                "new_users": _count(
                    User,
                    User.created_at >= day_start_utc,
@@ -330,6 +348,11 @@ def dashboard_overview(
                "comparisons": _count(ComparisonRecord, *daily_comparison_conds),
            }
        )
+    period_retention_rate = (
+        round(retention_retained_total / retention_cohort_total, 4)
+        if retention_cohort_total
+        else None
+    )

    period_coin_conds = (
        CoinTransaction.created_at >= start_local,
@@ -413,6 +436,98 @@ def dashboard_overview(
        else None
    )

+    # ===== 领券核心数据(2026-07-05 产品新增)=====
+    # 数据源:coupon_session(一次领券一行,started_date 北京自然日)+ coupon_claim_record
+    # (一券/点位一天一条终态,claim_date 北京自然日)。点位与 session 不按 trace_id 关联——
+    # record_claims 更新路径不覆盖 trace_id(同设备同券同日重跑归第一次的 trace),按
+    # (device_id, 自然日) 桶关联才可靠;同桶多次发起共享同一份点位终态。
+    period_coupon_sessions = db.execute(
+        select(
+            CouponSession.device_id,
+            CouponSession.started_date,
+            CouponSession.status,
+            CouponSession.elapsed_ms,
+        ).where(
+            CouponSession.started_date >= period_from,
+            CouponSession.started_date <= period_to,
+            # 只统计正式环境,同「领券数据」页默认口径(防 debug 包调试数据串台;
+            # 命中 ix_coupon_session_date_env)。点位表无 app_env 列,但点位指标只经
+            # 下方 prod session 触达的 (device, 日) 桶进入统计,随之收敛到 prod。
+            CouponSession.app_env == "prod",
+        )
+    ).all()
+    coupon_started = len(period_coupon_sessions)
+    coupon_completed_elapsed = sorted(
+        s.elapsed_ms
+        for s in period_coupon_sessions
+        if s.status == "completed" and s.elapsed_ms is not None
+    )
+    # 点位桶:(device, 日) → (点位总数, 成功点位数)。成功口径与「我的」页累计领券一致
+    # (sum_claimed_count,2026-06-15 产品定):success + already_claimed(已领过=持有券)都算成功。
+    point_buckets: dict[tuple[str, date], tuple[int, int]] = {
+        (dev, d): (int(total), int(succ or 0))
+        for dev, d, total, succ in db.execute(
+            select(
+                CouponClaimRecord.device_id,
+                CouponClaimRecord.claim_date,
+                func.count(),
+                func.sum(
+                    case(
+                        (CouponClaimRecord.status.in_(("success", "already_claimed")), 1),
+                        else_=0,
+                    )
+                ),
+            )
+            .where(
+                CouponClaimRecord.claim_date >= period_from,
+                # 上界放宽一天:跨零点场次(23:5x 发起)的点位 claim_date 落在发起日+1,
+                # 桶只经下方 session 触达的键参与计数,放宽不会引入无关数据。
+                CouponClaimRecord.claim_date <= period_to + timedelta(days=1),
+            )
+            .group_by(CouponClaimRecord.device_id, CouponClaimRecord.claim_date)
+        ).all()
+    }
+    # 全部领成功的次数:completed 且其 (device, 日) 桶内点位全部成功(桶为空不算)。
+    coupon_all_success = 0
+    completed_bucket_totals: list[int] = []
+    session_bucket_keys: set[tuple[str, date]] = set()
+    for s in period_coupon_sessions:
+        key = (s.device_id, s.started_date)
+        if key not in point_buckets:
+            # 跨零点回退:发起日桶不存在(点位终态全部落在次日)时取 (device, 发起日+1)。
+            # 仅在发起日桶完全缺失时回退,避免抢占该设备次日 session 自己的桶。
+            next_key = (s.device_id, s.started_date + timedelta(days=1))
+            if next_key in point_buckets:
+                key = next_key
+        bucket = point_buckets.get(key)
+        if bucket is not None:
+            session_bucket_keys.add(key)
+        if s.status != "completed" or bucket is None:
+            continue
+        total, succ = bucket
+        completed_bucket_totals.append(total)
+        if total > 0 and succ == total:
+            coupon_all_success += 1
+    # 每次发起的应领点位数:取「完成过的领券」实际点位数的众数(done 帧会给所有点位终态,
+    # 完成场的点位数=当前配置的全量点位数;数据自校准,配置改点位数无需改代码)。本期无完成场
+    # 时给不出,点位成功率置空。
+    coupon_points_per_session = (
+        Counter(completed_bucket_totals).most_common(1)[0][0]
+        if completed_bucket_totals
+        else None
+    )
+    # 成功点位数:本期 session 触达过的 (device, 日) 桶内成功点位之和(桶级去重,同桶重试不重复计)。
+    coupon_point_success = sum(point_buckets[k][1] for k in session_bucket_keys)
+    # 点位成功率 = 成功点位数 / (发起数 × 应领点位数):中途退出未跑到的点位不产生记录,
+    # 但发起数×点位数把它们计入分母 → 视为失败,符合产品口径;重试会拉低该率(分母按次数计)。
+    coupon_point_success_rate = (
+        round(
+            min(1.0, coupon_point_success / (coupon_started * coupon_points_per_session)), 4
+        )
+        if coupon_started and coupon_points_per_session
+        else None
+    )
+
    return {
        "users": {
            "total": _count(User),
@@ -476,11 +591,13 @@ def dashboard_overview(
            "users": {
                "new": len(period_new_user_ids),
                "active": len(period_active_user_ids),
-                "retained_new_users": len(period_retained_new_user_ids),
+                "retained_new_users": retention_retained_total,
+                "retention_cohort": retention_cohort_total,
                "retention_rate": period_retention_rate,
                "retention_note": (
-                    "口径:登录(last_login_at)+开始比价(real_compare_start)+"
-                    "开始领券(real_coupon_start/claim_started),按用户去重"
+                    "次日留存:窗口内每天取前一日新增用户,统计其当日活跃"
+                    "(登录/开始比价/开始领券,按用户去重)比例,逐日累加;"
+                    "默认窗口=昨日,即前日新增用户的昨日留存"
                ),
            },
            "comparison": {
@@ -491,6 +608,17 @@ def dashboard_overview(
                "average_duration_ms": period_avg_duration_ms,
                "average_saved_cents": period_avg_saved_cents,
            },
+            "coupon": {
+                "started": coupon_started,
+                "all_success": coupon_all_success,
+                "success_rate": (
+                    round(coupon_all_success / coupon_started, 4) if coupon_started else None
+                ),
+                "point_success": coupon_point_success,
+                "points_per_session": coupon_points_per_session,
+                "point_success_rate": coupon_point_success_rate,
+                "median_elapsed_ms": _percentile(coupon_completed_elapsed, 50),
+            },
            "coins": {
                "granted_total": _sum(CoinTransaction.amount, *period_coin_conds),
                "reward_video_coin_total": period_reward_video_coin_total,
@@ -91,6 +91,7 @@ def get_ad_revenue_report(
        daily=[AdRevenueDaily(**d) for d in result["daily"]],
        hourly=[AdRevenueHourly(**h) for h in result["hourly"]],
        type_stats={k: AdRevenueTypeStat(**v) for k, v in result["type_stats"].items()},
+        scene_stats={k: AdRevenueTypeStat(**v) for k, v in result["scene_stats"].items()},
        dau=result["dau"],
        total=result["total"],
        truncated=result["truncated"],
@@ -57,9 +57,15 @@ def list_seeds(db: AdminDb) -> list[OpsMarqueeSeedOut]:
 def preview_feed(
    db: AdminDb,
    limit: Annotated[int, Query(ge=1, le=30)] = 8,
+    mode: Annotated[str | None, Query(description="mixed/real/seed;不传=当前持久化模式")] = None,
 ) -> OpsSavingsFeedPreviewOut:
-    """返回客户端实际会看到的 feed(真实记录会插队、种子随机抽取/金额随机/名字合成),供运营对效果。"""
-    return OpsSavingsFeedPreviewOut(items=ops_marquee.get_feed(db, limit=limit))
+    """返回客户端实际会看到的 feed(真实记录会插队、种子随机抽取/金额随机/名字合成),供运营对效果。
+
+    mode 显式指定则预览该模式(**不改持久化配置**,供前端切换开关时实时预览);不传则用当前持久化模式。
+    """
+    if mode is not None and mode not in ops_marquee.FEED_MODES:
+        raise HTTPException(status_code=400, detail="mode 需为 mixed / real / seed")
+    return OpsSavingsFeedPreviewOut(items=ops_marquee.get_feed(db, limit=limit, mode=mode))


 # 注:/mode 两个端点须在 /{seed_id} 之前注册,否则 PATCH /mode 会被 /{seed_id} 抢先按 id 解析。
@@ -42,7 +42,12 @@ def list_users(
    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",
+    # 最近活跃(登录/发起比价/发起领券取最大,见 queries._last_active_expr)筛选与排序
+    last_active_from: Annotated[datetime | None, Query()] = None,
+    last_active_to: Annotated[datetime | None, Query()] = None,
+    sort_by: Annotated[
+        str, Query(pattern="^(id|created_at|last_login_at|last_active_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,
@@ -51,6 +56,7 @@ def list_users(
        db, phone=phone, register_channel=register_channel, status=status,
        nickname=nickname, created_from=created_from, created_to=created_to,
        last_login_from=last_login_from, last_login_to=last_login_to,
+        last_active_from=last_active_from, last_active_to=last_active_to,
        sort_by=sort_by, sort_order=sort_order, limit=limit, cursor=cursor,
    )
    return CursorPage(
@@ -136,9 +136,16 @@ class AdRevenueReportOut(BaseModel):
        default_factory=dict,
        description="按广告类型(ad_type)小计 {ad_type: {impressions, revenue_yuan}};前端取 draw / reward_video 做分类大盘",
    )
+    scene_stats: dict[str, AdRevenueTypeStat] = Field(
+        default_factory=dict,
+        description="按信息流场景(feed_scene)小计 {comparison/coupon/welfare: {impressions, revenue_yuan}};"
+        "全量统计(不受分页截断),供数据大盘「领券广告 / 比价广告」卡;feed_scene 为空的事件不计入",
+    )
    dau: int | None = Field(
        None,
-        description="今日活跃用户数(复用大盘口径,last_login_at);**仅查询=今日单天时有值**,历史/多天为 null",
+        description="所选日期区间的去重活跃用户数(口径同数据大盘 period.users.active:登录 + 开始比价 + "
+        "开始领券)。按 date_from~date_to 区间统计,含今日、近 7 天、近 30 天等任意区间;全局口径,"
+        "不随 user_id / ad_type / feed_scene / app_env 筛选变化",
    )
    total: int = Field(..., description="广告事件总数(全量,不受分页影响;= 当前筛选下的分页总条数)")
    truncated: bool = Field(..., description="当前页之后是否还有更多事件(len(events) > offset + limit)")
@@ -43,7 +43,10 @@ class DashboardComparison(BaseModel):
 class DashboardPeriodUsers(BaseModel):
    new: int
    active: int
+    # 次日留存(2026-07-05 起):retained_new_users = 窗口内逐日「前一日新增且当日活跃」用户数之和,
+    # retention_cohort = 对应的前一日新增基数之和,retention_rate = 两者之比。
    retained_new_users: int
+    retention_cohort: int = 0
    retention_rate: float | None = None
    retention_note: str

@@ -57,6 +60,24 @@ class DashboardPeriodComparison(BaseModel):
    average_saved_cents: int | None = None


+class DashboardPeriodCoupon(BaseModel):
+    """领券核心数据(2026-07-05 产品新增)。点位=一张券(coupon_claim_record 一天一条终态);
+    成功口径 success+already_claimed(与「我的」页累计领券一致)。"""
+
+    started: int = 0
+    # 全部领成功的次数:completed 且当日该设备全部点位成功
+    all_success: int = 0
+    success_rate: float | None = None
+    # 本期 session 触达的点位中成功的条数(同设备同日去重)
+    point_success: int = 0
+    # 每次发起的应领点位数(本期完成场实际点位数的众数;无完成场为空)
+    points_per_session: int | None = None
+    # 点位成功率 = point_success / (started × points_per_session);未跑到的点位计入分母视为失败
+    point_success_rate: float | None = None
+    # 耗时中位数(仅 completed 的 elapsed_ms,同「领券数据」页口径)
+    median_elapsed_ms: int | None = None
+
+
 class DashboardPeriodCoins(BaseModel):
    granted_total: int
    reward_video_coin_total: int = 0
@@ -85,6 +106,7 @@ class DashboardPeriod(BaseModel):
    date_to: date
    users: DashboardPeriodUsers
    comparison: DashboardPeriodComparison
+    coupon: DashboardPeriodCoupon = DashboardPeriodCoupon()
    coins: DashboardPeriodCoins
    cash: DashboardPeriodCash
    trend: list[DashboardTrendPoint] = []
@@ -20,6 +20,9 @@ class AdminUserListItem(BaseModel):
    wechat_nickname: str | None = None
    created_at: datetime
    last_login_at: datetime
+    # 最近活跃 = max(最近登录, 最近发起比价, 最近发起领券);列表页由 queries._attach_last_active
+    # 瞬态挂上。其他复用本 schema 的入口(用户 360 等)没挂该属性 → None(前端显示 '-')。
+    last_active_at: datetime | None = None


 class AdminUserOverview(BaseModel):
@@ -130,6 +130,7 @@ class WithdrawBulkResult(BaseModel):

 class WithdrawLedgerCheckOut(BaseModel):
    ok: bool
+    # 普通现金账(coin_cash:金币兑换的现金)
    cash_balance_total_cents: int
    cash_transaction_total_cents: int
    balance_diff_cents: int
@@ -137,6 +138,14 @@ class WithdrawLedgerCheckOut(BaseModel):
    missing_refund_txn_count: int
    duplicate_refund_txn_count: int
    refund_txn_on_non_terminal_count: int
+    # 邀请奖励金账(invite_cash:与普通现金物理隔离,各自对账)。默认 0 向后兼容。
+    invite_cash_balance_total_cents: int = 0
+    invite_cash_transaction_total_cents: int = 0
+    invite_balance_diff_cents: int = 0
+    invite_missing_withdraw_txn_count: int = 0
+    invite_missing_refund_txn_count: int = 0
+    invite_duplicate_refund_txn_count: int = 0
+    invite_refund_txn_on_non_terminal_count: int = 0


 class WxpayHealthCheckOut(BaseModel):
@@ -25,9 +25,19 @@ from app.schemas.meituan import (
    ReferralLinkResponse,
    TopSalesRequest,
 )
+from app.utils.meituan_city import get_meituan_city

 logger = logging.getLogger("shagua.meituan")

+
+def _resolve_city_id(latitude: float, longitude: float) -> str:
+    """经纬度 → 美团城市 ID;解析失败返 ""（调用方应降级返空）。"""
+    try:
+        return get_meituan_city(latitude, longitude).get("city_id", "")
+    except Exception:
+        logger.exception("get_meituan_city 失败")
+        return ""
+
 router = APIRouter(prefix="/api/v1/meituan", tags=["meituan-cps"])


@@ -175,13 +185,19 @@ def feed(req: FeedRequest, db: Session = Depends(get_db)) -> FeedResponse:
        status = "degraded" if (not cards and wm_fail and dd_fail) else ("ok" if cards else "empty")
        return FeedResponse(items=cards, has_next=wm_hn or dd_hn, page=req.page, status=status)

-    # 智能推荐(rec):走【离线库】筛佣金率 ≥ 3%,分页返回(SQL 侧去重+排序+分页,秒级、不打美团)。
+    # 智能推荐(rec):走【离线库】筛佣金率 ≥ 3%,按城市过滤,分页返回(SQL 侧去重+排序+分页,秒级、不打美团)。
    # 实测库里佣金≥3% 去重后仅 ~578 条(几乎全是外卖;到店团购佣金普遍 <3%):实时按"同城热销榜单"
    # 拉既撞限流、又填不满(该榜单中位佣金 ~0.8%,筛完每页剩 0-1 条),故从库出。佣金阈值逻辑不变。
    if tab == "rec":
+        city_id = _resolve_city_id(lat, lon)
+        if not city_id:
+            return FeedResponse(items=[], has_next=False, page=req.page, status="degraded")
        PAGE = 20
        try:
-            base = select(MeituanCoupon).where(MeituanCoupon.commission_percent >= 3.0)
+            base = select(MeituanCoupon).where(
+                MeituanCoupon.commission_percent >= 3.0,
+                MeituanCoupon.city_id == city_id,
+            )
            deduped = base.distinct(MeituanCoupon.dedup_key).order_by(
                MeituanCoupon.dedup_key,
                MeituanCoupon.commission_percent.desc(),
@@ -211,6 +227,9 @@ def feed(req: FeedRequest, db: Session = Depends(get_db)) -> FeedResponse:
                card.distance_text = None
                card.distance_meters = None
                cards.append(card)
+        if not cards and req.page == 1:
+            # 命中城市却 0 券:该城确无 ≥3% 券,或 ETL 灌的 city_id 与 city_dict 口径不一致。
+            logger.info("[feed] rec city_id=%s 命中 0 券(该城确无券?或 ETL/city_dict 的 city_id 口径不一致)", city_id)
        return FeedResponse(items=cards, has_next=has_next, page=req.page,
                            status="ok" if cards else "empty")

@@ -254,14 +273,24 @@ def referral_link(req: ReferralLinkRequest) -> ReferralLinkResponse:


@router.post("/top-sales", response_model=CouponListResponse,
-             summary="销量最高(从离线库 meituan_coupon 按销量降序 + 跨源去重,不实时打美团)")
+             summary="销量最高(从离线库 meituan_coupon 按销量降序 + 跨源去重,按城市过滤,不实时打美团)")
 def top_sales(req: TopSalesRequest, db: Session = Depends(get_db)) -> CouponListResponse:
+    # 按设备经纬度定位城市,只查同城券;老客户端不带坐标 → 降级返空(不 422、不误返全城)。
+    if req.latitude is None or req.longitude is None:
+        return CouponListResponse(items=[], has_next=False, search_id=None, status="degraded")
+    city_id = _resolve_city_id(req.latitude, req.longitude)
+    if not city_id:
+        return CouponListResponse(items=[], has_next=False, search_id=None, status="degraded")
+
    # 去重 + 排序 + 分页全在 SQL 做,每页只取并解析当前页 ~20 条。
    # (之前实现每翻一页都全表拉取 + 全量 from_raw 解析,翻页慢 → 客户端滑动卡顿/翻不动。)
    # 库为空(prod 刚部署 / ETL 未跑完)时返空 + status=empty,不崩;库查询异常降级 degraded。
    try:
        # 1) DISTINCT ON (dedup_key):每个去重键(品牌|名|价)只留销量最高那条(同销量再按佣金)
-        base = select(MeituanCoupon).where(MeituanCoupon.sale_volume_num.isnot(None))
+        base = select(MeituanCoupon).where(
+            MeituanCoupon.sale_volume_num.isnot(None),
+            MeituanCoupon.city_id == city_id,
+        )
        if req.platform is not None:
            base = base.where(MeituanCoupon.platform == req.platform)
        deduped = base.distinct(MeituanCoupon.dedup_key).order_by(
@@ -292,6 +321,14 @@ def top_sales(req: TopSalesRequest, db: Session = Depends(get_db)) -> CouponList
        except Exception:  # noqa: BLE001
            continue
        if card.product_view_sign:
+            # 不显示距离:库里的距离是相对城市默认点的(对用户无意义、且误导)。
+            # 置空后前端"距离 店名"那行只剩店名、自动顶到最左(店名移到原距离的位置)。
+            # 逻辑与推荐流保持一致
+            card.distance_text = None
+            card.distance_meters = None
            cards.append(card)
+    if not cards and req.page == 1:
+        # 命中城市却 0 券:可能该城确无券,也可能 ETL 灌的 city_id 与 city_dict 口径不一致(静默降级的隐患)。
+        logger.info("[top-sales] city_id=%s 命中 0 券(该城确无券?或 ETL/city_dict 的 city_id 口径不一致)", city_id)
    return CouponListResponse(items=cards, has_next=has_next, search_id=None,
                              status="ok" if cards else "empty")
@@ -71,6 +71,12 @@ async def lifespan(_: FastAPI) -> AsyncIterator[None]:
        settings.DATABASE_URL.split("://", 1)[0],
    )
    get_pricebot_client()  # 预热透传 client:把建 SSL 上下文的一次性成本付在启动,首个领券请求即热
+    try:
+        # 预热离线地理库:首次加载 ~2.5M 行 CSV + 建 KDTree,摊到启动、不砸首个按城市过滤的请求
+        from app.utils import geo
+        geo.ensure_loaded()
+    except Exception:  # noqa: BLE001
+        logger.exception("reverse_geocoder 预热失败(城市反查将在首个请求时懒加载)")
    reconcile_task = start_withdraw_reconcile_worker()
    heartbeat_task = start_heartbeat_monitor()
    daily_exchange_task = start_daily_exchange_worker()
@@ -30,6 +30,7 @@ from app.models.comparison import ComparisonRecord
 from app.models.ops_marquee_seed import OpsMarqueeSeed
 from app.models.user import User
 from app.repositories import app_config
+from app.repositories.user import is_default_nickname

 # 首页轮播数据源模式(存 app_config.marquee_feed_mode):
 #   mixed=真实优先+种子补位+合成兜底(默认,原行为);real=只真实(不足则少/空);seed=只种子+合成兜底。
@@ -140,9 +141,12 @@ def _synth_masked_name(rng: random.Random) -> str:

 def _mask_real(nickname: str | None, user_id: int) -> str:
    """真实用户脱敏(对齐 PRD「用户标识打码规则」):设过昵称→昵称脱敏(中英文皆可);
-    没昵称→「用户」+5星+id 后 2 位(用户*****08),按 user_id 稳定、刷新不变脸。"""
+    没昵称→「用户」+5星+id 后 2 位(用户*****08),按 user_id 稳定、刷新不变脸。
+
+    创建时自动分配的默认昵称(「用户」+9 位随机,见 user.is_default_nickname)不算用户主动设的昵称,
+    按「无昵称」处理走 id 规则(产品决策 2026-07:默认昵称归入「没昵称」档)。"""
    nick = (nickname or "").strip()
-    if nick:
+    if nick and not is_default_nickname(nick):
        return _mask_nickname(nick)
    return _mask_anon(user_id)

@@ -213,9 +217,11 @@ def _recent_real_rows(db: Session) -> list[tuple[int, int, str | None]]:
    return out


-def get_feed(db: Session, limit: int = 8) -> list[dict]:
+def get_feed(db: Session, limit: int = 8, mode: str | None = None) -> list[dict]:
    """返回最多 limit 条 {masked_user, saved_amount_cents, time(HH:MM:SS 北京)}。

+    mode:显式传入(admin 预览指定模式)则用它、**不改持久化配置**;不传(客户端 /savings-feed)读
+    持久化的 marquee_feed_mode;非法值一律回退到持久化模式。
    真实条:success 且 0 < saved ≤ 上限,按 user 去重(同一用户只取最新一条,避免单人刷屏)。
    不足用启用的种子补齐——**公平随机抽取** need 个(而非固定取前 N),让所有种子都有机会露出;
    种子用户名留空则随机合成(避开撞名),金额取**长尾随机**(小额居多、偶尔大额,更像真实分布)。
@@ -223,7 +229,8 @@ def get_feed(db: Session, limit: int = 8) -> list[dict]:
    展示时间统一「刷新」成相对现在的最近时刻(从 now 往前**随机抖动**递减),保证轮播永远像刚发生、
    节奏自然不机械(真实用户/金额不变,只换展示时间——避免旧测试数据 / 低谷期记录显示成过时时间)。
    """
-    mode = get_feed_mode(db)  # mixed / real / seed(运营可在「首页轮播种子」页切换)
+    # 预览可显式指定模式(所见=选中模式,不依赖 PATCH 落库时序);None/非法 → 读持久化配置。
+    mode = mode if mode in FEED_MODES else get_feed_mode(db)  # mixed / real / seed

    items: list[dict] = []
    used_names: set[str] = set()
@@ -42,6 +42,22 @@ def _gen_nickname() -> str:
    )


+def is_default_nickname(nickname: str | None) -> bool:
+    """是否为创建时自动分配的默认昵称(= "用户" + 9 位字母数字,见 [_gen_nickname])。
+
+    这类不是用户主动设置的昵称,展示脱敏时按「无昵称」处理(走 id 规则,见 ops_marquee._mask_real)。
+    精确匹配生成格式(前缀 + 定长字母数字集),不误伤真人以「用户」开头的昵称(如「用户体验师」含汉字、
+    长度也不符)。用户改过昵称即不再匹配。"""
+    if not nickname:
+        return False
+    s = nickname.strip()
+    return (
+        len(s) == len(_NICKNAME_PREFIX) + _NICKNAME_LEN
+        and s.startswith(_NICKNAME_PREFIX)
+        and all(c in _NICKNAME_ALPHABET for c in s[len(_NICKNAME_PREFIX):])
+    )
+
+
 def get_user_by_username(db: Session, username: str) -> User | None:
    return db.execute(
        select(User).where(User.username == username)
@@ -174,9 +174,13 @@ class FeedResponse(BaseModel):

 class TopSalesRequest(BaseModel):
    """销量最高 tab:从离线库 meituan_coupon 按销量降序取(不实时打美团)。"""
+    # 可选:老客户端(本次改动前发版)不带经纬度。缺省时后端降级返空(status=degraded),
+    # 不做 422 硬拒,也不误返"全城"结果。新客户端会传坐标 → 按城市过滤。
+    longitude: float | None = Field(None, description="经度(用于定位城市;缺省=老客户端,降级返空)")
+    latitude: float | None = Field(None, description="纬度(用于定位城市;缺省=老客户端,降级返空)")
    page: int = Field(1, ge=1)
    page_size: int = Field(20, ge=1, le=50)
-    platform: int | None = Field(None, description="可选: 1只外卖 / 2只到店; 不填=全部(全城销量)")
+    platform: int | None = Field(None, description="可选: 1只外卖 / 2只到店; 不填=全部(同城销量)")


 # ───────────────── 换链 请求 / 响应 ─────────────────
@@ -0,0 +1,360 @@
+城市ID	城市名称	省份名称
+3NUYJKKJXPHVNZUHFK3HWUDHNM	宣城市	安徽省
+LXXSHOY7LNK74ZK2SKVUXFY72Q	阜阳市	安徽省
+ZEBF2LBJOEHGM4XGFPNW4IHBIA	合肥市	安徽省
+WADWEY3GR6IARJLSNGQWG2KI4E	滁州市	安徽省
+Z62QL3X66AOT6MSY7LB6LVO4CI	芜湖市	安徽省
+M6QCWRCECRT6ZEJ6RERR6IWHFI	淮南市	安徽省
+UP2NBJACSAO7FUH4XQQDMBOUE4	马鞍山市	安徽省
+WLL7BSHUBPTLTMITFITJX2GKWY	蚌埠市	安徽省
+ECTBNJ4KNNHPGXEVI4TBJNU7BY	亳州市	安徽省
+KNEGDNOSRGNQPAMOMH54ATLIUU	六安市	安徽省
+YH53FRR55H6VA4KXW36OJ7RNSE	宿州市	安徽省
+LH6LX5DUVFPOFCAQ6NEGPWCLBI	淮北市	安徽省
+RIFXWJ46SEJXE7EP6HZXEUIALU	铜陵市	安徽省
+FK6F7KMO4WNARZKUXMMSBWGATM	安庆市	安徽省
+M3CHGNNUSFSPS5HRV3W7MCBWFI	黄山市	安徽省
+XFI6PM7SRO6NHBGYQUZEEA2WT4	池州市	安徽省
+D2ZILSASTTGEFQWZIDTHA7PWU4	澳门	澳门特别行政区
+WKV2HMXUEK634WP64CUCUQGM64	北京市	北京市
+HPMKHLM3QR6EZGMY7GEI4H3QYQ	泉州市	福建省
+6V523YRU54Y3PEAM2XPADNJM2U	福州市	福建省
+HH3ZZCERPVQIYUZPW4A2U4JKZI	莆田市	福建省
+BQ5RWEJS4O7W27SQMLPMRIRJDU	宁德市	福建省
+TDN7XDQMZEP6ZCK6UO3VVMCSMM	三明市	福建省
+ZKNTORN6YTZL2BXRYUSRGV3CHU	厦门市	福建省
+Y2DI2QLZN5NNACMD3KI2DBR4IA	龙岩市	福建省
+C4RS32I6QAHWLP55UQWI3N5LLY	南平市	福建省
+5T23WDEOAP7RYNU4JNL2ZG7PDQ	漳州市	福建省
+UHZBROATFB2KWNMNLS23DPRJBY	定西市	甘肃省
+WLPAHIUOIVKS644QSN4V5ZY5XQ	金昌市	甘肃省
+J7TO3UHZ57ABNUKIQUBCIJZQFA	白银市	甘肃省
+GX277SS75375VEFYVCEHBL6ISA	临夏回族自治州	甘肃省
+ORA3R7F2LSJHUOCIDTZCP54G7Q	张掖市	甘肃省
+L6VQYYOJNTHSLW5JCR5SXBITDM	武威市	甘肃省
+65OXQPQVFXNOYHXTMCE2RNFRL4	兰州市	甘肃省
+IUIZYQ7E2SPMEAIGOUUNZWBQOA	天水市	甘肃省
+BYBRGRDRV4NKAWCU6GWBIVLX3Q	酒泉市	甘肃省
+KDST2VRETG6WK5SMJO2G2FN2RU	嘉峪关市	甘肃省
+R3Q2XWVFVF4T2ADZZZMPZJRWBA	庆阳市	甘肃省
+7FWNT2TP66SU4QEP6IBBMZWFNE	陇南市	甘肃省
+T33S2GYGPVHAL5SR2FLSPTJSBE	平凉市	甘肃省
+RR6KAWBLOKD4H2UINKYPFCPXO4	甘南藏族自治州	甘肃省
+QKX4DS3CTJJG7SFW5SBHPLD42I	茂名市	广东省
+JJZ75A32XCQNZU4IN2ZCEUGN3M	梅州市	广东省
+SJSOXOSJASLUT6LBH4E32SUKKQ	清远市	广东省
+SQQWAN5BQOVSX55S7EPF7QHMAU	珠海市	广东省
+NGRJMW6JMRS6U2KUJEONSORAEY	韶关市	广东省
+FAUMIGOSOET4E5WR5BL6P3OZHA	佛山市	广东省
+JSBIH55ICFZQ2D3LEV47YMZ2NI	河源市	广东省
+KOYAYPD2DBLDCF2ZI5GCW4LF6Y	中山市	广东省
+647JGFPUYM4VWVLZCPSHT63XKQ	汕头市	广东省
+AMOIPZW3Q2NMTDSEREFVM4SV74	深圳市	广东省
+XIHEJY4H2CDZJCLIXDIN36BKXQ	广州市	广东省
+UZ6OT4CYUR42KCTTED2KJW6EGA	东莞市	广东省
+RM3HLOIUEYKTQ5O2JSVEKDMFRY	阳江市	广东省
+C6XNJAZA6N3NNUDBUU3JIZPTDI	潮州市	广东省
+AUPF3G2ULSV4TDT4L3NMHRTY6Y	揭阳市	广东省
+7HIITKBPRXTVBA2FBBN443XITQ	云浮市	广东省
+TO6ILZ7MPJMJN3S7W2SXMIFQQY	江门市	广东省
+DTTBMGCIOMPCZY5NETUEKWJ6PY	汕尾市	广东省
+HJY7JYWBA6FQY42RYSKX3RZTRI	湛江市	广东省
+SLICHB4FBDVDLI53MR74WVUUNI	肇庆市	广东省
+ZPX4JXJVBBYSSD2KTWHAPXO6NE	惠州市	广东省
+JH4Q44RQA4EZ3Q6MHQVEVE7KZQ	百色市	广西壮族自治区
+H2JXFEJFIL4PPFMYOS4MHZ5IBM	崇左市	广西壮族自治区
+SXIRRISUOEGBU335AWT2ZFL6A4	贵港市	广西壮族自治区
+HEQHKC4KP7YGGYVBZM5JEUI5AQ	北海市	广西壮族自治区
+SKGG7KMFKVDIDKRVQEPTS7SIE4	贺州市	广西壮族自治区
+N4WR7CWCULNA5Z35OTDJSZYDCU	钦州市	广西壮族自治区
+T4RXX2WY6WPQYZEUXVJNZBXQZU	梧州市	广西壮族自治区
+3R23AS3EIY7EYE2D5MWWORZODI	河池市	广西壮族自治区
+57SMWWCV7X44E256P4I23OQ3AA	防城港市	广西壮族自治区
+YHGHVIQ37UCTNQ4JKPQEAUWIQA	桂林市	广西壮族自治区
+MQJZTM455OKZLAN5WQYUTA5TDE	柳州市	广西壮族自治区
+C6FZPLB4NJQ6VUPSKDJH3EWQDM	玉林市	广西壮族自治区
+BFSU5W6E5XBIDFPQLVPGRDSATY	南宁市	广西壮族自治区
+CKXOQUZDNOVNME3PEBOY2CULQQ	来宾市	广西壮族自治区
+LV32FV6IQTKFR7JIBEQMHRUVCA	贵阳市	贵州省
+F26RCNKMFTZONJCSJ5C6FHVY74	毕节市	贵州省
+G2LMYRWVRCK7BTD2WM4NWX4SYM	黔南布依族苗族自治州	贵州省
+MFSOO3NBMB2PVLIVSI5EJK7MWY	黔西南布依族苗族自治州	贵州省
+KWUL44L7SEMJGIMXCWSSEB3OOA	遵义市	贵州省
+T2P3OFGQZUGR7D6TGRCMDF22GI	铜仁市	贵州省
+AGUFUANSZNGC4TMOPZO65IRSPI	六盘水市	贵州省
+2XOCOSNUAK3J5QDGTKIBWKK7KU	安顺市	贵州省
+6XRTSAEYJTA2UBKXO4XEPQE5ZY	黔东南苗族侗族自治州	贵州省
+YRMKRP2GOE2VMRS73N4YRIZUHY	三亚市	海南省
+CJRGVLBNLJAVBJ4ZKKIZ3FZ2LY	白沙黎族自治县	海南省
+5XOUAJ5Z4J4K7SVIQGXL2OM2JQ	保亭黎族苗族自治县	海南省
+2UFQ6A2QRJPXPH3VOYEAQHMVSQ	海口市	海南省
+TGCVXVS4M7NDQM4ROUDCVI6I3A	承德市	河北省
+JEUP6QWCOXPSM3SQTINQCJKIGM	衡水市	河北省
+Z442MNCW6BO2BBHIRUPRBACXPI	唐山市	河北省
+RFE6R34GD4FY3LUKC2ICSF6AFY	张家口市	河北省
+CWJN55M73VZDCYJEQ7AHDBWGGY	沧州市	河北省
+DFL4ES776ECRGBYNOPLWKB247I	雄安新区	河北省
+ZLSXYY34IHBHIC2NOVPQQBFTBE	保定市	河北省
+3DO6Z2QRJQFMPLLDS55PG7DSBU	石家庄市	河北省
+PR57XT25LI3246VGASEPSHP63E	邢台市	河北省
+SKYLNH737BS56TD452FOKYL36U	邯郸市	河北省
+5PWPERL7GQKJD6QPLR2TWUUM7E	秦皇岛市	河北省
+5T2TGV6SJFVL3MO7HIMN2KTQTA	廊坊市	河北省
+ECSTLZ7GP7IX3MB5EVNKS47MLE	焦作市	河南省
+VTWW34QB2F5Q4LW7ISNUMWX7GY	开封市	河南省
+D2NUN47NY4Q55X3UED4JMSI6CM	周口市	河南省
+TR3XJFQR4EFYRRIX7TUQF3B26Y	郑州市	河南省
+CKJGF5S6XMHW5ZJEBU7MJC47QA	新乡市	河南省
+IFASZ625MCFJQKPLJ7EA2SMJUU	商丘市	河南省
+SKXPYKTTRG4YAUHE2HZXWRWXGM	鹤壁市	河南省
+G5LXE74CUHO2K6BBRN7Q5DSRJY	漯河市	河南省
+SLNOAFJV2LTBSH7SJCRXJA36K4	驻马店市	河南省
+65WO7LH7CFDUGKYMXQLRAYKKWM	安阳市	河南省
+RIX2X7FAVTZCAQ5RT2C2CWK22Q	南阳市	河南省
+SZOW5OY3U54SSY4WRC65VJUNTI	平顶山市	河南省
+7VPIDDUS4P2LSZ6Q5S57MAQDEM	信阳市	河南省
+4VYCRORUOZ4DC2U6S3CT6H6KWE	洛阳市	河南省
+M5WNO2BQ3UGLLHBCG4NCEFPP5U	濮阳市	河南省
+LY3O6PBPIWETMA3ZOL6ETY5UB4	三门峡市	河南省
+FXXJLIRE72LS2W4OWWQVJMRJHA	许昌市	河南省
+5XH353QTY3VWF2KYOCZCL3TOXY	牡丹江市	黑龙江省
+2KGRZKF6IECV2W7K5J64Y2LY4M	齐齐哈尔市	黑龙江省
+FASGWS5ADVSTFGJG6TGBZPZP6Q	鹤岗市	黑龙江省
+2O6CDIXSWIKBXILZEEPKCS7MVI	双鸭山市	黑龙江省
+OZ2PTOBYTBG57XJZMIC23QFJKM	佳木斯市	黑龙江省
+FO24MQMULT3J5JW64APNXSQEPU	伊春市	黑龙江省
+ETZ2HYWVU6U7SKU6G4JAO64RUQ	黑河市	黑龙江省
+PR7EJNBY2VZBEUT36JAWE3TM7I	七台河市	黑龙江省
+HADAAVLERKIW4SQGCTQYGX4AL4	哈尔滨市	黑龙江省
+CGTU45YC5C3JYLHMA47USDPA7Y	大庆市	黑龙江省
+T4W7SQIPOM4EYMEFFRAB5BSTII	鸡西市	黑龙江省
+TYGZHNQL6YT7CX6EEG5DJQQHMA	绥化市	黑龙江省
+OOSJTSN2CVUUCKD6XAB7EYYIPY	大兴安岭地区	黑龙江省
+I3YF3EKZHIZTN6TZOTYTGZ2UXQ	随州市	湖北省
+ESGVBOSTHW7JWEVCGYJUTEHEBQ	宜昌市	湖北省
+MTJRWJ53XBW5SBTWHKNNZDLM7U	十堰市	湖北省
+PXZLF2ISKQL5ACM67ZCBNOGDT4	黄石市	湖北省
+44RMTOEHPUFXBHZXX4IQ4IRZVQ	荆州市	湖北省
+OTKZGG743NFC474ADMMRX4ZOOA	鄂州市	湖北省
+EXOUAZAQ73OEFAK72CHQ32GQHQ	恩施土家族苗族自治州	湖北省
+SUCY7I72QJDZD7EBFXREIQ67SI	咸宁市	湖北省
+QENSGB5R7HGYDXCG2LQZQTO3TU	荆门市	湖北省
+OHIWL6SAE2PR4EJR4BOMLAE6FU	武汉市	湖北省
+ZXCE4WV2CDVPQTA4HAOVELQMNE	襄阳市	湖北省
+KEFN5OPSS4ZZF6NU2TTL72S6HE	孝感市	湖北省
+ROAHLMQ67H6M5NDFVXROJG723E	黄冈市	湖北省
+YBEBX2YYN4WPBNH6Z6C73DNE7I	张家界市	湖南省
+45XGRKYGSCPE5VNRYF4FVJGFMM	株洲市	湖南省
+LK3SEIBRU7GTDT4J2EPTLIO33U	永州市	湖南省
+R4YXFIK53W5E556BSGSBJWS4DM	郴州市	湖南省
+PQDO3RNADWXX75OWZW2GSXJ4SE	怀化市	湖南省
+RRRT6QOJYEJ432L3F76ZN5NHCA	长沙市	湖南省
+B6WPNMCZ3ENQSV4NFY5MSTPDAM	岳阳市	湖南省
+KNDZW5EHDPKP2DX7HBLKP4DYLM	益阳市	湖南省
+PA2GHG3XZ7I47HTKZ4YAFH3OYY	湘西土家族苗族自治州	湖南省
+I7CNIUA5PYV2EHDEW3RGYT2R4U	邵阳市	湖南省
+SRI2SU4FN66FMJJCKQOCZD72ZY	常德市	湖南省
+H7UHHJAMQUL7UA5QEUTGKNSL3A	湘潭市	湖南省
+EFB255OBTB2BUDZENR5UVIC7ZQ	衡阳市	湖南省
+RDMANB4KCM3OJSNVGZWVYVME6E	娄底市	湖南省
+LD37PDU5OB4UAV5QDOBMKG5YTY	吉林市	吉林省
+EO3GF4XNF5RXWRPUVAT3KTQO4U	四平市	吉林省
+4GD7OS4CAQABH5YIWVK5SKGHMY	通化市	吉林省
+6DRI2R5VAWMYJHJPCJKUNMDYEQ	延边朝鲜族自治州	吉林省
+TVBCNVGUND4MOUOOUXFGX7DIUA	松原市	吉林省
+JYY62HSKBUVK5OU7KGJDKQ4RTA	白城市	吉林省
+QEDUHKMZ36CHJTKRD6O2ZPLNBU	长春市	吉林省
+4EADVCBJMZ5UBH2FVRT6QCLS2U	辽源市	吉林省
+EUQD5EGS2LR5KJSFNG6PPSIHHI	白山市	吉林省
+YLTIISPCLBEGTZZX3WUWAD7WDE	淮安市	江苏省
+L6U5DZP6MESXPMHOHCDMJS55O4	宿迁市	江苏省
+HQMLYA7TDGMYQAXFCDUXBZPYHI	镇江市	江苏省
+K6XJ4UN65ZD6XQKYEG5YN7HCRI	盐城市	江苏省
+36I4X3EZZU4EHOSCLQI5OAKKBE	南通市	江苏省
+S3GWFQU6QAVRDKLJT77LD6OFLE	泰州市	江苏省
+IO6F4AFGAVIFRGYTZEC4TXM7W4	无锡市	江苏省
+NUXNK2VOFSD2JFTEO2AMWX6NSU	扬州市	江苏省
+TEVZU6CU6SK57HFW7DFNGMQ44A	南京市	江苏省
+UTYSRBQ4FSB7XLWCF3Z2HTKNUA	常州市	江苏省
+OCZOBCJDEXKE7KBN3BD7AYQG2Q	徐州市	江苏省
+6LIBPJGZROLXE3CLZGJRYMYBOU	连云港市	江苏省
+FS4PIU74F7QKYARDWR5ZMOLICI	苏州市	江苏省
+R2F4OWUO65HYZW2IQIKINORZ7Y	赣州市	江西省
+YW346BTN3VFYNRC3744UR5MZXY	抚州市	江西省
+QR3FDR26U2EJIXOMBHL7IJLQSA	南昌市	江西省
+OAJHJL7L7VNW2Q5UXRE7F4CUJQ	九江市	江西省
+OMH7D45R4DX2KNHLV3G2UP56OY	景德镇市	江西省
+YSB2PAEROB2IZSJZFVFH7KJPEI	鹰潭市	江西省
+5OYAMNORCXKYA6UF7DW6KFFBIU	上饶市	江西省
+SMHZOYKE7BXQJ2NT6Q24TFMLEQ	吉安市	江西省
+2RZV26OUPKUHUJ5ZPB673VDGZU	萍乡市	江西省
+232VHZEEZ6SXACE4AC5HQ4ZTFQ	新余市	江西省
+QRLM74YXNDW2QDBWLTFGEMXK2I	宜春市	江西省
+S6OHUVUKIIWPVMQD44RREUMNT4	葫芦岛市	辽宁省
+DQQ4OIFUGFYJY3XZRK5VDWMLCA	辽阳市	辽宁省
+S4YXGFEYXEUG6ISZ6O337OPVSI	阜新市	辽宁省
+D3JHM7A4CG6RJMBD7YRDS5JOYU	盘锦市	辽宁省
+VTRWMOSS6PCUYUAIPG6VPBKUUQ	营口市	辽宁省
+ZPHFGWBIEVLKP5CVZNZUB3CRT4	朝阳市	辽宁省
+NGYYULZ4UAGD3Q2PG726FFXSHU	抚顺市	辽宁省
+Q5BRTSW752VSHIAKLLL7KL5TNA	锦州市	辽宁省
+ZGV3WNPOSS7J4ZWBP6ZQG46BNM	沈阳市	辽宁省
+XEX676YYMTYIV5QPIUZB4TA7IY	本溪市	辽宁省
+PRTEQZMLNLQNZXJHRCYYLWZB4E	丹东市	辽宁省
+4GN4WF6UQRFU64T4FVZPRDXRWQ	鞍山市	辽宁省
+3QTZDFLJFSLLOOVCZ65PSDAVOU	铁岭市	辽宁省
+CC4ZTMKKXI73ZEVT5QQTJN5SMM	大连市	辽宁省
+3MBJEFDLAVOMQZ7L7CM5MNSYKA	鄂尔多斯市	内蒙古自治区
+5NOS4YC5WO2IZCQPVB6MCBYDJ4	呼和浩特市	内蒙古自治区
+OQNIP675H7L5R64652BH7KHUOQ	通辽市	内蒙古自治区
+4WA6I63MGVINV5DNLNWRRHCDDM	阿拉善盟	内蒙古自治区
+ELI6BDJBAN6RCYTETMK2EX2UKU	乌兰察布市	内蒙古自治区
+PV5ZAAXFW2DZCVZKCF4I4KK7BQ	巴彦淖尔市	内蒙古自治区
+YU6UUT6G6T6AMWTJFECDIUQFEQ	乌海市	内蒙古自治区
+V4MYANW5QFZCXG3FIDPXA3HOTE	呼伦贝尔市	内蒙古自治区
+S5DCFJWJ7J3MJSLY2PHKWLNPOQ	包头市	内蒙古自治区
+LY7SAZRFSJJMRU3JEO5SKNKIVM	兴安盟	内蒙古自治区
+NM2XP54CNQCFOILKACYEQWUSGM	锡林郭勒盟	内蒙古自治区
+S5G3IO75IDEJPZQA6VFM3OYPDI	赤峰市	内蒙古自治区
+UUFUUPM5RT6ZU5UKILQC5YQV54	吴忠市	宁夏回族自治区
+VMSRLIATK44WQXQEWAL63AXJ3M	固原市	宁夏回族自治区
+4GWWCAAKGNJV2SMQPSWWZNCGYY	中卫市	宁夏回族自治区
+6IE7GEETBQEF7GUSGU2FLIUEEM	石嘴山市	宁夏回族自治区
+VI4YIH3URSON4Q4MWOEESXJ56Q	银川市	宁夏回族自治区
+SIE4ED6QWVRT727GEHWBFH3DAA	海东市	青海省
+JNJH6OJZIOQKXDXWW5ZGEHG5MA	海西蒙古族藏族自治州	青海省
+MJADYNCKQNDJU2TXACTDP5I52M	海北藏族自治州	青海省
+LRGFXIVB6RJWQWYAFH7EIUHCPE	黄南藏族自治州	青海省
+J4TG3PCK2ZEMNEUMIPZF32UNQY	果洛藏族自治州	青海省
+2YS5POGG53LKZGFBIUMDWP57SM	玉树藏族自治州	青海省
+GRZMJEZCA2DNCZK3O6ZSUHMRPM	西宁市	青海省
+NBFQIACRBBCAH5AZWJ5LVT7AU4	海南藏族自治州	青海省
+MQUKCLQ76P4FRRECDBA3HBKT7Q	滨州市	山东省
+633FVSBDDBM5WSMXSKOCX6QC5I	潍坊市	山东省
+4434FVT3PXLMV6UAWLEW6O3M5A	菏泽市	山东省
+P7PK4UBVCOHW3PI6IPEIA54DLY	济南市	山东省
+I5M6JGTGSQEWX6HL7E5I6GRBAY	德州市	山东省
+V562AOMBVU5NG5GB3EPK6U42XY	烟台市	山东省
+4OSPHTE5TD24J6DYGR6DXMEDKY	淄博市	山东省
+227TLAVTUJABWPJD4S4ZECJ3FY	临沂市	山东省
+DAEZKZU32ZAPJGUTA6LLGO3WTY	聊城市	山东省
+LBRRK2EOYJN5MLYJWT4R3QBSXM	东营市	山东省
+AB6PBGCDBTNTG4KUQROY2FJ4GY	枣庄市	山东省
+EVANGU7WZCVRAAM6NWTDJVP7SU	济宁市	山东省
+GNUEGWZ3OKRWAKKVJ5THHHX6YY	泰安市	山东省
+F3VWSF4ART2FYYBBOZYWKRXTUI	青岛市	山东省
+KD6MNWWLVKB4E655XMV6MMA3KE	日照市	山东省
+LHYVF4LBCOZ34G3WNZYUVEIQGA	威海市	山东省
+ENVYDMYGDO3BMDXSAVQYZXLX74	阳泉市	山西省
+UXOUG4UIF7ZRJYCNMQJ3LDN5FY	临汾市	山西省
+4NZPT6Z35BMYACJ2HZGHUWRJ6E	吕梁市	山西省
+KSNXQME2A3VFHCE3DM3SFZKIJQ	晋城市	山西省
+HDOX7WKYSHJKEHET6TUYMVCTMQ	太原市	山西省
+DFJIZVXJGBGBIABPSL3DGMIDIE	长治市	山西省
+5KQYYTJR2EMP653QIALMA6LXXI	忻州市	山西省
+T76EOJA332RIHML7B6LYS5LF4U	朔州市	山西省
+HVX67CKT5TS6GPRDFDYOOLK4PE	大同市	山西省
+S4NGXQJDOH7E4IHDWOH3EK6IIE	晋中市	山西省
+GWDLZXLAWU54FKQ6G3HRQRR7E4	运城市	山西省
+3FFTTN5PPV7MBCE5AGY2NGYOOI	安康市	陕西省
+GACVPL3SWO3ZKH73JMJV6YI4NY	延安市	陕西省
+6KPS7VRMW57P2DAC6OPR4ISHQQ	商洛市	陕西省
+OMMF6XLNDNYWG5TBSNTWO2ZJZ4	渭南市	陕西省
+EALFXGMWYRS6E6TWXQ2K3YHV4M	咸阳市	陕西省
+WFG7U6JNUWDIS5ZZYM4FSM5C64	榆林市	陕西省
+R3VBMYTCF5LVHO35X3MYJQFOOE	宝鸡市	陕西省
+RQOWP7C234IS4RKSHB26IYZ5IU	西安市	陕西省
+K4YU6B4T5GZLRWVHGVCR3576HI	铜川市	陕西省
+VVFVAPLKSCN5KN4Q6RK2GPGUUA	汉中市	陕西省
+2QSF6IG3KMDXWO5VP7FXHMMKXA	上海市	上海市
+X3JCRNIPTCUU6DGOFFJ4MUK37M	眉山市	四川省
+GQ24IZNTZJ3PUB5FDAMDA4W7UI	攀枝花市	四川省
+6B6WT62WHBZRHPQUT7BAD2N6ZI	泸州市	四川省
+HJ35P4KXL442MLIII7PFFWUNAE	雅安市	四川省
+K4A6VSJH2AJYT46LMUSVQZPCCU	资阳市	四川省
+646ZNPATOOM3MHI3LDU6HI4KFI	阿坝藏族羌族自治州	四川省
+MU735ZDBFPXRQDUZ3I35JK3XEU	内江市	四川省
+4WPGGJ63USY77GSRN2PPFCYKPQ	广安市	四川省
+O4FFS4DALDAAKIFAUH4F5V5VS4	宜宾市	四川省
+IRFJVK2KXBE6BZ7CSN4UFCI624	绵阳市	四川省
+NELFD7FEKKUNDJ46VLD55SMDCE	甘孜藏族自治州	四川省
+TKMVEUPZSQCXNRZPBEIK3F45AI	遂宁市	四川省
+VQW7DPB4KTUI65COJBO3NODU24	巴中市	四川省
+STP4ELXTVGQSB572LFRFJRIUUY	南充市	四川省
+6ST5EX2JVXUCLR5GP5VEFSKN5M	成都市	四川省
+UWNFCMW3HYJRALQI2MJH6EM2O4	德阳市	四川省
+J5ZYU7XRV6CHSJAGOPQKS5YXNA	达州市	四川省
+KYJTF5S746T35RFBMR65BLGM6U	凉山彝族自治州	四川省
+RDUXR23XROLB4NGRVDDLXFXDSE	乐山市	四川省
+4TUBIBHMVESJUCGMTUSLJPHXWI	广元市	四川省
+AXQL57AO27NCHYMEOLRHAAKMTA	自贡市	四川省
+4RXX566RZORCXS6HLEX3DIICSM	花莲县	台湾
+BD5Y7SISWSSQGP3HTVPU6TXAH4	台东县	台湾
+I4DNWLECRYOJAZLGYQB7PBBJXQ	台中市	台湾
+GIZQIESFOMAEQSDQKOEQ5RTTPA	南投县	台湾
+MPM6M2C634FAW7KYG3KIHERDTU	彰化县	台湾
+NH2NK6JVOBBYYTK2G53ADWLX4Y	苗栗县	台湾
+DW2Q2R2UEEDNQA7IHBGYV423K4	新竹市	台湾
+FX5AOPFRPHGHHYZB4XNIPXLNNM	新北市	台湾
+UVNZNB6G4M35RV3IGRUN6OXMXE	屏东县	台湾
+MPB3M2YK24ZORO3EDCJ6UDWIGQ	基隆市	台湾
+EBHVITJPDHJEEMMZTM4TD4UVRU	台北市	台湾
+FQS4PZNCTQEX6I5F34Z2AGJUZM	高雄市	台湾
+WVOJ636Q7MGT6RMN6QYQ4SZWIE	嘉义市	台湾
+QRLER4EEMMKYGQLER2RWEQA74E	台南市	台湾
+K2LHF64R2P4OJ7MDHJ6J2NSTPE	桃园市	台湾
+BILG6LJIWUCTXZ6CDPXYAVM6XI	澎湖县	台湾
+3FYRA3O2HUMLIQAAJQCPX2TETE	宜兰县	台湾
+4MW6X22PAPVMHB6SBGF3RYS324	天津市	天津市
+YEYPP4SQOBXU5UCNDN7ORSR6DI	拉萨市	西藏自治区
+UNE6UPENGWQDOWGABDJEAQ2FEY	山南市	西藏自治区
+VDXKN2YCIUPOHBZKKQHPN6HJWE	林芝市	西藏自治区
+EAWIMNI77H72EYSOAYV3M76CB4	阿里地区	西藏自治区
+HCF6UHTXOOKIOA43AIJH3ARKXA	昌都市	西藏自治区
+Y47QI3KJY352QV3VOPXHM2IDWU	日喀则市	西藏自治区
+R4UWJX44GVAA54NFKHT4Y4ZC5A	那曲市	西藏自治区
+2D37GB5XUALJDXONWJIGXV3QXU	香港	香港特别行政区
+PA5W7Z255K3EGYA4LTA7BGLHRA	巴音郭楞蒙古自治州	新疆维吾尔自治区
+RJZOCU5ECQCOLCOCHJH2UNLQJM	哈密市	新疆维吾尔自治区
+RYK6AR3VDQJFXZLX3MHYFV5VAI	塔城地区	新疆维吾尔自治区
+MXUVGU5NPVTNINAKKPNLWUQ54Q	博尔塔拉蒙古自治州	新疆维吾尔自治区
+T5RKMSH5VIGRTHDZOKV2EIKPIM	伊犁哈萨克自治州	新疆维吾尔自治区
+NABMKFZPOUCZMS4TUVJSZ24DNA	克孜勒苏柯尔克孜自治州	新疆维吾尔自治区
+2YQBXWNFYVJX4NU6WXB5II6X34	昌吉回族自治州	新疆维吾尔自治区
+DBKCQCCQU2URQG2EP5ZNPKBETY	乌鲁木齐市	新疆维吾尔自治区
+DON6KYBCR2XJQOJQGOZTYV4RMM	阿克苏地区	新疆维吾尔自治区
+WKG47NEVYII5JISZJN7QSI2BDQ	克拉玛依市	新疆维吾尔自治区
+DWLK6D3OUOXOVQHSEJVTRIDRAI	喀什地区	新疆维吾尔自治区
+SAPKF2PQGJD4UMVJZTC3IZKI64	阿勒泰地区	新疆维吾尔自治区
+ARWSLGG54LGUGN3XMIWW76NW34	吐鲁番市	新疆维吾尔自治区
+VQCWAKL6ADHYFTSVPBGPDFSB2I	北屯市	新疆维吾尔自治区
+ES5A6MOROAG6F2XAQ25TYYPWUE	铁门关市	新疆维吾尔自治区
+36IUY52AESIPF4QEQAR2RTNQYA	和田地区	新疆维吾尔自治区
+Z26KSUL6ULS65ITZNUCRRWBYJM	文山壮族苗族自治州	云南省
+XBBUUATPBD2IUJR47FCKVUXB2I	昭通市	云南省
+TK2LP3JCYYMPTV4OA3WJCH7UQ4	怒江傈僳族自治州	云南省
+ISJ4FESOYKCQ5LXOQO6NL7TQHA	曲靖市	云南省
+ELBUBVI5UMUIEQGIOAHPMESXFA	西双版纳傣族自治州	云南省
+QHOYHEGZM4WSJZPFEU6FCBYIWY	玉溪市	云南省
+4G4SPJ7MVHMYZAWMQ4642PMLVI	保山市	云南省
+HCHRV2LGJ2TJ4X6BWNWI2IMID4	普洱市	云南省
+IS4Q6NASBWHO3RFO7UCIWOXVI4	昆明市	云南省
+TDJZOAZFQUQPYRR5BHOJTG6RWM	红河哈尼族彝族自治州	云南省
+EIYC62RNU4SHQW3RLAMDPTQYTI	大理白族自治州	云南省
+BA3XFPITAYKBUWDKU3QONRHBC4	德宏傣族景颇族自治州	云南省
+6P6FFFO6C5MLNCVRJAJUICSVQI	临沧市	云南省
+OXHMWH2TSIDI7BQ43EHAMXJ6N4	丽江市	云南省
+QQPDT4LBI2K2KMBNXZ6YH7X2FI	楚雄彝族自治州	云南省
+XBG4EJAWCRJL2TDPNJ23PTFYHQ	迪庆藏族自治州	云南省
+DINNCH54AP74TJ62MICEYAZP74	宁波市	浙江省
+XYTSLYGB2ETU6HG7GIXA7X5SOE	嘉兴市	浙江省
+NNAALJZXGAWALR3LGE2V4UZT6U	丽水市	浙江省
+H5UOJ5MQYJ737GS3TXYN2OJHUU	杭州市	浙江省
+HG5VQGOMSCEGNXJXKO6XCNCHMY	湖州市	浙江省
+LJ2SWEPRINTYDH5A2QHRMI5US4	衢州市	浙江省
+TW4RRM62TDA7WWU77FDSLSAXGY	台州市	浙江省
+HBBN247QZ6YUW5ZYSS6D7RVJCA	绍兴市	浙江省
+GVFB23SJZGRPRXXTIKDCAOCDPI	金华市	浙江省
+UEW4ENX7N7IFGFM7FD5SZ5GI7Y	舟山市	浙江省
+HCCXS5DGRJQMYZMRLGVAMUIQEA	温州市	浙江省
+FDGY55I6IHKY76E3MWDBOT2R6Y	重庆市	重庆市
@@ -0,0 +1,65 @@
+"""通过经纬度反查城市（reverse_geocoder 离线库，零网络调用）。
+
+reverse_geocoder 内置 ~2.5M 条全球城市/聚居点的经纬度→地名映射表，
+构建一次 KDTree（~几十MB 内存）后，查询为纯内存搜索，不作任何外部网络调用。
+
+⚠️ 必须持有单例、且用 mode=1（单进程）：
+  - reverse_geocoder 的模块级 rg.search()/rg.get() **每次调用都会 new 一个 RGeocoder**，
+    即每次都重新解析 ~2.5M 行 CSV + 重建 KDTree（数秒/次）。绝不能在服务端按请求调用。
+  - 默认 mode=2 用 multiprocessing 按 CPU 数 spawn 子进程做并行查询；在服务端 / Windows
+    spawn 下会重复 import 主模块（无 __main__ guard 时直接报错），既慢又危险。
+  故本模块持有一个 mode=1 的 RGeocoder 单例，建一次树、复用；查询走单进程内存搜索。
+
+⚠️ 精度说明：gazetteer 里的中国数据粒度不一致——直辖市/省会通常直接命中城市名，
+但部分城市会命中到区/街道级（如天津→Erwangzhuang、西安→Zhangjiabao），
+此时 admin1（省级行政区）可作为回退。业务侧建议优先用 admin1 做城市级判定。
+"""
+from __future__ import annotations
+
+from typing import Any
+
+import reverse_geocoder as rg  # type: ignore[import-untyped]
+
+# mode=1 单进程 KDTree 的单例;None 表示尚未构建(见 ensure_loaded)。
+_geocoder: rg.RGeocoder | None = None
+
+
+def ensure_loaded() -> None:
+    """构建（或复用）RGeocoder 单例（幂等）。
+
+    首次调用解析 ~2.5M 行 CSV + 构建 KDTree（~秒级、数十 MB）。生产应在 main.py 的
+    lifespan 启动阶段主动调用一次，把这份一次性成本摊到启动，避免砸在第一个
+    /feed?tab=rec / /top-sales 请求上。mode=1 = 单进程，不 spawn 子进程。
+    """
+    global _geocoder
+    if _geocoder is None:
+        _geocoder = rg.RGeocoder(mode=1, verbose=False)
+
+
+def get_city(latitude: float, longitude: float) -> dict[str, str]:
+    """根据经纬度反查最近聚居点。
+
+    返回 dict:
+      - name:       最近聚居点名称（英文），如 "Beijing" / "Fengsheng"；
+                    中国境内可能是区/街道级；海洋/无人区返 ""
+      - admin1:     省级行政区（英文），如 "Beijing" / "Hubei" / "Chongqing Shi"；
+                    直辖市 admin1 即为城市名
+      - country:    ISO 3166-1 alpha-2，如 "CN"
+      - latitude:   匹配到的参考点纬度（字符串）
+      - longitude:  匹配到的参考点经度（字符串）
+
+    未匹配到（海洋/远洋）时返回空字符串字段。
+    """
+    ensure_loaded()
+    assert _geocoder is not None  # ensure_loaded 保证已构建
+    results: list[dict[str, Any]] = _geocoder.query([(latitude, longitude)])
+    if not results:
+        return {"name": "", "admin1": "", "country": "", "latitude": "", "longitude": ""}
+    r = results[0]
+    return {
+        "name": str(r.get("name", "")),
+        "admin1": str(r.get("admin1", "")),
+        "country": str(r.get("cc", "")),
+        "latitude": str(r.get("lat", "")),
+        "longitude": str(r.get("lon", "")),
+    }
@@ -0,0 +1,448 @@
+"""美团城市词典 + reverse_geocoder 离线反查。
+
+从 feed 入参的 latitude/longitude 计算出美团城市 ID，
+用于后续美团 CPS 接口的 cityId 参数。
+
+⚠️ 跨系统耦合:本模块返回的 city_id 取自 data/city_dict.txt,而离线库
+`meituan_coupon.city_id` 由 ETL(另一套系统)灌入。二者必须用同一份城市 ID 口径,
+否则 `WHERE city_id == <本模块结果>` 会静默查到 0 行 → 接口永久降级返空。
+改动 city_dict.txt 或 ETL 的城市 ID 来源时,务必同步两侧。
+"""
+from __future__ import annotations
+
+import logging
+import re
+from functools import lru_cache
+from pathlib import Path
+
+from app.utils.geo import get_city as _get_geo_city
+
+logger = logging.getLogger("shagua.meituan_city")
+
+# city_dict.txt 作为运行时数据随包分发(见 pyproject [tool.setuptools.package-data])
+_CITY_DICT_PATH = Path(__file__).resolve().parent / "data" / "city_dict.txt"
+
+# ─────────── 反向地理编码 admin1 → 中文省份名 ───────────
+# reverse_geocoder 的 admin1 格式不统一:
+#   直辖市: "Beijing" / "Shanghai Shi" / "Tianjin Shi" / "Chongqing Shi"
+#   省份:   "Guangdong" / "Jiangsu Sheng" / "Hubei" ...
+#   自治区: "Xinjiang Uygur Zizhiqu" / "Tibet Autonomous Region" ...
+# 下面用前缀匹配，去掉了 Sheng/Shi/Zizhiqu/Autonomous Region 等后缀。
+
+_PROVINCE_EN_PREFIX: list[tuple[str, str]] = [
+    # 直辖市 — admin1 即城市名
+    ("Beijing", "北京市"),
+    ("Shanghai", "上海市"),
+    ("Tianjin", "天津市"),
+    ("Chongqing", "重庆市"),
+    # 省
+    ("Hebei", "河北省"),
+    ("Shanxi", "山西省"),       # 注意: 指山西省,不是陕西
+    ("Liaoning", "辽宁省"),
+    ("Jilin", "吉林省"),
+    ("Heilongjiang", "黑龙江省"),
+    ("Jiangsu", "江苏省"),
+    ("Zhejiang", "浙江省"),
+    ("Anhui", "安徽省"),
+    ("Fujian", "福建省"),
+    ("Jiangxi", "江西省"),
+    ("Shandong", "山东省"),
+    ("Henan", "河南省"),
+    ("Hubei", "湖北省"),
+    ("Hunan", "湖南省"),
+    ("Guangdong", "广东省"),
+    ("Hainan", "海南省"),
+    ("Sichuan", "四川省"),
+    ("Guizhou", "贵州省"),
+    ("Yunnan", "云南省"),
+    ("Shaanxi", "陕西省"),      # 双写 a 是官方拼音
+    ("Gansu", "甘肃省"),
+    ("Qinghai", "青海省"),
+    # 自治区 — 注意匹配顺序, Xinjiang 要在 Guangxi 前面(Guangxi 也是 Xi 开头但先匹配 Xin 不会误判)
+    ("Guangxi", "广西壮族自治区"),
+    ("Inner Mongolia", "内蒙古自治区"),
+    ("Nei Mongol", "内蒙古自治区"),
+    ("Tibet", "西藏自治区"),
+    ("Xizang", "西藏自治区"),
+    ("Ningxia", "宁夏回族自治区"),
+    ("Xinjiang", "新疆维吾尔自治区"),
+    # 特别行政区
+    ("Hong Kong", "香港特别行政区"),
+    ("Macau", "澳门特别行政区"),
+    ("Macao", "澳门特别行政区"),
+    # 台湾（city_dict 里省份名为 "台湾"，没有省/自治区后缀）
+    ("Taiwan", "台湾"),
+]
+
+# ─────────── 常见城市名 英文→中文 映射 ───────────
+# 覆盖所有直辖市 + 省会 + 一线城市 + 部分 reverse_geocoder 只能命中到区/县的城市。
+# key 全小写，匹配时做小写比较。
+_CITY_EN_TO_CN: dict[str, str] = {
+    # 直辖市
+    "beijing": "北京市",
+    "shanghai": "上海市",
+    "tianjin": "天津市",
+    "chongqing": "重庆市",
+    # 省会 / 副省级
+    "guangzhou": "广州市",
+    "shenzhen": "深圳市",
+    "chengdu": "成都市",
+    "hangzhou": "杭州市",
+    "wuhan": "武汉市",
+    "xi'an": "西安市",
+    "nanjing": "南京市",
+    "changsha": "长沙市",
+    "zhengzhou": "郑州市",
+    "jinan": "济南市",
+    "kunming": "昆明市",
+    "fuzhou": "福州市",
+    "harbin": "哈尔滨市",
+    "lanzhou": "兰州市",
+    "guiyang": "贵阳市",
+    "nanning": "南宁市",
+    "shijiazhuang": "石家庄市",
+    "taiyuan": "太原市",
+    "shenyang": "沈阳市",
+    "changchun": "长春市",
+    "hefei": "合肥市",
+    "nanchang": "南昌市",
+    "haikou": "海口市",
+    "hohhot": "呼和浩特市",
+    "huhehaote": "呼和浩特市",
+    "urumqi": "乌鲁木齐市",
+    "wulumuqi": "乌鲁木齐市",
+    "lhasa": "拉萨市",
+    "yinchuan": "银川市",
+    "xining": "西宁市",
+    # 其他常见城市
+    "xiamen": "厦门市",
+    "suzhou": "苏州市",
+    "qingdao": "青岛市",
+    "dalian": "大连市",
+    "ningbo": "宁波市",
+    "wuxi": "无锡市",
+    "foshan": "佛山市",
+    "dongguan": "东莞市",
+    "zhuhai": "珠海市",
+    "zhongshan": "中山市",
+    "wenzhou": "温州市",
+    "shaoxing": "绍兴市",
+    "jiaxing": "嘉兴市",
+    "jinhua": "金华市",
+    "taizhou": "台州市",
+    "yangzhou": "扬州市",
+    "nantong": "南通市",
+    "changzhou": "常州市",
+    "xuzhou": "徐州市",
+    "zhengjiang": "镇江市",
+    "yantai": "烟台市",
+    "weifang": "潍坊市",
+    "zibo": "淄博市",
+    "linyi": "临沂市",
+    "weihai": "威海市",
+    "rizhao": "日照市",
+    "luoyang": "洛阳市",
+    "kaifeng": "开封市",
+    "xinxiang": "新乡市",
+    "nanyang": "南阳市",
+    "yichang": "宜昌市",
+    "xiangyang": "襄阳市",
+    "huangshi": "黄石市",
+    "zhuzhou": "株洲市",
+    "xiangtan": "湘潭市",
+    "yueyang": "岳阳市",
+    "hengyang": "衡阳市",
+    "mianyang": "绵阳市",
+    "luzhou": "泸州市",
+    "yibin": "宜宾市",
+    "nanchong": "南充市",
+    "zigong": "自贡市",
+    "qujing": "曲靖市",
+    "yuxi": "玉溪市",
+    "zunyi": "遵义市",
+    "guilin": "桂林市",
+    "liuzhou": "柳州市",
+    "sanya": "三亚市",
+    "tangshan": "唐山市",
+    "baoding": "保定市",
+    "handan": "邯郸市",
+    "qinhuangdao": "秦皇岛市",
+    "langfang": "廊坊市",
+    "datong": "大同市",
+    "changzhi": "长治市",
+    "linfen": "临汾市",
+    "baotou": "包头市",
+    "ordos": "鄂尔多斯市",
+    "eerduosi": "鄂尔多斯市",
+    "daqing": "大庆市",
+    "qiqihar": "齐齐哈尔市",
+    "jilin_city": "吉林市",
+    "anshan": "鞍山市",
+    "fushun": "抚顺市",
+    "benxi": "本溪市",
+    "jinzhou": "锦州市",
+    "yingkou": "营口市",
+    "dandong": "丹东市",
+    "huizhou": "惠州市",
+    "jiangmen": "江门市",
+    "zhanjiang": "湛江市",
+    "maoming": "茂名市",
+    "zhaoqing": "肇庆市",
+    "chaozhou": "潮州市",
+    "shantou": "汕头市",
+    "shaoguan": "韶关市",
+    "meizhou": "梅州市",
+    "jieyang": "揭阳市",
+    "qingyuan": "清远市",
+    "heyuan": "河源市",
+    "yangjiang": "阳江市",
+    "shanwei": "汕尾市",
+    "yunfu": "云浮市",
+}
+
+
+# ─────────── 省会映射（城市匹配失败时回退） ───────────
+# city_dict.txt 内省份的第一个城市不一定是省会，故显式维护。
+_PROVINCE_CAPITAL: dict[str, str] = {
+    "安徽省": "合肥市",
+    "澳门特别行政区": "澳门",
+    "北京市": "北京市",
+    "福建省": "福州市",
+    "甘肃省": "兰州市",
+    "广东省": "广州市",
+    "广西壮族自治区": "南宁市",
+    "贵州省": "贵阳市",
+    "海南省": "海口市",
+    "河北省": "石家庄市",
+    "河南省": "郑州市",
+    "黑龙江省": "哈尔滨市",
+    "湖北省": "武汉市",
+    "湖南省": "长沙市",
+    "吉林省": "长春市",
+    "江苏省": "南京市",
+    "江西省": "南昌市",
+    "辽宁省": "沈阳市",
+    "内蒙古自治区": "呼和浩特市",
+    "宁夏回族自治区": "银川市",
+    "青海省": "西宁市",
+    "山东省": "济南市",
+    "山西省": "太原市",
+    "陕西省": "西安市",
+    "上海市": "上海市",
+    "四川省": "成都市",
+    "台湾": "台北市",
+    "天津市": "天津市",
+    "西藏自治区": "拉萨市",
+    "香港特别行政区": "香港",
+    "新疆维吾尔自治区": "乌鲁木齐市",
+    "云南省": "昆明市",
+    "浙江省": "杭州市",
+    "重庆市": "重庆市",
+}
+
+
+# ─────────── 城市字典加载 ───────────
+
+def _parse_city_dict(path: str | Path) -> list[dict[str, str]]:
+    """解析 city_dict.txt，返回 [{city_id, city_name, province_name}, ...]。
+
+    city_dict.txt 格式（TSV）:
+      城市ID\t城市名称\t省份名称
+
+    示例行:
+      3NUYJKKJXPHVNZUHFK3HWUDHNM\t宣城市\t安徽省
+    """
+    data: list[dict[str, str]] = []
+    with open(path, encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            parts = line.split("\t")
+            if len(parts) < 3:
+                continue
+            city_id, city_name, province_name = parts[0], parts[1], parts[2]
+            if city_id == "城市ID":
+                continue  # 跳过表头
+            if city_id and city_name and province_name:
+                data.append({
+                    "city_id": city_id,
+                    "city_name": city_name,
+                    "province_name": province_name,
+                })
+    return data
+
+
+# 模块加载时一次解析
+try:
+    _CITY_DICT: list[dict[str, str]] = _parse_city_dict(_CITY_DICT_PATH)
+except Exception:
+    logger.exception("加载 city_dict.txt 失败,美团城市反查将不可用")
+    _CITY_DICT = []
+
+
+def _build_province_index() -> dict[str, list[dict[str, str]]]:
+    """构建 省份名 → 该省全部城市列表 的索引。"""
+    idx: dict[str, list[dict[str, str]]] = {}
+    for entry in _CITY_DICT:
+        idx.setdefault(entry["province_name"], []).append(entry)
+    return idx
+
+
+_PROVINCE_INDEX: dict[str, list[dict[str, str]]] | None = None
+
+
+def _get_province_index() -> dict[str, list[dict[str, str]]]:
+    global _PROVINCE_INDEX
+    if _PROVINCE_INDEX is None:
+        _PROVINCE_INDEX = _build_province_index()
+    return _PROVINCE_INDEX
+
+
+# ─────────── 查询 ───────────
+
+def _map_admin1_to_cn_province(admin1: str) -> str:
+    """将 reverse_geocoder 的 admin1 映射到 city_dict 中的中文省份名。"""
+    if not admin1:
+        return ""
+    normalized = admin1.strip()
+    # 多级匹配:先精确、再前缀
+    for en_prefix, cn_name in _PROVINCE_EN_PREFIX:
+        if normalized == en_prefix or normalized.startswith(en_prefix):
+            return cn_name
+    return ""
+
+
+def _lookup_city_in_province(city_en_lower: str, province_cn: str) -> str:
+    """在指定省份内查找匹配的城市名（EN→CN 映射）。"""
+    if not province_cn:
+        return ""
+    index = _get_province_index()
+    candidates = index.get(province_cn, [])
+    if not candidates:
+        return ""
+
+    # 1) 精确映射
+    if city_en_lower in _CITY_EN_TO_CN:
+        cn_city = _CITY_EN_TO_CN[city_en_lower]
+        for c in candidates:
+            if c["city_name"] == cn_city:
+                return cn_city
+
+    # 2) 前缀/包含匹配（处理 admin1 直辖市场景:行政区 → 直辖市本身）
+    for c in candidates:
+        # 去掉"市"后缀比较
+        city_core = c["city_name"].rstrip("市")
+        if city_en_lower.startswith(city_core.lower()) or city_core.lower().startswith(city_en_lower):
+            return c["city_name"]
+        # city_en_lower 可能是拼音，city_core 是中文，尝试从 EN→CN 映射反向匹配
+        for en_k, cn_v in _CITY_EN_TO_CN.items():
+            if cn_v == c["city_name"] and (city_en_lower in en_k or en_k in city_en_lower):
+                return cn_v
+
+    # 3) 匹配不到 → 返回省会
+    capital = _PROVINCE_CAPITAL.get(province_cn, "")
+    if capital:
+        for c in candidates:
+            if c["city_name"] == capital:
+                return capital
+    return candidates[0]["city_name"]  # 终极兜底
+
+
+def _sanitize_city_name(name: str) -> str:
+    """去除 reverse_geocoder name 中常见的行政后缀使匹配更鲁棒。"""
+    # 去掉 " District" / " Qu" / " Shi" 等英文后缀
+    for suffix in ("District", "Qu", "Shi", "Sheng", "Xian", "Cun", "Zhen", "Xiang",
+                   "Zizhiqu", "Autonomous Region", "Special Administrative Region"):
+        name = re.sub(rf"\s+{suffix}$", "", name, flags=re.IGNORECASE)
+    return name.strip()
+
+
+@lru_cache(maxsize=512)
+def _resolve_meituan_city(latitude: float, longitude: float) -> dict[str, str]:
+    """反查实现;入参已量化(见 get_meituan_city),故 lru_cache 命中率高。
+
+    返回的 dict 被缓存复用 —— 调用方勿原地修改(get_meituan_city 已返回副本)。
+    """
+    if not _CITY_DICT:
+        return {"city_id": "", "city_name": "", "province_name": ""}
+
+    logger.debug("resolve_meituan_city: lat=%.2f lon=%.2f", latitude, longitude)
+    geo = _get_geo_city(latitude, longitude)
+    name_en = _sanitize_city_name(geo.get("name", ""))
+    admin1 = geo.get("admin1", "")
+    country = geo.get("country", "")
+
+    if country != "CN":
+        logger.debug("resolve_meituan_city: 坐标(%.2f,%.2f)不在中国境内(country=%s)", latitude, longitude, country)
+        return {"city_id": "", "city_name": "", "province_name": ""}
+
+    # 1) 映射省份
+    province_cn = _map_admin1_to_cn_province(admin1)
+    if not province_cn:
+        logger.warning("get_meituan_city: admin1=%r 无法映射到中文省份", admin1)
+        return {"city_id": "", "city_name": "", "province_name": ""}
+
+    # 2) 查找城市
+    name_lower = name_en.lower()
+    city_cn = _lookup_city_in_province(name_lower, province_cn)
+
+    # 3) 按省份+城市匹配 city_dict 中的城市 ID
+    index = _get_province_index()
+    candidates = index.get(province_cn, [])
+    for c in candidates:
+        if city_cn and c["city_name"] == city_cn:
+            return {
+                "city_id": c["city_id"],
+                "city_name": c["city_name"],
+                "province_name": province_cn,
+            }
+
+    # 4) 最终回退:返回该省省会
+    if candidates:
+        capital = _PROVINCE_CAPITAL.get(province_cn, "")
+        if capital:
+            for c in candidates:
+                if c["city_name"] == capital:
+                    logger.info("get_meituan_city: 城市匹配失败 name_en=%r, 回退到省会 %s", name_en, capital)
+                    return {
+                        "city_id": c["city_id"],
+                        "city_name": capital,
+                        "province_name": province_cn,
+                    }
+        # 终极兜底:第一个城市
+        fallback = candidates[0]
+        logger.info("get_meituan_city: 城市匹配失败 name_en=%r, 回退到 %s", name_en, fallback["city_name"])
+        return {
+            "city_id": fallback["city_id"],
+            "city_name": fallback["city_name"],
+            "province_name": province_cn,
+        }
+
+    return {"city_id": "", "city_name": "", "province_name": ""}
+
+
+def get_meituan_city(latitude: float, longitude: float) -> dict[str, str]:
+    """根据经纬度反查美团城市 ID + 城市名 + 省份名(对外入口)。
+
+    返回:
+      - city_id:      美团城市 ID(如 3NUYJKKJXPHVNZUHFK3HWUDHNM);
+                      匹配失败时返回 ""
+      - city_name:    中文城市名(如 "北京市")
+      - province_name: 中文省份名(如 "北京市")
+
+    原理:
+      1. reverse_geocoder 根据经纬度查出英文地名 + 省份
+      2. 英文省份→中文省份映射(前缀匹配)
+      3. 英文地名→中文城市名映射(精确映射 + 省内候选回退)
+      4. 在 city_dict.txt 中按省份+城市名匹配城市 ID
+
+    城市名匹配失败的策略:
+      - 直辖市(京沪津渝): admin1 本身即城市名,直接取
+      - 省会: 回退到该省第一个城市(city_dict.txt 中每个省的省会通常排第一位)
+
+    实现说明:先把坐标量化到 ~1km(round 到 2 位小数)再进 lru_cache —— 原始 GPS 坐标
+    每次抖动到小数点后 5~6 位,直接做缓存 key 几乎不命中;城市级解析对 1km 误差不敏感,
+    量化后"同一地点反复请求"可命中缓存。返回缓存 dict 的副本,调用方可安全读写。
+    """
+    return dict(_resolve_meituan_city(round(latitude, 2), round(longitude, 2)))
@@ -0,0 +1,22 @@
+# 本地开发/测试用 PostgreSQL。生产用原生 PG(scripts/init_postgres.py),不使用本文件。
+services:
+  postgres:
+    image: postgres:16-alpine
+    container_name: shaguabijia-pg
+    environment:
+      POSTGRES_USER: shaguabijia_app
+      POSTGRES_PASSWORD: shaguabijia_dev_pw
+      POSTGRES_DB: shaguabijia
+    ports:
+      - "5432:5432"
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+      - ./docker/initdb:/docker-entrypoint-initdb.d:ro
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U shaguabijia_app -d shaguabijia"]
+      interval: 3s
+      timeout: 3s
+      retries: 20
+
+volumes:
+  pgdata:
@@ -0,0 +1,3 @@
+-- 仅在 pgdata 卷首次初始化时执行一次(以 shaguabijia_app 连 shaguabijia 库运行)。
+-- 幂等兜底见 scripts/ensure_pg.py 的 _ensure_test_db()。
+CREATE DATABASE shaguabijia_test OWNER shaguabijia_app;
@@ -27,7 +27,21 @@ PG 默认上 16 版(工具链最齐),驱动用 **psycopg3**(SQLAlchemy 2.0 时

 ## 1. 本地起 PG + 跑通空库(半天)

-### 1.1 装 PG
+### 1.0 推荐:Docker 一键起(本地开发/测试)
+
+本地开发不必手动装 PG。已提供 `docker-compose.yml` + `scripts/ensure_pg.py`:
+
+```bash
+cp .env.example .env    # DATABASE_URL 默认已是 Docker PG 连接串
+./run.sh                # 或 run.bat;会自动:探测 PG → 没起则启 Docker → 起 PG 容器 → 建库 → alembic → uvicorn
+pytest                  # conftest 自动引导同一容器的 shaguabijia_test 库
+```
+
+容器:`postgres:16-alpine`(名 `shaguabijia-pg`,端口 5432,命名卷 `pgdata` 持久化),
+首启即建业务库 `shaguabijia` 与测试库 `shaguabijia_test`。下面 1.1-1.5 的手动装 PG 步骤仅在
+不用 Docker 时才需要;生产仍走 §4 的原生 PG。
+
+### 1.1 装 PG(不用 Docker 时的手动方式)

 macOS:
 ```bash
@@ -0,0 +1,740 @@
+# 本地开发切 Docker PostgreSQL 实现计划
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 让 app-server 本地开发运行与 pytest 都跑在 Docker 化的 PostgreSQL 16 上,退掉 SQLite,`run.bat`/`run.sh` 启动时自动检测并拉起 PG(必要时先启 Docker Desktop、缺镜像先拉)。
+
+**Architecture:** 新增 `docker-compose.yml`(声明 PG 服务/卷/健康检查)+ `scripts/ensure_pg.py`(跨平台引导:探测→启 Docker→compose up→等就绪→幂等建测试库),由 `run.sh`/`run.bat`/`tests/conftest.py` 三处共用。`.env.example` 默认切 PG。`app/db/session.py` 与 `alembic/env.py` 已天然支持 PG,无需改。
+
+**Tech Stack:** Docker Compose、`postgres:16-alpine`、Python 3.10+ 标准库(`socket`/`subprocess`/`urllib.parse`)、psycopg3(已装)、SQLAlchemy 2.0 + Alembic、pytest。
+
+**工作目录:** 本计划在 worktree `.worktrees/local-dev-postgres-docker`(分支 `chore/local-dev-postgres-docker`,基于 `main`)内执行。下面所有路径相对该 worktree 根(= 仓库根)。
+
+**设计依据:** [docs/superpowers/specs/2026-07-08-local-dev-postgres-docker-design.md](../specs/2026-07-08-local-dev-postgres-docker-design.md)
+
+**连接参数(全程固定值):**
+- 镜像 `postgres:16-alpine`,容器名 `shaguabijia-pg`,宿主端口 `5432`
+- 用户 `shaguabijia_app`,dev 密码 `shaguabijia_dev_pw`(本地非机密)
+- 业务库 `shaguabijia`,测试库 `shaguabijia_test`,命名卷 `pgdata`
+- dev URL:`postgresql+psycopg://shaguabijia_app:shaguabijia_dev_pw@localhost:5432/shaguabijia`
+- test URL:`...@localhost:5432/shaguabijia_test`
+
+**前置:** 执行机已安装 Docker Desktop。
+
+---
+
+## Task 1: Docker Compose + 测试库 initdb 脚本
+
+**Files:**
+- Create: `docker-compose.yml`
+- Create: `docker/initdb/01-create-test-db.sql`
+
+- [ ] **Step 1: 写 `docker-compose.yml`**
+
+```yaml
+# 本地开发/测试用 PostgreSQL。生产用原生 PG(scripts/init_postgres.py),不使用本文件。
+services:
+  postgres:
+    image: postgres:16-alpine
+    container_name: shaguabijia-pg
+    environment:
+      POSTGRES_USER: shaguabijia_app
+      POSTGRES_PASSWORD: shaguabijia_dev_pw
+      POSTGRES_DB: shaguabijia
+    ports:
+      - "5432:5432"
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+      - ./docker/initdb:/docker-entrypoint-initdb.d:ro
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U shaguabijia_app -d shaguabijia"]
+      interval: 3s
+      timeout: 3s
+      retries: 20
+
+volumes:
+  pgdata:
+```
+
+- [ ] **Step 2: 写 `docker/initdb/01-create-test-db.sql`**
+
+```sql
+-- 仅在 pgdata 卷首次初始化时执行一次(以 shaguabijia_app 连 shaguabijia 库运行)。
+-- 幂等兜底见 scripts/ensure_pg.py 的 _ensure_test_db()。
+CREATE DATABASE shaguabijia_test OWNER shaguabijia_app;
+```
+
+- [ ] **Step 3: 起容器验证**
+
+Run: `docker compose up -d`
+Expected: 拉取 `postgres:16-alpine`(首次)后 `Container shaguabijia-pg  Started`。
+
+- [ ] **Step 4: 验证两个库都在 + 健康**
+
+Run: `docker compose exec -T postgres psql -U shaguabijia_app -d shaguabijia -tAc "SELECT datname FROM pg_database WHERE datname IN ('shaguabijia','shaguabijia_test') ORDER BY 1"`
+Expected 输出:
+```
+shaguabijia
+shaguabijia_test
+```
+
+- [ ] **Step 5: 验证 `.worktrees/` 与 `data/` 忽略不受影响、compose 无落盘到项目目录**
+
+Run: `git status --short`
+Expected: 只列出本任务新增的 `docker-compose.yml`、`docker/initdb/01-create-test-db.sql`(数据在命名卷 `pgdata`,不在项目目录;`.worktrees/` 已忽略)。
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add docker-compose.yml docker/initdb/01-create-test-db.sql
+git commit -m "feat(dev): docker-compose 起本地 PostgreSQL(含测试库 initdb)"
+```
+
+---
+
+## Task 2: `scripts/ensure_pg.py` 引导脚本(TDD)
+
+**Files:**
+- Create: `scripts/ensure_pg.py`
+- Test: `tests/test_ensure_pg.py`
+
+> 说明:纯函数(URL 解析 / sqlite 判定 / 端口探测 / 平台命令映射 / sqlite 守卫 / 端口通时短路)走 TDD 单测;真正拉 Docker 的编排 `ensure()` 全链路靠 Task 3/5 的运行来验证(需真 Docker,不做单测)。此时 `conftest.py` 仍是 SQLite,不依赖 PG,单测可独立跑。
+
+- [ ] **Step 1: 写失败测试 `tests/test_ensure_pg.py`**
+
+```python
+"""scripts/ensure_pg.py 纯函数单测(不需要 Docker/PG)。"""
+from __future__ import annotations
+
+import socket
+
+from scripts.ensure_pg import (
+    _docker_desktop_cmd,
+    _is_sqlite,
+    _parse_host_port,
+    _port_open,
+    ensure,
+)
+
+
+def test_is_sqlite():
+    assert _is_sqlite("sqlite:///./data/app.db")
+    assert _is_sqlite("  SQLite:///x ")
+    assert not _is_sqlite("postgresql+psycopg://u:p@localhost:5432/db")
+
+
+def test_parse_host_port_full():
+    assert _parse_host_port(
+        "postgresql+psycopg://u:p@localhost:5432/shaguabijia"
+    ) == ("localhost", 5432)
+
+
+def test_parse_host_port_defaults():
+    # 缺端口 → 5432
+    assert _parse_host_port("postgresql+psycopg://u:p@db.example/x")[1] == 5432
+    # 缺 host → localhost
+    assert _parse_host_port("postgresql+psycopg:///x") == ("localhost", 5432)
+
+
+def test_parse_host_port_testdb():
+    assert _parse_host_port(
+        "postgresql+psycopg://u:p@localhost:5432/shaguabijia_test"
+    ) == ("localhost", 5432)
+
+
+def test_port_open_true():
+    srv = socket.socket()
+    srv.bind(("127.0.0.1", 0))
+    srv.listen(1)
+    port = srv.getsockname()[1]
+    try:
+        assert _port_open("127.0.0.1", port, timeout=1.0)
+    finally:
+        srv.close()
+
+
+def test_port_open_false():
+    s = socket.socket()
+    s.bind(("127.0.0.1", 0))
+    port = s.getsockname()[1]
+    s.close()  # 释放端口,无人监听 → 连接应失败
+    assert not _port_open("127.0.0.1", port, timeout=0.3)
+
+
+def test_docker_desktop_cmd_windows():
+    cmd = _docker_desktop_cmd("win32", r"C:\Program Files")
+    assert cmd is not None
+    assert cmd[0].endswith("Docker Desktop.exe")
+    assert "Docker" in cmd[0]
+
+
+def test_docker_desktop_cmd_darwin():
+    assert _docker_desktop_cmd("darwin", "") == ["open", "-a", "Docker"]
+
+
+def test_docker_desktop_cmd_linux():
+    assert _docker_desktop_cmd("linux", "") is None
+
+
+def test_ensure_rejects_sqlite():
+    # dev 守卫:sqlite 直接 False(不碰 Docker)
+    assert ensure("sqlite:///./data/app.db") is False
+
+
+def test_ensure_shortcircuits_when_pg_up(monkeypatch):
+    # 端口通 → 直接 True,绝不触碰 docker
+    monkeypatch.setattr("scripts.ensure_pg._port_open", lambda *a, **k: True)
+
+    def _boom():
+        raise AssertionError("端口通时不应调用 docker")
+
+    monkeypatch.setattr("scripts.ensure_pg._docker_cli_ok", _boom)
+    assert ensure("postgresql+psycopg://u:p@localhost:5432/shaguabijia") is True
+```
+
+- [ ] **Step 2: 跑测试确认失败**
+
+Run: `pytest tests/test_ensure_pg.py -v`
+Expected: FAIL —— `ModuleNotFoundError: No module named 'scripts.ensure_pg'`(还没建)。
+
+- [ ] **Step 3: 写实现 `scripts/ensure_pg.py`**
+
+```python
+"""确保本地 PostgreSQL 就绪(开发/测试统一用 Docker PG)。
+
+被三处复用:
+  - run.sh / run.bat:`python -m scripts.ensure_pg`(CLI,失败退非 0)
+  - tests/conftest.py:`from scripts.ensure_pg import ensure; ensure(test_url)`
+
+流程:读 DATABASE_URL → TCP 探测 → 没起就(必要时启 Docker Desktop)→
+`docker compose up -d` → 等 PG ready → 幂等确保测试库存在。全程无 SQLite 兜底。
+
+生产用原生 PG(scripts/init_postgres.py),不走本模块。
+"""
+from __future__ import annotations
+
+import os
+import socket
+import subprocess
+import sys
+import time
+from pathlib import Path
+from urllib.parse import urlsplit
+
+ROOT = Path(__file__).resolve().parent.parent
+
+# 日志里可能含 emoji(如 ✅);Windows GBK 控制台(cmd.exe)无法编码会抛 UnicodeEncodeError → 脚本崩、
+# run.bat 误判 ensure_pg 失败。用 backslashreplace 保底:中文仍正常,仅不可编码字符被转义,不崩。
+for _stream in (sys.stdout, sys.stderr):
+    try:
+        _stream.reconfigure(errors="backslashreplace")
+    except (AttributeError, ValueError):
+        pass
+
+APP_DB = "shaguabijia"
+TEST_DB = "shaguabijia_test"
+DB_USER = "shaguabijia_app"
+COMPOSE_SERVICE = "postgres"
+
+DOCKER_START_TIMEOUT = int(os.environ.get("ENSURE_PG_DOCKER_TIMEOUT", "120"))
+PG_READY_TIMEOUT = int(os.environ.get("ENSURE_PG_READY_TIMEOUT", "60"))
+POLL_INTERVAL = 3.0
+
+SQLITE_FIX_HINT = (
+    "postgresql+psycopg://shaguabijia_app:shaguabijia_dev_pw@localhost:5432/shaguabijia"
+)
+
+
+def _log(msg: str) -> None:
+    print(f"[ensure_pg] {msg}", flush=True)
+
+
+def _is_sqlite(url: str) -> bool:
+    return url.strip().lower().startswith("sqlite")
+
+
+def _parse_host_port(url: str) -> tuple[str, int]:
+    """从 SQLAlchemy URL 取 host/port,缺省 localhost:5432。"""
+    parts = urlsplit(url)
+    return (parts.hostname or "localhost"), (parts.port or 5432)
+
+
+def _port_open(host: str, port: int, timeout: float = 1.0) -> bool:
+    try:
+        with socket.create_connection((host, port), timeout=timeout):
+            return True
+    except OSError:
+        return False
+
+
+def _docker_desktop_cmd(platform: str, program_files: str) -> list[str] | None:
+    """按平台给出启动 Docker Desktop 的命令;Linux 返回 None(daemon 需 sudo,让用户手动)。"""
+    if platform.startswith("win"):
+        return [str(Path(program_files) / "Docker" / "Docker" / "Docker Desktop.exe")]
+    if platform == "darwin":
+        return ["open", "-a", "Docker"]
+    return None
+
+
+def _docker_ok(subcmd: str) -> bool:
+    """`docker version`(CLI 在不在)/`docker info`(daemon 起没起)成功与否。"""
+    try:
+        subprocess.run(
+            ["docker", subcmd],
+            cwd=ROOT,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            check=True,
+        )
+        return True
+    except (OSError, subprocess.CalledProcessError):
+        return False
+
+
+def _docker_cli_ok() -> bool:
+    return _docker_ok("version")
+
+
+def _docker_daemon_ok() -> bool:
+    return _docker_ok("info")
+
+
+def _start_docker_daemon() -> bool:
+    """守护进程没起时按平台拉起,轮询到就绪。返回是否成功。"""
+    if _docker_daemon_ok():
+        return True
+    cmd = _docker_desktop_cmd(
+        sys.platform, os.environ.get("ProgramFiles", r"C:\Program Files")
+    )
+    if cmd is None:
+        _log("Docker 守护进程未运行。Linux 请手动:sudo systemctl start docker,然后重试。")
+        return False
+    if sys.platform.startswith("win") and not Path(cmd[0]).exists():
+        _log(f"找不到 Docker Desktop:{cmd[0]}。请手动启动 Docker Desktop 后重试。")
+        return False
+    _log(f"启动 Docker Desktop(首次冷启可能 30-60s)…")
+    try:
+        subprocess.Popen(cmd, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+    except OSError as e:
+        _log(f"启动 Docker Desktop 失败:{e}")
+        return False
+    deadline = time.monotonic() + DOCKER_START_TIMEOUT
+    while time.monotonic() < deadline:
+        if _docker_daemon_ok():
+            _log("Docker 守护进程已就绪。")
+            return True
+        _log("等待 Docker 守护进程…")
+        time.sleep(POLL_INTERVAL)
+    _log(f"等待 Docker 守护进程超时({DOCKER_START_TIMEOUT}s)。")
+    return False
+
+
+def _compose_up() -> bool:
+    _log("docker compose up -d(镜像缺失会自动拉取,首用约几十秒)…")
+    try:
+        subprocess.run(["docker", "compose", "up", "-d"], cwd=ROOT, check=True)
+        return True
+    except (OSError, subprocess.CalledProcessError) as e:
+        _log(f"docker compose up 失败:{e}")
+        return False
+
+
+def _pg_isready() -> bool:
+    r = subprocess.run(
+        ["docker", "compose", "exec", "-T", COMPOSE_SERVICE,
+         "pg_isready", "-U", DB_USER, "-d", APP_DB],
+        cwd=ROOT, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+    )
+    return r.returncode == 0
+
+
+def _wait_pg_ready(host: str, port: int) -> bool:
+    deadline = time.monotonic() + PG_READY_TIMEOUT
+    while time.monotonic() < deadline:
+        if _port_open(host, port) and _pg_isready():
+            _log("PostgreSQL 已就绪。")
+            return True
+        _log("等待 PostgreSQL 就绪…")
+        time.sleep(POLL_INTERVAL)
+    _log(f"等待 PostgreSQL 就绪超时({PG_READY_TIMEOUT}s)。")
+    return False
+
+
+def _ensure_test_db() -> None:
+    """幂等建测试库(兼容老 pgdata 卷首启没跑 initdb 的情况)。"""
+    check = subprocess.run(
+        ["docker", "compose", "exec", "-T", COMPOSE_SERVICE,
+         "psql", "-U", DB_USER, "-d", APP_DB, "-tAc",
+         f"SELECT 1 FROM pg_database WHERE datname='{TEST_DB}'"],
+        cwd=ROOT, capture_output=True, text=True,
+    )
+    if check.returncode == 0 and check.stdout.strip() == "1":
+        return
+    _log(f"建测试库 {TEST_DB}…")
+    subprocess.run(
+        ["docker", "compose", "exec", "-T", COMPOSE_SERVICE,
+         "psql", "-U", DB_USER, "-d", APP_DB, "-c",
+         f"CREATE DATABASE {TEST_DB} OWNER {DB_USER}"],
+        cwd=ROOT, check=False,
+    )
+
+
+def ensure(database_url: str | None = None) -> bool:
+    """确保 PG 就绪,返回 True/False。database_url 缺省从 settings 读(尊重 .env)。"""
+    if database_url is None:
+        from app.core.config import settings  # 延迟导入,避免过早固化 settings
+
+        database_url = settings.DATABASE_URL
+
+    if _is_sqlite(database_url):
+        _log("检测到 DATABASE_URL 仍是 SQLite。本地开发/测试已切 PostgreSQL,请改成:")
+        _log(f"  DATABASE_URL={SQLITE_FIX_HINT}")
+        return False
+
+    host, port = _parse_host_port(database_url)
+
+    if _port_open(host, port):
+        _log(f"✅ PostgreSQL 已在 {host}:{port} 运行,跳过 Docker。")
+        return True
+
+    _log(f"{host}:{port} 无 PostgreSQL,准备用 Docker 拉起…")
+
+    if not _docker_cli_ok():
+        _log("未检测到 docker 命令。请先安装 Docker Desktop:")
+        _log("  https://www.docker.com/products/docker-desktop/")
+        return False
+    if not _start_docker_daemon():
+        return False
+    if not _compose_up():
+        return False
+    if not _wait_pg_ready(host, port):
+        return False
+
+    _ensure_test_db()
+    return True
+
+
+if __name__ == "__main__":
+    sys.exit(0 if ensure() else 1)
+```
+
+- [ ] **Step 4: 跑测试确认通过**
+
+Run: `pytest tests/test_ensure_pg.py -v`
+Expected: 11 passed。
+
+- [ ] **Step 5: 手动冒烟(PG 已在跑时应秒过短路)**
+
+Run: `python -m scripts.ensure_pg`
+Expected: 打印 `[ensure_pg] ✅ PostgreSQL 已在 localhost:5432 运行,跳过 Docker。`,退出码 0。
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add scripts/ensure_pg.py tests/test_ensure_pg.py
+git commit -m "feat(dev): scripts/ensure_pg.py 探测/拉起本地 Docker PostgreSQL"
+```
+
+---
+
+## Task 3: `run.sh` / `run.bat` 接入 ensure_pg
+
+**Files:**
+- Modify: `run.sh`(在 `alembic upgrade head` 前插一步)
+- Modify: `run.bat`(同上)
+
+- [ ] **Step 1: 改 `run.sh`**
+
+在 `mkdir -p data` 之后、`"$PY" -m alembic upgrade head` 之前插入:
+
+```bash
+"$PY" -m scripts.ensure_pg   # 确保本地 Docker PostgreSQL 就绪(没起会自动拉起;失败即退出)
+```
+
+(`set -e` 已在文件顶部,ensure_pg 失败会自动终止脚本。)
+
+- [ ] **Step 2: 改 `run.bat`**
+
+在 `if not exist data mkdir data` 之后、`call "%PY%" -m alembic upgrade head` 之前插入:
+
+```bat
+REM 确保本地 Docker PostgreSQL 就绪(没起会自动拉起 Docker + PG 容器)
+call "%PY%" -m scripts.ensure_pg
+if errorlevel 1 (
+    echo [X] ensure_pg failed ^(PostgreSQL 未就绪^)
+    exit /b %errorlevel%
+)
+```
+
+- [ ] **Step 3: 验证 `run.sh`(PG 已在跑,应短路后继续 alembic + uvicorn)**
+
+Run(Git Bash):`bash run.sh 8770`
+Expected: 依次出现 `[ensure_pg] ✅ PostgreSQL 已在 localhost:5432 运行` → alembic 无报错 → uvicorn `Application startup complete`。`Ctrl-C` 停。
+
+- [ ] **Step 4: 验证 `run.bat`(同上,Windows 原生)**
+
+Run(cmd/PowerShell):`.\run.bat 8770`
+Expected: 同 Step 3。`Ctrl-C` 停。
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add run.sh run.bat
+git commit -m "feat(dev): run.sh/run.bat 启动前确保 Docker PostgreSQL 就绪"
+```
+
+---
+
+## Task 4: `.env.example` 默认切 PostgreSQL
+
+**Files:**
+- Modify: `.env.example`(第 8-10 行「数据库」段)
+
+- [ ] **Step 1: 改 `.env.example` 的 DATABASE_URL**
+
+把:
+```ini
+# ===== 数据库 =====
+# SQLite 本地文件路径。生产环境用 /opt/shaguabijia-app-server/data.db
+DATABASE_URL=sqlite:///./data/app.db
+```
+改成:
+```ini
+# ===== 数据库 =====
+# 本地开发/测试统一用 Docker PostgreSQL:run.bat/run.sh 会自动拉起容器
+# (docker-compose.yml + scripts/ensure_pg.py)。详见 docs/database/postgres-migration.md。
+# 生产用原生 PG,由 scripts/init_postgres.py 写入强随机密码的连接串。
+# ⚠️ scheme 必须是 postgresql+psycopg://(psycopg3);不要写成 postgresql://(会去找未装的 psycopg2)。
+DATABASE_URL=postgresql+psycopg://shaguabijia_app:shaguabijia_dev_pw@localhost:5432/shaguabijia
+```
+
+- [ ] **Step 2: 验证(新 .env 从模板复制后能起服务)**
+
+Run: `cp .env.example /tmp/env.check && grep '^DATABASE_URL=' /tmp/env.check`
+Expected: `DATABASE_URL=postgresql+psycopg://shaguabijia_app:shaguabijia_dev_pw@localhost:5432/shaguabijia`
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add .env.example
+git commit -m "feat(dev): .env.example 默认 DATABASE_URL 切 Docker PostgreSQL"
+```
+
+---
+
+## Task 5: `tests/conftest.py` 切 PostgreSQL 测试库
+
+**Files:**
+- Modify: `tests/conftest.py`(整体替换:去掉临时 SQLite,改指 `shaguabijia_test` + 调 ensure_pg + fixture 改 drop/create)
+
+- [ ] **Step 1: 整体替换 `tests/conftest.py`**
+
+```python
+"""测试用 fixtures。
+
+测试库用 Docker PG 的 shaguabijia_test(与 dev 业务库 shaguabijia 隔离)。
+顺序(必须):设 test DATABASE_URL(在 import app.* 之前)→ ensure PG 就绪 →
+import app → 建表。持久卷可能残留上次的表 → session 开头先 drop 再 create。
+"""
+from __future__ import annotations
+
+import os
+from collections.abc import Iterator
+
+# 1) 测试库连接串——必须在 import app.* 之前设好(app.db.session 在 import 期建 engine)
+_TEST_DB_URL = (
+    "postgresql+psycopg://shaguabijia_app:shaguabijia_dev_pw@localhost:5432/shaguabijia_test"
+)
+os.environ["DATABASE_URL"] = _TEST_DB_URL
+os.environ.setdefault("JWT_SECRET_KEY", "test-secret-please-ignore-this-is-only-for-pytest-not-real")
+os.environ.setdefault("ADMIN_JWT_SECRET", "test-admin-secret-please-ignore-only-for-pytest-not-real")
+os.environ.setdefault("JG_APP_KEY", "test-key")
+os.environ.setdefault("JG_MASTER_SECRET", "test-secret")
+os.environ.setdefault("SMS_MOCK", "true")
+os.environ.setdefault("APP_ENV", "dev")
+os.environ.setdefault("APP_DEBUG", "false")  # 测试不打 SQL 日志
+os.environ.setdefault("WECHAT_APP_ID", "wxtest0000000000")
+os.environ.setdefault("WECHAT_APP_SECRET", "test-secret")
+os.environ.setdefault("WXPAY_MCH_ID", "test-mch")
+os.environ.setdefault("WXPAY_MCH_SERIAL_NO", "test-serial")
+os.environ.setdefault("WXPAY_PUBLIC_KEY_ID", "test-pubkey-id")
+os.environ.setdefault("RATE_LIMIT_ENABLED", "false")
+os.environ.setdefault("PANGLE_CALLBACK_ENABLED", "true")
+os.environ.setdefault("PANGLE_REWARD_SECRET", "test-pangle-secret-only-for-pytest")
+
+# 2) 保证 Docker PG 就绪 + 测试库存在(必须在 import app.db.session 建 engine 之前)
+from scripts.ensure_pg import ensure
+
+if not ensure(_TEST_DB_URL):
+    raise RuntimeError(
+        "测试需要 Docker PostgreSQL 就绪。请确认已装 Docker Desktop;"
+        "或先跑一次 run.bat/run.sh 把 PG 拉起,再重试 pytest。"
+    )
+
+import pytest
+from fastapi.testclient import TestClient
+
+from app.db.base import Base
+from app.db.session import engine
+from app.main import app
+
+
+@pytest.fixture(scope="session", autouse=True)
+def _setup_db() -> Iterator[None]:
+    # 持久卷可能残留上次跑崩后的表/数据 → 先 drop 再 create,保证干净起点
+    Base.metadata.drop_all(engine)
+    Base.metadata.create_all(engine)
+    yield
+    Base.metadata.drop_all(engine)
+
+
+@pytest.fixture()
+def client() -> TestClient:
+    return TestClient(app)
+```
+
+- [ ] **Step 2: 验证 conftest 能引导 PG 并收集用例(选一个不涉 DB 的测试文件)**
+
+Run: `pytest tests/test_ensure_pg.py -v`
+Expected: conftest 先打印 `[ensure_pg] ✅ PostgreSQL 已在 localhost:5432 运行`(或拉起过程),随后 12 passed。说明「测试走 PG 引导」链路通、且纯函数测试不受影响。
+
+- [ ] **Step 3: 验证建表落到 PG 测试库(跑一个 DB 相关用例)**
+
+Run: `pytest tests/test_invite.py -v`
+Expected: 用例在 `shaguabijia_test` 上建表并执行(可能有个别红,留待 Task 6);关键是不再出现 SQLite 临时文件、engine 连的是 PG。
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add tests/conftest.py
+git commit -m "test(dev): conftest 切 shaguabijia_test(Docker PG),引导+drop/create"
+```
+
+---
+
+## Task 6: 全量跑 pytest on PG,逐个修红用例
+
+> SQLite 宽松、PG 严格,切库会暴露一批真 bug(迁移指南 §2.2 已列)。本任务是**发现驱动**:先跑全量、按类别归因、按下述配方修,直到全绿。修改范围限被测业务/模型代码,不改测试来掩盖真 bug(除非测试本身依赖 SQLite 特性,如秒级时间精度)。
+
+**Files:**
+- Modify: 视失败而定(常见:`app/models/*.py`、`app/**/repositories/*.py`、少量 `tests/*.py`)
+
+- [ ] **Step 1: 全量跑,拿到失败清单**
+
+Run: `pytest -q`
+Expected: 大部分通过;记录所有 FAIL 的用例名与报错文本,按下面类别归因。
+
+- [ ] **Step 2: 修「naive datetime / 时区」类**
+
+定位:`git grep -n "utcnow()" app/`。把 `datetime.utcnow()` 改成 `datetime.now(timezone.utc)`(并 `from datetime import timezone`)。
+症状:PG `TIMESTAMPTZ` 与 naive datetime 比较/写入报错或结果错位;`tests/test_cps_admin.py` 已注释过 SQLite 忽略 tzinfo 的行为。
+
+例:
+```python
+# 改前
+from datetime import datetime
+ts = datetime.utcnow()
+# 改后
+from datetime import datetime, timezone
+ts = datetime.now(timezone.utc)
+```
+
+- [ ] **Step 3: 修「字符串/整数隐式比较」类**
+
+症状:SQLite 允许 `WHERE phone = 13800138000`(自动转型),PG 直接报类型错。定位报错用例引用的查询,确保比较两侧类型一致(手机号等一律按字符串传参 `:phone`,不要传裸 int)。
+
+- [ ] **Step 3.5: 修「事务已中止」类**
+
+症状:某用例后续报 `current transaction is aborted, commands ignored until end of transaction block`,根因是前一句 SQL 出错后业务代码缺 `db.rollback()`/`db.commit()` 边界。补上正确的 commit/rollback。
+
+- [ ] **Step 4: 修「测试依赖 SQLite 特性」类(仅此类可改测试)**
+
+症状:测试断言依赖 SQLite 秒级时间精度或 FK 不强制(见 `test_invite.py:328`、`test_compare_harvest.py:153` 的注释)。PG 下时间精度更高/FK 更严——调整测试数据(如手动拉开时间间隔、用合法 FK)使断言在 PG 下成立,不改业务逻辑。
+
+- [ ] **Step 5: 反复跑到全绿**
+
+Run: `pytest -q`
+Expected: `N passed`(0 failed)。若仍有红,回到 Step 2-4 继续归因。
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add -A
+git commit -m "fix(db): 测试套件切 PostgreSQL 后修复严格性暴露的用例"
+```
+
+---
+
+## Task 7: 文档更新
+
+**Files:**
+- Modify: `docs/database/postgres-migration.md`(§1 增「本地 Docker 一键起」小节)
+- Modify: `CLAUDE.md`(DB 段注明 dev/test = Docker PG)
+- Modify: `scripts/init_postgres.py`(顶部注释区分生产/本地)
+
+- [ ] **Step 1: `postgres-migration.md` 在「## 1. 本地起 PG」开头插入推荐做法**
+
+在 `## 1. 本地起 PG + 跑通空库(半天)` 标题下、`### 1.1 装 PG` 之前插入:
+
+```markdown
+### 1.0 推荐:Docker 一键起(本地开发/测试)
+
+本地开发不必手动装 PG。已提供 `docker-compose.yml` + `scripts/ensure_pg.py`:
+
+```bash
+cp .env.example .env    # DATABASE_URL 默认已是 Docker PG 连接串
+./run.sh                # 或 run.bat;会自动:探测 PG → 没起则启 Docker → 起 PG 容器 → 建库 → alembic → uvicorn
+pytest                  # conftest 自动引导同一容器的 shaguabijia_test 库
+```
+
+容器:`postgres:16-alpine`(名 `shaguabijia-pg`,端口 5432,命名卷 `pgdata` 持久化),
+首启即建业务库 `shaguabijia` 与测试库 `shaguabijia_test`。下面 1.1-1.5 的手动装 PG 步骤仅在
+不用 Docker 时才需要;生产仍走 §4 的原生 PG。
+```
+
+- [ ] **Step 2: `CLAUDE.md` DB 段补充**
+
+找到 DB 相关行(`**Prod**: PostgreSQL — just change DATABASE_URL...`)所在段,在其上方加一行:
+
+```markdown
+- **Dev/Test**: Docker PostgreSQL 16 — `run.sh`/`run.bat` 经 `scripts/ensure_pg.py` + `docker-compose.yml` 自动拉起;`.env.example` 默认即 PG 连接串;pytest 用同容器的 `shaguabijia_test` 库。**本地不再用 SQLite**。
+```
+
+- [ ] **Step 3: `scripts/init_postgres.py` 顶部注释区分场景**
+
+把模块 docstring 第一行下方(`新机器初始化用。前置:...` 那行)改为:
+
+```python
+新机器初始化用(面向【生产原生 PG】:apt/systemd 装好的 PostgreSQL)。
+本地开发/测试请改用 docker-compose.yml + scripts/ensure_pg.py(run.sh/run.bat 自动拉起),不必跑本脚本。
+前置:已装 PostgreSQL 16 + 知道 postgres 超级用户密码。
+```
+
+- [ ] **Step 4: 验证无坏链接/格式**
+
+Run: `git diff --stat`
+Expected: 三个文档文件有改动,无其他文件被误改。
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add docs/database/postgres-migration.md CLAUDE.md scripts/init_postgres.py
+git commit -m "docs(dev): 记录本地 Docker PostgreSQL 用法,区分生产原生 PG 路径"
+```
+
+---
+
+## 完成标准(对齐 spec §8 验收)
+
+- [ ] 全新机器(装了 Docker Desktop、`.env` 从 `.env.example` 复制)跑 `run.bat`/`run.sh` 全自动拉起 PG 并起服务,无手动装 PG。
+- [ ] `docker ps` 见 `shaguabijia-pg` healthy;`shaguabijia` 与 `shaguabijia_test` 两库都在。
+- [ ] PG 已在跑时再跑 `run`,ensure_pg 秒过短路。
+- [ ] `pytest -q` 全绿(连 `shaguabijia_test`)。
+- [ ] `.env` 改回 sqlite 时,`python -m scripts.ensure_pg` 硬失败并打印正确 PG 串。
+- [ ] 能在 `admin/repositories` 写一段 PG 专有聚合(如 `count(*) FILTER (WHERE ...)`),`run` 手动跑通且相应 pytest 通过。
+
+## Self-Review 记录(计划作者已核)
+
+- **Spec 覆盖:** spec §9 待实现清单 8 项 → Task 1(compose+initdb)、Task 2(ensure_pg)、Task 3(run 接线)、Task 4(.env.example)、Task 5(conftest)、Task 6(修红用例)、Task 7(文档);「session.py 无需改」在 Header 与 spec §4.7 说明;「data/ 忽略」在 Task 1 Step 5 验证。无遗漏。
+- **占位符:** 全部步骤含真实代码/命令/期望输出。Task 6 是发现驱动,已用「类别+具体转换配方+定位命令」代替不可预知的逐条 diff——非占位。
+- **类型/命名一致:** `ensure(database_url=None)` 签名在 Task 2 定义,Task 5 以 `ensure(_TEST_DB_URL)` 调用一致;库名/用户/密码/端口全程为 Header 固定值;compose 服务名 `postgres` 与 ensure_pg `COMPOSE_SERVICE` 一致;`shaguabijia_test` 在 initdb SQL、`_ensure_test_db()`、conftest 三处一致。
@@ -0,0 +1,281 @@
+# 本地开发切 Docker PostgreSQL —— 设计文档
+
+> 让本地开发与测试统一跑在 Docker 化的 PostgreSQL 上,彻底退掉 SQLite。
+> `run.bat` / `run.sh` 启动时自动检测本机 PG,没起就拉起 Docker → 起 PG 容器(镜像缺失先拉),
+> 目的是让开发/大模型能放心用 PG 专有的高效聚合函数,不再为兼容 SQLite 而退化成"取基础数据后内存聚合"。
+>
+> 状态:已定稿(待用户复核)。作者对话日期:2026-07-08。
+> 关联:[postgres-migration.md](../../database/postgres-migration.md)(切引擎完整步骤)、`scripts/init_postgres.py`(生产原生 PG 初始化)。
+> ⚠️ **2026-07-27 增补(见 §10)**:D4 已从「sqlite 硬失败」松为「显式 SQLite 逃生舱」。§1-9 描述的是初版「彻底退掉 SQLite」设计;凡涉及「无 Docker / DATABASE_URL 是 sqlite 时如何处理」,**以 §10 为准**(测试仍只跑 PG 不变)。
+
+---
+
+## 1. 背景与目标
+
+### 问题
+当前开发环境默认用 SQLite(`DATABASE_URL=sqlite:///./data/app.db`),生产用 PostgreSQL 16。两套引擎并存,导致写数据访问代码时(尤其 `app/admin/repositories/` 的报表聚合)为了"两边都能跑",放弃 PG 专有能力(窗口函数、`FILTER`、`JSONB` 操作符、`GROUPING SETS` 等),改成"先查基础数据、再在 Python 内存里聚合"——既慢又啰嗦。
+
+### 目标
+本地开发与测试都跑在 PG 上,SQLite 退出本地开发闭环。之后写 PG 专有 SQL 时:
+- 开发运行时(`run.bat`/`run.sh`)直接连 PG,手动验证可行;
+- `pytest` 也连 PG,PG 专有 SQL 在被测代码路径里也安全,不会因 SQLite 而挂——**这是"双库兼容代码彻底消失"的必要条件**。
+
+### 非目标(本期不做)
+- 不动**生产**部署(生产仍是原生 PG16 + systemd,无 Docker;`init_postgres.py` 保持不变)。
+- 不做数据搬迁(MVP 阶段无真实用户数据,详见迁移指南背景假设)。
+- 不接 CI(仓库当前无 `.github/workflows`;若将来加 CI,再单独让 CI 起 PG service)。
+- 不引入 Redis / testcontainers / 连接池中间件。
+
+---
+
+## 2. 决策记录(本次对话已拍板)
+
+| # | 决策点 | 结论 | 理由 |
+|---|---|---|---|
+| D1 | PG 覆盖范围 | **dev 运行 + 测试都切 PG** | 只切运行时的话,被 SQLite 测试覆盖的代码路径(如 `test_cps_admin.py` 覆盖的 `admin/repositories/cps.py`)仍不能用 PG 专有 SQL,双库代码不会真正消失 |
+| D2 | 打包方式 | **方案 A:Compose + `scripts/ensure_pg.py`** | 唯一真正需要定制的部分(启动 Docker 守护进程、等 PG 就绪)集中到一个跨平台模块,`run.bat`/`run.sh`/`conftest.py` 共用;声明式的容器/卷/健康检查交给 Compose |
+| D3 | 宿主端口 | **5432**(与生产/文档一致) | 边界:若本机已有原生 PG 占 5432,`ensure_pg` 会探测到"PG 已在"直接复用它(可能连到不带业务库的实例)——见 §7 风险,文档提示 |
+| D4 | dev 下 `DATABASE_URL` 仍是 sqlite | **硬失败**(打印一行 fix 后非 0 退出) | 彻底断掉 SQLite 退路,符合"让大家都用 PG"的目标 |
+| D5 | dev 数据库密码 | 固定 `shaguabijia_dev_pw`,写进 compose + `.env.example` | 本地容器仅绑 `localhost`,非机密;保证 `.env.example` 复制即可用。生产密码另由 `init_postgres.py` 强随机生成,不复用 |
+| D6 | 改哪些启动脚本 | `run.bat` 与 `run.sh` **都改** | 仓库一贯保持两者同步 |
+| D7 | 镜像 | `postgres:16-alpine` | 对齐生产 PG16;alpine 体积小 |
+
+---
+
+## 3. 现状(改动前)
+
+- **配置**:`app/core/config.py` `DATABASE_URL` 默认 `sqlite:///./data/app.db`,pydantic-settings 从 `.env` 读(环境变量优先级高于 `.env` 文件)。
+- **引擎**:`app/db/session.py` 用 `_is_sqlite = DATABASE_URL.startswith("sqlite")` 分流——SQLite 加 `check_same_thread=False`、不建池;非 SQLite 加 `pool_size=10/max_overflow=20/pool_recycle=3600`。**已天然支持 PG,无需改。**
+- **迁移**:`alembic/env.py` 从 `settings.DATABASE_URL` 读连接串,`render_as_batch` 仅对 sqlite 开;PG 下自动关。**无 psycopg2 硬编码,切 PG 无需改。**
+- **驱动**:`pyproject.toml` 已装 `psycopg[binary]>=3.1`(psycopg3)。URL scheme 必须 `postgresql+psycopg://`(裸 `postgresql://` 会被 SQLAlchemy 路由到未安装的 psycopg2 → ModuleNotFoundError)。
+- **测试**:`tests/conftest.py` 在 import app 前把 `DATABASE_URL` 设成临时文件 SQLite;session 级 autouse fixture 做 `Base.metadata.create_all(engine)` / 结束 `drop_all`(schema 来自 model 而非 alembic,无逐用例 rollback,全会话共享一个库)。
+- **启动脚本**:`run.bat` / `run.sh` 均为:校验 `.env` 存在 → `mkdir data` → `alembic upgrade head` → uvicorn 监听 `0.0.0.0:8770`(`.sh` 带 `--reload --reload-dir app`)。
+- **现有 PG 资产**:`scripts/init_postgres.py`(交互式:建用户/建库/授权/写 .env/跑迁移,面向**已装好的原生 PG**)、`docs/database/postgres-migration.md`(切引擎完整步骤,含 §2 测试切 PG、§2.2 会暴露的真 bug 清单)。
+- **CI**:无(`.github/workflows` 不存在),故测试切 PG 无 CI 联动负担。
+
+---
+
+## 4. 方案详解
+
+### 4.1 新增 `docker-compose.yml`(app-server 根目录)
+```yaml
+services:
+  postgres:
+    image: postgres:16-alpine
+    container_name: shaguabijia-pg
+    environment:
+      POSTGRES_USER: shaguabijia_app
+      POSTGRES_PASSWORD: shaguabijia_dev_pw
+      POSTGRES_DB: shaguabijia
+    ports:
+      - "5432:5432"
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+      - ./docker/initdb:/docker-entrypoint-initdb.d:ro
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U shaguabijia_app -d shaguabijia"]
+      interval: 3s
+      timeout: 3s
+      retries: 20
+volumes:
+  pgdata:
+```
+- `POSTGRES_USER` 设定后,该用户以超级用户身份创建并拥有 `POSTGRES_DB`,故能再建测试库。
+- 首启 initdb 脚本建测试库(见 4.2)。命名卷 `pgdata` 让数据跨重启留存。
+
+### 4.2 新增 `docker/initdb/01-create-test-db.sql`
+```sql
+-- 仅在 pgdata 卷首次初始化时执行一次。以 shaguabijia_app(超级用户)连 shaguabijia 库运行。
+CREATE DATABASE shaguabijia_test OWNER shaguabijia_app;
+```
+
+### 4.3 新增 `scripts/ensure_pg.py`(纯标准库 + docker CLI,跨平台)
+对外同时暴露**可导入函数** `ensure()`(供 `conftest.py` 直接调)和 **CLI 入口** `if __name__ == "__main__": sys.exit(0 if ensure() else 1)`(供 `run` 以 `python -m scripts.ensure_pg` 跑)。`ensure()` 从 `app.core.config.settings` 读 `DATABASE_URL`,解析 host/port,主流程:
+1. **sqlite 守卫**:若 `DATABASE_URL` 以 `sqlite` 开头 → 打印"dev 已切 PG,请把 .env 的 DATABASE_URL 改成 `postgresql+psycopg://shaguabijia_app:shaguabijia_dev_pw@localhost:5432/shaguabijia`"→ 非 0 退出(D4)。
+2. **TCP 探测** `host:port`(stdlib `socket`,超时 1s)。通 → 打印"✅ PG 已就绪"直接返回(幂等:PG 已在跑时开销≈一次握手)。
+3. 不通 → `docker version` 探 CLI;缺失 → 中文报错"请先安装 Docker Desktop:https://www.docker.com/products/docker-desktop/" → 非 0 退出。
+4. `docker info` 探守护进程;不通 → 按平台启动:
+   - Windows:`start "" "%ProgramFiles%\Docker\Docker\Docker Desktop.exe"`(找不到则报错让用户手动开)
+   - macOS:`open -a Docker`
+   - Linux:不自动 sudo,打印 `sudo systemctl start docker` 让用户执行后重试
+   然后轮询 `docker info` 直到就绪或超时(默认 120s,每 3s 一次,打印进度)。
+5. `docker compose up -d`(Compose 在镜像缺失时**自动拉取**,首用拉 alpine ~90MB;有进度输出)。
+6. 轮询 healthcheck(`docker inspect` 的 health 状态)/ TCP 直到 PG 接受连接(默认 60s 超时)。
+7. **幂等确保测试库存在**(兼容"老 pgdata 卷没跑过 initdb"的情况):
+   `docker compose exec -T postgres psql -U shaguabijia_app -tc "SELECT 1 FROM pg_database WHERE datname='shaguabijia_test'"`,不存在则 `CREATE DATABASE shaguabijia_test OWNER shaguabijia_app`。
+
+失败即清晰中文报错 + 非 0 退出,**全程不回退 SQLite**。所有超时可用环境变量覆盖(如 `ENSURE_PG_DOCKER_TIMEOUT`)。
+
+### 4.4 `run.bat` / `run.sh` 接线
+在 `alembic upgrade head` **之前**插一行调用,失败即退出:
+- `run.sh`:`"$PY" -m scripts.ensure_pg`(`set -e` 已在,失败自动退出)
+- `run.bat`:`call "%PY%" -m scripts.ensure_pg` + `if errorlevel 1 exit /b 1`
+
+其余逻辑不动(`mkdir data` 保留给 media 等落盘目录)。
+
+### 4.5 `.env.example` 默认切 PG
+把
+```ini
+DATABASE_URL=sqlite:///./data/app.db
+```
+改为
+```ini
+# 本地开发/测试统一用 Docker PG(run.bat/run.sh 会自动拉起容器;详见 docs/database/postgres-migration.md §本地 Docker 一键起)。
+# 生产用原生 PG,由 scripts/init_postgres.py 写入强随机密码的连接串。
+DATABASE_URL=postgresql+psycopg://shaguabijia_app:shaguabijia_dev_pw@localhost:5432/shaguabijia
+```
+
+### 4.6 `tests/conftest.py` 切 PG
+调整顶部顺序(仍必须在 `import app.*` 之前完成 env 设定):
+1. 设 `os.environ["DATABASE_URL"] = "postgresql+psycopg://shaguabijia_app:shaguabijia_dev_pw@localhost:5432/shaguabijia_test"`(测试库,永不碰 dev 业务库)。
+2. 调 `scripts.ensure_pg.ensure()`(保证容器在 + 测试库在;PG 已在时几乎零开销)。
+3. `import app...`。
+session 级 autouse fixture:改为 **`Base.metadata.drop_all(engine)` → `create_all(engine)`(开头先清干净,防持久卷里上一次跑残留的表/数据)→ yield → 结束 `drop_all`**;删掉临时 SQLite 文件相关代码。
+
+> 预期:部分用例会因 PG 的严格性变红(SQLite 宽松、PG 严格),按迁移指南 §2.2 逐个修——常见为:字符串/整数隐式比较、`datetime.utcnow()` naive vs `TIMESTAMPTZ`、事务边界(`current transaction is aborted`)。这既是工作量也是本次改造的**直接收益**(暴露真 bug)。实现阶段需为"跑 pytest 并修红用例"单列步骤。
+
+### 4.7 `app/db/session.py`
+**无需改动**——`_is_sqlite` 为假时自动走 PG 池化分支。
+
+### 4.8 文档
+- `docs/database/postgres-migration.md` 增一节「本地 Docker 一键起 PG(推荐)」,指向 compose + `ensure_pg`,并说明它替代了 §1.1 的手动 brew/apt 装 PG。
+- `CLAUDE.md` 的 DB 段注明:dev/test = Docker PG(`run` 自动拉起);prod = 原生 PG(`init_postgres.py`)。
+- `scripts/init_postgres.py` 顶部注释补一句"本脚本面向生产原生 PG;本地开发用 docker-compose + scripts/ensure_pg"。
+
+---
+
+## 5. 连接参数汇总
+
+| 项 | 值 |
+|---|---|
+| 镜像 | `postgres:16-alpine` |
+| 容器名 | `shaguabijia-pg` |
+| 宿主端口 | `5432` |
+| 超级/业务用户 | `shaguabijia_app` |
+| dev 密码 | `shaguabijia_dev_pw`(本地非机密) |
+| 业务库(dev 运行) | `shaguabijia` |
+| 测试库(pytest) | `shaguabijia_test` |
+| dev `DATABASE_URL` | `postgresql+psycopg://shaguabijia_app:shaguabijia_dev_pw@localhost:5432/shaguabijia` |
+| test `DATABASE_URL` | `postgresql+psycopg://shaguabijia_app:shaguabijia_dev_pw@localhost:5432/shaguabijia_test` |
+| 数据持久化 | 命名卷 `pgdata` |
+
+---
+
+## 6. 失败处理矩阵(无 SQLite 兜底)
+
+| 情形 | ensure_pg 行为 |
+|---|---|
+| `DATABASE_URL` 是 sqlite | 打印应改成的 PG 串 → 非 0 退出 |
+| PG 已在跑(TCP 通) | 打印"已就绪" → 返回 0(跳过 docker) |
+| 无 docker CLI | 提示装 Docker Desktop + 官网链接 → 非 0 退出 |
+| docker 守护进程未起 | 尝试按平台启动 Docker Desktop,轮询到就绪;超时则报错 → 非 0 退出 |
+| 镜像缺失 | `docker compose up -d` 自动拉取(不额外处理) |
+| 容器起了但 PG 未 ready | 轮询 healthcheck 到超时;超时报错 → 非 0 退出 |
+| 老 pgdata 卷缺测试库 | 幂等 `CREATE DATABASE shaguabijia_test` |
+
+---
+
+## 7. 风险与边界
+
+- **端口占用(原生 PG 撞 5432)**:D3 选了 5432。若开发机已有原生 PG 监听 5432,step 2 的 TCP 探测会判"PG 已在"并复用它——但那个实例可能没有 `shaguabijia`/`shaguabijia_test` 库或用户,后续 `alembic upgrade head` / 测试会报连不上库或认证失败。**缓解**:文档提示"本机别再单独跑原生 PG";报错信息里提示检查是不是撞了原生 PG。
+- **首次启动慢**:首用需 Docker Desktop 冷启(~30–60s)+ 拉镜像(~数十秒~数分钟,视网络)。`ensure_pg` 全程打印进度,超时可配。
+- **`DATABASE_URL` 环境变量优先级**:pydantic-settings 里 shell 环境变量优先于 `.env`。若开发者 shell 残留旧的 `DATABASE_URL`(如指向 sqlite),会盖过 `.env`。sqlite 守卫(D4)能挡住 sqlite 残留;但若残留的是另一个 PG 串,则以它为准——文档提示。
+- **持久卷脏状态**:测试用 drop_all→create_all 开头清库,避免上次崩溃残留污染;dev 业务库随卷留存(符合预期)。
+- **Docker 未安装/公司网络拉镜像受限**:硬失败并给出明确指引;不提供 SQLite 退路是刻意选择(D4/目标)。
+
+---
+
+## 8. 验收标准
+
+1. 全新机器(装了 Docker Desktop、`.env` 从 `.env.example` 复制)执行 `run.bat`(或 `run.sh`):自动拉起 Docker→起 PG 容器→建库→`alembic upgrade head`→uvicorn 起在 8770,无手动装 PG 步骤。
+2. `docker ps` 见 `shaguabijia-pg` 健康;`psql`/客户端能连 `shaguabijia` 与 `shaguabijia_test` 两个库。
+3. PG 已在跑时再次 `run`,`ensure_pg` 秒过(不重复拉容器)。
+4. `pytest` 连 `shaguabijia_test` 跑;红用例全部修绿(PG 严格性暴露的问题)。
+5. `.env` 的 `DATABASE_URL` 改回 sqlite 时,`run`/`pytest` 硬失败并打印正确的 PG 串。
+6. 能在 `admin/repositories/` 里写一段 PG 专有聚合 SQL(如带 `FILTER (WHERE ...)` 的聚合),`run` 下手动跑通、相应 pytest 也通过——即"双库兼容负担消失"的实证。
+
+---
+
+## 9. 待实现清单(供 writing-plans 拆解)
+
+- [ ] 新增 `docker-compose.yml`
+- [ ] 新增 `docker/initdb/01-create-test-db.sql`
+- [ ] 新增 `scripts/ensure_pg.py`(TCP 探测 / 启 Docker Desktop 轮询 / compose up / 等 healthy / 幂等建测试库 / sqlite 守卫)
+- [ ] `run.sh`、`run.bat` 接入 `ensure_pg`
+- [ ] `.env.example` 的 `DATABASE_URL` 切 PG
+- [ ] `tests/conftest.py` 切 `shaguabijia_test` + 调 `ensure_pg` + fixture 改 drop/create
+- [ ] 跑 `pytest`,按迁移指南 §2.2 修红用例
+- [ ] 文档:`postgres-migration.md` 增「本地 Docker 一键起」节;`CLAUDE.md` DB 段;`init_postgres.py` 注释
+- [ ] `.gitignore` 确认 `data/` 已忽略(compose 用命名卷,不落项目目录,无需额外忽略)
+
+---
+
+## 10. 增补(2026-07-27):D4 反转 —— 显式 SQLite 逃生舱
+
+> 背景:§2 的 D4 定为「dev 下 `DATABASE_URL` 仍是 sqlite → 硬失败」,目的是彻底断掉 SQLite 退路。实践中这对「本机装不了 Docker」的开发者过于刚性——直接被卡死、连跑都跑不起来。本次(2026-07-27 对话)把 D4 从「硬失败」松成「**显式逃生舱**」:工具**从不替你静默切库**,但会在没 Docker 时告诉你怎么手动降级,且降级时每次启动都醒目告警。
+
+### 10.1 决策更新
+
+| # | 原决策 | 新决策 | 理由 |
+|---|---|---|---|
+| D4′ | dev sqlite URL → 硬失败退出 | **放行 + 每次打印醒目降级横幅**(仍非静默) | 已手动改 `.env`=sqlite = 开发者的显式选择,尊重它;但吼一嗓子防止忘了自己在降级、把 PG 专有 SQL 提交上去 |
+| D8(新) | (无) | 无 docker CLI 时,报错里**追加逃生舱指路**(改 `.env`=sqlite),但仍非 0 退出 | 「显式」的关键:工具不替你切库,只指路;开发者改完 `.env` 再跑一次才真正降级 |
+
+**未变**:D1(测试仍只跑 PG)、D2-D3、D5-D7 全部保留。逃生舱**只作用于 `run.sh`/`run.bat` 运行时**;`pytest` 仍写死连 PG 测试库(`conftest.py` 传 PG URL,sqlite 分支根本不触发),没 Docker 就 `raise`、跑不了完整套件——这正是 D1「测试上 PG 才能暴露真 bug」的初衷,刻意不给逃生舱。
+
+### 10.2 代码改动(仅 `scripts/ensure_pg.py` 的 `ensure()`)
+
+1. **sqlite 分支**(原 `return False`)→ 打印多行降级横幅后 `return True`。横幅点明:PG 专有 SQL/严格类型在此模式**不被验证**、提交前须在有 Docker 的机器上用 PG 复跑、装好 Docker 后把 `DATABASE_URL` 改回 PG 串。
+2. **无 docker CLI 分支**(原仅提示装 Docker + `return False`)→ 追加一句「装不了 Docker?把 `.env` 的 `DATABASE_URL` 改成 `sqlite:///./data/app.db` 可降级运行」;**仍 `return False`**(run 脚本照常退出,开发者需显式改 .env 再跑)。
+3. **常量**:新增 `SQLITE_URL = "sqlite:///./data/app.db"`(逃生舱指路用);`SQLITE_FIX_HINT` 重命名 `PG_URL`(降级横幅"改回 PG"引用)。
+4. 更新模块 docstring 中「全程无 SQLite 兜底」一句,改述为「无 Docker/sqlite URL 时【显式】降级 SQLite(带醒目告警),测试侧不降级」。
+
+**其余全不动**:`run.sh`/`run.bat`(sqlite 下 `ensure` 返 True → 照常 `alembic upgrade head` + uvicorn)、`docker-compose.yml`、`app/db/session.py`(SQLite 引擎分支本就保留为 fallback)、`tests/conftest.py`、`.env.example`(默认仍 PG)。
+
+### 10.3 改完后行为矩阵(覆盖用户列的 5 场景)
+
+| 场景 | `DATABASE_URL` | ensure_pg 行为 |
+|---|---|---|
+| ① 无 Docker | PG(默认) | 报错 + 指逃生舱 → 退出;开发者改 `.env`=sqlite → 再跑 → **放行 + 降级横幅**,alembic/uvicorn 跑 SQLite |
+| ② 有 Docker 未启动 | PG | 启 Docker Desktop → `compose up` → 等 ready → 建测试库(**不变**) |
+| ③ 有 Docker 已启动 | PG | `compose up` → 等 ready(**不变**) |
+| ④ PG 已在跑 | PG | TCP 通 → 秒过跳过 Docker(**不变**) |
+| ⑤ PG 起来后 | 任意 | run 脚本 `alembic upgrade head`(**不变**;SQLite 走 `render_as_batch`) |
+
+### 10.4 风险
+
+- **降级被忽视**:横幅仅在 `run` 启动时打印一次;若开发者用 IDE 直接起 uvicorn(绕过 run 脚本)则看不到。缓解:横幅足够醒目 + 文档强调;**不**引入 app 启动期重复告警(YAGNI)。
+- **测试无 Docker 跑不了**:刻意保留(D1)。文档提示无 Docker 者:要么装 Docker 跑全量测试,要么只在 CI/有 Docker 的机器上验证 PG 相关改动。
+
+### 10.5 Redis 前瞻(不在本次)
+
+§2 未涉及 Redis。②③ 场景未来若加 Redis 实例:在 `docker-compose.yml` 增 `redis` 服务即可,`docker compose up -d` 天然带起;仅当启动期有组件依赖 Redis 才需给 `ensure_pg` 加 redis readiness 探测。本次不做,方案对它友好。
+
+### 10.6 附带修复:`_docker_cli_ok` 守护进程误判(2026-07-27)
+
+诊断「装了 Docker Desktop 却报未检测到 docker」时发现的真 bug:`_docker_cli_ok()` 原用 `docker version`
+判断 CLI 是否存在,但该命令**要连 daemon**,守护进程没起时退非零 → 把「Docker 装了但没启动」
+误判成「没装 CLI」,`ensure()` 直接打印"请安装 Docker Desktop"并 `return False`,**绕过了专为需求②
+写的 `_start_docker_daemon()` 自动拉起逻辑**——需求②(有 Docker 未启动 → 自动启动)因此从未真正生效。
+修复:改用 `docker --version`(纯客户端、不连 daemon、退 0)。`_docker_daemon_ok()` 仍用 `docker info`
+(正确,该检查本就依赖 daemon)。实测机器:Docker Desktop 20.10.12 已装但引擎未起,修复前 `_docker_cli_ok()`
+误报 False,修复后 True。
+
+### 10.7 附带修复:固定 compose 项目名 + 清理残留同名容器(2026-07-27)
+
+诊断「`docker compose up` 报 `container name "/shaguabijia-pg" already in use`」时发现的又一 bug:compose
+项目名默认取运行目录 basename,在不同目录/worktree(如 `local-dev-postgres-docker` vs `shaguabijia-app-server`)
+之间切换会各自成一个项目;而 `docker-compose.yml` 写死了 `container_name: shaguabijia-pg`(全局唯一名),
+于是新项目 `up` 时要创建同名容器 → 撞上旧项目留下的那个 → 冲突。副作用:`pgdata` 卷也按项目名分裂
+成 `local-dev-postgres-docker_pgdata` / `shaguabijia-app-server_pgdata`,数据被切成两半。
+
+修复(均在 `scripts/ensure_pg.py`,`docker-compose.yml` 不动、容器名仍是 `shaguabijia-pg`):
+1. 模块级 `os.environ.setdefault("COMPOSE_PROJECT_NAME", "shaguabijia")` —— 钉死项目名,无论从哪个
+   目录/worktree 跑都是同一个项目、同一个卷 `shaguabijia_pgdata`,所有 `docker compose up/exec` 一致。
+2. `_compose_up()` 前置 `_remove_stale_container()`:若存在「同名但不属于本项目」的残留容器,先 `docker rm -f`
+   再 up(靠 `docker ps --filter name/label` 判归属;数据在命名卷里,删容器不丢)。旧目录/worktree 留下的
+   残留容器就此自动清掉,不需手动干预。
+
+影响:本次修复后首跑,旧的 `shaguabijia-pg`(属项目 `local-dev-postgres-docker`)会被自动删除、在项目
+`shaguabijia` 下重建,挂载全新的 `shaguabijia_pgdata`(空库,`alembic upgrade head` 重建表)。旧数据仍留在
+`local-dev-postgres-docker_pgdata` 卷里(未删,可恢复);确认不需要后可 `docker volume rm` 清理两个旧卷。
@@ -37,6 +37,9 @@ dependencies = [

    # 邀请指纹归因:解析浏览器 UA 拿手机型号(Build.MODEL),跨端匹配用
    "user-agents>=2.2.0",
+
+    # 离线经纬度→城市反查(美团 CPS 按城市过滤);会带入 numpy/scipy 依赖
+    "reverse_geocoder>=1.5.1",
 ]

 [project.optional-dependencies]
@@ -50,6 +53,10 @@ dev = [
 [tool.setuptools.packages.find]
 include = ["app*"]

+# 随包分发的运行时数据文件(美团城市词典;被 app/utils/meituan_city.py 加载)
+[tool.setuptools.package-data]
+"app.utils" = ["data/*.txt"]
+
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
 testpaths = ["tests"]
@@ -30,7 +30,14 @@ if not exist .env (

 if not exist data mkdir data

-REM Build/upgrade SQLite schema (idempotent; no-op if already at head)
+REM Ensure local Docker PostgreSQL is up (auto-starts Docker + PG container if needed)
+call "%PY%" -m scripts.ensure_pg
+if errorlevel 1 (
+    echo [X] ensure_pg failed ^(PostgreSQL not ready^)
+    exit /b %errorlevel%
+)
+
+REM Build/upgrade schema (idempotent; no-op if already at head)
 call "%PY%" -m alembic upgrade head
 if errorlevel 1 (
    echo [X] alembic upgrade head failed
@@ -18,7 +18,8 @@ if [ ! -f .env ]; then
  exit 1
 fi

-mkdir -p data            # sqlite 文件所在目录
+mkdir -p data            # 运行期落盘目录(媒体上传等)
+"$PY" -m scripts.ensure_pg      # 确保本地 Docker PostgreSQL 就绪(没起会自动拉起;失败即退出)
 "$PY" -m alembic upgrade head   # 确保表已建（幂等，已是最新则 no-op）

 # --reload 只盯源码目录 app/:别去监视 logs/(日志写入触发"检测→再写日志"回环)和
@@ -0,0 +1,50 @@
+@echo off
+REM Admin backend startup (Windows) - the :8771 peer of run.bat.
+REM
+REM Usage:
+REM   cd shaguabijia-app-server
+REM   run8771.bat
+REM
+REM Runs the ADMIN FastAPI app (app.admin.main:admin_app) on 127.0.0.1:8771 —
+REM a SEPARATE process from run.bat (which runs app.main:app on 8770). The admin
+REM web frontend (Next.js :3001) points at http://localhost:8771. Auto-reload on
+REM code change.
+REM
+REM Prerequisite (first time):
+REM   conda activate pricebot ^&^& pip install -e .
+REM   copy .env.example .env  ^&^& fill JWT_SECRET_KEY
+REM
+REM Tip: shaguabijia-admin-web\start.bat starts user-api(8770) + admin-api(8771)
+REM + frontend(3001) in one go, if you prefer a single command.
+
+cd /d "%~dp0"
+
+REM Prefer the project virtualenv (.venv) so we never inherit a wrong
+REM global/conda interpreter. FastAPI<0.115 on Pydantic 2.12 crashes at import
+REM with "'FieldInfo' object has no attribute 'in_'". Falls back to PATH python.
+set "PY=python"
+if exist "%~dp0.venv\Scripts\python.exe" set "PY=%~dp0.venv\Scripts\python.exe"
+
+if not exist .env (
+    echo [X] Missing .env. Run: copy .env.example .env  and fill JWT_SECRET_KEY ^(plus MT_CPS_* if you test Meituan^)
+    exit /b 1
+)
+
+if not exist data mkdir data
+
+REM Ensure local Docker PostgreSQL is up (auto-starts Docker + PG container if needed)
+call "%PY%" -m scripts.ensure_pg
+if errorlevel 1 (
+    echo [X] ensure_pg failed ^(PostgreSQL not ready^)
+    exit /b %errorlevel%
+)
+
+REM Build/upgrade schema (idempotent; no-op if already at head)
+call "%PY%" -m alembic upgrade head
+if errorlevel 1 (
+    echo [X] alembic upgrade head failed
+    exit /b %errorlevel%
+)
+
+REM Long-running foreground process. Ctrl+C to stop.
+"%PY%" -m uvicorn app.admin.main:admin_app --host 127.0.0.1 --port 8771 --reload
@@ -0,0 +1,317 @@
+"""确保本地 PostgreSQL 就绪(开发/测试统一用 Docker PG)。
+
+被三处复用:
+  - run.sh / run.bat:`python -m scripts.ensure_pg`(CLI,失败退非 0)
+  - tests/conftest.py:`from scripts.ensure_pg import ensure; ensure(test_url)`
+
+流程:读 DATABASE_URL → TCP 探测 → 没起就(必要时启 Docker Desktop)→
+`docker compose up -d` → 等 PG ready → 幂等确保测试库存在。
+
+运行时(run.sh/run.bat)支持【显式】SQLite 逃生舱:DATABASE_URL 设为 sqlite → 放行并打印
+醒目降级横幅(绝不静默替你切库);无 docker CLI 时报错里也指路该逃生舱。测试侧
+(conftest 传 PG URL)不降级——sqlite 分支不触发,没 PG 直接 raise。详见设计文档 §10。
+
+生产用原生 PG(scripts/init_postgres.py),不走本模块。
+"""
+from __future__ import annotations
+
+import os
+import socket
+import subprocess
+import sys
+import time
+from pathlib import Path
+from urllib.parse import urlsplit
+
+ROOT = Path(__file__).resolve().parent.parent
+
+# 日志里可能含 emoji(如 ✅);Windows GBK 控制台(cmd.exe)无法编码会抛 UnicodeEncodeError → 脚本崩、
+# run.bat 误判 ensure_pg 失败。用 backslashreplace 保底:中文仍正常,仅不可编码字符被转义,不崩。
+for _stream in (sys.stdout, sys.stderr):
+    try:
+        _stream.reconfigure(errors="backslashreplace")
+    except (AttributeError, ValueError):
+        pass
+
+APP_DB = "shaguabijia"
+TEST_DB = "shaguabijia_test"
+DB_USER = "shaguabijia_app"
+COMPOSE_SERVICE = "postgres"
+CONTAINER_NAME = "shaguabijia-pg"  # 必须与 docker-compose.yml 的 container_name 一致
+
+# 钉死 compose 项目名:否则它默认取运行目录 basename,在不同目录/worktree 之间切会各自
+# 成一个项目 → 同一个固定 container_name 撞名报错、pgdata 卷还会按项目名分裂成多份。
+# 钉成 app 名后,无论从哪个目录/worktree 跑都是同一个项目、同一个卷。setdefault:尊重外部覆盖。
+os.environ.setdefault("COMPOSE_PROJECT_NAME", "shaguabijia")
+
+DOCKER_START_TIMEOUT = int(os.environ.get("ENSURE_PG_DOCKER_TIMEOUT", "120"))
+PG_READY_TIMEOUT = int(os.environ.get("ENSURE_PG_READY_TIMEOUT", "60"))
+# 单条 docker 探测/exec 命令的超时:防 Docker 守护进程半死(尤其 Windows 冷启)时
+# docker info / exec 无限挂起、绕过上面的总超时。
+DOCKER_CMD_TIMEOUT = int(os.environ.get("ENSURE_PG_CMD_TIMEOUT", "15"))
+POLL_INTERVAL = 3.0
+
+PG_URL = (
+    "postgresql+psycopg://shaguabijia_app:shaguabijia_dev_pw@localhost:5432/shaguabijia"
+)
+SQLITE_URL = "sqlite:///./data/app.db"  # 无 Docker 时的显式降级逃生舱(仅 run 运行时)
+
+
+def _log(msg: str) -> None:
+    print(f"[ensure_pg] {msg}", flush=True)
+
+
+def _is_sqlite(url: str) -> bool:
+    return url.strip().lower().startswith("sqlite")
+
+
+def _parse_host_port(url: str) -> tuple[str, int]:
+    """从 SQLAlchemy URL 取 host/port,缺省 localhost:5432。"""
+    parts = urlsplit(url)
+    return (parts.hostname or "localhost"), (parts.port or 5432)
+
+
+def _port_open(host: str, port: int, timeout: float = 1.0) -> bool:
+    try:
+        with socket.create_connection((host, port), timeout=timeout):
+            return True
+    except OSError:
+        return False
+
+
+def _docker_desktop_cmd(platform: str, program_files: str) -> list[str] | None:
+    """按平台给出启动 Docker Desktop 的命令;Linux 返回 None(daemon 需 sudo,让用户手动)。"""
+    if platform.startswith("win"):
+        return [str(Path(program_files) / "Docker" / "Docker" / "Docker Desktop.exe")]
+    if platform == "darwin":
+        return ["open", "-a", "Docker"]
+    return None
+
+
+def _docker_ok(subcmd: str) -> bool:
+    """`docker --version`(CLI 在不在,纯客户端)/`docker info`(daemon 起没起)成功与否。"""
+    try:
+        subprocess.run(
+            ["docker", subcmd],
+            cwd=ROOT,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            check=True,
+            timeout=DOCKER_CMD_TIMEOUT,
+        )
+        return True
+    except (OSError, subprocess.CalledProcessError, subprocess.TimeoutExpired):
+        return False
+
+
+def _docker_cli_ok() -> bool:
+    # 必须用 `docker --version`(纯客户端,不连 daemon)而非 `docker version`
+    # (后者要连 daemon,守护进程没起时退非零)——否则「装了 Docker 但没启动」
+    # 会被误判成「没装 CLI」,直接绕过下面 _start_docker_daemon() 的自动拉起(需求②)。
+    return _docker_ok("--version")
+
+
+def _docker_daemon_ok() -> bool:
+    return _docker_ok("info")
+
+
+def _start_docker_daemon() -> bool:
+    """守护进程没起时按平台拉起,轮询到就绪。返回是否成功。"""
+    if _docker_daemon_ok():
+        return True
+    cmd = _docker_desktop_cmd(
+        sys.platform, os.environ.get("ProgramFiles", r"C:\Program Files")
+    )
+    if cmd is None:
+        _log("Docker 守护进程未运行。Linux 请手动:sudo systemctl start docker,然后重试。")
+        return False
+    if sys.platform.startswith("win") and not Path(cmd[0]).exists():
+        _log(f"找不到 Docker Desktop:{cmd[0]}。请手动启动 Docker Desktop 后重试。")
+        return False
+    _log("启动 Docker Desktop(首次冷启可能 30-60s)…")
+    try:
+        subprocess.Popen(cmd, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+    except OSError as e:
+        _log(f"启动 Docker Desktop 失败:{e}")
+        return False
+    deadline = time.monotonic() + DOCKER_START_TIMEOUT
+    while time.monotonic() < deadline:
+        if _docker_daemon_ok():
+            _log("Docker 守护进程已就绪。")
+            return True
+        _log("等待 Docker 守护进程…")
+        time.sleep(POLL_INTERVAL)
+    _log(f"等待 Docker 守护进程超时({DOCKER_START_TIMEOUT}s)。")
+    return False
+
+
+def _ps_names(*filters: str) -> str:
+    """docker ps -a 按 filter 查容器名(每行一个);失败返回空串。"""
+    args = ["docker", "ps", "-a", "--format", "{{.Names}}"]
+    for f in filters:
+        args += ["--filter", f]
+    try:
+        r = subprocess.run(
+            args, cwd=ROOT, capture_output=True, text=True, timeout=DOCKER_CMD_TIMEOUT,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return ""
+    return r.stdout if r.returncode == 0 else ""
+
+
+def _remove_stale_container() -> None:
+    """删掉「同名但不属于本 compose 项目」的残留容器(旧目录/worktree 建的)。
+
+    固定的 container_name 是全局唯一名:若旧项目留下一个同名容器,`docker compose up`
+    会因撞名报 "container name already in use" 而失败。这里在 up 之前主动清掉它。
+    数据在命名卷(<project>_pgdata)里,删容器不删卷、不丢数据。
+    """
+    project = os.environ.get("COMPOSE_PROJECT_NAME", "")
+    name_filter = f"name=^{CONTAINER_NAME}$"
+    if CONTAINER_NAME not in _ps_names(name_filter).split():
+        return  # 没有同名容器
+    ours = _ps_names(name_filter, f"label=com.docker.compose.project={project}")
+    if CONTAINER_NAME in ours.split():
+        return  # 就是本项目的容器,compose 会自己 start/复用,别删
+    _log(f"发现残留同名容器 {CONTAINER_NAME}(非本项目 '{project}'),删除以避免撞名"
+         f"(数据在卷里,不丢)…")
+    try:
+        subprocess.run(
+            ["docker", "rm", "-f", CONTAINER_NAME], cwd=ROOT,
+            stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=DOCKER_CMD_TIMEOUT,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        _log(f"⚠️ 删除残留容器失败,可手动: docker rm -f {CONTAINER_NAME}")
+
+
+def _compose_up() -> bool:
+    _remove_stale_container()
+    _log("docker compose up -d(镜像缺失会自动拉取,首用约几十秒)…")
+    try:
+        subprocess.run(["docker", "compose", "up", "-d"], cwd=ROOT, check=True)
+        return True
+    except (OSError, subprocess.CalledProcessError) as e:
+        _log(f"docker compose up 失败:{e}")
+        return False
+
+
+def _pg_isready() -> bool:
+    try:
+        r = subprocess.run(
+            ["docker", "compose", "exec", "-T", COMPOSE_SERVICE,
+             "pg_isready", "-U", DB_USER, "-d", APP_DB],
+            cwd=ROOT, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+            timeout=DOCKER_CMD_TIMEOUT,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return False
+    return r.returncode == 0
+
+
+def _wait_pg_ready(host: str, port: int) -> bool:
+    deadline = time.monotonic() + PG_READY_TIMEOUT
+    while time.monotonic() < deadline:
+        if _port_open(host, port) and _pg_isready():
+            _log("PostgreSQL 已就绪。")
+            return True
+        _log("等待 PostgreSQL 就绪…")
+        time.sleep(POLL_INTERVAL)
+    _log(f"等待 PostgreSQL 就绪超时({PG_READY_TIMEOUT}s)。")
+    return False
+
+
+def _test_db_exists() -> bool:
+    """测试库是否已存在(连业务库 shaguabijia 查 pg_database)。"""
+    try:
+        r = subprocess.run(
+            ["docker", "compose", "exec", "-T", COMPOSE_SERVICE,
+             "psql", "-U", DB_USER, "-d", APP_DB, "-tAc",
+             f"SELECT 1 FROM pg_database WHERE datname='{TEST_DB}'"],
+            cwd=ROOT, capture_output=True, text=True, timeout=DOCKER_CMD_TIMEOUT,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return False
+    return r.returncode == 0 and r.stdout.strip() == "1"
+
+
+def ensure_test_db() -> bool:
+    """幂等建测试库(兼容老 pgdata 卷首启没跑 initdb 的情况)。返回测试库是否就绪。
+
+    公开给 conftest 单独调用:ensure() 在「端口已通」时会短路返回、不建测试库,
+    所以测试侧需在 ensure() 之后再显式补一刀(best-effort)。
+    """
+    if _test_db_exists():
+        return True
+    _log(f"建测试库 {TEST_DB}…")
+    try:
+        create = subprocess.run(
+            ["docker", "compose", "exec", "-T", COMPOSE_SERVICE,
+             "psql", "-U", DB_USER, "-d", APP_DB, "-c",
+             f"CREATE DATABASE {TEST_DB} OWNER {DB_USER}"],
+            cwd=ROOT, capture_output=True, text=True, timeout=DOCKER_CMD_TIMEOUT,
+        )
+    except (OSError, subprocess.TimeoutExpired) as e:
+        _log(f"⚠️ 建测试库 {TEST_DB} 失败:{e}")
+        return False
+    # returncode==0=建成功;非 0 但库已存在=与并发创建者竞争失败(42P04),仍算就绪
+    if create.returncode == 0 or _test_db_exists():
+        return True
+    _log(f"⚠️ 建测试库 {TEST_DB} 失败:{(create.stderr or '').strip()}")
+    return False
+
+
+def _warn_sqlite_degraded() -> None:
+    """DATABASE_URL 是 SQLite 时打印醒目降级横幅(显式逃生舱,非静默切库)。"""
+    for line in (
+        "⚠️ ================= 降级模式(SQLite) =================",
+        "⚠️  DATABASE_URL 是 SQLite,不是 PostgreSQL。",
+        "⚠️  PG 专有 SQL(窗口函数/FILTER/JSONB)与严格类型在此模式【不被验证】。",
+        "⚠️  提交前请在装了 Docker 的机器上用 PG 复跑;装好后把 DATABASE_URL 改回:",
+        f"⚠️    {PG_URL}",
+        "⚠️ ===================================================",
+    ):
+        _log(line)
+
+
+def ensure(database_url: str | None = None) -> bool:
+    """确保 PG 就绪,返回 True/False。database_url 缺省从 settings 读(尊重 .env)。
+
+    运行时若 DATABASE_URL 是 SQLite → 打印降级横幅并返回 True(显式逃生舱);
+    conftest 传的是 PG URL,故测试侧永不走此分支。
+    """
+    if database_url is None:
+        from app.core.config import settings  # 延迟导入,避免过早固化 settings
+
+        database_url = settings.DATABASE_URL
+
+    if _is_sqlite(database_url):
+        _warn_sqlite_degraded()
+        return True
+
+    host, port = _parse_host_port(database_url)
+
+    if _port_open(host, port):
+        _log(f"✅ PostgreSQL 已在 {host}:{port} 运行,跳过 Docker。")
+        return True
+
+    _log(f"{host}:{port} 无 PostgreSQL,准备用 Docker 拉起…")
+
+    if not _docker_cli_ok():
+        _log("未检测到 docker 命令。请先安装 Docker Desktop:")
+        _log("  https://www.docker.com/products/docker-desktop/")
+        _log(f"装不了 Docker?把 .env 的 DATABASE_URL 改成  {SQLITE_URL}  可降级用 SQLite 跑")
+        _log("  (PG 专有 SQL/严格性不被验证,仅救急);改完重跑 run.sh/run.bat。")
+        return False
+    if not _start_docker_daemon():
+        return False
+    if not _compose_up():
+        return False
+    if not _wait_pg_ready(host, port):
+        return False
+    if not ensure_test_db():
+        return False
+    return True
+
+
+if __name__ == "__main__":
+    sys.exit(0 if ensure() else 1)
@@ -1,6 +1,8 @@
 """Bootstrap PostgreSQL: 建用户 + 建库 + 授权 + 写 .env + 跑迁移。

-新机器初始化用。前置:已装 PostgreSQL 16 + 知道 postgres 超级用户密码。
+新机器初始化用(面向【生产原生 PG】:apt/systemd 装好的 PostgreSQL)。
+本地开发/测试请改用 docker-compose.yml + scripts/ensure_pg.py(run.sh/run.bat 自动拉起),不必跑本脚本。
+前置:已装 PostgreSQL 16 + 知道 postgres 超级用户密码。

 用法:
    python scripts/init_postgres.py
@@ -0,0 +1,170 @@
+"""把 meituan_coupon 的线上采样 TSV 灌进本地 SQLite。
+
+用途:本地开发/调试时,把线上 `meituan_coupon` 表的采样数据(tests/meituan_coupon_data.tsv)
+灌进 dev 库(默认 `./data/app.db`),免得每次都实时打美团接口。
+
+TSV 说明:
+  - 制表符分隔,每行一条记录,列顺序与线上 PostgreSQL 物理列一致
+    (image_size / image_type 是后加的迁移,排在最后两列 —— 与本地 SQLite 一致)。
+  - 空字段 = NULL(文件里没有 `\\N` 标记)。
+  - 个别记录的文本/JSON 字段内含换行,会把一条逻辑行拆成多物理行 —— 按“累计到 26 列”重组。
+  - 文件尾部可能有一条被导出截断的残行(列数不足 / raw JSON 不完整),直接跳过。
+
+datetime 三列(first_seen/last_seen/updated_at)去掉尾部时区偏移(`+08`),
+存成 SQLAlchemy 在 SQLite 上用的朴素格式 `YYYY-MM-DD HH:MM:SS.ffffff`,保证 ORM 能读回。
+
+用法:
+    python scripts/load_meituan_coupon_tsv.py                     # 默认 TSV + .env 里的库
+    python scripts/load_meituan_coupon_tsv.py path/to.tsv         # 指定 TSV
+    DATABASE_URL=sqlite:///./data/app.db python scripts/load_meituan_coupon_tsv.py
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import sqlite3
+import sys
+from pathlib import Path
+
+_PROJECT_ROOT = Path(__file__).resolve().parent.parent
+
+# 列顺序 = TSV 字段顺序 = 本地 SQLite 物理列顺序
+COLS = [
+    "id", "source", "platform", "biz_line", "city_id", "product_view_sign",
+    "sku_view_id", "name", "brand_name", "sell_price_cents", "original_price_cents",
+    "head_url", "sale_volume", "sale_volume_num", "commission_percent",
+    "commission_amount_cents", "poi_name", "available_poi_num", "delivery_distance_m",
+    "dedup_key", "raw", "first_seen", "last_seen", "updated_at", "image_size", "image_type",
+]
+NCOL = len(COLS)
+
+# 按列做类型转换(空串 -> None)。未列出的列 = 原样字符串(source/city_id/... 等 NOT NULL 文本)。
+_INT_COLS = {0, 2, 3, 9, 10, 13, 15, 17, 24}           # id, platform, biz_line, prices, ...
+_FLOAT_COLS = {14, 18}                                  # commission_percent, delivery_distance_m
+_NULLABLE_STR_COLS = {6, 7, 8, 11, 12, 16, 25}          # sku_view_id, name, brand_name, ...
+_DT_COLS = {21, 22, 23}                                 # first_seen, last_seen, updated_at
+_RAW_COL = 20
+
+_TZ_SUFFIX = re.compile(r"[+-]\d{2}(:?\d{2})?$")        # 尾部时区偏移 +08 / +08:00 / +0800
+
+
+def _resolve_sqlite_path() -> Path:
+    """从 DATABASE_URL(env 或 .env)解析出 SQLite 文件路径。只支持 sqlite://。"""
+    url = os.environ.get("DATABASE_URL", "")
+    if not url:
+        env = _PROJECT_ROOT / ".env"
+        if env.exists():
+            for line in env.read_text(encoding="utf-8").splitlines():
+                if line.strip().startswith("DATABASE_URL="):
+                    url = line.split("=", 1)[1].strip()
+                    break
+    if not url:
+        url = "sqlite:///./data/app.db"
+    if not url.startswith("sqlite:"):
+        sys.exit(f"仅支持 sqlite:// 库,当前 DATABASE_URL={url!r}")
+    rest = url.split("sqlite:///", 1)[1] if "sqlite:///" in url else url.split("sqlite://", 1)[1]
+    p = Path(rest)
+    if not p.is_absolute():
+        p = (_PROJECT_ROOT / rest).resolve()
+    return p
+
+
+def _reconstruct_rows(text: str) -> tuple[list[list[str]], int]:
+    """把文件文本重组成一条条 26 列的逻辑行。返回 (rows, skipped)。
+
+    单个字段内含换行 -> 一条逻辑行被拆成多物理行:累计字段,拆点用 \\n 重新拼回,
+    直到凑满 26 列。列数溢出(内嵌 TAB / 错位)或文件尾残行 -> 跳过并计数。
+    """
+    lines = text.split("\n")
+    while lines and lines[-1] == "":
+        lines.pop()
+    rows: list[list[str]] = []
+    skipped = 0
+    buf: list[str] = []
+    for raw_line in lines:
+        parts = raw_line.split("\t")
+        if not buf:
+            buf = parts
+        else:
+            buf[-1] += "\n" + parts[0]       # 拼回被换行拆开的字段
+            buf.extend(parts[1:])
+        if len(buf) == NCOL:
+            rows.append(buf)
+            buf = []
+        elif len(buf) > NCOL:                # 溢出:数据异常,丢弃这段重新开始
+            print(f"  [skip] 列数溢出({len(buf)}>{NCOL}),field0={buf[0][:20]!r}")
+            skipped += 1
+            buf = []
+    if buf:                                  # 文件尾被截断的残行
+        print(f"  [skip] 尾部残行不足 {NCOL} 列(实 {len(buf)} 列),field0={buf[0][:20]!r}")
+        skipped += 1
+    return rows, skipped
+
+
+def _convert(row: list[str]) -> tuple | None:
+    """按列类型转换一行;非法(必填 int 为空 / raw 非 JSON)返回 None。"""
+    out: list = []
+    for i, v in enumerate(row):
+        if i in _DT_COLS:
+            out.append(_TZ_SUFFIX.sub("", v))
+            continue
+        if i == _RAW_COL:
+            try:
+                json.loads(v)
+            except Exception as e:
+                print(f"  [skip] id={row[0]} raw 非法 JSON: {e}")
+                return None
+            out.append(v)
+            continue
+        if i in _INT_COLS:
+            out.append(int(v) if v != "" else None)
+        elif i in _FLOAT_COLS:
+            out.append(float(v) if v != "" else None)
+        elif i in _NULLABLE_STR_COLS:
+            out.append(v if v != "" else None)
+        else:                                # 必填文本列,原样
+            out.append(v)
+    return tuple(out)
+
+
+def main() -> None:
+    tsv = Path(sys.argv[1]) if len(sys.argv) > 1 else _PROJECT_ROOT / "tests" / "meituan_coupon_data.tsv"
+    if not tsv.is_absolute():
+        tsv = (_PROJECT_ROOT / tsv).resolve()
+    db = _resolve_sqlite_path()
+    print(f"TSV: {tsv}")
+    print(f"DB : {db}")
+    if not tsv.exists():
+        sys.exit(f"TSV 不存在: {tsv}")
+    if not db.exists():
+        sys.exit(f"SQLite 库不存在: {db}(先跑 alembic upgrade head 建表)")
+
+    rows, skipped = _reconstruct_rows(tsv.read_text(encoding="utf-8"))
+    print(f"重组逻辑行: {len(rows)}  跳过(残/异常): {skipped}")
+
+    records = []
+    bad = 0
+    for r in rows:
+        rec = _convert(r)
+        if rec is None:
+            bad += 1
+            continue
+        records.append(rec)
+    print(f"可入库: {len(records)}  转换失败: {bad}")
+
+    placeholders = ",".join(["?"] * NCOL)
+    sql = f"INSERT OR REPLACE INTO meituan_coupon ({','.join(COLS)}) VALUES ({placeholders})"
+    con = sqlite3.connect(str(db))
+    try:
+        before = con.execute("SELECT count(*) FROM meituan_coupon").fetchone()[0]
+        con.executemany(sql, records)
+        con.commit()
+        after = con.execute("SELECT count(*) FROM meituan_coupon").fetchone()[0]
+    finally:
+        con.close()
+    print(f"入库前 {before} 行 -> 入库后 {after} 行(本次 {len(records)} 条)")
+
+
+if __name__ == "__main__":
+    main()
@@ -0,0 +1,189 @@
+"""给指定用户灌一批 mock 比价记录(开发 / 真机走查用)。
+
+为什么:首页「上次比价」横幅(4 分钟新鲜窗口)、比价记录页、「我的」省钱战绩卡都读
+`comparison_record`。dev 库里这个用户没数据时这些 UI 是空的,本脚本灌一批真实感的外卖
+比价记录,方便端上走查。
+
+用法(项目根、已 pip install -e . 的环境):
+  python scripts/mock_compare_records.py                      # 默认 user 昵称后缀 DlSKoc5S7, 10 条
+  python scripts/mock_compare_records.py --user DlSKoc5S7     # 按 昵称后缀/用户名/邀请码/手机号
+  python scripts/mock_compare_records.py --user 5             # 直接按 user.id
+  python scripts/mock_compare_records.py --user 5 --count 6
+
+要点:
+  - 幂等:trace_id 固定为 mock-<标识>-NN,重跑覆盖同号记录(不会越灌越多)。
+  - 第 1 条 created_at = 跑脚本当下(4 分钟内),其余铺在近 7 天;重跑会刷新时间戳
+    (所以重跑一次即可让「上次比价」横幅重新进入 4 分钟窗口)。
+  - best_* / saved / status 由真实的 repositories.comparison.upsert_record 从 comparison_results 派生。
+"""
+from __future__ import annotations
+
+import argparse
+from datetime import datetime, timedelta
+
+from sqlalchemy import or_, select
+
+from app.core.rewards import CN_TZ
+from app.db.session import SessionLocal
+from app.models.user import User
+from app.repositories.comparison import upsert_record
+from app.schemas.compare_record import ComparisonRecordIn
+
+# 平台名 → id(展示用;横幅按 platform_name 渲染,id 仅留痕)
+_PLATFORM_ID = {"美团": "meituan", "京东": "jd", "淘宝闪购": "taobao", "饿了么": "ele"}
+
+# 10 单真实感外卖订单:source=美团,targets=(平台, 到手价/元, 优惠来源名|None, 红包额/元)。
+# failed=True 表示目标平台没采到价(targets 价置 None → 派生 status=failed)。
+_CATALOG = [
+    dict(store="瑞幸咖啡(国贸店)", items=[("生椰拿铁(大杯)", 2)],
+         source=("美团", 39.8),
+         targets=[("淘宝闪购", 29.9, "平台红包", 6.0), ("京东", 33.0, None, 0)]),
+    dict(store="茶百道(大悦城店)", items=[("杨梅冰萃(大杯)", 1), ("脆波波奶茶", 1)],
+         source=("美团", 31.0),
+         targets=[("京东", 24.5, "百亿补贴", 4.5), ("饿了么", 27.9, None, 0)]),
+    dict(store="麦当劳(西单店)", items=[("板烧鸡腿堡套餐", 1)],
+         source=("美团", 32.0),
+         targets=[("京东", 25.9, "神券", 3.0), ("淘宝闪购", 28.0, None, 0)]),
+    dict(store="肯德基(朝阳大悦城店)", items=[("疯狂星期四全家桶", 1)],
+         source=("美团", 89.0),
+         targets=[("京东", 79.9, "百亿补贴", 9.0)]),
+    dict(store="张亮麻辣烫(双井店)", items=[("自选麻辣烫", 1)],
+         source=("美团", 35.0),
+         targets=[("京东", None, None, 0), ("淘宝闪购", None, None, 0)],
+         failed=True, fail_reason="京东外卖、淘宝闪购均未找到该店"),
+    dict(store="必胜客(王府井店)", items=[("超级至尊比萨(9寸)", 1), ("香辣鸡翅", 1)],
+         source=("美团", 78.0),
+         targets=[("淘宝闪购", 62.0, "跨店满减", 10.0), ("京东", 69.0, None, 0)]),
+    dict(store="蜜雪冰城(中关村店)", items=[("多肉葡萄", 2), ("冰鲜柠檬水", 1)],
+         source=("美团", 21.0),
+         targets=[("京东", 16.5, None, 0)]),
+    dict(store="海底捞外送(三里屯店)", items=[("番茄锅底", 1), ("鲜毛肚", 2), ("虾滑", 1)],
+         source=("美团", 168.0),
+         targets=[("京东", 155.0, "大额神券", 13.0), ("饿了么", 162.0, None, 0)]),
+    dict(store="华莱士(回龙观店)", items=[("全鸡汉堡套餐", 1)],
+         source=("美团", 26.0),
+         targets=[("京东", None, None, 0)],
+         failed=True, fail_reason="该商品在京东外卖未上架"),
+    dict(store="星巴克(国贸店)", items=[("燕麦拿铁(大杯)", 2)],
+         source=("美团", 66.0),
+         targets=[("饿了么", 58.0, "会员券", 8.0), ("京东", 61.0, None, 0)]),
+]
+
+# 第 2..N 条的 created_at 相对当下的回退量(都 > 4 分钟,确保只有第 1 条落在新鲜窗口)。
+_OFFSETS = [
+    timedelta(minutes=25), timedelta(hours=2, minutes=10), timedelta(hours=6),
+    timedelta(days=1, hours=3), timedelta(days=1, hours=20), timedelta(days=2, hours=9),
+    timedelta(days=3, hours=14), timedelta(days=5, hours=7), timedelta(days=7, hours=2),
+]
+
+
+def _resolve_user(db, ident: str) -> User | None:
+    """按 id(纯数字)/ 用户名 / 邀请码 / 手机号 / 昵称(或昵称去掉「用户」前缀的后缀)解析用户。"""
+    if ident.isdigit():
+        u = db.get(User, int(ident))
+        if u is not None:
+            return u
+    return db.execute(
+        select(User).where(
+            or_(
+                User.username == ident,
+                User.invite_code == ident,
+                User.phone == ident,
+                User.nickname == ident,
+                User.nickname == f"用户{ident}",
+                User.nickname.like(f"%{ident}"),
+            )
+        )
+    ).scalars().first()
+
+
+def _build_results(order: dict) -> tuple[list[dict], str]:
+    """造 comparison_results + information 文案;返回 (results, information)。"""
+    src_name, src_price = order["source"]
+    failed = order.get("failed", False)
+    rows: list[dict] = [dict(
+        platform_id=_PLATFORM_ID.get(src_name), platform_name=src_name,
+        price=src_price, is_source=True, status="success",
+    )]
+    for pname, price, cname, csaved in order["targets"]:
+        row = dict(
+            platform_id=_PLATFORM_ID.get(pname), platform_name=pname,
+            price=(None if failed else price), is_source=False,
+            status=("store_not_found" if failed else "success"),
+        )
+        if not failed and csaved:
+            row["coupon_saved"] = csaved
+            row["coupon_name"] = cname
+        rows.append(row)
+
+    # rank:有价的按升序 1..N;无价的不排
+    priced = sorted((r for r in rows if r["price"] is not None), key=lambda r: r["price"])
+    for i, r in enumerate(priced, start=1):
+        r["rank"] = i
+
+    if failed:
+        return rows, order.get("fail_reason", "目标平台未找到该商品")
+    best = priced[0]
+    saved = src_price - best["price"]
+    if best["is_source"]:
+        info = f"{src_name}已是最低价,本单未比出更低"
+    else:
+        info = f"已在{best['platform_name']}比出最低价 ¥{best['price']:.2f}(比{src_name}省 ¥{saved:.2f})"
+    return rows, info
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="给用户灌一批 mock 比价记录")
+    parser.add_argument("--user", default="DlSKoc5S7", help="user.id / 用户名 / 邀请码 / 手机号 / 昵称后缀")
+    parser.add_argument("--count", type=int, default=10, help="条数(1..10),默认 10")
+    args = parser.parse_args()
+
+    count = max(1, min(args.count, len(_CATALOG)))
+    now = datetime.now(CN_TZ).replace(tzinfo=None)
+
+    db = SessionLocal()
+    try:
+        user = _resolve_user(db, args.user)
+        if user is None:
+            raise SystemExit(f"❌ 找不到用户:{args.user}(试试 --user <id>)")
+        print(f"→ 用户 id={user.id} nickname={user.nickname} phone={user.phone}")
+
+        ok = failed = 0
+        for idx in range(count):
+            order = _CATALOG[idx]
+            src_name, src_price = order["source"]
+            results, info = _build_results(order)
+            payload = ComparisonRecordIn(
+                trace_id=f"mock-{args.user}-{idx:02d}",
+                business_type="food",
+                device_id="mock-seed",
+                store_name=order["store"],
+                source_platform_id=_PLATFORM_ID.get(src_name),
+                source_platform_name=src_name,
+                source_price=src_price,
+                items=[{"name": n, "qty": q} for n, q in order["items"]],
+                comparison_results=results,
+                total_dish_count=sum(q for _, q in order["items"]),
+                information=info,
+                app_version="mock",
+            )
+            rec = upsert_record(db, user_id=user.id, payload=payload)
+            # created_at:第 1 条 = 当下(4 分钟新鲜窗口);其余铺近 7 天。重跑刷新时间戳。
+            rec.created_at = now if idx == 0 else now - _OFFSETS[idx - 1]
+            db.commit()
+            if rec.status == "success":
+                ok += 1
+            else:
+                failed += 1
+            tag = "🆕now" if idx == 0 else f"-{_OFFSETS[idx - 1]}"
+            print(f"  [{rec.status:7}] id={rec.id} {order['store']}  best={rec.best_platform_name} "
+                  f"¥{(rec.best_price_cents or 0)/100:.2f}  saved=¥{(rec.saved_amount_cents or 0)/100:.2f}  {tag}")
+
+        print(f"✅ 已为 user id={user.id} 写入 {count} 条(success {ok} / failed {failed});"
+              f"第 1 条 created_at=当下,4 分钟内进 app 可见「上次比价」横幅。")
+    finally:
+        db.close()
+
+
+if __name__ == "__main__":
+    main()
@@ -1,22 +1,19 @@
 """测试用 fixtures。

-测试 DB 用临时文件 SQLite。
-  - 不用 in-memory:in-memory 默认 per-connection,跨连接看不到表。
-  - 用临时文件保证 SessionLocal 每次新连都看到同一份 schema。
-
-顺序:set env(必须在 import app.* 之前) → import app → 建表 → TestClient
+测试库用 Docker PostgreSQL 的 shaguabijia_test(与 dev 业务库 shaguabijia 隔离)。
+顺序(必须):设 test DATABASE_URL(在 import app.* 之前)→ ensure PG 就绪 + 测试库存在 →
+import app → 建表。持久卷可能残留上次的表 → session 开头先 drop 再 create。
 """
 from __future__ import annotations

 import os
-import tempfile
 from collections.abc import Iterator

-# 临时 db 文件路径,进程退出后清理
-_tmp_db = tempfile.NamedTemporaryFile(suffix=".db", delete=False)
-_tmp_db.close()
-
-os.environ["DATABASE_URL"] = f"sqlite:///{_tmp_db.name}"
+# 1) 测试库连接串——必须在 import app.* 之前设好(app.db.session 在 import 期就建 engine)
+_TEST_DB_URL = (
+    "postgresql+psycopg://shaguabijia_app:shaguabijia_dev_pw@localhost:5432/shaguabijia_test"
+)
+os.environ["DATABASE_URL"] = _TEST_DB_URL
 os.environ.setdefault("JWT_SECRET_KEY", "test-secret-please-ignore-this-is-only-for-pytest-not-real")
 os.environ.setdefault("ADMIN_JWT_SECRET", "test-admin-secret-please-ignore-only-for-pytest-not-real")
 os.environ.setdefault("JG_APP_KEY", "test-key")
@@ -35,6 +32,18 @@ os.environ.setdefault("RATE_LIMIT_ENABLED", "false")  # 限流内存计数会跨
 os.environ.setdefault("PANGLE_CALLBACK_ENABLED", "true")
 os.environ.setdefault("PANGLE_REWARD_SECRET", "test-pangle-secret-only-for-pytest")

+# 2) 保证 Docker PG 就绪(必须在 import app.db.session 建 engine 之前)。
+#    ensure() 在「端口已通」时会短路、不建测试库,故随后再显式补一刀 ensure_test_db()。
+from scripts.ensure_pg import ensure, ensure_test_db
+
+if not ensure(_TEST_DB_URL):
+    raise RuntimeError(
+        "测试需要 Docker PostgreSQL 就绪。请确认已装 Docker Desktop;"
+        "或先跑一次 run.bat/run.sh 把 PG 拉起,再重试 pytest。"
+    )
+# best-effort 兜底建测试库(PG 已在跑但测试库缺失=老卷)。真缺库时下面 create_all 会明确报错。
+ensure_test_db()
+
 import pytest
 from fastapi.testclient import TestClient

@@ -45,13 +54,11 @@ from app.main import app

@pytest.fixture(scope="session", autouse=True)
 def _setup_db() -> Iterator[None]:
+    # 持久卷可能残留上次跑崩后的表/数据 → 先 drop 再 create,保证干净起点
+    Base.metadata.drop_all(engine)
    Base.metadata.create_all(engine)
    yield
    Base.metadata.drop_all(engine)
-    try:
-        os.unlink(_tmp_db.name)
-    except OSError:
-        pass


@pytest.fixture()
@@ -18,6 +18,7 @@ import httpx
 from app.db.session import SessionLocal
 from app.models.comparison import ComparisonRecord
 from app.repositories import comparison as crud
+from app.repositories.user import get_user_by_phone
 from app.schemas.compare_record import ComparisonRecordIn
 from sqlalchemy import select

@@ -47,6 +48,17 @@ def _get(db, trace_id: str) -> ComparisonRecord | None:
    ).scalar_one_or_none()


+def _make_user(client, phone: str) -> int:
+    """登录建号并返回其真实 user_id。
+
+    PG 强制 comparison_record.user_id → user.id 外键,须引用真实存在的用户;
+    用本用例自己登录出的用户,不会与别的用例撞。
+    """
+    client.post("/api/v1/auth/sms/login", json={"phone": phone, "code": "123456"})
+    with SessionLocal() as db:
+        return get_user_by_phone(db, phone).id
+
+
 # ============================================================
 # repo 层
 # ============================================================
@@ -144,17 +156,18 @@ def test_harvest_abort_missing_row_returns_none(client) -> None:
 def test_upsert_record_no_downgrade_after_harvest_success(client) -> None:
    """harvest 落 success 后,老客户端 fromFailure 的 cancelled 上报不许把它盖回去。"""
    tid = _tid()
+    # PG 强制 comparison_record.user_id → user.id 外键(SQLite 不强制,老写法用合成 id
+    # 987654)。用本用例自己登录出的真实用户,既满足外键、又不与别的用例撞。
+    uid = _make_user(client, "13800007701")
    with SessionLocal() as db:
        crud.harvest_done(db, trace_id=tid, user_id=None, done_params=_done_params())
        payload = ComparisonRecordIn(
            trace_id=tid, business_type="food", status="cancelled",
            information="用户终止", comparison_results=[],
        )
-        # 用一个不会与顺序自增用户撞的合成 id(SQLite 测试库 FK 不强制;别用小整数,
-        # 否则会撞上别的测试 login 出来的真实 user_id → 记录混进那个用户的列表)。
-        rec = crud.upsert_record(db, user_id=987654, payload=payload)
+        rec = crud.upsert_record(db, user_id=uid, payload=payload)
        assert rec.status == "success"              # 不降级
-        assert rec.user_id == 987654                 # 但补上了 user_id(原为 None)
+        assert rec.user_id == uid                    # 但补上了 user_id(原为 None)


 # ============================================================
@@ -0,0 +1,87 @@
+"""scripts/ensure_pg.py 纯函数单测(不需要 Docker/PG)。"""
+from __future__ import annotations
+
+import socket
+
+from scripts.ensure_pg import (
+    _docker_desktop_cmd,
+    _is_sqlite,
+    _parse_host_port,
+    _port_open,
+    ensure,
+)
+
+
+def test_is_sqlite():
+    assert _is_sqlite("sqlite:///./data/app.db")
+    assert _is_sqlite("  SQLite:///x ")
+    assert not _is_sqlite("postgresql+psycopg://u:p@localhost:5432/db")
+
+
+def test_parse_host_port_full():
+    assert _parse_host_port(
+        "postgresql+psycopg://u:p@localhost:5432/shaguabijia"
+    ) == ("localhost", 5432)
+
+
+def test_parse_host_port_defaults():
+    # 缺端口 → 5432
+    assert _parse_host_port("postgresql+psycopg://u:p@db.example/x")[1] == 5432
+    # 缺 host → localhost
+    assert _parse_host_port("postgresql+psycopg:///x") == ("localhost", 5432)
+
+
+def test_parse_host_port_testdb():
+    assert _parse_host_port(
+        "postgresql+psycopg://u:p@localhost:5432/shaguabijia_test"
+    ) == ("localhost", 5432)
+
+
+def test_port_open_true():
+    srv = socket.socket()
+    srv.bind(("127.0.0.1", 0))
+    srv.listen(1)
+    port = srv.getsockname()[1]
+    try:
+        assert _port_open("127.0.0.1", port, timeout=1.0)
+    finally:
+        srv.close()
+
+
+def test_port_open_false():
+    s = socket.socket()
+    s.bind(("127.0.0.1", 0))
+    port = s.getsockname()[1]
+    s.close()  # 释放端口,无人监听 → 连接应失败
+    assert not _port_open("127.0.0.1", port, timeout=0.3)
+
+
+def test_docker_desktop_cmd_windows():
+    cmd = _docker_desktop_cmd("win32", r"C:\Program Files")
+    assert cmd is not None
+    assert cmd[0].endswith("Docker Desktop.exe")
+    assert "Docker" in cmd[0]
+
+
+def test_docker_desktop_cmd_darwin():
+    assert _docker_desktop_cmd("darwin", "") == ["open", "-a", "Docker"]
+
+
+def test_docker_desktop_cmd_linux():
+    assert _docker_desktop_cmd("linux", "") is None
+
+
+def test_ensure_rejects_sqlite():
+    # dev 守卫:sqlite 直接 False(不碰 Docker)
+    assert ensure("sqlite:///./data/app.db") is False
+
+
+def test_ensure_shortcircuits_when_pg_up(monkeypatch):
+    # 端口通 → 直接 True,绝不触碰 docker
+    monkeypatch.setattr("scripts.ensure_pg._port_open", lambda *a, **k: True)
+
+    def _boom():
+        raise AssertionError("端口通时不应调用 docker")
+
+    monkeypatch.setattr("scripts.ensure_pg._docker_cli_ok", _boom)
+    assert ensure("postgresql+psycopg://u:p@localhost:5432/shaguabijia") is True
@@ -0,0 +1,137 @@
+"""reverse_geocoder 经纬度→城市 测试。
+
+验证离线库对国内主要城市的匹配准确性。注意：gazetteer 的中国数据粒度不一致——
+直辖市/省会通常直接命中城市名，部分城市可能命中到区/街道级（如天津→Erwangzhuang、
+西安→Zhangjiabao），此时 admin1 为省级行政区。测试以 admin1（省级）匹配为主。
+"""
+from __future__ import annotations
+
+import pytest
+
+from app.utils.geo import get_city
+
+# ─────────────── 国内主要城市 ───────────────
+# (城市, 纬度, 经度, 期望 admin1 包含字串)
+_CITY_CASES = [
+    # 直辖市 — admin1 即城市名(可能带 Shi 后缀)
+    ("北京",     39.9042,  116.4074,  "Beijing"),
+    ("上海",     31.2304,  121.4737,  "Shanghai"),
+    ("重庆",     29.4316,  106.9123,  "Chongqing"),
+    ("天津",     39.3434,  117.3616,  "Tianjin"),
+    # 省会 / 一线 — admin1 为省份
+    ("广州",     23.1291,  113.2644,  "Guangdong"),
+    ("深圳",     22.5431,  114.0579,  "Guangdong"),
+    ("成都",     30.5728,  104.0668,  "Sichuan"),
+    ("杭州",     30.2741,  120.1551,  "Zhejiang"),
+    ("武汉",     30.5928,  114.3055,  "Hubei"),
+    ("西安",     34.3416,  108.9398,  "Shaanxi"),
+    ("南京",     32.0603,  118.7969,  "Jiangsu"),
+    ("长沙",     28.2282,  112.9388,  "Hunan"),
+    ("郑州",     34.7466,  113.6253,  "Henan"),
+    ("济南",     36.6512,  116.9946,  "Shandong"),
+    ("昆明",     25.0389,  102.7183,  "Yunnan"),
+    ("福州",     26.0745,  119.2965,  "Fujian"),
+    ("哈尔滨",   45.8038,  126.5350,  "Heilongjiang"),
+    ("乌鲁木齐", 43.8256,  87.6168,   "Xinjiang"),
+    ("拉萨",     29.6500,  91.1000,   "Tibet"),
+    # 非省会
+    ("厦门",     24.4798,  118.0894,  "Fujian"),
+    ("苏州",     31.2990,  120.5853,  "Jiangsu"),
+    ("青岛",     36.0671,  120.3826,  "Shandong"),
+]
+
+
+@pytest.mark.parametrize("label,lat,lon,expected_admin1", _CITY_CASES)
+def test_city_admin1_match(label: str, lat: float, lon: float, expected_admin1: str) -> None:
+    """所有城市经纬度应能匹配到正确的省级行政区 (admin1)。"""
+    r = get_city(lat, lon)
+    assert r["name"] != "", f"{label}: name should not be empty"
+    assert r["country"] == "CN", f"{label}: expected country=CN, got={r['country']}"
+    assert expected_admin1 in r["admin1"], \
+        f"{label}: expected admin1 to contain '{expected_admin1}', got={r['admin1']!r}"
+
+
+# ─────────────── 直辖市 / 省会直接命中城市名 ───────────────
+# 这些城市在 gazetteer 中的坐标恰好命中城市级条目（而非区/街道级），
+# 验证 name 字段也正确。
+_DIRECT_HIT_CASES = [
+    ("北京",   39.9042,  116.4074,  "Beijing"),
+    ("上海",   31.2304,  121.4737,  "Shanghai"),
+    ("广州",   23.1291,  113.2644,  "Guangzhou"),
+    ("深圳",   22.5431,  114.0579,  "Shenzhen"),
+    ("成都",   30.5728,  104.0668,  "Chengdu"),
+    ("杭州",   30.2741,  120.1551,  "Hangzhou"),
+    ("郑州",   34.7466,  113.6253,  "Zhengzhou"),
+    ("济南",   36.6512,  116.9946,  "Jinan"),
+    ("昆明",   25.0389,  102.7183,  "Kunming"),
+    ("哈尔滨", 45.8038,  126.5350,  "Harbin"),
+    ("厦门",   24.4798,  118.0894,  "Xiamen"),
+    ("苏州",   31.2990,  120.5853,  "Suzhou"),
+    ("青岛",   36.0671,  120.3826,  "Qingdao"),
+    ("拉萨",   29.6500,  91.1000,   "Lhasa"),
+]
+
+
+@pytest.mark.parametrize("label,lat,lon,expected_name", _DIRECT_HIT_CASES)
+def test_city_name_direct_hit(label: str, lat: float, lon: float, expected_name: str) -> None:
+    """直辖市/省会等主要城市坐标应直接命中城市名(而非区/街道级)。"""
+    r = get_city(lat, lon)
+    assert r["name"] == expected_name, \
+        f"{label}: expected name={expected_name}, got={r['name']!r}"
+
+
+# ─────────────── 边界情况 ───────────────
+
+def test_ocean_not_china() -> None:
+    """远洋坐标不应误判为国内城市。"""
+    # 太平洋中部 → 可能匹配到最近有人岛(如法属波利尼西亚 Taiohae)，但绝不应是 CN
+    r = get_city(0.0, -140.0)
+    assert r["country"] != "CN", f"mid-Pacific should not be CN, got {r}"
+
+    # 南大西洋
+    r2 = get_city(-30.0, -20.0)
+    assert r2["country"] != "CN", f"South Atlantic should not be CN, got {r2}"
+
+
+def test_return_keys_and_types() -> None:
+    """返回 dict 应包含全部五个字段且类型为 str。"""
+    r = get_city(39.9042, 116.4074)
+    for key in ("name", "admin1", "country", "latitude", "longitude"):
+        assert key in r, f"missing key: {key}"
+        assert isinstance(r[key], str), f"key {key} should be str, got {type(r[key])}"
+
+
+def test_empty_result_keys() -> None:
+    """结果始终应包含完整字段且全为 str 类型（即使匹配到偏远地）。"""
+    # reverse_geocoder KDTree 总找最近聚居点；业务侧如需判定"是否有效城市"
+    # 应自行按 country / admin1 做二次校验，而非依赖空字符串。
+    r = get_city(0.0, -140.0)
+    assert r["name"] != ""
+    assert isinstance(r["name"], str)
+    assert isinstance(r["admin1"], str)
+    assert isinstance(r["country"], str)
+    assert isinstance(r["latitude"], str)
+    assert isinstance(r["longitude"], str)
+
+
+def test_same_coords_consistent() -> None:
+    """同一坐标两次查询应返回相同结果（幂等）。"""
+    r1 = get_city(31.2304, 121.4737)
+    r2 = get_city(31.2304, 121.4737)
+    assert r1 == r2
+
+
+def test_near_border_has_result() -> None:
+    """省界附近的坐标应返回结果(非空 + 国内)。"""
+    # 苏鲁豫皖交界区域(徐州/商丘/宿州附近)
+    r = get_city(34.2, 116.8)
+    assert r["name"] != "", "border region should find a nearby populated place"
+    assert r["country"] == "CN"
+
+
+def test_extreme_lat_lon_no_crash() -> None:
+    """极值经纬度不应抛异常。"""
+    r1 = get_city(90.0, 0.0)    # 北极
+    r2 = get_city(-90.0, 0.0)   # 南极
+    assert isinstance(r1, dict)
+    assert isinstance(r2, dict)
@@ -0,0 +1,64 @@
+"""app.utils.meituan_city.get_meituan_city 经纬度→美团城市 反查测试。
+
+覆盖 get_meituan_city 的分支(test_geo.py 只覆盖底层 get_city):
+  - 主要城市 → 正确省份 + 非空 city_id(+ 直辖市/省会命中中文城市名)
+  - 非中国境内坐标 → city_id 为空(接口据此降级返空)
+  - 返回 dict 结构 / 类型
+  - 坐标量化(~1km)后近点命中同一缓存结果
+  - 返回的是缓存副本(调用方原地修改不污染缓存)
+"""
+from __future__ import annotations
+
+import pytest
+
+from app.utils.meituan_city import get_meituan_city
+
+# (标签, 纬度, 经度, 期望省份名, 期望城市名)
+_CASES = [
+    ("北京", 39.9042, 116.4074, "北京市", "北京市"),
+    ("上海", 31.2304, 121.4737, "上海市", "上海市"),
+    ("广州", 23.1291, 113.2644, "广东省", "广州市"),
+    ("深圳", 22.5431, 114.0579, "广东省", "深圳市"),
+    ("成都", 30.5728, 104.0668, "四川省", "成都市"),
+    ("杭州", 30.2741, 120.1551, "浙江省", "杭州市"),
+    ("武汉", 30.5928, 114.3055, "湖北省", "武汉市"),
+    ("郑州", 34.7466, 113.6253, "河南省", "郑州市"),
+    ("厦门", 24.4798, 118.0894, "福建省", "厦门市"),
+    ("青岛", 36.0671, 120.3826, "山东省", "青岛市"),
+]
+
+
+@pytest.mark.parametrize("label,lat,lon,exp_province,exp_city", _CASES)
+def test_major_city_resolves(label: str, lat: float, lon: float,
+                             exp_province: str, exp_city: str) -> None:
+    r = get_meituan_city(lat, lon)
+    assert r["province_name"] == exp_province, f"{label}: province {r!r}"
+    assert r["city_name"] == exp_city, f"{label}: city {r!r}"
+    assert r["city_id"], f"{label}: city_id 不应为空 {r!r}"
+
+
+def test_non_china_returns_empty_city_id() -> None:
+    """境外/远洋坐标 → city_id 空(接口据此返回 degraded 空列表)。"""
+    r = get_meituan_city(0.0, -140.0)   # 太平洋中部
+    assert r["city_id"] == "", f"境外不应给出 city_id: {r!r}"
+
+
+def test_return_shape_and_types() -> None:
+    r = get_meituan_city(39.9042, 116.4074)
+    for key in ("city_id", "city_name", "province_name"):
+        assert key in r and isinstance(r[key], str)
+
+
+def test_quantized_coords_hit_same_result() -> None:
+    """相距 <1km(round 到 2 位小数后相同)的两点应解析出同一城市。"""
+    a = get_meituan_city(39.9042, 116.4074)
+    b = get_meituan_city(39.9031, 116.4066)   # round 后同为 (39.90, 116.41)
+    assert a == b
+
+
+def test_result_is_defensive_copy() -> None:
+    """返回的是缓存副本:原地修改不应污染后续查询。"""
+    first = get_meituan_city(31.2304, 121.4737)
+    first["city_id"] = "TAMPERED"
+    second = get_meituan_city(31.2304, 121.4737)
+    assert second["city_id"] != "TAMPERED"
@@ -0,0 +1,150 @@
+"""提现现金账本校验(admin ledger-check)测试:两本物理隔离的账各自对账。
+
+历史盲区:`withdraw_ledger_check` 曾拿全部提现单去和**普通现金流水**(cash_transaction)比对,
+而 source=invite_cash 的提现单流水其实在 invite_cash_transaction 表,导致每笔邀请提现单都被
+误报「缺扣款/缺退款流水」。这里用真实提现 API 造单 + before/after 差值断言锁定修复:
+  1) 邀请提现单不再污染普通现金账的缺流水计数;
+  2) 邀请账户已被纳入对账(能抓到它自己的缺流水);
+  3) 普通现金账的原有对账未被改坏。
+
+conftest 的库是 session 级共享、测试间不清,故一律用 before/after 差值,只反映本用例造的数据。
+"""
+from __future__ import annotations
+
+from sqlalchemy import delete, select
+
+from app.admin.repositories.queries import withdraw_ledger_check
+from app.db.session import SessionLocal
+from app.models.user import User
+from app.models.wallet import CoinAccount, InviteCashTransaction
+from app.repositories import wallet as crud_wallet
+
+
+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 _auth(token: str) -> dict[str, str]:
+    return {"Authorization": f"Bearer {token}"}
+
+
+def _patch_userinfo(monkeypatch, openid: str) -> None:
+    monkeypatch.setattr(
+        "app.integrations.wxpay.code_to_userinfo",
+        lambda code: {"openid": openid, "nickname": None, "avatar_url": None, "raw": {}},
+    )
+
+
+def _seed_balances(client, token: str, phone: str, *, cash: int = 0, invite_cash: int = 0) -> None:
+    client.get("/api/v1/wallet/account", headers=_auth(token))
+    db = SessionLocal()
+    try:
+        user = db.execute(select(User).where(User.phone == phone)).scalar_one()
+        acc = db.get(CoinAccount, user.id)
+        acc.cash_balance_cents = cash
+        acc.invite_cash_balance_cents = invite_cash
+        db.commit()
+    finally:
+        db.close()
+
+
+def _reject(bill: str, reason: str = "测试拒绝") -> None:
+    db = SessionLocal()
+    try:
+        crud_wallet.reject_withdraw(db, bill, reason)
+    finally:
+        db.close()
+
+
+def _ledger() -> dict:
+    db = SessionLocal()
+    try:
+        return withdraw_ledger_check(db)
+    finally:
+        db.close()
+
+
+def test_rejected_invite_withdraw_not_flagged_missing(client, monkeypatch) -> None:
+    """核心回归:一笔被拒绝的 invite_cash 提现单,扣款/退款流水都在 invite_cash_transaction,
+    不应让普通现金账的缺扣款/缺退款计数增加(修复前每笔会各 +1)。"""
+    before = _ledger()
+
+    _patch_userinfo(monkeypatch, "openid_lc_1")
+    token = _login(client, "13800005001")
+    _seed_balances(client, token, "13800005001", cash=0, invite_cash=500)
+    client.post("/api/v1/wallet/bind-wechat", json={"code": "c"}, headers=_auth(token))
+    r = client.post(
+        "/api/v1/wallet/withdraw",
+        json={"amount_cents": 200, "source": "invite_cash"},
+        headers=_auth(token),
+    )
+    assert r.status_code == 200, r.text
+    _reject(r.json()["out_bill_no"])  # rejected + 退款流水落 invite_cash_transaction
+
+    after = _ledger()
+
+    # 普通现金账不该因这笔 invite 单产生缺流水(修复前会各 +1 → 就是页面上看到的误报)
+    assert after["missing_withdraw_txn_count"] == before["missing_withdraw_txn_count"]
+    assert after["missing_refund_txn_count"] == before["missing_refund_txn_count"]
+    # 邀请账扣款 + 退款流水齐全,邀请账自身也不该缺
+    assert after["invite_missing_withdraw_txn_count"] == before["invite_missing_withdraw_txn_count"]
+    assert after["invite_missing_refund_txn_count"] == before["invite_missing_refund_txn_count"]
+
+
+def test_invite_ledger_detects_missing_withdraw_txn(client, monkeypatch) -> None:
+    """删掉一笔 invite 提现单的扣款流水 → 邀请账缺扣款计数 +1、ok=False,
+    证明邀请账户已真正纳入对账(修复前邀请账完全不校验、永远报不出问题)。"""
+    _patch_userinfo(monkeypatch, "openid_lc_2")
+    token = _login(client, "13800005002")
+    _seed_balances(client, token, "13800005002", cash=0, invite_cash=500)
+    client.post("/api/v1/wallet/bind-wechat", json={"code": "c"}, headers=_auth(token))
+    r = client.post(
+        "/api/v1/wallet/withdraw",
+        json={"amount_cents": 200, "source": "invite_cash"},
+        headers=_auth(token),
+    )
+    bill = r.json()["out_bill_no"]
+
+    before = _ledger()
+    db = SessionLocal()
+    try:
+        db.execute(
+            delete(InviteCashTransaction).where(
+                InviteCashTransaction.ref_id == bill,
+                InviteCashTransaction.biz_type == "invite_withdraw",
+            )
+        )
+        db.commit()
+    finally:
+        db.close()
+    after = _ledger()
+
+    assert (
+        after["invite_missing_withdraw_txn_count"]
+        == before["invite_missing_withdraw_txn_count"] + 1
+    )
+    assert after["ok"] is False
+
+
+def test_coin_cash_withdraw_still_reconciled(client, monkeypatch) -> None:
+    """普通现金 coin_cash 提现单齐全时不新增缺流水(确保分账改造没弄坏原有普通现金对账)。"""
+    _patch_userinfo(monkeypatch, "openid_lc_3")
+    token = _login(client, "13800005003")
+    _seed_balances(client, token, "13800005003", cash=500, invite_cash=0)
+    client.post("/api/v1/wallet/bind-wechat", json={"code": "c"}, headers=_auth(token))
+
+    before = _ledger()
+    r = client.post(
+        "/api/v1/wallet/withdraw",
+        json={"amount_cents": 200, "source": "coin_cash"},
+        headers=_auth(token),
+    )
+    assert r.status_code == 200, r.text
+    after = _ledger()
+
+    # 普通现金提现扣款流水随单写入 cash_transaction,缺扣款计数不变;邀请账更不受影响
+    assert after["missing_withdraw_txn_count"] == before["missing_withdraw_txn_count"]
+    assert after["invite_missing_withdraw_txn_count"] == before["invite_missing_withdraw_txn_count"]
Author	SHA1	Message	Date
guke	e052fb778b	feat(dev): ensure_pg 加显式 SQLite 逃生舱 + 修 Docker 检测/项目名撞名;新增 run8771 起 admin - ensure_pg: 无 Docker 时【显式】降级 SQLite(带醒目降级横幅),不再硬失败(反转设计 D4) - ensure_pg: _docker_cli_ok 改用 `docker --version`(纯客户端),修「装了 Docker 但没启动」被 `docker version`(要连 daemon)误判成「没装 CLI」而绕过自动拉起(需求②) - ensure_pg: 钉死 COMPOSE_PROJECT_NAME=shaguabijia + 清「同名但非本项目」残留容器, 修跨目录/worktree 切换时 container_name 撞名 + pgdata 卷分裂 - run8771.bat: 新增 admin 后端(:8771)启动脚本,跑 app.admin.main:admin_app(run.bat 对等版) - 设计文档 §10 记录以上 D4 反转与三处修复 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-27 19:12:29 +08:00
guke	b0482ec157	docs(dev): 记录本地 Docker PostgreSQL 用法,区分生产原生 PG 路径 - postgres-migration.md 增「1.0 Docker 一键起」推荐节 - CLAUDE.md 订正 Dev/Test 已切 Docker PG(不再 SQLite)+ conftest 描述 - init_postgres.py docstring 标明其面向生产原生 PG,本地改用 compose Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-08 19:13:51 +08:00
guke	0aee9d4dd0	test(db): 修 test_compare_harvest 外键严格性(切 PG 暴露) upsert 用例原用合成 user_id=987654,靠 SQLite 不强制外键;PG 强制 comparison_record.user_id → user.id,故改为登录建真实用户再用其 id。纯测试改动,不动业务逻辑。剩余 5 个红为预存(奖励/透传,与本改动无关)。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-08 18:49:46 +08:00
guke	c6309f0f74	test(dev): conftest 切 shaguabijia_test(Docker PG) conftest 在 import app 前设 test DATABASE_URL、调 ensure()+ensure_test_db() 引导 PG,fixture 改 drop_all→create_all(防持久卷残留)。ensure_pg 把 _ensure_test_db 提为公开 ensure_test_db(短路路径不建库,测试侧需显式补)。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-08 18:46:07 +08:00
guke	3b90e2f212	feat(dev): .env.example 默认 DATABASE_URL 切 Docker PostgreSQL Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-08 18:38:59 +08:00
guke	b2ea6c727c	feat(dev): run.sh/run.bat 启动前确保 Docker PostgreSQL 就绪在 alembic upgrade head 之前调用 scripts.ensure_pg:没起会自动拉起 Docker + PG 容器,失败即退出(run.bat 判 errorlevel)。顺带订正过时的 "sqlite" 注释。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-08 18:38:09 +08:00
guke	5e706fd003	refactor(dev): ensure_pg 应用代码评审改进 - 所有 docker 探测/exec 加 per-call timeout(防守护进程半死时无限挂起、绕过总超时) - _ensure_test_db 改为返回 bool 并由 ensure() 传播;建库失败(含超时)显式告警, 与并发创建者竞争失败但库已存在(42P04)仍算就绪 - 抽出 _test_db_exists 复用;去掉一处冗余 f-string Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-08 18:31:02 +08:00
guke	9c55344e85	fix(dev): ensure_pg 日志对 GBK 控制台编码安全(✅ emoji 不再崩 run.bat) Windows cmd.exe 默认 GBK,print ✅(U+2705)抛 UnicodeEncodeError → 脚本退非0、 run.bat 误判 ensure_pg 失败。改为启动时对 stdout/stderr 设 errors=backslashreplace: 中文照常,仅不可编码字符转义。顺带订正计划里的测试计数(11)。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-08 18:16:11 +08:00
guke	4d3b73ae70	feat(dev): scripts/ensure_pg.py 探测/拉起本地 Docker PostgreSQL	2026-07-08 18:09:50 +08:00
guke	5dff56bbb2	feat(dev): docker-compose 起本地 PostgreSQL(含测试库 initdb)	2026-07-08 17:52:25 +08:00
guke	c734c00742	docs: 本地开发切 Docker PG 实现计划 7 个 TDD 任务:compose+initdb → ensure_pg.py(单测)→ run 接线 → .env.example → conftest 切测试库 → 修红用例 → 文档。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-08 17:36:41 +08:00
guke	886e781a4f	docs: 本地开发切 Docker PG 设计文档新增 spec:让 dev 运行与 pytest 都跑在 Docker 化的 PostgreSQL 上,退掉 SQLite,使 admin 报表聚合可用 PG 专有函数(不再内存聚合)。方案 A: docker-compose + scripts/ensure_pg.py,run.bat/run.sh/conftest 共用。顺带把 .worktrees/ 加入 .gitignore(superpowers 隔离工作区)。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-08 17:20:11 +08:00
guke	a52fc1973f	revert `58b59c264d` revert fix(dashboard): 比价/领券奖励金币按 feed_scene 汇总(修复恒 0 + 激励视频双计) 比价/领券奖励金币此前查 coin_transaction.biz_type in (comparison/coupon...), 但这些 biz_type 全站从未写入——比价/领券信息流广告金币实际记为 feed_ad_reward、场景区分在 ad_feed_reward_record.feed_scene——故两卡恒 0;领券桶还误含 reward_video/ad_reward,把激励视频金币双计进领券。改为:comparison/coupon 奖励金币 = biz_type 桶(历史空、留作兜底)+ 按 ad_feed_reward_record.feed_scene 的 granted 实发金币(reward_date 北京自然日窗口); reward_video/ad_reward 拆成独立 REWARD_VIDEO_BIZ_TYPES,不再混入领券, REGULAR_TASK_EXCLUDED_BIZ_TYPES 保持不变。测试:tests/test_admin_read.py 加 3 个用例(比价/领券按 feed_scene 汇总、 too_short 不计、领券排除激励视频);全量 pytest 除 5 个既有失败外全绿。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-07 17:52:57 +08:00
guke	58b59c264d	fix(dashboard): 比价/领券奖励金币按 feed_scene 汇总(修复恒 0 + 激励视频双计) 比价/领券奖励金币此前查 coin_transaction.biz_type in (comparison/coupon...), 但这些 biz_type 全站从未写入——比价/领券信息流广告金币实际记为 feed_ad_reward、场景区分在 ad_feed_reward_record.feed_scene——故两卡恒 0;领券桶还误含 reward_video/ad_reward,把激励视频金币双计进领券。改为:comparison/coupon 奖励金币 = biz_type 桶(历史空、留作兜底)+ 按 ad_feed_reward_record.feed_scene 的 granted 实发金币(reward_date 北京自然日窗口); reward_video/ad_reward 拆成独立 REWARD_VIDEO_BIZ_TYPES,不再混入领券, REGULAR_TASK_EXCLUDED_BIZ_TYPES 保持不变。测试:tests/test_admin_read.py 加 3 个用例(比价/领券按 feed_scene 汇总、 too_short 不计、领券排除激励视频);全量 pytest 除 5 个既有失败外全绿。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-07 17:46:09 +08:00
Ghost	0e149c83e7	修复美团 CPS 订单 pay_time 入库为空导致大盘美团收益漏算 (#119 ) Co-authored-by: guke <guke@autohome.com.cn> Co-authored-by: 陈世睿 <2839904623@qq.com> Reviewed-on: #119 Co-authored-by: Ghost <> Co-committed-by: Ghost <>	2026-07-07 17:11:00 +08:00
zhuzihao	9e011f699a	feat(marquee): 预览可按数据源模式实时 + 默认昵称归入「无昵称」脱敏档 (#122 ) 后台「首页轮播种子」预览与用户名脱敏两处改动,对齐《省钱log&平台数据显示策略》: - 预览按模式实时:get_feed 增加可选 mode 入参(不落库),admin 预览接口 /marquee-seeds/preview 透传 ?mode=,后台切换「混播/只真实/只种子」时预览即时对应; 不传 mode 时读持久化配置,客户端 /savings-feed 行为不变。 - 默认昵称归「无昵称」档:创建时自动分配的默认昵称(「用户」+9 位随机)不算用户主动设的昵称,脱敏走 id 规则「用户*****+id后2位」而非昵称规则。新增 user.is_default_nickname 精确匹配生成格式,不误伤真人以「用户」开头的昵称(如「用户体验师」)。 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: zzhyyyyy <2685922758@qq.com> Reviewed-on: #122 Co-authored-by: zhuzihao <zhuzihao@wonderable.ai> Co-committed-by: zhuzihao <zhuzihao@wonderable.ai>	2026-07-07 00:16:20 +08:00
zhuzihao	66c1e3ad8f	fix(withdraw): 提现账本校验按 source 分账,邀请奖励金提现纳入对账 (#121 ) 线上后台「提现审核」页现金账本报红(缺扣款/缺退款流水),根因是 withdraw_ledger_check 用全部提现单去比对普通现金流水(cash_transaction), 而 source=invite_cash 的提现,其扣款/退款流水写在独立的 invite_cash_transaction 表,于是每笔邀请提现单都在普通现金流水里找不到、被误报为「缺流水」。改动: - 抽出 _check_withdraw_ledger_side 复用单账核对逻辑;withdraw_ledger_check 改为按 order.source 分两本账各自对账: coin_cash ↔ cash_transaction(withdraw/withdraw_refund), invite_cash ↔ invite_cash_transaction(invite_withdraw/invite_withdraw_refund)。 - 邀请奖励金账户的余额差额也纳入校验(此前完全未对账)。 - 纯只读校验,不改任何资金/流水写入;不掩盖真实缺流水 (coin_cash 单若真缺流水仍照报)。 - WithdrawLedgerCheckOut 新增 7 个 invite_* 字段(默认 0,向后兼容)。 - 补 tests/test_withdraw_ledger_check.py(此前无 ledger-check 测试): 覆盖邀请提现不再误报、邀请账缺流水能被抓、普通现金账未回归。 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: zzhyyyyy <2685922758@qq.com> Reviewed-on: #121 Co-authored-by: zhuzihao <zhuzihao@wonderable.ai> Co-committed-by: zhuzihao <zhuzihao@wonderable.ai>	2026-07-07 00:16:12 +08:00
zhuzihao	982e92bc24	feat(ad-revenue): 收益报表 DAU/ARPU 按所选区间统计(复用大盘活跃口径) (#120 ) - 抽出 stats.period_active_dau(date_from, date_to):任意北京自然日区间的去重活跃用户 (登录 + 开始比价 + 开始领券),口径与数据大盘 period.users.active 一致。today_dau 与 dashboard_overview 的 period 活跃、逐日趋势统一复用它,消除三处重复的并集计算,行为不变。 - ad_revenue_report 去掉「仅今日单天才给 dau」的 is_today 限制,dau 改为按 date_from~date_to 区间统计(含今日、近 7 天、近 30 天);ARPU = 区间预估收益 ÷ 区间活跃用户对三个时段均可算, dau 与大盘同区间同值。 - dau 为全局口径,不随 user_id/ad_type/feed_scene/app_env 筛选变化;更新 schema 字段说明。 - 验证:admin 读接口测试(含 dashboard_overview)全过;实测多天区间 dau 非空且 == 大盘 period.users.active。前端展示改动见 admin-web 对应 PR。 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: zzhyyyyy <2685922758@qq.com> Reviewed-on: #120 Co-authored-by: zhuzihao <zhuzihao@wonderable.ai> Co-committed-by: zhuzihao <zhuzihao@wonderable.ai>	2026-07-06 00:23:36 +08:00
zhuzihao	6241543119	运营后台后端:RBAC 权限管理 + 系统配置下发修复 + 比价记录店/商品搜索 (#117 ) 一、RBAC 权限管理(角色 → 可见页面) - 新增 admin_role 表 + 权限目录 permissions.py:角色持有一组页面 key,登录后左侧只展示这些页 - 内建角色管理员(super_admin 全权锁定)/运营/财务/技术,页集对齐原型;key 承重(require_role 用),另加中文 label 展示 - 角色 CRUD 端点(仅 super_admin)+ 目录端点;登录/me 下发当前角色有效可见页 - admins 加删除、角色存在性校验;可复看已确定登录密码:UI 建的账号留存明文 plain_password,脚本建的超管不留存二、系统配置下发修复 - 首页数据「保存即生效」:显式保存(apply_now)对 real/manual 直接落配置目标值、绕过只增不减护栏(修「改了 app 端不变」),护栏仍管自动 tick - 首页轮播新增数据源三选一:mixed(真实优先+种子)/real(只真实)/seed(只种子),get_feed 分支 + /marquee-seeds/mode 端点 - 福利页 Tab 隐藏任务/里程碑,及看广告的单次金币/每轮次数/信息流开关:CONFIG_DEFS 加 hidden + list_config 过滤,业务读取默认值不受影响三、比价记录店/商品搜索 - comparison_record 加 product_names 派生列(从下单 items 拼商品名),迁移建列并回填历史行 - admin 比价记录列表店/商品分列可搜:走 product_names 普通列 LIKE,规避 SQLite JSON 中文 ensure_ascii 转义搜不到的坑 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: zzhyyyyy <2685922758@qq.com> Reviewed-on: #117 Co-authored-by: zhuzihao <zhuzihao@wonderable.ai> Co-committed-by: zhuzihao <zhuzihao@wonderable.ai>	2026-07-05 09:46:19 +08:00
guke	7b6756f936	feat(meituan-cps): 经纬度→城市离线反查 + rec/销量最高按城市过滤 (#116 ) ## 主要功能新增离线「经纬度 → 美团 cityId」反查,让 `rec`(智能推荐)与 `top-sales`(销量最高)从离线库只返同城券(此前会混返异地券)。 - `app/utils/geo.py` + `app/utils/meituan_city.py`:坐标 → 美团 `city_id`(reverse_geocoder 离线反查,零网络)。 - `feed?tab=rec` / `/top-sales`:按 `city_id` 过滤;解析不出 / 老客户端不带坐标 → 降级返空。 - `top-sales` 与 `rec` 一致置空库内距离(相对城市默认点、对用户无意义)。 --------- Co-authored-by: guke <guke@autohome.com.cn> Reviewed-on: #116 Co-authored-by: guke <guke@wonderable.ai> Co-committed-by: guke <guke@wonderable.ai>	2026-07-05 09:31:53 +08:00