Merge branch 'main' into feat/admin-api-db-docs

提现人工审核(提现不再即时打款):
- models/wallet.py: WithdrawOrder 状态机改为
  reviewing →(审核通过)→ pending → success/failed;reviewing →(驳回)→ rejected(已退款),
  默认态 pending → reviewing(扣现金建单但不打款);新增 user_name 列(实名, 微信达额转账要求)
- admin/routers/withdraw.py + admin/schemas/wallet.py: 运营后台审核接口(通过触发微信转账 / 驳回退款)
- api/v1/wallet.py + repositories/wallet.py: 发起提现进 reviewing 态, 驳回退回现金并写 withdraw_refund
- schemas/welfare.py: 提现出参增 reviewing/rejected 状态 + fail_reason

看广告每日时长限流(防刷主闸 + 次数兜底):
- 新增 models/ad_watch_log.py: 按 (user_id, watch_date) 聚合当日观看秒数
- 新增 repositories/ad_watch.py: watched_seconds_today / add_watch_seconds(夹 [0, MAX_SINGLE_WATCH_SECONDS])
- api/v1/ad.py: 新增 POST /ad/watch-report(JWT 取 user, 落时长返当日累计);
  /ad/reward-status 增 watched_seconds_today / limit / remaining
- schemas/ad.py: WatchReportIn/Out
- core/rewards.py: 新增 DAILY_AD_WATCH_SECONDS_LIMIT=50 分钟(主闸)+ MAX_SINGLE_WATCH_SECONDS=120;
  DAILY_AD_REWARD_LIMIT 20→200 改作次数兜底(防前端少报时长绕过时长闸, 又不误伤看短广告的正常用户)
- repositories/ad_reward.py + models/__init__.py: 接入新表与时长闸

alembic: withdraw_review_and_ad_watch 迁移(withdraw_order.user_name 列 + ad_watch_log 表)
tests: 补 test_ad_reward / test_withdraw

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

---------

Co-authored-by: pure <pure@192.168.0.104>
Reviewed-on: #15

.env.example

@@ -41,6 +41,35 @@ MT_CPS_APP_SECRET=
 # 默认渠道追踪标识(sid),用于区分不同 app 的 CPS 数据
 MT_CPS_DEFAULT_SID=sgbjia
 
+# ===== Pricebot 上游 (领券业务透传目标) =====
+# 客户端调本服务的 /api/v1/coupon/step,我们透传到 pricebot-backend 的 /api/coupon/step。
+# 本地开发用 localhost:8000。生产部署改成内网地址(如 http://pricebot.internal:8000)。
+PRICEBOT_BASE_URL=http://localhost:8000
+# 领券单帧最多 wait 6s,加网络往返,30s 兜底
+PRICEBOT_REQUEST_TIMEOUT_SEC=30
+
 # ===== CORS =====
 # 逗号分隔,生产留空(只让 app 调,不开放 web)。本地开发可加 http://localhost:5173 之类
 CORS_ALLOW_ORIGINS=
+
+# ===== 微信支付(商家转账到零钱 / 提现)=====
+# appid/secret 来自微信开放平台移动应用;mch/序列号/公钥ID 来自微信支付商户平台。
+# 证书 .pem 放 secrets/(已 gitignore)。
+WECHAT_APP_ID=wxxxxxxxxxxxxxxxxx
+WECHAT_APP_SECRET=your_app_secret
+WXPAY_MCH_ID=your_mch_id
+WXPAY_MCH_SERIAL_NO=your_cert_serial_no
+WXPAY_MCH_PRIVATE_KEY_PATH=./secrets/apiclient_key.pem
+WXPAY_PUBLIC_KEY_ID=PUB_KEY_ID_xxxxxxxx
+WXPAY_PUBLIC_KEY_PATH=./secrets/pub_key.pem
+WXPAY_TRANSFER_SCENE_ID=1000
+
+# ===== 穿山甲激励视频(服务端发奖回调)=====
+# 看完激励视频后穿山甲服务器 S2S 回调本服务发金币(客户端不参与发奖)。
+# PANGLE_REWARD_SECRET 是穿山甲后台配置的"奖励校验密钥",用于验签,从后台取到后填这里;
+# 配齐并把 ENABLED=true 后,/api/v1/ad/pangle-callback 才受理回调(否则 503)。
+PANGLE_CALLBACK_ENABLED=false
+PANGLE_REWARD_SECRET=
+# ⚠️ 仅本地联调:true 时开放 POST /api/v1/ad/test-grant,让 debug 客户端看完广告直接发奖,
+# 验证"看广告→金币到账"全链路(未部署公网、穿山甲 S2S 打不到本地时用)。生产必须 false(绕过反作弊)。
+AD_REWARD_TEST_GRANT_ENABLED=false

.gitignore

@@ -34,3 +34,6 @@ secrets/*
 .idea/
 .vscode/
 *.swp
+
+# 运行日志(run.sh 输出, 不入库)
+*.log

README.md

@@ -2,10 +2,15 @@
 
 傻瓜比价正式 App 后端 — FastAPI + SQLAlchemy + JWT。
 
-> 占坑期已有的试验后台 `shaguabijia-server` 是无状态 mock,本项目是正式版,
-> 引入账号体系、JWT 登录态、Alembic 迁移、SQLite 起步可平滑切 PostgreSQL。
+覆盖:**账号体系**(极光一键登录 / 短信登录 + JWT)、**福利钱包**(金币 / 现金 / 签到 / 任务 / 省钱战绩)、**微信提现**(商家转账到零钱)、**看广告发奖**(穿山甲 GroMore S2S 回调)、**美团 CPS**(领券透传 / 比价推荐)。
 
-详细技术说明见 [docs/后端技术实现.md](docs/后端技术实现.md)(登录链路、极光 RSA、部署 checklist)。
+> 占坑期的试验后台 `shaguabijia-server` 是无状态 mock;本项目是正式版,引入账号体系、JWT 登录态、Alembic 迁移,SQLite 起步可平滑切 PostgreSQL。
+
+**文档导航**(都在 [docs/](docs/README.md)):
+- [docs/api/](docs/api/README.md) — **接口契约**(索引 + 一接口一文件)
+- [docs/integrations/](docs/integrations/README.md) — **集成层**(SDK 签名 / 加解密 / 协议细节)
+- [docs/后端技术实现.md](docs/后端技术实现.md) — **架构与链路**(分层、登录、CPS、数据模型)
+- [docs/数据库迁移.md](docs/数据库迁移.md) — **数据库迁移**(Alembic 怎么建表 / 升级)
 
 ---
 
@@ -16,57 +21,75 @@
 | 语言 | Python 3.11+ | |
 | Web | FastAPI 0.115+ | |
 | ASGI | uvicorn[standard] | |
-| ORM | SQLAlchemy 2.0 | Mapped/DeclarativeBase 新风格 |
+| ORM | SQLAlchemy 2.0 | Mapped / DeclarativeBase 新风格 |
 | 迁移 | Alembic | render_as_batch 兼容 SQLite |
-| DB | SQLite | 后续切 PostgreSQL 只改 `DATABASE_URL` |
+| DB | SQLite 起步 | 切 PostgreSQL 只改 `DATABASE_URL` |
 | Auth | JWT (PyJWT) | access(2h) + refresh(30d) |
-| 极光一键登录 | httpx + cryptography | RSA 解密,逻辑参考试验后台 |
+| HTTP 客户端 | httpx | 调极光 / 微信 / 美团 / 穿山甲 |
+| 加解密 | cryptography | 极光 RSA 解密、微信 V3 签名 / 敏感字段加密 |
+| 微信支付 | 商家转账到零钱 V3 | 提现;懒加载商户证书 |
 | 配置 | pydantic-settings | `.env` 加载 |
 | 测试 | pytest + TestClient | |
 
 ---
 
+## 架构分层
+
+一个请求自上而下:**api(薄,收发) → integrations(外部 SDK) / repositories(数据) → models / db**。
+
+- `api/v1/` 只做"解析请求 → 调 repositories/integration → 组装响应 + HTTP 错误码映射",不放重逻辑。
+- **SDK 集成的重逻辑(签名 / 验签 / 加解密 / 外部 HTTP)一律在 `integrations/`**,换方案 / 换供应商只动这一层。
+- 数据访问统一在 `repositories/`(早期叫 `crud/`,已并入)。
+
 ## 目录结构
 
 ```
 shaguabijia-app-server/
 ├── app/
-│   ├── main.py                FastAPI 入口 + /health + CORS
-│   ├── core/
+│   ├── main.py                FastAPI 入口:注册全部 router + /health + CORS + lifespan
+│   ├── api/
+│   │   ├── deps.py            共享依赖:get_current_user(Bearer 校验)、get_db
+│   │   └── v1/                接口层(薄)
+│   │       ├── auth.py        认证 6 端点(极光 / 短信 send+login / refresh / me / logout)
+│   │       ├── wallet.py      钱包 / 提现 11 端点(余额 / 流水 / 兑换 / 绑微信 / 提现 / 查单)
+│   │       ├── signin.py      签到 2 端点
+│   │       ├── tasks.py       一次性任务 2 端点
+│   │       ├── savings.py     省钱 3 端点(汇总 / 战绩 / 明细)
+│   │       ├── ad.py          看广告发奖 3 端点(穿山甲回调 / 进度 / 联调发奖)
+│   │       ├── coupon.py      领券透传 /coupon/step(转发 pricebot)
+│   │       └── meituan.py     美团 CPS 3 端点(券列表 / feed / 换链)
+│   ├── integrations/          外部服务 / SDK 客户端(重逻辑)
+│   │   ├── jiguang.py         极光 REST 验 token + RSA 解密(多 padding 试错)
+│   │   ├── sms.py             短信验证码(mock,进程内冷却表)
+│   │   ├── meituan.py         美团 CPS 网关签名 + query_coupon / get_referral_link
+│   │   ├── pangle.py          穿山甲激励视频发奖回调验签(SHA256)
+│   │   └── wxpay.py           微信支付 V3 商家转账(提现)+ code 换 openid
+│   ├── core/                  基础设施(无外部业务集成)
 │   │   ├── config.py          Settings (pydantic-settings)
-│   │   ├── logging.py         统一日志配置
 │   │   ├── security.py        JWT 签发 / 校验 / token 对
-│   │   ├── jiguang.py         极光 REST 调用 + RSA 解密
-│   │   └── sms.py             短信验证码 (mock 实现)
-│   ├── db/
-│   │   ├── base.py            DeclarativeBase
-│   │   └── session.py         engine + SessionLocal + get_db
-│   ├── models/
-│   │   └── user.py            User 表
-│   ├── schemas/
-│   │   └── auth.py            登录/Token 相关 Pydantic
-│   ├── crud/
-│   │   └── user.py            upsert_user_for_login 等
-│   └── api/
-│       ├── deps.py            get_current_user (Bearer 校验)
-│       └── v1/
-│           └── auth.py        /api/v1/auth/* 路由
+│   │   ├── ratelimit.py       同 IP 滑动窗口限流依赖
+│   │   ├── rewards.py         发奖 / 兑换 / 提现额度等业务常量与换算
+│   │   └── logging.py         统一日志配置
+│   ├── repositories/          数据访问 + 事务(早期叫 crud,已并入)
+│   │   ├── user.py            upsert_user_for_login 等
+│   │   ├── wallet.py          账户 / 流水 / 兑换 / 提现单(调 integrations/wxpay)
+│   │   ├── signin.py          签到记录 / 连续天数 / 档位
+│   │   ├── task.py            一次性任务领取
+│   │   ├── savings.py         省钱汇总 / 战绩 / 明细
+│   │   └── ad_reward.py       看广告发奖(按 trans_id 幂等 + 每日上限)
+│   ├── models/                ORM 表结构(user / wallet / signin / task / savings / ad_reward)
+│   ├── schemas/               Pydantic 收发契约(auth / meituan / welfare / ad)
+│   └── db/                    base.py(DeclarativeBase) + session.py(engine / get_db)
 │
-├── alembic/                   迁移脚本
-│   ├── env.py
-│   ├── script.py.mako
-│   └── versions/              (空,第一次跑 alembic revision 生成)
+├── alembic/                   数据库迁移(versions/ 9 个迁移;文件名已去 hex 前缀,链靠文件内 down_revision)
 ├── alembic.ini
-│
-├── deploy/
-│   ├── shaguabijia-app-server.service   systemd unit
-│   └── nginx/
-│       └── app-api.shaguabijia.com.conf
-│
-├── secrets/                   不入 git。放 jverify_rsa_private.pem
-├── data/                      不入 git。SQLite 文件默认在这里
-├── tests/                     冒烟 + auth 流程
-│
+├── deploy/                    systemd(.service) + nginx(.conf)
+├── secrets/                   不入 git:极光 RSA 私钥 / 微信支付证书
+├── data/                      不入 git:SQLite 文件默认在这里
+├── scripts/                   运维脚本(migrate 迁移 / 对账 / 重置签到·福利 / 模拟穿山甲回调)
+├── tests/                     pytest(auth / health / welfare / withdraw / ad_reward / coupon_proxy)
+├── docs/                      文档库(api/ + integrations/ + 技术实现 / 迁移 / 待办)
+├── run.sh                     本地启动(自动先跑迁移再起服务)
 ├── pyproject.toml
 ├── .env.example
 └── README.md
@@ -76,98 +99,63 @@ shaguabijia-app-server/
 
 ## API 接口
 
-| 方法 | 路径 | 说明 | 鉴权 |
+完整契约见 **[docs/api/README.md](docs/api/README.md)**(总览表 + 一接口一文件)。按组速览:
+
+| 组 | 前缀 | 端点数 | 鉴权 |
 |---|---|---|---|
-| GET  | `/health` | 健康检查 | 无 |
-| POST | `/api/v1/auth/jverify-login` | 极光一键登录(`loginToken` → 注册即登录 → 签发 token 对) | 无 |
-| POST | `/api/v1/auth/sms/send` | 发短信验证码(mock 阶段任意 6 位通过) | 无 |
-| POST | `/api/v1/auth/sms/login` | 手机号+验证码登录 | 无 |
-| POST | `/api/v1/auth/refresh` | 用 `refresh_token` 换新的 token 对 | 无 |
-| GET  | `/api/v1/auth/me` | 获取当前登录用户 | `Bearer access_token` |
-| POST | `/api/v1/auth/logout` | 登出(占位,客户端清 token) | `Bearer access_token` |
+| 健康检查 | `/health` | 1 | 无 |
+| 认证 Auth | `/api/v1/auth` | 6 | 登录类无 / `me`·`logout` Bearer |
+| 钱包·提现 Wallet | `/api/v1/wallet` | 11 | Bearer(`exchange-info` 无) |
+| 签到 Signin | `/api/v1/signin` | 2 | Bearer |
+| 任务 Tasks | `/api/v1/tasks` | 2 | Bearer |
+| 省钱 Savings | `/api/v1/savings` | 3 | Bearer |
+| 看广告发奖 Ad | `/api/v1/ad` | 3 | 回调验签 / 其余 Bearer |
+| 领券 Coupon | `/api/v1/coupon` | 1 | Bearer |
+| 美团 CPS Meituan | `/api/v1/meituan` | 3 | 无 |
 
-登录类接口的响应统一格式:
-```json
-{
-  "access_token": "eyJxxx...",
-  "refresh_token": "eyJxxx...",
-  "token_type": "Bearer",
-  "expires_in": 7200,
-  "refresh_expires_in": 2592000,
-  "user": {
-    "id": 1,
-    "phone": "13800138000",
-    "nickname": null,
-    "avatar_url": null,
-    "register_channel": "jverify",
-    "status": "active",
-    "created_at": "2026-05-23T04:30:00Z",
-    "last_login_at": "2026-05-23T04:30:00Z"
-  }
-}
-```
-
-文档启动后看 `http://localhost:8770/docs` (Swagger UI)。
+登录类接口响应统一是 `TokenWithUser`(access/refresh token 对 + user);金额字段一律以**分**为单位(`*_cents`)。`APP_ENV` 非 prod 时开 `http://localhost:8770/docs`(Swagger UI)。
 
 ---
 
 ## 本地开发
 
 ### 1. 装依赖
-
 ```bash
 cd shaguabijia-app-server
 python3.11 -m venv .venv
-source .venv/bin/activate
+source .venv/bin/activate      # Windows: .venv\Scripts\activate
 pip install -e ".[dev]"
 ```
 
-### 2. 准备配置
-
+### 2. 配置
 ```bash
 cp .env.example .env
-# 编辑 .env,生产部署务必改 JWT_SECRET_KEY
+# 至少改 JWT_SECRET_KEY;测美团填 MT_CPS_*;测提现填 WXPAY_*/WECHAT_*;测看广告填 PANGLE_*
 ```
+测极光一键登录把 RSA 私钥放到 `./secrets/jverify_rsa_private.pem`(没放也不影响其他接口,只是 `jverify-login` 返 502)。
 
-如果要测极光一键登录,把 RSA 私钥放到 `./secrets/jverify_rsa_private.pem`。
-没放也不影响其他接口(`sms`/`/health` 等),只是 `jverify-login` 会 502。
-
-### 3. 建表(首次)
-
+### 3. 建表 / 升级数据库
 ```bash
-# 生成首版 migration(已有 User model,会自动生成 create_table)
-alembic revision --autogenerate -m "init user table"
-# 应用 migration
-alembic upgrade head
-```
-
-后续改 model 后:
-```bash
-alembic revision --autogenerate -m "add nickname index"
-alembic upgrade head
+mkdir -p data            # SQLite 库目录
+alembic upgrade head     # 按迁移链建到最新(幂等)
 ```
+> 详见 [docs/数据库迁移.md](docs/数据库迁移.md)。只想迁移不启服务:`bash scripts/migrate.sh`。
 
 ### 4. 跑起来
-
 ```bash
-uvicorn app.main:app --reload --port 8770
+./run.sh                 # 监听 0.0.0.0:8770,自动先跑迁移;改代码自动重启
+# 或手动: uvicorn app.main:app --reload --port 8770
 ```
-
 冒烟:
 ```bash
-curl http://localhost:8770/health
-# {"status":"ok"}
-
-# mock 走通登录闭环
-curl -X POST http://localhost:8770/api/v1/auth/sms/send -H 'Content-Type: application/json' -d '{"phone":"13800138000"}'
-
+curl http://localhost:8770/health        # {"status":"ok"}
+# mock 登录闭环
+curl -X POST http://localhost:8770/api/v1/auth/sms/send  -H 'Content-Type: application/json' -d '{"phone":"13800138000"}'
 curl -X POST http://localhost:8770/api/v1/auth/sms/login -H 'Content-Type: application/json' -d '{"phone":"13800138000","code":"123456"}'
-# 拿到 access_token 后:
 curl http://localhost:8770/api/v1/auth/me -H "Authorization: Bearer <access_token>"
 ```
 
 ### 5. 测试
-
 ```bash
 pytest -q
 ```
@@ -176,17 +164,13 @@ pytest -q
 
 ## 部署(生产)
 
-参考 `deploy/`,部署到 `app-api.shaguabijia.com`:
-
+部署到 `app-api.shaguabijia.com`(参考 `deploy/`):
 ```bash
-# 一次性
-ssh server "apt-get install -y python3.11-venv python3-pip"
-
 # 后续更新
-rsync -avz --exclude='__pycache__' --exclude='.venv' --exclude='data' --exclude='secrets/jverify_rsa_private.pem' \
+rsync -avz --exclude='__pycache__' --exclude='.venv' --exclude='data' --exclude='secrets/*' \
     ./ server:/opt/shaguabijia-app-server/
 
-# 私钥单独同步(只首次 / 私钥更换时)
+# 证书 / 私钥单独同步(首次 / 更换时):极光私钥 + 微信支付商户私钥·平台公钥
 scp secrets/jverify_rsa_private.pem server:/opt/shaguabijia-app-server/secrets/
 
 ssh server "
@@ -196,8 +180,7 @@ ssh server "
     systemctl restart shaguabijia-app-server
 "
 ```
-
-详见 `deploy/shaguabijia-app-server.service` 和 `deploy/nginx/app-api.shaguabijia.com.conf`。
+详见 `deploy/`。**看广告发奖上线**前对照 [docs/看广告赚金币上线清单.md](docs/看广告赚金币上线清单.md)(GroMore 回调配置、清理调试脚手架、端到端验收)。
 
 ---
 
@@ -206,11 +189,9 @@ ssh server "
 | 维度 | 试验后台 (shaguabijia-server) | 本项目 (shaguabijia-app-server) |
 |---|---|---|
 | 数据库 | stdlib sqlite3,无 ORM | SQLAlchemy 2.0 + Alembic |
-| 业务 | mock parse(无账号体系) | 完整账号体系 + JWT |
-| 登录态 | 无,客户端发 phone 当 ID | JWT access+refresh |
+| 业务 | mock parse(无账号体系) | 账号 + 钱包 / 提现 / 签到 / 看广告 / CPS |
+| 登录态 | 无,客户端发 phone 当 ID | JWT access + refresh |
 | 配置 | 硬编码 | pydantic-settings + `.env` |
-| 短信登录 | 无 | 有(mock 实现,留扩展点) |
-| 域名 | api.shaguabijia.com (试验) | app-api.shaguabijia.com (正式) |
+| 域名 | api.shaguabijia.com(试验) | app-api.shaguabijia.com(正式) |
 
-极光一键登录的具体实现(REST 调用、RSA padding 试错顺序)直接参考自试验后台,
-逻辑等价。
+极光一键登录的实现(REST 调用、RSA padding 试错顺序)参考自试验后台,逻辑等价。

alembic/versions/8ac524a8ea02_merge_comparison_and_savings_heads.py

@@ -0,0 +1,26 @@
+"""merge comparison and savings heads
+
+Revision ID: 8ac524a8ea02
+Revises: d4e5f6a7b8c9, savings_report_fields
+Create Date: 2026-06-02 09:53:06.924912
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '8ac524a8ea02'
+down_revision: Union[str, Sequence[str], None] = ('d4e5f6a7b8c9', 'savings_report_fields')
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    pass
+
+
+def downgrade() -> None:
+    pass

alembic/versions/9258bddde4ea_新增_price_report_上报更低价表.py

@@ -0,0 +1,65 @@
+"""新增 price_report 上报更低价表
+
+Revision ID: 9258bddde4ea
+Revises: ad60a1b2c3d4
+Create Date: 2026-06-05 10:15:51.508598
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '9258bddde4ea'
+down_revision: Union[str, Sequence[str], None] = 'ad60a1b2c3d4'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table('price_report',
+    sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
+    sa.Column('user_id', sa.Integer(), nullable=False),
+    sa.Column('comparison_record_id', sa.Integer(), nullable=True),
+    sa.Column('store_name', sa.String(length=128), nullable=True),
+    sa.Column('dish_summary', sa.String(length=256), nullable=True),
+    sa.Column('original_platform_id', sa.String(length=32), nullable=True),
+    sa.Column('original_platform_name', sa.String(length=32), nullable=True),
+    sa.Column('original_price_cents', sa.Integer(), nullable=True),
+    sa.Column('reported_platform_id', sa.String(length=32), nullable=False),
+    sa.Column('reported_platform_name', sa.String(length=32), nullable=False),
+    sa.Column('reported_price_cents', sa.Integer(), nullable=False),
+    sa.Column('images', sa.JSON(), nullable=False),
+    sa.Column('status', sa.String(length=16), nullable=False),
+    sa.Column('reject_reason', sa.String(length=256), nullable=True),
+    sa.Column('reward_coins', sa.Integer(), nullable=True),
+    sa.Column('reviewed_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.text('(CURRENT_TIMESTAMP)'), nullable=False),
+    sa.ForeignKeyConstraint(['comparison_record_id'], ['comparison_record.id'], ),
+    sa.ForeignKeyConstraint(['user_id'], ['user.id'], ),
+    sa.PrimaryKeyConstraint('id')
+    )
+    with op.batch_alter_table('price_report', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_price_report_comparison_record_id'), ['comparison_record_id'], unique=False)
+        batch_op.create_index(batch_op.f('ix_price_report_created_at'), ['created_at'], unique=False)
+        batch_op.create_index(batch_op.f('ix_price_report_status'), ['status'], unique=False)
+        batch_op.create_index(batch_op.f('ix_price_report_user_id'), ['user_id'], unique=False)
+    # 注:autogenerate 另检测到「删除 order_record 表」——那是已降级为审计的历史表
+    #     (model 已移除、库表保留),与本次无关,手动剔除,避免误删他人审计数据。
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    # (对称:upgrade 未删 order_record,downgrade 也不重建它)
+    with op.batch_alter_table('price_report', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_price_report_user_id'))
+        batch_op.drop_index(batch_op.f('ix_price_report_status'))
+        batch_op.drop_index(batch_op.f('ix_price_report_created_at'))
+        batch_op.drop_index(batch_op.f('ix_price_report_comparison_record_id'))
+
+    op.drop_table('price_report')
+    # ### end Alembic commands ###

alembic/versions/ad_ecpm_record.py

@@ -0,0 +1,47 @@
+"""ad_ecpm_record table (广告展示 eCPM 上报记录,内部收益统计/对账)
+
+Revision ID: a1b2c3d4e5f6
+Revises: f01db5d77dac
+Create Date: 2026-05-31 11:30:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'a1b2c3d4e5f6'
+down_revision: Union[str, Sequence[str], None] = 'f01db5d77dac'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        'ad_ecpm_record',
+        sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
+        sa.Column('user_id', sa.Integer(), nullable=False),
+        sa.Column('ad_type', sa.String(length=32), nullable=False),
+        sa.Column('adn', sa.String(length=32), nullable=True),
+        sa.Column('slot_id', sa.String(length=64), nullable=True),
+        sa.Column('ecpm_raw', sa.String(length=32), nullable=False),
+        sa.Column('report_date', sa.String(length=10), nullable=False),
+        sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.text('(CURRENT_TIMESTAMP)'), nullable=False),
+        sa.ForeignKeyConstraint(['user_id'], ['user.id'], ),
+        sa.PrimaryKeyConstraint('id'),
+    )
+    with op.batch_alter_table('ad_ecpm_record', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_ad_ecpm_record_user_id'), ['user_id'], unique=False)
+        batch_op.create_index(batch_op.f('ix_ad_ecpm_record_report_date'), ['report_date'], unique=False)
+        batch_op.create_index(batch_op.f('ix_ad_ecpm_record_created_at'), ['created_at'], unique=False)
+
+
+def downgrade() -> None:
+    with op.batch_alter_table('ad_ecpm_record', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_ad_ecpm_record_created_at'))
+        batch_op.drop_index(batch_op.f('ix_ad_ecpm_record_report_date'))
+        batch_op.drop_index(batch_op.f('ix_ad_ecpm_record_user_id'))
+
+    op.drop_table('ad_ecpm_record')

alembic/versions/ad_reward_record.py

@@ -0,0 +1,50 @@
+"""ad_reward_record table (看激励视频发奖记录)
+
+Revision ID: c8d9e0f1a2b3
+Revises: b1c2d3e4f5a6
+Create Date: 2026-05-26 10:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'c8d9e0f1a2b3'
+down_revision: Union[str, Sequence[str], None] = 'b1c2d3e4f5a6'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        'ad_reward_record',
+        sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
+        sa.Column('trans_id', sa.String(length=64), nullable=False),
+        sa.Column('user_id', sa.Integer(), nullable=False),
+        sa.Column('coin', sa.Integer(), nullable=False),
+        sa.Column('status', sa.String(length=16), nullable=False),
+        sa.Column('reward_date', sa.String(length=10), nullable=False),
+        sa.Column('reward_name', sa.String(length=64), nullable=True),
+        sa.Column('raw', sa.String(length=1024), nullable=True),
+        sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.text('(CURRENT_TIMESTAMP)'), nullable=False),
+        sa.ForeignKeyConstraint(['user_id'], ['user.id'], ),
+        sa.PrimaryKeyConstraint('id'),
+    )
+    with op.batch_alter_table('ad_reward_record', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_ad_reward_record_trans_id'), ['trans_id'], unique=True)
+        batch_op.create_index(batch_op.f('ix_ad_reward_record_user_id'), ['user_id'], unique=False)
+        batch_op.create_index(batch_op.f('ix_ad_reward_record_reward_date'), ['reward_date'], unique=False)
+        batch_op.create_index(batch_op.f('ix_ad_reward_record_created_at'), ['created_at'], unique=False)
+
+
+def downgrade() -> None:
+    with op.batch_alter_table('ad_reward_record', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_ad_reward_record_created_at'))
+        batch_op.drop_index(batch_op.f('ix_ad_reward_record_reward_date'))
+        batch_op.drop_index(batch_op.f('ix_ad_reward_record_user_id'))
+        batch_op.drop_index(batch_op.f('ix_ad_reward_record_trans_id'))
+
+    op.drop_table('ad_reward_record')

alembic/versions/admin_tables.py

@@ -0,0 +1,65 @@
+"""admin_user + admin_audit_log tables (运营 admin 后台:账号 + 操作审计)
+
+Revision ID: ad60a1b2c3d4
+Revises: 8ac524a8ea02
+Create Date: 2026-06-03 10:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'ad60a1b2c3d4'
+down_revision: Union[str, Sequence[str], None] = '8ac524a8ea02'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        'admin_user',
+        sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
+        sa.Column('username', sa.String(length=64), nullable=False),
+        sa.Column('password_hash', sa.String(length=255), nullable=False),
+        sa.Column('role', sa.String(length=20), nullable=False, server_default='operator'),
+        sa.Column('status', sa.String(length=20), nullable=False, server_default='active'),
+        sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.text('(CURRENT_TIMESTAMP)'), nullable=False),
+        sa.Column('last_login_at', sa.DateTime(timezone=True), nullable=True),
+        sa.PrimaryKeyConstraint('id'),
+    )
+    with op.batch_alter_table('admin_user', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_admin_user_username'), ['username'], unique=True)
+
+    op.create_table(
+        'admin_audit_log',
+        sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
+        sa.Column('admin_id', sa.Integer(), nullable=False),
+        sa.Column('admin_username', sa.String(length=64), nullable=False),
+        sa.Column('action', sa.String(length=64), nullable=False),
+        sa.Column('target_type', sa.String(length=32), nullable=False),
+        sa.Column('target_id', sa.String(length=64), nullable=True),
+        sa.Column('detail', sa.JSON().with_variant(sa.dialects.postgresql.JSONB(), 'postgresql'), nullable=True),
+        sa.Column('ip', sa.String(length=64), nullable=True),
+        sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.text('(CURRENT_TIMESTAMP)'), nullable=False),
+        sa.ForeignKeyConstraint(['admin_id'], ['admin_user.id'], ),
+        sa.PrimaryKeyConstraint('id'),
+    )
+    with op.batch_alter_table('admin_audit_log', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_admin_audit_log_admin_id'), ['admin_id'], unique=False)
+        batch_op.create_index(batch_op.f('ix_admin_audit_log_action'), ['action'], unique=False)
+        batch_op.create_index(batch_op.f('ix_admin_audit_log_created_at'), ['created_at'], unique=False)
+
+
+def downgrade() -> None:
+    with op.batch_alter_table('admin_audit_log', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_admin_audit_log_created_at'))
+        batch_op.drop_index(batch_op.f('ix_admin_audit_log_action'))
+        batch_op.drop_index(batch_op.f('ix_admin_audit_log_admin_id'))
+    op.drop_table('admin_audit_log')
+
+    with op.batch_alter_table('admin_user', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_admin_user_username'))
+    op.drop_table('admin_user')

alembic/versions/app_config_table.py

@@ -0,0 +1,33 @@
+"""app_config table (运营可配置项:rewards 常量等后台化)
+
+Revision ID: cfg1a2b3c4d5
+Revises: ad60a1b2c3d4
+Create Date: 2026-06-04 12:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'cfg1a2b3c4d5'
+down_revision: Union[str, Sequence[str], None] = 'ad60a1b2c3d4'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        'app_config',
+        sa.Column('key', sa.String(length=64), nullable=False),
+        sa.Column('value', sa.JSON().with_variant(sa.dialects.postgresql.JSONB(), 'postgresql'), nullable=False),
+        sa.Column('updated_by_admin_id', sa.Integer(), nullable=True),
+        sa.Column('updated_at', sa.DateTime(timezone=True), server_default=sa.text('(CURRENT_TIMESTAMP)'), nullable=False),
+        sa.PrimaryKeyConstraint('key'),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table('app_config')

alembic/versions/b7e2c1a9f4d3_comparison_record_best_deeplink.py

@@ -0,0 +1,32 @@
+"""comparison_record 加 best_deeplink(再次比价直达商家深链)
+
+Revision ID: b7e2c1a9f4d3
+Revises: 9258bddde4ea
+Create Date: 2026-06-05
+
+「再次比价」要直达上次最低价平台的商家/商品页。深链(link)在比价时客户端已从剪贴板采到
+(collectedLinks[best_index]),本列把它落库;再次比价时写剪贴板 + launch 该平台 App 直达。
+旧记录无此列值(None) → 前端降级为打开对应 App 首页。
+
+手写迁移(只加一列):autogenerate 会误报"删 order_record"(降级为审计的历史表,model 已移除、
+库表保留),手写规避该噪音。
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+revision: str = "b7e2c1a9f4d3"
+down_revision: Union[str, Sequence[str], None] = "9258bddde4ea"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    with op.batch_alter_table("comparison_record", schema=None) as batch_op:
+        batch_op.add_column(sa.Column("best_deeplink", sa.String(length=1024), nullable=True))
+
+
+def downgrade() -> None:
+    with op.batch_alter_table("comparison_record", schema=None) as batch_op:
+        batch_op.drop_column("best_deeplink")

alembic/versions/c64a944a6139_add_order_record_table.py

@@ -1,49 +0,0 @@
-"""add order_record table
-
-Revision ID: c64a944a6139
-Revises: 9c559acc164a
-Create Date: 2026-05-26 21:09:40.047619
-
-"""
-from typing import Sequence, Union
-
-from alembic import op
-import sqlalchemy as sa
-
-
-# revision identifiers, used by Alembic.
-revision: str = 'c64a944a6139'
-down_revision: Union[str, Sequence[str], None] = '9c559acc164a'
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    # ### commands auto generated by Alembic - please adjust! ###
-    op.create_table('order_record',
-    sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
-    sa.Column('user_id', sa.Integer(), nullable=False),
-    sa.Column('platform', sa.String(length=30), nullable=False),
-    sa.Column('store_name', sa.String(length=128), nullable=False),
-    sa.Column('dishes', sa.Text(), nullable=False),
-    sa.Column('order_date', sa.String(length=10), nullable=False),
-    sa.Column('price', sa.String(length=20), nullable=False),
-    sa.Column('original_price', sa.String(length=20), nullable=True),
-    sa.Column('savings', sa.String(length=20), nullable=True),
-    sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.text('(CURRENT_TIMESTAMP)'), nullable=False),
-    sa.ForeignKeyConstraint(['user_id'], ['user.id'], ),
-    sa.PrimaryKeyConstraint('id')
-    )
-    with op.batch_alter_table('order_record', schema=None) as batch_op:
-        batch_op.create_index(batch_op.f('ix_order_record_user_id'), ['user_id'], unique=False)
-
-    # ### end Alembic commands ###
-
-
-def downgrade() -> None:
-    # ### commands auto generated by Alembic - please adjust! ###
-    with op.batch_alter_table('order_record', schema=None) as batch_op:
-        batch_op.drop_index(batch_op.f('ix_order_record_user_id'))
-
-    op.drop_table('order_record')
-    # ### end Alembic commands ###

alembic/versions/cash_transaction_table.py

@@ -0,0 +1,49 @@
+"""cash_transaction table
+
+Revision ID: 3d9cb19df76f
+Revises: 357520ea3015
+Create Date: 2026-05-24 16:21:22.950992
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '3d9cb19df76f'
+down_revision: Union[str, Sequence[str], None] = '357520ea3015'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table('cash_transaction',
+    sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
+    sa.Column('user_id', sa.Integer(), nullable=False),
+    sa.Column('amount_cents', sa.Integer(), nullable=False),
+    sa.Column('balance_after_cents', sa.Integer(), nullable=False),
+    sa.Column('biz_type', sa.String(length=32), nullable=False),
+    sa.Column('ref_id', sa.String(length=64), nullable=True),
+    sa.Column('remark', sa.String(length=128), nullable=True),
+    sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.text('(CURRENT_TIMESTAMP)'), nullable=False),
+    sa.ForeignKeyConstraint(['user_id'], ['user.id'], ),
+    sa.PrimaryKeyConstraint('id')
+    )
+    with op.batch_alter_table('cash_transaction', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_cash_transaction_created_at'), ['created_at'], unique=False)
+        batch_op.create_index(batch_op.f('ix_cash_transaction_user_id'), ['user_id'], unique=False)
+
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    with op.batch_alter_table('cash_transaction', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_cash_transaction_user_id'))
+        batch_op.drop_index(batch_op.f('ix_cash_transaction_created_at'))
+
+    op.drop_table('cash_transaction')
+    # ### end Alembic commands ###

alembic/versions/comparison_milestone_claim_table.py

@@ -0,0 +1,41 @@
+"""comparison_milestone_claim table (比价战绩里程碑领取记录)
+
+Revision ID: d4e5f6a7b8c9
+Revises: c3d4e5f6a7b8
+Create Date: 2026-05-31 18:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'd4e5f6a7b8c9'
+down_revision: Union[str, Sequence[str], None] = 'c3d4e5f6a7b8'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        'comparison_milestone_claim',
+        sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
+        sa.Column('user_id', sa.Integer(), nullable=False),
+        sa.Column('milestone', sa.Integer(), nullable=False),
+        sa.Column('coin_awarded', sa.Integer(), nullable=False),
+        sa.Column('claimed_at', sa.DateTime(timezone=True), server_default=sa.text('(CURRENT_TIMESTAMP)'), nullable=False),
+        sa.ForeignKeyConstraint(['user_id'], ['user.id'], ),
+        sa.PrimaryKeyConstraint('id'),
+        sa.UniqueConstraint('user_id', 'milestone', name='uq_compare_milestone_user'),
+    )
+    with op.batch_alter_table('comparison_milestone_claim', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_comparison_milestone_claim_user_id'), ['user_id'], unique=False)
+
+
+def downgrade() -> None:
+    with op.batch_alter_table('comparison_milestone_claim', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_comparison_milestone_claim_user_id'))
+
+    op.drop_table('comparison_milestone_claim')

alembic/versions/comparison_record_information.py

@@ -0,0 +1,28 @@
+"""comparison_record.information (done 帧文案/失败原因)
+
+Revision ID: c3d4e5f6a7b8
+Revises: b2c3d4e5f6a7
+Create Date: 2026-05-31 18:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'c3d4e5f6a7b8'
+down_revision: Union[str, Sequence[str], None] = 'b2c3d4e5f6a7'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    with op.batch_alter_table('comparison_record', schema=None) as batch_op:
+        batch_op.add_column(sa.Column('information', sa.String(length=256), nullable=True))
+
+
+def downgrade() -> None:
+    with op.batch_alter_table('comparison_record', schema=None) as batch_op:
+        batch_op.drop_column('information')

alembic/versions/comparison_record_table.py

@@ -0,0 +1,64 @@
+"""comparison_record table (比价记录:每次比价完整明细,「我的比价记录」数据源)
+
+Revision ID: b2c3d4e5f6a7
+Revises: a1b2c3d4e5f6
+Create Date: 2026-05-31 15:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'b2c3d4e5f6a7'
+down_revision: Union[str, Sequence[str], None] = 'a1b2c3d4e5f6'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        'comparison_record',
+        sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
+        sa.Column('user_id', sa.Integer(), nullable=False),
+        sa.Column('device_id', sa.String(length=64), nullable=True),
+        sa.Column('business_type', sa.String(length=16), nullable=False),
+        sa.Column('trace_id', sa.String(length=64), nullable=False),
+        sa.Column('source_platform_id', sa.String(length=32), nullable=True),
+        sa.Column('source_platform_name', sa.String(length=32), nullable=True),
+        sa.Column('source_package', sa.String(length=128), nullable=True),
+        sa.Column('source_price_cents', sa.Integer(), nullable=True),
+        sa.Column('best_platform_id', sa.String(length=32), nullable=True),
+        sa.Column('best_platform_name', sa.String(length=32), nullable=True),
+        sa.Column('best_price_cents', sa.Integer(), nullable=True),
+        sa.Column('saved_amount_cents', sa.Integer(), nullable=True),
+        sa.Column('is_source_best', sa.Boolean(), nullable=True),
+        sa.Column('store_name', sa.String(length=128), nullable=True),
+        sa.Column('total_dish_count', sa.Integer(), nullable=True),
+        sa.Column('skipped_dish_count', sa.Integer(), nullable=True),
+        sa.Column('status', sa.String(length=16), nullable=False),
+        # PG 上为 JSONB,其它(SQLite)为 JSON——与模型层 with_variant 对齐
+        sa.Column('items', sa.JSON().with_variant(sa.dialects.postgresql.JSONB(), 'postgresql'), nullable=False),
+        sa.Column('comparison_results', sa.JSON().with_variant(sa.dialects.postgresql.JSONB(), 'postgresql'), nullable=False),
+        sa.Column('skipped_dish_names', sa.JSON().with_variant(sa.dialects.postgresql.JSONB(), 'postgresql'), nullable=False),
+        sa.Column('raw_payload', sa.JSON().with_variant(sa.dialects.postgresql.JSONB(), 'postgresql'), nullable=True),
+        sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.text('(CURRENT_TIMESTAMP)'), nullable=False),
+        sa.ForeignKeyConstraint(['user_id'], ['user.id'], ),
+        sa.PrimaryKeyConstraint('id'),
+        sa.UniqueConstraint('user_id', 'trace_id', name='uq_comparison_user_trace'),
+    )
+    with op.batch_alter_table('comparison_record', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_comparison_record_user_id'), ['user_id'], unique=False)
+        batch_op.create_index(batch_op.f('ix_comparison_record_business_type'), ['business_type'], unique=False)
+        batch_op.create_index(batch_op.f('ix_comparison_record_created_at'), ['created_at'], unique=False)
+
+
+def downgrade() -> None:
+    with op.batch_alter_table('comparison_record', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_comparison_record_created_at'))
+        batch_op.drop_index(batch_op.f('ix_comparison_record_business_type'))
+        batch_op.drop_index(batch_op.f('ix_comparison_record_user_id'))
+
+    op.drop_table('comparison_record')

alembic/versions/ebb6af5c0b56_merge_app_config_and_price_report_heads.py

@@ -0,0 +1,26 @@
+"""merge app_config and price_report heads
+
+Revision ID: ebb6af5c0b56
+Revises: cfg1a2b3c4d5, b7e2c1a9f4d3
+Create Date: 2026-06-06 02:29:13.475265
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'ebb6af5c0b56'
+down_revision: Union[str, Sequence[str], None] = ('cfg1a2b3c4d5', 'b7e2c1a9f4d3')
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    pass
+
+
+def downgrade() -> None:
+    pass

alembic/versions/ef96beb47b1e_convert_savings_record_dishes_from_json_.py

@@ -0,0 +1,36 @@
+"""convert savings_record.dishes from json to jsonb
+
+PG only. SQLite 上 JSON/JSONB 都是 TEXT, 此迁移是 no-op。
+
+Revision ID: ef96beb47b1e
+Revises: c8d9e0f1a2b3
+Create Date: 2026-05-29 10:57:21.471774
+"""
+from typing import Sequence, Union
+
+from alembic import op
+from sqlalchemy.dialects.postgresql import JSONB
+
+
+revision: str = 'ef96beb47b1e'
+down_revision: Union[str, Sequence[str], None] = 'c8d9e0f1a2b3'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    if op.get_bind().dialect.name != "postgresql":
+        return
+    op.execute(
+        "ALTER TABLE savings_record "
+        "ALTER COLUMN dishes TYPE JSONB USING dishes::JSONB"
+    )
+
+
+def downgrade() -> None:
+    if op.get_bind().dialect.name != "postgresql":
+        return
+    op.execute(
+        "ALTER TABLE savings_record "
+        "ALTER COLUMN dishes TYPE JSON USING dishes::JSON"
+    )

alembic/versions/f01db5d77dac_merge_pg_jsonb_and_feedback_heads.py

@@ -0,0 +1,26 @@
+"""merge pg_jsonb and feedback heads
+
+Revision ID: f01db5d77dac
+Revises: ef96beb47b1e, d1e2f3a4b5c6
+Create Date: 2026-05-29 16:09:58.498935
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'f01db5d77dac'
+down_revision: Union[str, Sequence[str], None] = ('ef96beb47b1e', 'd1e2f3a4b5c6')
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    pass
+
+
+def downgrade() -> None:
+    pass

alembic/versions/feedback_table.py

@@ -0,0 +1,44 @@
+"""feedback table (用户帮助与反馈)
+
+Revision ID: d1e2f3a4b5c6
+Revises: c8d9e0f1a2b3
+Create Date: 2026-05-28 12:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'd1e2f3a4b5c6'
+down_revision: Union[str, Sequence[str], None] = 'c8d9e0f1a2b3'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        'feedback',
+        sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
+        sa.Column('user_id', sa.Integer(), nullable=False),
+        sa.Column('content', sa.Text(), nullable=False),
+        sa.Column('contact', sa.String(length=128), nullable=False),
+        sa.Column('images', sa.JSON(), nullable=True),
+        sa.Column('status', sa.String(length=16), nullable=False),
+        sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.text('(CURRENT_TIMESTAMP)'), nullable=False),
+        sa.ForeignKeyConstraint(['user_id'], ['user.id'], ),
+        sa.PrimaryKeyConstraint('id'),
+    )
+    with op.batch_alter_table('feedback', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_feedback_user_id'), ['user_id'], unique=False)
+        batch_op.create_index(batch_op.f('ix_feedback_created_at'), ['created_at'], unique=False)
+
+
+def downgrade() -> None:
+    with op.batch_alter_table('feedback', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_feedback_created_at'))
+        batch_op.drop_index(batch_op.f('ix_feedback_user_id'))
+
+    op.drop_table('feedback')

alembic/versions/savings_record_table.py

@@ -0,0 +1,49 @@
+"""savings_record table
+
+Revision ID: bf2a67c0e2ab
+Revises: 3d9cb19df76f
+Create Date: 2026-05-24 16:24:34.622394
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'bf2a67c0e2ab'
+down_revision: Union[str, Sequence[str], None] = '3d9cb19df76f'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table('savings_record',
+    sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
+    sa.Column('user_id', sa.Integer(), nullable=False),
+    sa.Column('order_amount_cents', sa.Integer(), nullable=False),
+    sa.Column('saved_amount_cents', sa.Integer(), nullable=False),
+    sa.Column('platform', sa.String(length=32), nullable=True),
+    sa.Column('title', sa.String(length=128), nullable=True),
+    sa.Column('source', sa.String(length=16), nullable=False),
+    sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.text('(CURRENT_TIMESTAMP)'), nullable=False),
+    sa.ForeignKeyConstraint(['user_id'], ['user.id'], ),
+    sa.PrimaryKeyConstraint('id')
+    )
+    with op.batch_alter_table('savings_record', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_savings_record_created_at'), ['created_at'], unique=False)
+        batch_op.create_index(batch_op.f('ix_savings_record_user_id'), ['user_id'], unique=False)
+
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    with op.batch_alter_table('savings_record', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_savings_record_user_id'))
+        batch_op.drop_index(batch_op.f('ix_savings_record_created_at'))
+
+    op.drop_table('savings_record')
+    # ### end Alembic commands ###

alembic/versions/savings_report_fields.py

@@ -0,0 +1,49 @@
+"""savings_record:真实比价上报字段 + (user_id, client_event_id) 幂等唯一约束
+
+把 savings_record 升级为「记账唯一真相表」:真实上报(source='compare')写入
+原价/比价价/支付渠道/平台包名/源平台名/源链接/幂等键/device_id;
+demo seeder 行(source='demo')这些列均为 NULL。
+
+Revision ID: savings_report_fields
+Revises: f01db5d77dac
+Create Date: 2026-05-31 19:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'savings_report_fields'
+down_revision: Union[str, Sequence[str], None] = 'f01db5d77dac'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    with op.batch_alter_table('savings_record', schema=None) as batch_op:
+        batch_op.add_column(sa.Column('original_price_cents', sa.Integer(), nullable=True))
+        batch_op.add_column(sa.Column('compared_price_cents', sa.Integer(), nullable=True))
+        batch_op.add_column(sa.Column('pay_channel', sa.String(length=16), nullable=True))
+        batch_op.add_column(sa.Column('platform_package', sa.String(length=128), nullable=True))
+        batch_op.add_column(sa.Column('source_platform_name', sa.String(length=32), nullable=True))
+        batch_op.add_column(sa.Column('source_deeplink', sa.String(length=512), nullable=True))
+        batch_op.add_column(sa.Column('client_event_id', sa.String(length=64), nullable=True))
+        batch_op.add_column(sa.Column('device_id', sa.String(length=128), nullable=True))
+        # (user_id, client_event_id) 幂等;demo 行 client_event_id 为 NULL 不冲突
+        batch_op.create_unique_constraint('uq_savings_user_event', ['user_id', 'client_event_id'])
+
+
+def downgrade() -> None:
+    with op.batch_alter_table('savings_record', schema=None) as batch_op:
+        batch_op.drop_constraint('uq_savings_user_event', type_='unique')
+        batch_op.drop_column('device_id')
+        batch_op.drop_column('client_event_id')
+        batch_op.drop_column('source_deeplink')
+        batch_op.drop_column('source_platform_name')
+        batch_op.drop_column('platform_package')
+        batch_op.drop_column('pay_channel')
+        batch_op.drop_column('compared_price_cents')
+        batch_op.drop_column('original_price_cents')

alembic/versions/savings_shop_dishes.py

@@ -0,0 +1,33 @@
+"""savings_record.shop_name + dishes(订单明细卡:店铺名 + 菜品列表)
+
+Revision ID: b1c2d3e4f5a6
+Revises: a7c8d9e0f1b2
+Create Date: 2026-05-26 10:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'b1c2d3e4f5a6'
+down_revision: Union[str, Sequence[str], None] = 'a7c8d9e0f1b2'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    with op.batch_alter_table('savings_record', schema=None) as batch_op:
+        batch_op.add_column(sa.Column('shop_name', sa.String(length=128), nullable=True))
+        # dishes 存 JSON(SQLite 落 TEXT);旧行给 '[]' 默认,满足 NOT NULL
+        batch_op.add_column(
+            sa.Column('dishes', sa.JSON(), nullable=False, server_default=sa.text("'[]'"))
+        )
+
+
+def downgrade() -> None:
+    with op.batch_alter_table('savings_record', schema=None) as batch_op:
+        batch_op.drop_column('dishes')
+        batch_op.drop_column('shop_name')

alembic/versions/unique_wechat_openid.py

@@ -0,0 +1,32 @@
+"""unique index on user.wechat_openid (一个微信只绑一个账号)
+
+Revision ID: a7c8d9e0f1b2
+Revises: f5b2d3c4e6a7
+Create Date: 2026-05-25 19:10:00.000000
+
+注意:升级前需保证 wechat_openid 无重复值(NULL 不算重复)。
+本仓库 data/app.db 升级前已手动清掉重复 openid(保留最近绑定的账号)。
+"""
+from typing import Sequence, Union
+
+from alembic import op
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'a7c8d9e0f1b2'
+down_revision: Union[str, Sequence[str], None] = 'f5b2d3c4e6a7'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # nullable 列上的唯一索引:SQLite / Postgres 都允许多个 NULL,只约束非空值唯一
+    with op.batch_alter_table('user', schema=None) as batch_op:
+        batch_op.create_index(
+            batch_op.f('ix_user_wechat_openid'), ['wechat_openid'], unique=True
+        )
+
+
+def downgrade() -> None:
+    with op.batch_alter_table('user', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_user_wechat_openid'))

alembic/versions/user_wechat_nickname_avatar.py

@@ -0,0 +1,30 @@
+"""user.wechat_nickname + wechat_avatar_url
+
+Revision ID: f5b2d3c4e6a7
+Revises: e4a1c2b3d4f5
+Create Date: 2026-05-25 18:40:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'f5b2d3c4e6a7'
+down_revision: Union[str, Sequence[str], None] = 'e4a1c2b3d4f5'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    with op.batch_alter_table('user', schema=None) as batch_op:
+        batch_op.add_column(sa.Column('wechat_nickname', sa.String(length=64), nullable=True))
+        batch_op.add_column(sa.Column('wechat_avatar_url', sa.String(length=512), nullable=True))
+
+
+def downgrade() -> None:
+    with op.batch_alter_table('user', schema=None) as batch_op:
+        batch_op.drop_column('wechat_avatar_url')
+        batch_op.drop_column('wechat_nickname')

alembic/versions/welfare_tables_coin_account_coin_txn.py

@@ -0,0 +1,96 @@
+"""welfare tables: coin account, coin txn, signin, user task
+
+Revision ID: 357520ea3015
+Revises: 9c559acc164a
+Create Date: 2026-05-24 16:16:20.677711
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '357520ea3015'
+down_revision: Union[str, Sequence[str], None] = '9c559acc164a'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table('coin_account',
+    sa.Column('user_id', sa.Integer(), nullable=False),
+    sa.Column('coin_balance', sa.Integer(), nullable=False),
+    sa.Column('cash_balance_cents', sa.Integer(), nullable=False),
+    sa.Column('total_coin_earned', sa.Integer(), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), server_default=sa.text('(CURRENT_TIMESTAMP)'), nullable=False),
+    sa.ForeignKeyConstraint(['user_id'], ['user.id'], ),
+    sa.PrimaryKeyConstraint('user_id')
+    )
+    op.create_table('coin_transaction',
+    sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
+    sa.Column('user_id', sa.Integer(), nullable=False),
+    sa.Column('amount', sa.Integer(), nullable=False),
+    sa.Column('balance_after', sa.Integer(), nullable=False),
+    sa.Column('biz_type', sa.String(length=32), nullable=False),
+    sa.Column('ref_id', sa.String(length=64), nullable=True),
+    sa.Column('remark', sa.String(length=128), nullable=True),
+    sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.text('(CURRENT_TIMESTAMP)'), nullable=False),
+    sa.ForeignKeyConstraint(['user_id'], ['user.id'], ),
+    sa.PrimaryKeyConstraint('id')
+    )
+    with op.batch_alter_table('coin_transaction', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_coin_transaction_created_at'), ['created_at'], unique=False)
+        batch_op.create_index(batch_op.f('ix_coin_transaction_user_id'), ['user_id'], unique=False)
+
+    op.create_table('signin_record',
+    sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
+    sa.Column('user_id', sa.Integer(), nullable=False),
+    sa.Column('signin_date', sa.Date(), nullable=False),
+    sa.Column('cycle_day', sa.Integer(), nullable=False),
+    sa.Column('streak', sa.Integer(), nullable=False),
+    sa.Column('coin_awarded', sa.Integer(), nullable=False),
+    sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.text('(CURRENT_TIMESTAMP)'), nullable=False),
+    sa.ForeignKeyConstraint(['user_id'], ['user.id'], ),
+    sa.PrimaryKeyConstraint('id'),
+    sa.UniqueConstraint('user_id', 'signin_date', name='uq_signin_user_date')
+    )
+    with op.batch_alter_table('signin_record', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_signin_record_user_id'), ['user_id'], unique=False)
+
+    op.create_table('user_task',
+    sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
+    sa.Column('user_id', sa.Integer(), nullable=False),
+    sa.Column('task_key', sa.String(length=48), nullable=False),
+    sa.Column('status', sa.String(length=16), nullable=False),
+    sa.Column('coin_awarded', sa.Integer(), nullable=False),
+    sa.Column('completed_at', sa.DateTime(timezone=True), server_default=sa.text('(CURRENT_TIMESTAMP)'), nullable=False),
+    sa.ForeignKeyConstraint(['user_id'], ['user.id'], ),
+    sa.PrimaryKeyConstraint('id'),
+    sa.UniqueConstraint('user_id', 'task_key', name='uq_task_user_key')
+    )
+    with op.batch_alter_table('user_task', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_user_task_user_id'), ['user_id'], unique=False)
+
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    with op.batch_alter_table('user_task', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_user_task_user_id'))
+
+    op.drop_table('user_task')
+    with op.batch_alter_table('signin_record', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_signin_record_user_id'))
+
+    op.drop_table('signin_record')
+    with op.batch_alter_table('coin_transaction', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_coin_transaction_user_id'))
+        batch_op.drop_index(batch_op.f('ix_coin_transaction_created_at'))
+
+    op.drop_table('coin_transaction')
+    op.drop_table('coin_account')
+    # ### end Alembic commands ###

alembic/versions/withdraw_order_and_user_openid.py

@@ -0,0 +1,56 @@
+"""withdraw_order table + user.wechat_openid
+
+Revision ID: e4a1c2b3d4f5
+Revises: bf2a67c0e2ab
+Create Date: 2026-05-25 16:20:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'e4a1c2b3d4f5'
+down_revision: Union[str, Sequence[str], None] = 'bf2a67c0e2ab'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        'withdraw_order',
+        sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
+        sa.Column('user_id', sa.Integer(), nullable=False),
+        sa.Column('out_bill_no', sa.String(length=64), nullable=False),
+        sa.Column('amount_cents', sa.Integer(), nullable=False),
+        sa.Column('status', sa.String(length=16), nullable=False),
+        sa.Column('wechat_state', sa.String(length=32), nullable=True),
+        sa.Column('transfer_bill_no', sa.String(length=64), nullable=True),
+        sa.Column('package_info', sa.String(length=512), nullable=True),
+        sa.Column('fail_reason', sa.String(length=256), nullable=True),
+        sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.text('(CURRENT_TIMESTAMP)'), nullable=False),
+        sa.Column('updated_at', sa.DateTime(timezone=True), server_default=sa.text('(CURRENT_TIMESTAMP)'), nullable=False),
+        sa.ForeignKeyConstraint(['user_id'], ['user.id'], ),
+        sa.PrimaryKeyConstraint('id'),
+    )
+    with op.batch_alter_table('withdraw_order', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_withdraw_order_created_at'), ['created_at'], unique=False)
+        batch_op.create_index(batch_op.f('ix_withdraw_order_user_id'), ['user_id'], unique=False)
+        batch_op.create_index(batch_op.f('ix_withdraw_order_out_bill_no'), ['out_bill_no'], unique=True)
+
+    with op.batch_alter_table('user', schema=None) as batch_op:
+        batch_op.add_column(sa.Column('wechat_openid', sa.String(length=64), nullable=True))
+
+
+def downgrade() -> None:
+    with op.batch_alter_table('user', schema=None) as batch_op:
+        batch_op.drop_column('wechat_openid')
+
+    with op.batch_alter_table('withdraw_order', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_withdraw_order_out_bill_no'))
+        batch_op.drop_index(batch_op.f('ix_withdraw_order_user_id'))
+        batch_op.drop_index(batch_op.f('ix_withdraw_order_created_at'))
+
+    op.drop_table('withdraw_order')

alembic/versions/withdraw_review_and_ad_watch.py

@@ -0,0 +1,62 @@
+"""withdraw_order.user_name 列 + ad_watch_log 表
+
+提现审核功能:WithdrawOrder 加 user_name(审核异步打款时传给微信的实名,达额转账要求)。
+看广告时长防刷:新增 ad_watch_log 表(前端 onAdClose 上报观看秒数,按 (user_id, watch_date)
+聚合做"每天 50 分钟"硬上限)。
+
+Revision ID: withdraw_review_ad_watch
+Revises: ebb6af5c0b56
+Create Date: 2026-06-05 12:00:00.000000
+
+注:本迁移原 down_revision=ad60a1b2c3d4(分支创建时的 head);rebase 合 main 后 main 侧已新增
+app_config / price_report 等迁移并 merge 出 head=ebb6af5c0b56,故改挂到其上,保持单 head(本迁移
+与那些表互不相干,叠加顺序无影响)。
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'withdraw_review_ad_watch'
+down_revision: Union[str, Sequence[str], None] = 'ebb6af5c0b56'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # ① 提现单加实名列:审核通过后异步打款时传给微信(达额转账要求),发起提现时存下
+    with op.batch_alter_table('withdraw_order', schema=None) as batch_op:
+        batch_op.add_column(sa.Column('user_name', sa.String(length=64), nullable=True))
+
+    # ② 看广告观看时长表:前端上报观看秒数,(user_id, watch_date) 聚合做每日 50 分钟防刷主闸
+    op.create_table(
+        'ad_watch_log',
+        sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
+        sa.Column('user_id', sa.Integer(), nullable=False),
+        sa.Column('watch_seconds', sa.Integer(), server_default='0', nullable=False),
+        sa.Column('watch_date', sa.String(length=10), nullable=False),
+        sa.Column(
+            'created_at', sa.DateTime(timezone=True),
+            server_default=sa.text('(CURRENT_TIMESTAMP)'), nullable=False,
+        ),
+        sa.ForeignKeyConstraint(['user_id'], ['user.id'], ),
+        sa.PrimaryKeyConstraint('id'),
+    )
+    with op.batch_alter_table('ad_watch_log', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_ad_watch_log_user_id'), ['user_id'], unique=False)
+        batch_op.create_index(batch_op.f('ix_ad_watch_log_watch_date'), ['watch_date'], unique=False)
+        batch_op.create_index(batch_op.f('ix_ad_watch_log_created_at'), ['created_at'], unique=False)
+
+
+def downgrade() -> None:
+    with op.batch_alter_table('ad_watch_log', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_ad_watch_log_created_at'))
+        batch_op.drop_index(batch_op.f('ix_ad_watch_log_watch_date'))
+        batch_op.drop_index(batch_op.f('ix_ad_watch_log_user_id'))
+    op.drop_table('ad_watch_log')
+
+    with op.batch_alter_table('withdraw_order', schema=None) as batch_op:
+        batch_op.drop_column('user_name')

app/admin/__init__.py

@@ -0,0 +1,6 @@
+"""运营 Admin 后台子应用。
+
+独立 FastAPI app(app.admin.main:admin_app),独立进程/端口运行,复用 App 的
+models/repositories/integrations + 同一个 DB,但鉴权完全隔离(独立 JWT secret)。
+现有 app.main:app 不 import 本包,admin 崩溃不影响 App 主进程。
+"""

app/admin/audit.py

@@ -0,0 +1,38 @@
+"""审计写入门面。
+
+每个 admin 写操作调一次 write_audit,把"谁(admin)在哪个 IP 对什么(target)做了什么
+(action)+ 前后值(detail)"落进 admin_audit_log。
+
+⚠️ 涉钱/涉状态的写操作:传 commit=False,和业务写操作放同一事务一起 commit,
+保证"改了就有痕、有痕就改了"原子(见 plan 风险点 1)。轻量操作可 commit=True。
+"""
+from __future__ import annotations
+
+from sqlalchemy.orm import Session
+
+from app.admin.repositories import audit_log as audit_repo
+from app.models.admin import AdminUser
+
+
+def write_audit(
+    db: Session,
+    admin: AdminUser,
+    *,
+    action: str,
+    target_type: str,
+    target_id: str | int | None = None,
+    detail: dict | None = None,
+    ip: str | None = None,
+    commit: bool = True,
+) -> None:
+    audit_repo.add_audit_log(
+        db,
+        admin_id=admin.id,
+        admin_username=admin.username,
+        action=action,
+        target_type=target_type,
+        target_id=str(target_id) if target_id is not None else None,
+        detail=detail,
+        ip=ip,
+        commit=commit,
+    )

app/admin/deps.py

@@ -0,0 +1,84 @@
+"""Admin API 共享依赖:DB session、当前 admin、角色守卫、客户端 IP。
+
+仿 app/api/deps.py 的 get_current_user,但验的是独立的 admin JWT、查的是 admin_user 表。
+"""
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import Depends, HTTPException, Request, status
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+from sqlalchemy.orm import Session
+
+from app.admin.repositories import admin_user as admin_repo
+from app.admin.security import AdminTokenError, decode_admin_token
+from app.db.session import get_db
+from app.models.admin import AdminUser
+
+_bearer = HTTPBearer(auto_error=False, scheme_name="AdminBearer")
+
+
+def get_current_admin(
+    credentials: Annotated[HTTPAuthorizationCredentials | None, Depends(_bearer)],
+    db: Annotated[Session, Depends(get_db)],
+) -> AdminUser:
+    """从 Authorization: Bearer <admin_token> 解出当前管理员。失败统一 401。"""
+    if credentials is None or credentials.scheme.lower() != "bearer":
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="missing bearer token",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    try:
+        payload = decode_admin_token(credentials.credentials)
+    except AdminTokenError as e:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail=str(e),
+            headers={"WWW-Authenticate": "Bearer"},
+        ) from e
+
+    admin = admin_repo.get_by_id(db, int(payload["sub"]))
+    if admin is None or admin.status != "active":
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="admin not found or disabled",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    return admin
+
+
+CurrentAdmin = Annotated[AdminUser, Depends(get_current_admin)]
+AdminDb = Annotated[Session, Depends(get_db)]
+
+
+def require_role(*roles: str):
+    """角色守卫依赖工厂。super_admin 恒通过(全权)。
+
+    用法:在路由签名加 `_: Annotated[AdminUser, Depends(require_role("finance"))]`,
+    或 `dependencies=[Depends(require_role("finance"))]`(不需要拿 admin 时)。
+    """
+    allowed = set(roles)
+
+    def _checker(admin: CurrentAdmin) -> AdminUser:
+        if admin.role != "super_admin" and admin.role not in allowed:
+            need = sorted(allowed | {"super_admin"})
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail=f"role '{admin.role}' not allowed (need one of {need})",
+            )
+        return admin
+
+    return _checker
+
+
+def get_client_ip(request: Request) -> str:
+    """取客户端 IP(审计日志用)。生产经 nginx 反代,优先 X-Forwarded-For 第一段;否则直连 IP。
+
+    ⚠️ XFF 可被客户端伪造。nginx 必须用 `proxy_set_header X-Forwarded-For $remote_addr`
+    覆盖客户端传入值(见 M4 部署),否则审计里的 IP 可被伪造。审计 IP 仅作记录、不参与鉴权。
+    """
+    xff = request.headers.get("x-forwarded-for")
+    if xff:
+        return xff.split(",")[0].strip()
+    return request.client.host if request.client else ""

app/admin/main.py

@@ -0,0 +1,82 @@
+"""Admin 后台 FastAPI app(独立进程)。
+
+启动:uvicorn app.admin.main:admin_app --host 127.0.0.1 --port 8771
+复用 App 的 DB/models/repositories/integrations;鉴权独立(admin JWT,见 app/admin/security.py)。
+现有 app.main:app 不 import 本模块,两进程互不影响。
+"""
+from __future__ import annotations
+
+import logging
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from app.admin.routers.admins import router as admins_router
+from app.admin.routers.audit import router as audit_router
+from app.admin.routers.auth import router as auth_router
+from app.admin.routers.config import router as config_router
+from app.admin.routers.dashboard import router as dashboard_router
+from app.admin.routers.feedback import router as feedback_router
+from app.admin.routers.users import router as users_router
+from app.admin.routers.wallet import router as wallet_router
+from app.admin.routers.withdraw import router as withdraw_router
+from app.core.config import settings
+from app.core.logging import setup_logging
+
+setup_logging(debug=settings.APP_DEBUG)
+logger = logging.getLogger("shagua.admin")
+
+
+@asynccontextmanager
+async def lifespan(_: FastAPI) -> AsyncIterator[None]:
+    logger.info(
+        "admin app started env=%s db=%s",
+        settings.APP_ENV,
+        settings.DATABASE_URL.split("://", 1)[0],
+    )
+    yield
+    logger.info("admin app shutting down")
+
+
+admin_app = FastAPI(
+    title=f"{settings.APP_NAME} · Admin",
+    version="0.1.0",
+    docs_url="/admin/docs" if not settings.is_prod else None,
+    redoc_url=None,
+    lifespan=lifespan,
+)
+
+# admin 前端独立部署。生产同域(nginx)无需 CORS;本地 next dev 跨域需放行开发源。
+_dev_origins = [
+    "http://localhost:3001",
+    "http://127.0.0.1:3001",
+    "http://localhost:3000",
+    "http://127.0.0.1:3000",
+]
+_origins = settings.cors_origins_list or ([] if settings.is_prod else _dev_origins)
+if _origins:
+    admin_app.add_middleware(
+        CORSMiddleware,
+        allow_origins=_origins,
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+
+@admin_app.get("/admin/api/health", tags=["meta"])
+def health() -> dict[str, str]:
+    return {"status": "ok", "service": "admin"}
+
+
+admin_app.include_router(auth_router)
+admin_app.include_router(dashboard_router)
+admin_app.include_router(users_router)
+admin_app.include_router(wallet_router)
+admin_app.include_router(withdraw_router)
+admin_app.include_router(feedback_router)
+admin_app.include_router(admins_router)
+admin_app.include_router(audit_router)
+admin_app.include_router(config_router)

app/admin/repositories/__init__.py

@@ -0,0 +1 @@
+"""admin 专用数据访问层(跨用户查询 + admin 账号 + 审计 + 大盘聚合)。"""

app/admin/repositories/admin_user.py

@@ -0,0 +1,64 @@
+"""admin_user 表 CRUD。"""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from app.core.security import hash_password
+from app.models.admin import AdminUser
+
+
+def get_by_id(db: Session, admin_id: int) -> AdminUser | None:
+    return db.get(AdminUser, admin_id)
+
+
+def get_by_username(db: Session, username: str) -> AdminUser | None:
+    stmt = select(AdminUser).where(AdminUser.username == username)
+    return db.execute(stmt).scalar_one_or_none()
+
+
+def create_admin(
+    db: Session, *, username: str, password: str, role: str = "operator"
+) -> AdminUser:
+    admin = AdminUser(
+        username=username,
+        password_hash=hash_password(password),
+        role=role,
+    )
+    db.add(admin)
+    db.commit()
+    db.refresh(admin)
+    return admin
+
+
+def update_last_login(db: Session, admin: AdminUser) -> None:
+    admin.last_login_at = datetime.now(timezone.utc)
+    db.commit()
+
+
+def list_admins(db: Session) -> list[AdminUser]:
+    stmt = select(AdminUser).order_by(AdminUser.id)
+    return list(db.execute(stmt).scalars().all())
+
+
+def set_role(db: Session, admin: AdminUser, *, role: str) -> AdminUser:
+    admin.role = role
+    db.commit()
+    db.refresh(admin)
+    return admin
+
+
+def set_status(db: Session, admin: AdminUser, *, status: str) -> AdminUser:
+    admin.status = status
+    db.commit()
+    db.refresh(admin)
+    return admin
+
+
+def set_password(db: Session, admin: AdminUser, *, password: str) -> AdminUser:
+    admin.password_hash = hash_password(password)
+    db.commit()
+    db.refresh(admin)
+    return admin

app/admin/repositories/audit_log.py

@@ -0,0 +1,70 @@
+"""admin_audit_log 写入 + 查询。
+
+审计日志只增不改不删——任何写操作经 app.admin.audit.write_audit 落一条。
+"""
+from __future__ import annotations
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from app.models.admin import AdminAuditLog
+
+
+def add_audit_log(
+    db: Session,
+    *,
+    admin_id: int,
+    admin_username: str,
+    action: str,
+    target_type: str,
+    target_id: str | None = None,
+    detail: dict | None = None,
+    ip: str | None = None,
+    commit: bool = True,
+) -> AdminAuditLog:
+    """插一条审计。commit=False 时只 flush,让调用方把审计和业务写操作放同一事务。"""
+    log = AdminAuditLog(
+        admin_id=admin_id,
+        admin_username=admin_username,
+        action=action,
+        target_type=target_type,
+        target_id=target_id,
+        detail=detail,
+        ip=ip,
+    )
+    db.add(log)
+    if commit:
+        db.commit()
+        db.refresh(log)
+    else:
+        db.flush()
+    return log
+
+
+def list_audit_logs(
+    db: Session,
+    *,
+    action: str | None = None,
+    target_type: str | None = None,
+    admin_id: int | None = None,
+    limit: int = 50,
+    cursor: int | None = None,
+) -> tuple[list[AdminAuditLog], int | None]:
+    """游标分页(id 倒序),与现有 list_* 约定一致。返回 (rows, next_cursor)。"""
+    stmt = select(AdminAuditLog)
+    if action:
+        stmt = stmt.where(AdminAuditLog.action == action)
+    if target_type:
+        stmt = stmt.where(AdminAuditLog.target_type == target_type)
+    if admin_id is not None:
+        stmt = stmt.where(AdminAuditLog.admin_id == admin_id)
+    if cursor is not None:
+        stmt = stmt.where(AdminAuditLog.id < cursor)
+    stmt = stmt.order_by(AdminAuditLog.id.desc())
+    rows = list(db.execute(stmt.limit(limit + 1)).scalars().all())
+    has_more = len(rows) > limit
+    items = rows[:limit]
+    # next_cursor 必须是"本页返回的最后一条"的 id(下一页查 id < 它),不能用 rows[limit]——
+    # rows[limit] 是探测下一页用的第 limit+1 条,它既不在本页也不在下页 → 每页边界丢一条。
+    next_cursor = items[-1].id if has_more else None
+    return items, next_cursor

app/admin/repositories/mutations.py

@@ -0,0 +1,36 @@
+"""admin 写操作 repo(状态改写)。
+
+涉钱的金币/提现复用 app.repositories.wallet(grant_coins / refresh_withdraw_status /
+reconcile_pending_withdraws),不在这里重写——重写涉钱逻辑就是给自己埋雷。
+
+set_user_status / update_feedback_status 支持 commit=False,让 router 把"业务写 + 审计写"
+放进同一事务一起 commit(原子:改了就有审计、有审计就真改了,见 plan 风险点 1)。
+"""
+from __future__ import annotations
+
+from sqlalchemy.orm import Session
+
+from app.models.feedback import Feedback
+from app.models.user import User
+
+
+def set_user_status(db: Session, user: User, *, status: str, commit: bool = True) -> User:
+    user.status = status
+    if commit:
+        db.commit()
+        db.refresh(user)
+    else:
+        db.flush()
+    return user
+
+
+def update_feedback_status(
+    db: Session, feedback: Feedback, *, status: str, commit: bool = True
+) -> Feedback:
+    feedback.status = status
+    if commit:
+        db.commit()
+        db.refresh(feedback)
+    else:
+        db.flush()
+    return feedback

app/admin/repositories/queries.py

@@ -0,0 +1,153 @@
+"""admin 跨用户查询(去掉现有 repo 的 user_id 强制过滤)+ 通用游标分页 helper + 用户概览。
+
+现有 app/repositories/ 的 list_* 都强绑单个 user_id(C 端只看自己);admin 要看全量、按条件筛,
+所以在这里另起一套。游标约定与现有一致:id 倒序,cursor=上页最后一条 id,返回 (items, next_cursor)。
+"""
+from __future__ import annotations
+
+from sqlalchemy import Select, func, select
+from sqlalchemy.orm import Session
+
+from app.models.comparison import ComparisonRecord
+from app.models.feedback import Feedback
+from app.models.user import User
+from app.models.wallet import CashTransaction, CoinAccount, CoinTransaction, WithdrawOrder
+
+
+def cursor_paginate(
+    db: Session, stmt: Select, id_col, *, limit: int, cursor: int | None
+) -> tuple[list, int | None]:
+    """通用游标分页(id 倒序)。stmt 不要预先带 order_by/limit。
+
+    多取 1 条探测有没有下一页;next_cursor 取本页最后一条的 id(下一页查 id < 它),
+    绝不用第 limit+1 条的 id——那条既不在本页也不在下页,会每页边界丢一条(见 audit_log 同款修复)。
+    """
+    if cursor is not None:
+        stmt = stmt.where(id_col < cursor)
+    stmt = stmt.order_by(id_col.desc()).limit(limit + 1)
+    rows = list(db.execute(stmt).scalars().all())
+    has_more = len(rows) > limit
+    items = rows[:limit]
+    next_cursor = items[-1].id if has_more else None
+    return items, next_cursor
+
+
+def list_users(
+    db: Session,
+    *,
+    phone: str | None = None,
+    register_channel: str | None = None,
+    status: str | None = None,
+    limit: int = 20,
+    cursor: int | None = None,
+) -> tuple[list[User], int | None]:
+    stmt = select(User)
+    if phone:
+        stmt = stmt.where(User.phone.like(f"{phone}%"))  # 前缀匹配
+    if register_channel:
+        stmt = stmt.where(User.register_channel == register_channel)
+    if status:
+        stmt = stmt.where(User.status == status)
+    return cursor_paginate(db, stmt, User.id, limit=limit, cursor=cursor)
+
+
+def list_all_coin_transactions(
+    db: Session,
+    *,
+    user_id: int | None = None,
+    biz_type: str | None = None,
+    limit: int = 20,
+    cursor: int | None = None,
+) -> tuple[list[CoinTransaction], int | None]:
+    stmt = select(CoinTransaction)
+    if user_id is not None:
+        stmt = stmt.where(CoinTransaction.user_id == user_id)
+    if biz_type:
+        stmt = stmt.where(CoinTransaction.biz_type == biz_type)
+    return cursor_paginate(db, stmt, CoinTransaction.id, limit=limit, cursor=cursor)
+
+
+def list_all_cash_transactions(
+    db: Session,
+    *,
+    user_id: int | None = None,
+    biz_type: str | None = None,
+    limit: int = 20,
+    cursor: int | None = None,
+) -> tuple[list[CashTransaction], int | None]:
+    stmt = select(CashTransaction)
+    if user_id is not None:
+        stmt = stmt.where(CashTransaction.user_id == user_id)
+    if biz_type:
+        stmt = stmt.where(CashTransaction.biz_type == biz_type)
+    return cursor_paginate(db, stmt, CashTransaction.id, limit=limit, cursor=cursor)
+
+
+def list_all_withdraw_orders(
+    db: Session,
+    *,
+    user_id: int | None = None,
+    status: str | None = None,
+    limit: int = 20,
+    cursor: int | None = None,
+) -> tuple[list[WithdrawOrder], int | None]:
+    stmt = select(WithdrawOrder)
+    if user_id is not None:
+        stmt = stmt.where(WithdrawOrder.user_id == user_id)
+    if status:
+        stmt = stmt.where(WithdrawOrder.status == status)
+    return cursor_paginate(db, stmt, WithdrawOrder.id, limit=limit, cursor=cursor)
+
+
+def list_feedbacks(
+    db: Session,
+    *,
+    status: str | None = None,
+    user_id: int | None = None,
+    limit: int = 20,
+    cursor: int | None = None,
+) -> tuple[list[Feedback], int | None]:
+    stmt = select(Feedback)
+    if status:
+        stmt = stmt.where(Feedback.status == status)
+    if user_id is not None:
+        stmt = stmt.where(Feedback.user_id == user_id)
+    return cursor_paginate(db, stmt, Feedback.id, limit=limit, cursor=cursor)
+
+
+def get_withdraw_by_out_bill_no(db: Session, out_bill_no: str) -> WithdrawOrder | None:
+    """按商户单号查提现单(admin 重试打款先拿 user_id 用,M3)。"""
+    return db.execute(
+        select(WithdrawOrder).where(WithdrawOrder.out_bill_no == out_bill_no)
+    ).scalar_one_or_none()
+
+
+def get_user_overview(db: Session, user_id: int) -> dict | None:
+    """用户 360 概览:基础资料 + 钱包余额 + 各项 count。历史明细走各自分页接口(带 user_id 过滤)。"""
+    user = db.get(User, user_id)
+    if user is None:
+        return None
+    acc = db.get(CoinAccount, user_id)  # 可能为 None(从未发生过金币动作)
+
+    def _count(model, *conds) -> int:
+        return db.execute(select(func.count(model.id)).where(*conds)).scalar_one()
+
+    return {
+        "user": user,
+        "coin_balance": acc.coin_balance if acc else 0,
+        "cash_balance_cents": acc.cash_balance_cents if acc else 0,
+        "total_coin_earned": acc.total_coin_earned if acc else 0,
+        "comparison_total": _count(ComparisonRecord, ComparisonRecord.user_id == user_id),
+        "comparison_success": _count(
+            ComparisonRecord,
+            ComparisonRecord.user_id == user_id,
+            ComparisonRecord.status == "success",
+        ),
+        "withdraw_total": _count(WithdrawOrder, WithdrawOrder.user_id == user_id),
+        "withdraw_success_cents": db.execute(
+            select(func.coalesce(func.sum(WithdrawOrder.amount_cents), 0)).where(
+                WithdrawOrder.user_id == user_id, WithdrawOrder.status == "success"
+            )
+        ).scalar_one(),
+        "feedback_total": _count(Feedback, Feedback.user_id == user_id),
+    }

app/admin/repositories/stats.py

@@ -0,0 +1,91 @@
+"""admin 大盘聚合查询(全局 count/sum/DAU/成功率)。全部只读、不改任何数据。
+
+⚠️ 性能:这些是全表 count/sum,P0 数据量小够用;用户量上来后热点字段(user.created_at /
+user.last_login_at / comparison_record.status / withdraw_order.status)要加索引,或改增量统计表。
+"""
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+
+from sqlalchemy import func, select
+from sqlalchemy.orm import Session
+
+from app.models.comparison import ComparisonRecord
+from app.models.feedback import Feedback
+from app.models.user import User
+from app.models.wallet import CoinTransaction, WithdrawOrder
+
+_BEIJING = timezone(timedelta(hours=8))
+
+
+def _beijing_today_start_utc() -> datetime:
+    """北京时间今天 0 点对应的 UTC 时刻(DAU / 今日新增按北京时区切天)。"""
+    now_bj = datetime.now(_BEIJING)
+    start_bj = now_bj.replace(hour=0, minute=0, second=0, microsecond=0)
+    return start_bj.astimezone(timezone.utc)
+
+
+def dashboard_overview(db: Session) -> dict:
+    today_start = _beijing_today_start_utc()
+
+    def _count(model, *conds) -> int:
+        stmt = select(func.count(model.id))
+        if conds:
+            stmt = stmt.where(*conds)
+        return db.execute(stmt).scalar_one()
+
+    def _sum(col, *conds) -> int:
+        stmt = select(func.coalesce(func.sum(col), 0))
+        if conds:
+            stmt = stmt.where(*conds)
+        return db.execute(stmt).scalar_one()
+
+    # ===== 用户 =====
+    by_status = dict(
+        db.execute(select(User.status, func.count(User.id)).group_by(User.status)).all()
+    )
+
+    # ===== 提现状态分布 =====
+    wd_by_status = dict(
+        db.execute(
+            select(WithdrawOrder.status, func.count(WithdrawOrder.id)).group_by(
+                WithdrawOrder.status
+            )
+        ).all()
+    )
+
+    # ===== 比价 =====
+    comparison_total = _count(ComparisonRecord)
+    comparison_success = _count(ComparisonRecord, ComparisonRecord.status == "success")
+    success_rate = round(comparison_success / comparison_total, 4) if comparison_total else 0.0
+
+    return {
+        "users": {
+            "total": _count(User),
+            "active": by_status.get("active", 0),
+            "disabled": by_status.get("disabled", 0),
+            "deleted": by_status.get("deleted", 0),
+            "new_today": _count(User, User.created_at >= today_start),
+            "dau": _count(User, User.last_login_at >= today_start),
+        },
+        "coins": {
+            # 累计发放金币(coin_transaction 里所有 amount>0 之和;负数是兑换/扣减不计)
+            "granted_total": _sum(CoinTransaction.amount, CoinTransaction.amount > 0),
+        },
+        "cash": {
+            "withdraw_success_cents": _sum(
+                WithdrawOrder.amount_cents, WithdrawOrder.status == "success"
+            ),
+            "withdraw_pending_count": wd_by_status.get("pending", 0),
+            "withdraw_success_count": wd_by_status.get("success", 0),
+            "withdraw_failed_count": wd_by_status.get("failed", 0),
+        },
+        "comparison": {
+            "total": comparison_total,
+            "success": comparison_success,
+            "success_rate": success_rate,
+        },
+        "feedback": {"new": _count(Feedback, Feedback.status == "new")},
+        # CPS 收入数据源未接(referral-link 只换链接,转化/佣金未回收)→ 前端显示"待接入"。
+        "cps": {"available": False, "note": "CPS 转化数据未接入(P2)"},
+    }

app/admin/routers/__init__.py

@@ -0,0 +1 @@
+"""admin 路由(前缀统一 /admin/api)。"""

app/admin/routers/admins.py

@@ -0,0 +1,69 @@
+"""admin 账号管理(仅 super_admin):列表 / 创建 / 改角色启停重置密码。均写审计。"""
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+
+from app.admin.audit import write_audit
+from app.admin.deps import AdminDb, CurrentAdmin, get_client_ip, require_role
+from app.admin.repositories import admin_user as admin_repo
+from app.admin.schemas.admin import AdminCreateRequest, AdminUpdateRequest
+from app.admin.schemas.auth import AdminOut
+from app.core.security import hash_password
+
+router = APIRouter(
+    prefix="/admin/api/admins",
+    tags=["admin-accounts"],
+    dependencies=[Depends(require_role())],  # require_role() 无参 = 仅 super_admin 通过
+)
+
+
+@router.get("", response_model=list[AdminOut], summary="管理员列表")
+def list_admins(db: AdminDb) -> list[AdminOut]:
+    return [AdminOut.model_validate(a) for a in admin_repo.list_admins(db)]
+
+
+@router.post("", response_model=AdminOut, summary="创建管理员")
+def create_admin(
+    body: AdminCreateRequest, request: Request, admin: CurrentAdmin, db: AdminDb
+) -> AdminOut:
+    if admin_repo.get_by_username(db, body.username) is not None:
+        raise HTTPException(status_code=409, detail="用户名已存在")
+    new = admin_repo.create_admin(
+        db, username=body.username, password=body.password, role=body.role
+    )
+    write_audit(
+        db, admin, action="admin.create", target_type="admin", target_id=new.id,
+        detail={"username": new.username, "role": new.role}, ip=get_client_ip(request), commit=True,
+    )
+    return AdminOut.model_validate(new)
+
+
+@router.patch("/{admin_id}", response_model=AdminOut, summary="改角色/启停/重置密码")
+def update_admin(
+    admin_id: int, body: AdminUpdateRequest, request: Request, admin: CurrentAdmin, db: AdminDb
+) -> AdminOut:
+    target = admin_repo.get_by_id(db, admin_id)
+    if target is None:
+        raise HTTPException(status_code=404, detail="管理员不存在")
+    if admin_id == admin.id and body.status == "disabled":
+        raise HTTPException(status_code=400, detail="不能禁用自己")
+
+    changes: dict = {}
+    if body.role is not None:
+        target.role = body.role
+        changes["role"] = body.role
+    if body.status is not None:
+        target.status = body.status
+        changes["status"] = body.status
+    if body.password is not None:
+        target.password_hash = hash_password(body.password)
+        changes["password"] = "reset"
+    if not changes:
+        raise HTTPException(status_code=400, detail="无任何变更字段")
+    db.commit()
+    db.refresh(target)
+    write_audit(
+        db, admin, action="admin.update", target_type="admin", target_id=admin_id,
+        detail=changes, ip=get_client_ip(request), commit=True,
+    )
+    return AdminOut.model_validate(target)

app/admin/routers/audit.py

@@ -0,0 +1,34 @@
+"""admin 操作审计日志查询(所有 admin 可看:谁在何时对什么做了什么)。"""
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, Query
+
+from app.admin.deps import AdminDb, get_current_admin
+from app.admin.repositories import audit_log as audit_repo
+from app.admin.schemas.admin import AdminAuditLogOut
+from app.admin.schemas.common import CursorPage
+
+router = APIRouter(
+    prefix="/admin/api/audit-logs",
+    tags=["admin-audit"],
+    dependencies=[Depends(get_current_admin)],
+)
+
+
+@router.get("", response_model=CursorPage[AdminAuditLogOut], summary="审计日志(谁改了什么)")
+def list_audit_logs(
+    db: AdminDb,
+    action: Annotated[str | None, Query()] = None,
+    target_type: Annotated[str | None, Query()] = None,
+    admin_id: Annotated[int | None, Query()] = None,
+    limit: Annotated[int, Query(ge=1, le=100)] = 50,
+    cursor: Annotated[int | None, Query()] = None,
+) -> CursorPage[AdminAuditLogOut]:
+    items, next_cursor = audit_repo.list_audit_logs(
+        db, action=action, target_type=target_type, admin_id=admin_id, limit=limit, cursor=cursor,
+    )
+    return CursorPage(
+        items=[AdminAuditLogOut.model_validate(x) for x in items], next_cursor=next_cursor,
+    )

app/admin/routers/auth.py

@@ -0,0 +1,48 @@
+"""Admin 认证:账号密码登录 → admin JWT(独立 secret)。"""
+from __future__ import annotations
+
+import logging
+
+from fastapi import APIRouter, Depends, HTTPException
+
+from app.admin.deps import AdminDb, CurrentAdmin
+from app.admin.repositories import admin_user as admin_repo
+from app.admin.schemas.auth import AdminLoginRequest, AdminLoginResponse, AdminOut
+from app.admin.security import create_admin_token
+from app.core.ratelimit import rate_limit
+from app.core.security import verify_password
+
+logger = logging.getLogger("shagua.admin.auth")
+
+router = APIRouter(prefix="/admin/api/auth", tags=["admin-auth"])
+
+
+@router.post(
+    "/login",
+    response_model=AdminLoginResponse,
+    summary="管理员登录",
+    dependencies=[Depends(rate_limit(10, 60, "admin-login"))],  # 同 IP 每分钟≤10 次,防爆破
+)
+def login(req: AdminLoginRequest, db: AdminDb) -> AdminLoginResponse:
+    admin = admin_repo.get_by_username(db, req.username)
+    # 用户名不存在 / 密码错统一 401 同文案(防账号枚举)。
+    # disabled 账号单独 403"账号已禁用":admin 是内部少数已知账号、无枚举价值,
+    # 明确提示比防枚举更有运维价值(与 App 端 auth.py 对 disabled 用户的 403 一致)。
+    if admin is None or not verify_password(req.password, admin.password_hash):
+        raise HTTPException(status_code=401, detail="用户名或密码错误")
+    if admin.status != "active":
+        raise HTTPException(status_code=403, detail="账号已禁用")
+
+    token, expires_in = create_admin_token(admin_id=admin.id, role=admin.role)
+    admin_repo.update_last_login(db, admin)
+    logger.info("admin login ok id=%d username=%s role=%s", admin.id, admin.username, admin.role)
+    return AdminLoginResponse(
+        access_token=token,
+        expires_in=expires_in,
+        admin=AdminOut.model_validate(admin),
+    )
+
+
+@router.get("/me", response_model=AdminOut, summary="当前管理员")
+def me(admin: CurrentAdmin) -> AdminOut:
+    return AdminOut.model_validate(admin)

app/admin/routers/config.py

@@ -0,0 +1,81 @@
+"""admin 运营配置:列出所有可配项 + 改某项(带审计 + 改值校验)。
+
+配置项定义见 app.core.config_schema.CONFIG_DEFS;业务读配置 fallback 默认(见 app_config repo)。
+权限:operator / finance 都可改(运营调奖励、财务调额度),super 恒可。
+"""
+from __future__ import annotations
+
+from typing import Annotated, Any
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+
+from app.admin.audit import write_audit
+from app.admin.deps import AdminDb, get_client_ip, get_current_admin, require_role
+from app.admin.schemas.config import ConfigItemOut, ConfigUpdateRequest
+from app.core.config_schema import CONFIG_DEFS
+from app.models.admin import AdminUser
+from app.repositories import app_config
+
+router = APIRouter(
+    prefix="/admin/api/config",
+    tags=["admin-config"],
+    dependencies=[Depends(get_current_admin)],
+)
+
+
+def _validate(key: str, value: Any) -> None:
+    """按配置项 type 校验新值,不合法抛 ValueError(router 转 400)。"""
+    t = CONFIG_DEFS[key]["type"]
+    if t == "int":
+        if not isinstance(value, int) or isinstance(value, bool) or value < 0:
+            raise ValueError("需为非负整数")
+    elif t == "int_list":
+        if not isinstance(value, list) or not value:
+            raise ValueError("需为非空整数列表")
+        if not all(isinstance(x, int) and not isinstance(x, bool) and x >= 0 for x in value):
+            raise ValueError("列表元素需为非负整数")
+        if key == "signin_rewards" and len(value) != 7:
+            raise ValueError("签到档位必须正好 7 个(对应 7 天循环)")
+    elif t == "dict_str_int":
+        if not isinstance(value, dict) or not all(
+            isinstance(k, str) and isinstance(v, int) and not isinstance(v, bool)
+            for k, v in value.items()
+        ):
+            raise ValueError("需为 {字符串: 整数} 映射")
+
+
+def _item(db, key: str) -> ConfigItemOut:
+    for item in app_config.list_all(db):
+        if item["key"] == key:
+            return ConfigItemOut(**item)
+    raise HTTPException(status_code=404, detail="未知配置项")
+
+
+@router.get("", response_model=list[ConfigItemOut], summary="所有可配项 + 当前值")
+def list_config(db: AdminDb) -> list[ConfigItemOut]:
+    return [ConfigItemOut(**item) for item in app_config.list_all(db)]
+
+
+@router.patch("/{key}", response_model=ConfigItemOut, summary="改某项配置(带审计)")
+def update_config(
+    key: str,
+    body: ConfigUpdateRequest,
+    request: Request,
+    admin: Annotated[AdminUser, Depends(require_role("operator", "finance"))],
+    db: AdminDb,
+) -> ConfigItemOut:
+    if key not in CONFIG_DEFS:
+        raise HTTPException(status_code=404, detail="未知配置项")
+    try:
+        _validate(key, body.value)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e)) from e
+
+    before = app_config.get_value(db, key)
+    app_config.set_value(db, key, body.value, admin_id=admin.id, commit=False)
+    write_audit(
+        db, admin, action="config.set", target_type="config", target_id=key,
+        detail={"before": before, "after": body.value}, ip=get_client_ip(request), commit=False,
+    )
+    db.commit()
+    return _item(db, key)

app/admin/routers/dashboard.py

@@ -0,0 +1,19 @@
+"""admin 数据大盘(只读聚合)。"""
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends
+
+from app.admin.deps import AdminDb, get_current_admin
+from app.admin.repositories import stats
+from app.admin.schemas.dashboard import DashboardOverview
+
+router = APIRouter(
+    prefix="/admin/api/stats",
+    tags=["admin-stats"],
+    dependencies=[Depends(get_current_admin)],
+)
+
+
+@router.get("/overview", response_model=DashboardOverview, summary="大盘核心指标")
+def overview(db: AdminDb) -> DashboardOverview:
+    return DashboardOverview.model_validate(stats.dashboard_overview(db))

app/admin/routers/feedback.py

@@ -0,0 +1,56 @@
+"""admin 反馈工单:列表(读)+ 标记已处理(写,带审计)。"""
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request
+
+from app.admin.audit import write_audit
+from app.admin.deps import AdminDb, get_client_ip, get_current_admin, require_role
+from app.admin.repositories import mutations, queries
+from app.admin.schemas.common import CursorPage, OkResponse
+from app.admin.schemas.feedback import FeedbackOut
+from app.models.admin import AdminUser
+from app.models.feedback import Feedback
+
+router = APIRouter(
+    prefix="/admin/api/feedbacks",
+    tags=["admin-feedback"],
+    dependencies=[Depends(get_current_admin)],
+)
+
+
+@router.get("", response_model=CursorPage[FeedbackOut], summary="反馈工单列表")
+def list_feedbacks(
+    db: AdminDb,
+    status: Annotated[str | None, Query()] = None,
+    user_id: Annotated[int | None, Query()] = None,
+    limit: Annotated[int, Query(ge=1, le=100)] = 20,
+    cursor: Annotated[int | None, Query()] = None,
+) -> CursorPage[FeedbackOut]:
+    items, next_cursor = queries.list_feedbacks(
+        db, status=status, user_id=user_id, limit=limit, cursor=cursor,
+    )
+    return CursorPage(
+        items=[FeedbackOut.model_validate(f) for f in items], next_cursor=next_cursor,
+    )
+
+
+@router.post("/{feedback_id}/handle", response_model=OkResponse, summary="标记反馈已处理")
+def handle_feedback(
+    feedback_id: int,
+    request: Request,
+    admin: Annotated[AdminUser, Depends(require_role("operator"))],
+    db: AdminDb,
+) -> OkResponse:
+    fb = db.get(Feedback, feedback_id)
+    if fb is None:
+        raise HTTPException(status_code=404, detail="反馈不存在")
+    before = fb.status
+    mutations.update_feedback_status(db, fb, status="handled", commit=False)
+    write_audit(
+        db, admin, action="feedback.handle", target_type="feedback", target_id=feedback_id,
+        detail={"before": before, "after": "handled"}, ip=get_client_ip(request), commit=False,
+    )
+    db.commit()
+    return OkResponse()

app/admin/routers/users.py

@@ -0,0 +1,111 @@
+"""admin 用户管理:列表 + 360 详情(读)+ 封禁/解封 + 手动调金币(写,带审计)。"""
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request
+
+from app.admin.audit import write_audit
+from app.admin.deps import AdminDb, get_client_ip, get_current_admin, require_role
+from app.admin.repositories import mutations, queries
+from app.admin.schemas.common import CursorPage, OkResponse
+from app.admin.schemas.user import (
+    AdminUserListItem,
+    AdminUserOverview,
+    GrantCoinsRequest,
+    SetUserStatusRequest,
+)
+from app.models.admin import AdminUser
+from app.repositories import user as user_repo
+from app.repositories import wallet as wallet_repo
+
+router = APIRouter(
+    prefix="/admin/api/users",
+    tags=["admin-users"],
+    dependencies=[Depends(get_current_admin)],
+)
+
+
+@router.get("", response_model=CursorPage[AdminUserListItem], summary="用户列表(筛选+分页)")
+def list_users(
+    db: AdminDb,
+    phone: Annotated[str | None, Query()] = None,
+    register_channel: Annotated[str | None, Query()] = None,
+    status: Annotated[str | None, Query()] = None,
+    limit: Annotated[int, Query(ge=1, le=100)] = 20,
+    cursor: Annotated[int | None, Query()] = None,
+) -> CursorPage[AdminUserListItem]:
+    items, next_cursor = queries.list_users(
+        db, phone=phone, register_channel=register_channel, status=status,
+        limit=limit, cursor=cursor,
+    )
+    return CursorPage(
+        items=[AdminUserListItem.model_validate(u) for u in items],
+        next_cursor=next_cursor,
+    )
+
+
+@router.get("/{user_id}", response_model=AdminUserOverview, summary="用户 360 详情")
+def get_user(user_id: int, db: AdminDb) -> AdminUserOverview:
+    overview = queries.get_user_overview(db, user_id)
+    if overview is None:
+        raise HTTPException(status_code=404, detail="用户不存在")
+    return AdminUserOverview.model_validate(overview)
+
+
+@router.post("/{user_id}/status", response_model=OkResponse, summary="封禁/解封用户")
+def set_user_status(
+    user_id: int,
+    body: SetUserStatusRequest,
+    request: Request,
+    admin: Annotated[AdminUser, Depends(require_role("operator"))],
+    db: AdminDb,
+) -> OkResponse:
+    user = user_repo.get_user_by_id(db, user_id)
+    if user is None:
+        raise HTTPException(status_code=404, detail="用户不存在")
+    if user.status == "deleted":
+        raise HTTPException(status_code=400, detail="已注销账号不可改状态")
+    before = user.status
+    # 业务写 + 审计写同一事务(commit=False),最后一起 commit:改了就有痕、有痕就真改了
+    mutations.set_user_status(db, user, status=body.status, commit=False)
+    write_audit(
+        db, admin, action="user.status.set", target_type="user", target_id=user_id,
+        detail={"before": before, "after": body.status}, ip=get_client_ip(request), commit=False,
+    )
+    db.commit()
+    return OkResponse()
+
+
+@router.post("/{user_id}/coins", response_model=OkResponse, summary="手动增减金币(带审计)")
+def grant_user_coins(
+    user_id: int,
+    body: GrantCoinsRequest,
+    request: Request,
+    admin: Annotated[AdminUser, Depends(require_role("finance"))],
+    db: AdminDb,
+) -> OkResponse:
+    if body.amount == 0:
+        raise HTTPException(status_code=400, detail="amount 不能为 0")
+    user = user_repo.get_user_by_id(db, user_id)
+    if user is None:
+        raise HTTPException(status_code=404, detail="用户不存在")
+    # 负数扣减时不允许扣成负余额(运营误操作保护)
+    if body.amount < 0:
+        acc_now = wallet_repo.get_or_create_account(db, user_id, commit=False)
+        if acc_now.coin_balance + body.amount < 0:
+            raise HTTPException(
+                status_code=400, detail=f"扣减后金币为负(当前余额 {acc_now.coin_balance})"
+            )
+    biz_type = "admin_grant" if body.amount > 0 else "admin_deduct"
+    # grant_coins 只 flush 不 commit;审计同 commit=False;最后一起 commit → 原子(改钱+留痕)
+    acc, _ = wallet_repo.grant_coins(
+        db, user_id, body.amount, biz_type=biz_type, remark=f"admin:{body.reason}"[:128],
+    )
+    write_audit(
+        db, admin, action="user.coins.grant", target_type="user", target_id=user_id,
+        detail={"amount": body.amount, "balance_after": acc.coin_balance, "reason": body.reason},
+        ip=get_client_ip(request), commit=False,
+    )
+    db.commit()
+    return OkResponse()

app/admin/routers/wallet.py

@@ -0,0 +1,49 @@
+"""admin 钱包:金币流水 + 现金流水(跨用户,可按 user_id 过滤)。手动调金币见 M3。"""
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, Query
+
+from app.admin.deps import AdminDb, get_current_admin
+from app.admin.repositories import queries
+from app.admin.schemas.common import CursorPage
+from app.admin.schemas.wallet import CashTxnOut, CoinTxnOut
+
+router = APIRouter(
+    prefix="/admin/api/wallet",
+    tags=["admin-wallet"],
+    dependencies=[Depends(get_current_admin)],
+)
+
+
+@router.get("/coin-transactions", response_model=CursorPage[CoinTxnOut], summary="金币流水")
+def coin_transactions(
+    db: AdminDb,
+    user_id: Annotated[int | None, Query()] = None,
+    biz_type: Annotated[str | None, Query()] = None,
+    limit: Annotated[int, Query(ge=1, le=100)] = 20,
+    cursor: Annotated[int | None, Query()] = None,
+) -> CursorPage[CoinTxnOut]:
+    items, next_cursor = queries.list_all_coin_transactions(
+        db, user_id=user_id, biz_type=biz_type, limit=limit, cursor=cursor,
+    )
+    return CursorPage(
+        items=[CoinTxnOut.model_validate(t) for t in items], next_cursor=next_cursor,
+    )
+
+
+@router.get("/cash-transactions", response_model=CursorPage[CashTxnOut], summary="现金流水")
+def cash_transactions(
+    db: AdminDb,
+    user_id: Annotated[int | None, Query()] = None,
+    biz_type: Annotated[str | None, Query()] = None,
+    limit: Annotated[int, Query(ge=1, le=100)] = 20,
+    cursor: Annotated[int | None, Query()] = None,
+) -> CursorPage[CashTxnOut]:
+    items, next_cursor = queries.list_all_cash_transactions(
+        db, user_id=user_id, biz_type=biz_type, limit=limit, cursor=cursor,
+    )
+    return CursorPage(
+        items=[CashTxnOut.model_validate(t) for t in items], next_cursor=next_cursor,
+    )

app/admin/routers/withdraw.py

@@ -0,0 +1,140 @@
+"""admin 提现:列表(读)+ 单笔重试查单 + 批量对账(写,带审计)。
+
+提现的钱逻辑(查微信/退款/撤单/幂等)全部复用 app.repositories.wallet,admin 只触发 + 记审计。
+这些 wallet 函数内部各自 commit(涉及微信调用),审计在其后单独 commit:操作本身幂等,
+审计记录"谁触发的 + 结果",事务边界比"改金币"宽松是有意的(不能塞进 wallet 的自有事务)。
+"""
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request
+
+from app.admin.audit import write_audit
+from app.admin.deps import AdminDb, get_client_ip, get_current_admin, require_role
+from app.admin.repositories import queries
+from app.admin.schemas.common import CursorPage
+from app.admin.schemas.wallet import ReconcileResult, WithdrawOrderOut, WithdrawRejectRequest
+from app.integrations import wxpay
+from app.models.admin import AdminUser
+from app.repositories import wallet as wallet_repo
+
+router = APIRouter(
+    prefix="/admin/api/withdraws",
+    tags=["admin-withdraw"],
+    dependencies=[Depends(get_current_admin)],
+)
+
+
+@router.get("", response_model=CursorPage[WithdrawOrderOut], summary="提现单列表")
+def list_withdraws(
+    db: AdminDb,
+    user_id: Annotated[int | None, Query()] = None,
+    status: Annotated[str | None, Query()] = None,
+    limit: Annotated[int, Query(ge=1, le=100)] = 20,
+    cursor: Annotated[int | None, Query()] = None,
+) -> CursorPage[WithdrawOrderOut]:
+    items, next_cursor = queries.list_all_withdraw_orders(
+        db, user_id=user_id, status=status, limit=limit, cursor=cursor,
+    )
+    return CursorPage(
+        items=[WithdrawOrderOut.model_validate(o) for o in items], next_cursor=next_cursor,
+    )
+
+
+# 注意:/reconcile 必须在 /{out_bill_no}/refresh 之前声明(静态路径优先于路径参数)
+@router.post("/reconcile", response_model=ReconcileResult, summary="批量对账(扫超时 pending 单)")
+def reconcile(
+    request: Request,
+    admin: Annotated[AdminUser, Depends(require_role("finance"))],
+    db: AdminDb,
+    older_than_minutes: Annotated[int, Query(ge=0)] = 15,
+) -> ReconcileResult:
+    try:
+        result = wallet_repo.reconcile_pending_withdraws(db, older_than_minutes=older_than_minutes)
+    except wxpay.WxPayNotConfiguredError as e:
+        raise HTTPException(status_code=503, detail="微信支付未配置") from e
+    write_audit(
+        db, admin, action="withdraw.reconcile", target_type="withdraw", target_id=None,
+        detail=result, ip=get_client_ip(request), commit=True,
+    )
+    return ReconcileResult(**result)
+
+
+@router.post("/{out_bill_no}/refresh", response_model=WithdrawOrderOut, summary="单笔重试查单")
+def refresh_withdraw(
+    out_bill_no: str,
+    request: Request,
+    admin: Annotated[AdminUser, Depends(require_role("finance"))],
+    db: AdminDb,
+) -> WithdrawOrderOut:
+    order = queries.get_withdraw_by_out_bill_no(db, out_bill_no)
+    if order is None:
+        raise HTTPException(status_code=404, detail="提现单不存在")
+    try:
+        refreshed = wallet_repo.refresh_withdraw_status(
+            db, order.user_id, out_bill_no, cancel_if_unconfirmed=True,
+        )
+    except wxpay.WxPayNotConfiguredError as e:
+        raise HTTPException(status_code=503, detail="微信支付未配置") from e
+    write_audit(
+        db, admin, action="withdraw.refresh", target_type="withdraw", target_id=out_bill_no,
+        detail={"status": refreshed.status, "wechat_state": refreshed.wechat_state},
+        ip=get_client_ip(request), commit=True,
+    )
+    return WithdrawOrderOut.model_validate(refreshed)
+
+
+@router.post("/{out_bill_no}/approve", response_model=WithdrawOrderOut, summary="审核通过(发起微信打款)")
+def approve_withdraw_order(
+    out_bill_no: str,
+    request: Request,
+    admin: Annotated[AdminUser, Depends(require_role("finance"))],
+    db: AdminDb,
+) -> WithdrawOrderOut:
+    """审核通过 → 调微信转账。仅 reviewing 单可通过(非 reviewing 返 409,防重复打款)。
+
+    打款的钱逻辑(转账/查单/退款/幂等)复用 wallet_repo.approve_withdraw → execute_withdraw_transfer;
+    返回的 order 可能是 pending(在途/待用户确认)/success/failed(打款失败已退),admin 前端按 status 展示。
+    """
+    try:
+        order = wallet_repo.approve_withdraw(db, out_bill_no)
+    except wallet_repo.WithdrawOrderNotFound as e:
+        raise HTTPException(status_code=404, detail="提现单不存在") from e
+    except wallet_repo.WithdrawNotReviewable as e:
+        raise HTTPException(status_code=409, detail=str(e)) from e
+    except wxpay.WxPayNotConfiguredError as e:
+        raise HTTPException(status_code=503, detail="微信支付未配置") from e
+    write_audit(
+        db, admin, action="withdraw.approve", target_type="withdraw", target_id=out_bill_no,
+        detail={
+            "status": order.status,
+            "wechat_state": order.wechat_state,
+            "amount_cents": order.amount_cents,
+        },
+        ip=get_client_ip(request), commit=True,
+    )
+    return WithdrawOrderOut.model_validate(order)
+
+
+@router.post("/{out_bill_no}/reject", response_model=WithdrawOrderOut, summary="审核拒绝(退回现金)")
+def reject_withdraw_order(
+    out_bill_no: str,
+    body: WithdrawRejectRequest,
+    request: Request,
+    admin: Annotated[AdminUser, Depends(require_role("finance"))],
+    db: AdminDb,
+) -> WithdrawOrderOut:
+    """审核拒绝 → 退回用户现金 + 置 rejected,理由写入 fail_reason(用户可见)。仅 reviewing 单可拒。"""
+    try:
+        order = wallet_repo.reject_withdraw(db, out_bill_no, body.reason)
+    except wallet_repo.WithdrawOrderNotFound as e:
+        raise HTTPException(status_code=404, detail="提现单不存在") from e
+    except wallet_repo.WithdrawNotReviewable as e:
+        raise HTTPException(status_code=409, detail=str(e)) from e
+    write_audit(
+        db, admin, action="withdraw.reject", target_type="withdraw", target_id=out_bill_no,
+        detail={"reason": body.reason, "amount_cents": order.amount_cents},
+        ip=get_client_ip(request), commit=True,
+    )
+    return WithdrawOrderOut.model_validate(order)

app/admin/schemas/__init__.py

@@ -0,0 +1 @@
+"""admin 请求/响应 schemas(snake_case,与前端约定一致)。"""

app/admin/schemas/admin.py

@@ -0,0 +1,37 @@
+"""admin 账号管理 + 审计日志 schemas。"""
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+_Role = Literal["super_admin", "finance", "operator"]
+
+
+class AdminCreateRequest(BaseModel):
+    username: str = Field(..., min_length=3, max_length=64)
+    password: str = Field(..., min_length=8, max_length=72)  # bcrypt ≤72 字节
+    role: _Role = "operator"
+
+
+class AdminUpdateRequest(BaseModel):
+    """改角色 / 启用禁用 / 重置密码,字段都可选(只改传了的)。"""
+
+    role: _Role | None = None
+    status: Literal["active", "disabled"] | None = None
+    password: str | None = Field(None, min_length=8, max_length=72)
+
+
+class AdminAuditLogOut(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    admin_id: int
+    admin_username: str
+    action: str
+    target_type: str
+    target_id: str | None = None
+    detail: dict | None = None
+    ip: str | None = None
+    created_at: datetime

app/admin/schemas/auth.py

@@ -0,0 +1,29 @@
+"""Admin 认证 schemas。"""
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class AdminLoginRequest(BaseModel):
+    username: str = Field(..., min_length=1, max_length=64)
+    password: str = Field(..., min_length=1, max_length=128)
+
+
+class AdminOut(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    username: str
+    role: str
+    status: str
+    created_at: datetime
+    last_login_at: datetime | None = None
+
+
+class AdminLoginResponse(BaseModel):
+    access_token: str
+    token_type: str = "Bearer"
+    expires_in: int = Field(..., description="access_token 剩余秒数(过期重新登录)")
+    admin: AdminOut

app/admin/schemas/common.py

@@ -0,0 +1,19 @@
+"""通用 schema:游标分页响应 + 通用 ok 响应。"""
+from __future__ import annotations
+
+from typing import Generic, TypeVar
+
+from pydantic import BaseModel
+
+T = TypeVar("T")
+
+
+class CursorPage(BaseModel, Generic[T]):
+    """游标分页响应:items + 下一页游标(next_cursor=None 表示末页)。"""
+
+    items: list[T]
+    next_cursor: int | None = None
+
+
+class OkResponse(BaseModel):
+    ok: bool = True

app/admin/schemas/config.py

@@ -0,0 +1,22 @@
+"""admin 运营配置 schemas。"""
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class ConfigItemOut(BaseModel):
+    key: str
+    label: str
+    group: str
+    type: str  # int / int_list / dict_str_int
+    help: str | None = None
+    default: Any
+    value: Any
+    overridden: bool  # 是否被运营覆盖过(false=用默认)
+    updated_at: str | None = None
+
+
+class ConfigUpdateRequest(BaseModel):
+    value: Any

app/admin/schemas/dashboard.py

@@ -0,0 +1,48 @@
+"""admin 大盘 schemas(对应 stats.dashboard_overview 的嵌套结构)。"""
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class DashboardUsers(BaseModel):
+    total: int
+    active: int
+    disabled: int
+    deleted: int
+    new_today: int
+    dau: int
+
+
+class DashboardCoins(BaseModel):
+    granted_total: int
+
+
+class DashboardCash(BaseModel):
+    withdraw_success_cents: int
+    withdraw_pending_count: int
+    withdraw_success_count: int
+    withdraw_failed_count: int
+
+
+class DashboardComparison(BaseModel):
+    total: int
+    success: int
+    success_rate: float
+
+
+class DashboardFeedback(BaseModel):
+    new: int
+
+
+class DashboardCps(BaseModel):
+    available: bool
+    note: str
+
+
+class DashboardOverview(BaseModel):
+    users: DashboardUsers
+    coins: DashboardCoins
+    cash: DashboardCash
+    comparison: DashboardComparison
+    feedback: DashboardFeedback
+    cps: DashboardCps

app/admin/schemas/feedback.py

@@ -0,0 +1,18 @@
+"""admin 反馈工单 schemas。"""
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict
+
+
+class FeedbackOut(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    user_id: int
+    content: str
+    contact: str
+    images: list[str] | None = None
+    status: str
+    created_at: datetime

app/admin/schemas/user.py

@@ -0,0 +1,47 @@
+"""admin 用户管理 schemas。"""
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class AdminUserListItem(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    phone: str
+    nickname: str | None = None
+    register_channel: str
+    status: str
+    wechat_openid: str | None = None
+    created_at: datetime
+    last_login_at: datetime
+
+
+class AdminUserOverview(BaseModel):
+    """用户 360 概览:基础资料 + 钱包余额 + 各项 count(历史明细走各自分页接口)。"""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    user: AdminUserListItem
+    coin_balance: int
+    cash_balance_cents: int
+    total_coin_earned: int
+    comparison_total: int
+    comparison_success: int
+    withdraw_total: int
+    withdraw_success_cents: int
+    feedback_total: int
+
+
+class GrantCoinsRequest(BaseModel):
+    amount: int = Field(..., description="金币变动:正=增加,负=扣减(不可为 0)")
+    reason: str = Field(..., min_length=1, max_length=128, description="操作原因(必填,入审计)")
+
+
+class SetUserStatusRequest(BaseModel):
+    status: Literal["active", "disabled"] = Field(
+        ..., description="active=解封 / disabled=封禁(注销 deleted 不走此接口)"
+    )

app/admin/schemas/wallet.py

@@ -0,0 +1,59 @@
+"""admin 钱包(金币/现金流水 + 提现单)schemas。"""
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class CoinTxnOut(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    user_id: int
+    amount: int
+    balance_after: int
+    biz_type: str
+    ref_id: str | None = None
+    remark: str | None = None
+    created_at: datetime
+
+
+class CashTxnOut(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    user_id: int
+    amount_cents: int
+    balance_after_cents: int
+    biz_type: str
+    ref_id: str | None = None
+    remark: str | None = None
+    created_at: datetime
+
+
+class WithdrawOrderOut(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    user_id: int
+    out_bill_no: str
+    amount_cents: int
+    user_name: str | None = None  # 提现实名(审核核对 + 打款用)
+    status: str
+    wechat_state: str | None = None
+    transfer_bill_no: str | None = None
+    fail_reason: str | None = None
+    created_at: datetime
+    updated_at: datetime
+
+
+class ReconcileResult(BaseModel):
+    checked: int
+    resolved: int
+
+
+class WithdrawRejectRequest(BaseModel):
+    reason: str = Field(
+        ..., min_length=1, max_length=200, description="拒绝理由(写入 fail_reason,用户可见)"
+    )

app/admin/security.py

@@ -0,0 +1,55 @@
+"""Admin JWT:与 App 用户 token 完全隔离。
+
+用独立 secret(settings.ADMIN_JWT_SECRET ≠ JWT_SECRET_KEY)+ payload typ="admin",
+双重保证 App 用户的 access_token 无法当 admin token 用(secret 不同直接验签失败)。
+admin 无 refresh:过期(默认 12h)重新登录,简单。
+"""
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from typing import Any
+
+import jwt
+
+from app.core.config import settings
+
+_ALGO = "HS256"
+
+
+class AdminTokenError(Exception):
+    """admin token 解析/校验失败,api 层捕获后返回 401。"""
+
+
+def _now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def create_admin_token(*, admin_id: int, role: str) -> tuple[str, int]:
+    """签发 admin access token,返回 (token, expires_in_seconds)。"""
+    now = _now()
+    expire = now + timedelta(minutes=settings.ADMIN_JWT_EXPIRE_MINUTES)
+    payload: dict[str, Any] = {
+        "sub": str(admin_id),
+        "role": role,
+        "typ": "admin",
+        "iat": int(now.timestamp()),
+        "exp": int(expire.timestamp()),
+    }
+    token = jwt.encode(payload, settings.ADMIN_JWT_SECRET, algorithm=_ALGO)
+    return token, int((expire - now).total_seconds())
+
+
+def decode_admin_token(token: str) -> dict[str, Any]:
+    """解析校验 admin token。签名错/过期/typ 非 admin → AdminTokenError。"""
+    try:
+        payload = jwt.decode(token, settings.ADMIN_JWT_SECRET, algorithms=[_ALGO])
+    except jwt.ExpiredSignatureError as e:
+        raise AdminTokenError("token expired") from e
+    except jwt.InvalidTokenError as e:
+        raise AdminTokenError(f"invalid token: {e}") from e
+
+    if payload.get("typ") != "admin":
+        raise AdminTokenError("not an admin token")
+    if "sub" not in payload:
+        raise AdminTokenError("token missing sub")
+    return payload

app/api/v1/ad.py

@@ -0,0 +1,200 @@
+"""看激励视频发奖 endpoint。
+
+路由前缀 `/api/v1/ad`:
+  GET  /pangle-callback   穿山甲 S2S 发奖回调(**无 JWT,靠验签**),穿山甲服务器调
+  GET  /reward-status     客户端查今日看广告发奖进度(Bearer)
+
+发奖走服务端:激励视频播完穿山甲回调本接口,验签通过后幂等发金币。客户端只负责
+看完后刷新余额,不参与发奖,被破解也刷不到钱。
+"""
+from __future__ import annotations
+
+import logging
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException, Request, status
+
+from app.api.deps import CurrentUser, DbSession
+from app.core import rewards
+from app.core.config import settings
+from app.integrations import pangle
+from app.core.ratelimit import rate_limit
+from app.repositories import ad_ecpm as crud_ecpm
+from app.repositories import ad_reward as crud_ad
+from app.repositories import ad_watch as crud_watch
+from app.schemas.ad import (
+    AdRewardStatusOut,
+    EcpmReportIn,
+    EcpmReportOut,
+    PangleCallbackOut,
+    TestGrantOut,
+    WatchReportIn,
+    WatchReportOut,
+)
+
+logger = logging.getLogger("shagua.ad")
+
+router = APIRouter(prefix="/api/v1/ad", tags=["ad"])
+
+# GroMore 回调 is_verify=false 时透传给客户端 SDK 的错误码(自定义,仅用于排查/客户端提示)
+REASON_OK = 0
+REASON_BAD_PARAMS = 1  # 验签过但缺 trans_id / user_id 非数字
+REASON_UNKNOWN_USER = 2  # user_id 不存在(可能伪造)
+
+
+@router.get(
+    "/pangle-callback",
+    response_model=PangleCallbackOut,
+    summary="穿山甲激励视频发奖回调(S2S,验签)",
+    dependencies=[Depends(rate_limit(300, 60, "pangle-callback"))],
+)
+def pangle_callback(request: Request, db: DbSession) -> PangleCallbackOut:
+    """穿山甲 GroMore 在激励视频播完后回调,带 user_id / trans_id / reward_amount / sign 等 query 参数。
+
+    流程:开关/密钥就绪 → 验签(SHA256(m-key:trans_id)) → 解析 user_id/reward_amount → 幂等发金币。
+    验签失败 403(留给真请求重试);参数缺/坏或 user 不存在 → is_verify=false + reason(不发,不重试)。
+    granted / capped → is_verify=true + reason=0。
+    """
+    if not settings.pangle_callback_configured:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE, detail="pangle callback not configured"
+        )
+
+    params = dict(request.query_params)
+
+    if not pangle.verify_callback_sign(params, settings.PANGLE_REWARD_SECRET):
+        logger.warning("pangle callback bad sign trans_id=%s", params.get("trans_id"))
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="bad sign")
+
+    trans_id = params.get("trans_id") or ""
+    raw_user_id = params.get("user_id") or ""
+    if not trans_id or not raw_user_id.isdigit():
+        # 验签过了但参数缺/坏:不发奖(is_verify=false),带错误码
+        logger.warning("pangle callback bad params: %s", params)
+        return PangleCallbackOut(is_verify=False, reason=REASON_BAD_PARAMS)
+
+    user_id = int(raw_user_id)
+    coin = rewards.resolve_ad_reward_coin(db, params.get("reward_amount"))
+    raw = "&".join(f"{k}={v}" for k, v in sorted(params.items()) if k != "sign")
+    try:
+        rec = crud_ad.grant_ad_reward(
+            db, user_id, trans_id, coin=coin,
+            reward_name=params.get("reward_name"), raw=raw[:1024],
+        )
+    except crud_ad.UnknownUserError:
+        logger.warning("pangle callback unknown user_id=%d trans_id=%s", user_id, trans_id)
+        return PangleCallbackOut(is_verify=False, reason=REASON_UNKNOWN_USER)
+
+    logger.info(
+        "ad reward user_id=%d trans_id=%s status=%s coin=%d", user_id, trans_id, rec.status, rec.coin
+    )
+    # granted / capped 均算"已处理":is_verify=true 不让穿山甲重试(capped 只是没加币)
+    return PangleCallbackOut(is_verify=True, reason=REASON_OK)
+
+
+@router.get("/reward-status", response_model=AdRewardStatusOut, summary="今日看广告发奖进度")
+def reward_status(user: CurrentUser, db: DbSession) -> AdRewardStatusOut:
+    (used, limit, coin_per, round_count, cooldown_until,
+     watched_sec, watch_limit) = crud_ad.today_status(db, user.id)
+    return AdRewardStatusOut(
+        used_today=used,
+        daily_limit=limit,
+        remaining=max(0, limit - used),
+        coin_per_ad=coin_per,
+        round_count=round_count,
+        cooldown_until=cooldown_until,
+        watched_seconds_today=watched_sec,
+        watch_seconds_limit=watch_limit,
+        watch_seconds_remaining=max(0, watch_limit - watched_sec),
+    )
+
+
+@router.post(
+    "/watch-report",
+    response_model=WatchReportOut,
+    summary="上报激励视频观看时长(每日 50 分钟防刷计时)",
+    dependencies=[Depends(rate_limit(120, 60, "ad-watch-report"))],
+)
+def watch_report(payload: WatchReportIn, user: CurrentUser, db: DbSession) -> WatchReportOut:
+    """客户端在激励视频关闭(onAdClose)后上报本次实际观看秒数,服务端累计到当日总时长。
+
+    Bearer 鉴权,user_id 取自 JWT(不信 body)。seconds 服务端夹 [0, MAX_SINGLE_WATCH_SECONDS]。
+    当日累计达 DAILY_AD_WATCH_SECONDS_LIMIT(50 分钟)后:① 本接口 / reward-status 返回 remaining=0,
+    客户端不再展示广告;② 后端发奖(S2S 回调)也会因时长闸记 capped 不发金币(双闸,前端绕不过)。
+    """
+    total = crud_watch.add_watch_seconds(db, user.id, payload.seconds)
+    limit = rewards.DAILY_AD_WATCH_SECONDS_LIMIT
+    logger.info(
+        "ad watch report user_id=%d +%ds total=%d/%d",
+        user.id, payload.seconds, total, limit,
+    )
+    return WatchReportOut(
+        watched_seconds_today=total,
+        watch_seconds_limit=limit,
+        watch_seconds_remaining=max(0, limit - total),
+    )
+
+
+@router.post(
+    "/ecpm-report",
+    response_model=EcpmReportOut,
+    summary="上报本次广告展示的 eCPM(内部收益统计)",
+    dependencies=[Depends(rate_limit(120, 60, "ad-ecpm-report"))],
+)
+def ecpm_report(payload: EcpmReportIn, user: CurrentUser, db: DbSession) -> EcpmReportOut:
+    """客户端在广告展示后(onAdShow 读 getShowEcpm)上报 eCPM,落库做内部收益统计/对账。
+
+    Bearer 鉴权,user_id 取自 JWT(不信 body)。best-effort:落库即 ok,客户端 fire-and-forget,
+    丢一两条不影响业务(穿山甲后台报表是结算权威)。eCPM 与发奖(S2S)是两条独立流,不逐条关联。
+    """
+    crud_ecpm.create_ecpm_record(
+        db, user.id,
+        ad_type=payload.ad_type, ecpm_raw=payload.ecpm,
+        adn=payload.adn, slot_id=payload.slot_id,
+    )
+    logger.info(
+        "ad ecpm report user_id=%d type=%s ecpm=%s adn=%s slot=%s",
+        user.id, payload.ad_type, payload.ecpm, payload.adn, payload.slot_id,
+    )
+    return EcpmReportOut(ok=True)
+
+
+@router.post(
+    "/test-grant",
+    response_model=TestGrantOut,
+    summary="[仅本地联调]模拟穿山甲回调发奖",
+    dependencies=[Depends(rate_limit(60, 60, "ad-test-grant"))],
+)
+def test_grant(user: CurrentUser, db: DbSession) -> TestGrantOut:
+    """⚠️ 仅本地联调用:没部署公网、穿山甲 S2S 回调打不到本地时,客户端(debug 包)看完广告后
+    调这个接口,直接走与回调相同的发奖逻辑(幂等 + 每日上限),验证"看广告→金币到账"全链路。
+
+    必须 settings.AD_REWARD_TEST_GRANT_ENABLED=true 才开放(默认 False),否则 404 当不存在。
+    它让已登录客户端能自助发奖 = 绕过反作弊,**生产必须关闭**。
+    """
+    if not settings.AD_REWARD_TEST_GRANT_ENABLED:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="not found")
+
+    # 每次新 trans_id,模拟一次独立的穿山甲发奖回调(幂等键各不相同 → 每次都发,直到当日上限)
+    trans_id = f"test-{user.id}-{uuid.uuid4().hex}"
+    try:
+        rec = crud_ad.grant_ad_reward(
+            db, user.id, trans_id, reward_name="测试发奖", raw="client debug test-grant"
+        )
+    except crud_ad.UnknownUserError as e:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="user not found") from e
+
+    (used, limit, coin_per, round_count, cooldown_until,
+     _watched, _watch_limit) = crud_ad.today_status(db, user.id)
+    logger.info("ad TEST grant user_id=%d status=%s coin=%d", user.id, rec.status, rec.coin)
+    return TestGrantOut(
+        granted=(rec.status == "granted"),
+        status=rec.status,
+        coin=rec.coin,
+        used_today=used,
+        daily_limit=limit,
+        remaining=max(0, limit - used),
+        coin_per_ad=coin_per,
+        round_count=round_count,
+        cooldown_until=cooldown_until,
+    )

app/api/v1/auth.py

@@ -12,13 +12,14 @@ from __future__ import annotations
 
 import logging
 
-from fastapi import APIRouter, HTTPException, status
+from fastapi import APIRouter, Depends, HTTPException, status
 
 from app.api.deps import CurrentUser, DbSession
-from app.core.jiguang import JiguangError, mask_phone, verify_and_get_phone
+from app.core.ratelimit import rate_limit
 from app.core.security import TokenError, decode_token, issue_token_pair
-from app.core.sms import SmsError, send_code, verify_code
-from app.crud import user as crud_user
+from app.integrations.jiguang import JiguangError, mask_phone, verify_and_get_phone
+from app.integrations.sms import SmsError, send_code, verify_code
+from app.repositories import user as user_repo
 from app.schemas.auth import (
     JverifyLoginRequest,
     LogoutResponse,
@@ -61,7 +62,7 @@ def jverify_login(req: JverifyLoginRequest, db: DbSession) -> TokenWithUser:
         logger.error("[JG] verify+decrypt failed: %s", e, exc_info=True)
         raise HTTPException(status_code=502, detail=f"jiguang verify failed: {e}") from e
 
-    user = crud_user.upsert_user_for_login(db, phone=phone, register_channel="jverify")
+    user = user_repo.upsert_user_for_login(db, phone=phone, register_channel="jverify")
     if user.status != "active":
         raise HTTPException(status_code=403, detail="account disabled")
 
@@ -71,24 +72,34 @@ def jverify_login(req: JverifyLoginRequest, db: DbSession) -> TokenWithUser:
 
 # ===================== 短信登录 =====================
 
-@router.post("/sms/send", response_model=SmsSendResponse, summary="发送短信验证码 (mock)")
+@router.post(
+    "/sms/send",
+    response_model=SmsSendResponse,
+    summary="发送短信验证码",
+    dependencies=[Depends(rate_limit(10, 60, "sms-send"))],  # 同 IP 每分钟≤10 次(防一 IP 刷不同号)
+)
 def sms_send(req: SmsSendRequest) -> SmsSendResponse:
     try:
         cooldown = send_code(req.phone)
     except SmsError as e:
-        raise HTTPException(status_code=429, detail=str(e)) from e
+        raise HTTPException(status_code=e.status_code, detail=str(e)) from e
 
     from app.core.config import settings  # 局部 import 避免循环
 
     return SmsSendResponse(sent=True, mock=settings.SMS_MOCK, cooldown_sec=cooldown)
 
 
-@router.post("/sms/login", response_model=TokenWithUser, summary="手机号+验证码登录")
+@router.post(
+    "/sms/login",
+    response_model=TokenWithUser,
+    summary="手机号+验证码登录",
+    dependencies=[Depends(rate_limit(20, 60, "sms-login"))],  # 防撞库爆破(另有单码失败次数上限)
+)
 def sms_login(req: SmsLoginRequest, db: DbSession) -> TokenWithUser:
     if not verify_code(req.phone, req.code):
         raise HTTPException(status_code=400, detail="invalid sms code")
 
-    user = crud_user.upsert_user_for_login(db, phone=req.phone, register_channel="sms")
+    user = user_repo.upsert_user_for_login(db, phone=req.phone, register_channel="sms")
     if user.status != "active":
         raise HTTPException(status_code=403, detail="account disabled")
 
@@ -106,7 +117,7 @@ def refresh(req: RefreshRequest, db: DbSession) -> TokenPair:
         raise HTTPException(status_code=401, detail=str(e)) from e
 
     user_id = int(payload["sub"])
-    user = crud_user.get_user_by_id(db, user_id)
+    user = user_repo.get_user_by_id(db, user_id)
     if user is None or user.status != "active":
         raise HTTPException(status_code=401, detail="user not found or disabled")
 

app/api/v1/compare.py

@@ -0,0 +1,95 @@
+"""外卖比价业务透传端点。
+
+把客户端的 POST /api/v1/intent/recognize 和 /api/v1/price/step 请求原样转发给
+pricebot-backend 的 /api/intent/recognize 和 /api/price/step。MVP 阶段**不鉴权**
+(同 coupon/step,见 docs/待办与技术债.md P1:device_id 透传区分设备,待补 JWT +
+device_id↔user_id 绑定后才能做用户级画像)。
+
+- Phase 1 /intent/recognize:从源平台(淘宝闪购/美团/京东外卖)购物车页识别店名+菜品+
+  价格,一次性。
+- Phase 2 /price/step:多轮循环,在目标平台复现订单读到手价,直到 done。
+
+真正的目标驱动比价逻辑在 pricebot-backend(GoalEngine,另一个 repo),本接口只是透传壳。
+电商(ecom)那两个端点 food MVP 暂不需要,以后放开 scene 时再加 /ecom/intent/recognize
+和 /ecom/step 两行即可。
+
+pricebot 协议文档:
+  pricebot-backend/docs/main/02_api_protocol.md
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import httpx
+from fastapi import APIRouter, HTTPException, Request, status
+
+from app.core.config import settings
+
+logger = logging.getLogger("shagua.compare")
+
+router = APIRouter(prefix="/api/v1", tags=["compare"])
+
+
+async def _passthrough(request: Request, upstream_path: str) -> dict[str, Any]:
+    """把请求体原样转发给 pricebot-backend 的 {upstream_path}。
+
+    跟 coupon_step 同款透传壳:不鉴权、不做 schema 校验,仅读 device_id/trace_id/step
+    打日志。比价单帧是大上下文 / 逐帧 LLM,超时用 PRICEBOT_COMPARE_TIMEOUT_SEC(60s,
+    比领券的 30s 长)。
+    """
+    try:
+        body = await request.json()
+    except Exception as e:
+        raise HTTPException(status_code=400, detail=f"invalid json body: {e}") from e
+
+    url = f"{settings.PRICEBOT_BASE_URL.rstrip('/')}{upstream_path}"
+    timeout = settings.PRICEBOT_COMPARE_TIMEOUT_SEC
+
+    logger.info(
+        "compare %s device_id=%s trace_id=%s step=%s",
+        upstream_path,
+        body.get("device_id"),
+        body.get("trace_id"),
+        body.get("step"),
+    )
+
+    try:
+        async with httpx.AsyncClient(timeout=timeout) as client:
+            resp = await client.post(url, json=body)
+    except httpx.RequestError as e:
+        logger.error("[pricebot] request failed: %s", e)
+        raise HTTPException(
+            status_code=status.HTTP_502_BAD_GATEWAY,
+            detail=f"pricebot upstream unreachable: {e}",
+        ) from e
+
+    if resp.status_code >= 500:
+        logger.error(
+            "[pricebot] 5xx status=%d body=%s",
+            resp.status_code,
+            resp.text[:500],
+        )
+        raise HTTPException(
+            status_code=status.HTTP_502_BAD_GATEWAY,
+            detail=f"pricebot upstream returned {resp.status_code}",
+        )
+
+    return resp.json()
+
+
+@router.post("/intent/recognize", summary="外卖比价 Phase 1 意图识别 (透传到 pricebot)")
+async def intent_recognize(request: Request) -> dict[str, Any]:
+    return await _passthrough(request, "/api/intent/recognize")
+
+
+@router.post("/intent/step", summary="外卖比价 Phase 1 多帧意图识别 (透传到 pricebot, 仅淘宝源)")
+async def intent_step(request: Request) -> dict[str, Any]:
+    # 多帧版意图识别(展开+滚动采集→提取): 循环调用直到 done(done 帧顶层带
+    # result+calibration)。目前仅淘宝源走这条, 其它源走上面单次 /intent/recognize。
+    return await _passthrough(request, "/api/intent/step")
+
+
+@router.post("/price/step", summary="外卖比价 Phase 2 步进 (透传到 pricebot)")
+async def price_step(request: Request) -> dict[str, Any]:
+    return await _passthrough(request, "/api/price/step")

app/api/v1/compare_milestone.py

@@ -0,0 +1,76 @@
+"""比价战绩里程碑 endpoint(福利页「记录比价战绩」)。
+
+路由前缀 `/api/v1/compare`:
+  GET  /milestones                进度与各档领取状态
+  POST /milestones/{milestone}/claim  领取某档奖励
+
+**均需鉴权**。解锁进度 = 该用户 status='success' 的 comparison_record 条数;每档领一次。
+"""
+from __future__ import annotations
+
+import logging
+
+from fastapi import APIRouter, HTTPException, status
+
+from app.api.deps import CurrentUser, DbSession
+from app.repositories import comparison_milestone as crud_milestone
+from app.schemas.compare_record import (
+    MilestoneClaimResultOut,
+    MilestoneStateOut,
+    MilestoneStatusOut,
+)
+
+logger = logging.getLogger("shagua.compare_milestone")
+
+router = APIRouter(prefix="/api/v1/compare", tags=["compare-milestone"])
+
+
+@router.get(
+    "/milestones",
+    response_model=MilestoneStatusOut,
+    summary="比价战绩里程碑进度",
+)
+def get_milestones(user: CurrentUser, db: DbSession) -> MilestoneStatusOut:
+    st = crud_milestone.get_status(db, user.id)
+    return MilestoneStatusOut(
+        success_count=st.success_count,
+        claimable_count=st.claimable_count,
+        milestones=[
+            MilestoneStateOut(milestone=m.milestone, coin=m.coin, state=m.state)
+            for m in st.milestones
+        ],
+    )
+
+
+@router.post(
+    "/milestones/{milestone}/claim",
+    response_model=MilestoneClaimResultOut,
+    summary="领取比价战绩里程碑奖励",
+)
+def claim_milestone(
+    milestone: int, user: CurrentUser, db: DbSession
+) -> MilestoneClaimResultOut:
+    try:
+        coin, balance = crud_milestone.claim(db, user.id, milestone)
+    except crud_milestone.UnknownMilestoneError as e:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="unknown milestone"
+        ) from e
+    except crud_milestone.MilestoneLockedError as e:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT, detail="milestone locked"
+        ) from e
+    except crud_milestone.AlreadyClaimedError as e:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT, detail="milestone already claimed"
+        ) from e
+
+    logger.info(
+        "compare milestone claimed user_id=%d milestone=%d coin=%d",
+        user.id,
+        milestone,
+        coin,
+    )
+    return MilestoneClaimResultOut(
+        milestone=milestone, coin_awarded=coin, coin_balance=balance
+    )

app/api/v1/compare_record.py

@@ -0,0 +1,86 @@
+"""比价记录 endpoint(「我的比价记录」数据源)。
+
+路由前缀 `/api/v1/compare`:
+  POST /record         上报一次比价结果(幂等:同 user+trace_id 覆盖)
+  GET  /records        比价记录列表(游标分页)
+  GET  /records/{id}   单条详情(含 raw_payload 全量)
+
+**均需鉴权**(CurrentUser)——与同文件无关的不鉴权透传 `compare.py` 分开:那个是
+转发壳(MVP 不鉴权),这里是按用户维度落库的业务接口,必须有 user_id。
+
+注:本轮只做 server 端,客户端(android 仓)在 done 帧后调 POST /record 上报的改动
+另起一轮(见 app-server docs/待办与技术债.md P1)。
+"""
+from __future__ import annotations
+
+import logging
+
+from fastapi import APIRouter, HTTPException, Query, status
+
+from app.api.deps import CurrentUser, DbSession
+from app.repositories import comparison as crud_compare
+from app.schemas.compare_record import (
+    ComparisonRecordCreatedOut,
+    ComparisonRecordDetailOut,
+    ComparisonRecordIn,
+    ComparisonRecordPage,
+    ComparisonRecordOut,
+)
+
+logger = logging.getLogger("shagua.compare_record")
+
+router = APIRouter(prefix="/api/v1/compare", tags=["compare-record"])
+
+
+@router.post(
+    "/record",
+    response_model=ComparisonRecordCreatedOut,
+    summary="上报一次比价结果(幂等)",
+)
+def report_record(
+    payload: ComparisonRecordIn, user: CurrentUser, db: DbSession
+) -> ComparisonRecordCreatedOut:
+    rec = crud_compare.upsert_record(db, user_id=user.id, payload=payload)
+    logger.info(
+        "compare record user=%s trace=%s biz=%s status=%s saved=%s",
+        user.id,
+        rec.trace_id,
+        rec.business_type,
+        rec.status,
+        rec.saved_amount_cents,
+    )
+    return ComparisonRecordCreatedOut(id=rec.id)
+
+
+@router.get(
+    "/records",
+    response_model=ComparisonRecordPage,
+    summary="比价记录列表(游标分页)",
+)
+def list_records(
+    user: CurrentUser,
+    db: DbSession,
+    limit: int = Query(20, ge=1, le=100),
+    cursor: int | None = Query(None, description="上一页末条 id"),
+) -> ComparisonRecordPage:
+    items, next_cursor = crud_compare.list_records(
+        db, user.id, limit=limit, cursor=cursor
+    )
+    return ComparisonRecordPage(
+        items=[ComparisonRecordOut.model_validate(it) for it in items],
+        next_cursor=next_cursor,
+    )
+
+
+@router.get(
+    "/records/{record_id}",
+    response_model=ComparisonRecordDetailOut,
+    summary="比价记录详情(含 raw_payload)",
+)
+def get_record(
+    record_id: int, user: CurrentUser, db: DbSession
+) -> ComparisonRecordDetailOut:
+    rec = crud_compare.get_record(db, user.id, record_id)
+    if rec is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="record not found")
+    return ComparisonRecordDetailOut.model_validate(rec)

app/api/v1/coupon.py

@@ -0,0 +1,72 @@
+"""领券业务透传端点。
+
+把客户端的 POST /api/v1/coupon/step 请求原样转发给 pricebot-backend
+的 /api/coupon/step。MVP 阶段**不鉴权**(见 docs/待办与技术债.md P1:
+device_id 透传给 pricebot 区分设备,待补 JWT + device_id↔user_id 绑定后
+才能做用户级画像)。
+
+pricebot 协议文档:
+  pricebot-backend/docs/projects/领券-客户端对接协议.md
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import httpx
+from fastapi import APIRouter, HTTPException, Request, status
+
+from app.core.config import settings
+
+logger = logging.getLogger("shagua.coupon")
+
+router = APIRouter(prefix="/api/v1/coupon", tags=["coupon"])
+
+
+@router.post("/step", summary="领券任务步进 (透传到 pricebot)")
+async def coupon_step(
+    request: Request,
+) -> dict[str, Any]:
+    """把请求体原样转发给 pricebot-backend 的 /api/coupon/step。
+
+    - 鉴权: MVP 阶段不鉴权(待补 JWT,见 docs/待办与技术债.md P1)
+    - 透传: 不做 schema 校验,pricebot 自己校验
+    - 失败: 网络不可达 / pricebot 5xx → 502 + 友好 message
+    """
+    try:
+        body = await request.json()
+    except Exception as e:
+        raise HTTPException(status_code=400, detail=f"invalid json body: {e}") from e
+
+    url = f"{settings.PRICEBOT_BASE_URL.rstrip('/')}/api/coupon/step"
+    timeout = settings.PRICEBOT_REQUEST_TIMEOUT_SEC
+
+    logger.info(
+        "coupon_step device_id=%s trace_id=%s step=%s",
+        body.get("device_id"),
+        body.get("trace_id"),
+        body.get("step"),
+    )
+
+    try:
+        async with httpx.AsyncClient(timeout=timeout) as client:
+            resp = await client.post(url, json=body)
+    except httpx.RequestError as e:
+        logger.error("[pricebot] request failed: %s", e)
+        raise HTTPException(
+            status_code=status.HTTP_502_BAD_GATEWAY,
+            detail=f"pricebot upstream unreachable: {e}",
+        ) from e
+
+    if resp.status_code >= 500:
+        logger.error(
+            "[pricebot] 5xx status=%d body=%s",
+            resp.status_code,
+            resp.text[:500],
+        )
+        raise HTTPException(
+            status_code=status.HTTP_502_BAD_GATEWAY,
+            detail=f"pricebot upstream returned {resp.status_code}",
+        )
+
+    return resp.json()

app/api/v1/feedback.py

@@ -0,0 +1,63 @@
+"""帮助与反馈 endpoint。
+
+路由前缀 `/api/v1/feedback`,需 Bearer 鉴权(反馈绑到登录用户,便于回访)。
+  POST /  提交反馈(multipart:content / contact 必填,images 可选 ≤4 张)
+
+截图复用 [app.core.media] 落盘到 /media/feedback/。
+"""
+from __future__ import annotations
+
+import logging
+
+from fastapi import APIRouter, File, Form, HTTPException, UploadFile
+
+from app.api.deps import CurrentUser, DbSession
+from app.core import media
+from app.repositories import feedback as feedback_repo
+from app.schemas.feedback import FeedbackOut
+
+logger = logging.getLogger("shagua.feedback")
+
+router = APIRouter(prefix="/api/v1/feedback", tags=["feedback"])
+
+_MAX_IMAGES = 4
+_CONTENT_MAX = 2000
+_CONTACT_MAX = 128
+
+
+@router.post("", response_model=FeedbackOut, summary="提交反馈")
+async def submit_feedback(
+    user: CurrentUser,
+    db: DbSession,
+    content: str = Form(...),
+    contact: str = Form(...),
+    images: list[UploadFile] = File(default=[]),
+) -> FeedbackOut:
+    content = content.strip()
+    contact = contact.strip()
+    if not content:
+        raise HTTPException(status_code=400, detail="反馈内容不能为空")
+    if len(content) > _CONTENT_MAX:
+        raise HTTPException(status_code=400, detail="反馈内容过长")
+    if not contact:
+        raise HTTPException(status_code=400, detail="联系方式不能为空")
+    if len(contact) > _CONTACT_MAX:
+        raise HTTPException(status_code=400, detail="联系方式过长")
+
+    files = [f for f in (images or []) if f is not None and f.filename]
+    if len(files) > _MAX_IMAGES:
+        raise HTTPException(status_code=400, detail=f"最多上传 {_MAX_IMAGES} 张图片")
+
+    urls: list[str] = []
+    for f in files:
+        data = await f.read()
+        try:
+            urls.append(media.save_feedback_image(user.id, data))
+        except media.MediaError as e:
+            raise HTTPException(status_code=400, detail=str(e)) from e
+
+    fb = feedback_repo.create_feedback(
+        db, user_id=user.id, content=content, contact=contact, images=urls,
+    )
+    logger.info("feedback id=%d user_id=%d images=%d", fb.id, user.id, len(urls))
+    return FeedbackOut.model_validate(fb)

app/api/v1/meituan.py

@@ -9,7 +9,8 @@ from concurrent.futures import ThreadPoolExecutor, as_completed
 
 from fastapi import APIRouter, HTTPException
 
-from app.core.meituan import MeituanCpsError, get_referral_link, query_coupon
+from app.core.config import settings
+from app.integrations.meituan import MeituanCpsError, get_referral_link, query_coupon
 from app.schemas.meituan import (
     CouponCard,
     CouponListRequest,
@@ -27,6 +28,8 @@ router = APIRouter(prefix="/api/v1/meituan", tags=["meituan-cps"])
 
 @router.post("/coupons", response_model=CouponListResponse, summary="券列表(为您推荐)")
 def list_coupons(req: CouponListRequest) -> CouponListResponse:
+    if not settings.mt_cps_configured:
+        return CouponListResponse(items=[], has_next=False, search_id=None)
     logger.info("[coupons] lon=%.6f lat=%.6f topic=%s", req.longitude, req.latitude, req.list_topic_id)
     try:
         raw = query_coupon(
@@ -78,6 +81,8 @@ def _interleave(waimai: list[dict], daodian: list[dict]) -> list[CouponCard]:
 
 @router.post("/feed", response_model=FeedResponse, summary="混合feed(外卖+到店交叉, 无限流)")
 def feed(req: FeedRequest) -> FeedResponse:
+    if not settings.mt_cps_configured:
+        return FeedResponse(items=[], has_next=False, page=req.page)
     page_idx = req.page - 1
     lon, lat = req.longitude, req.latitude
     logger.info("[feed] page=%s lon=%.6f lat=%.6f", req.page, lon, lat)
@@ -108,6 +113,8 @@ def feed(req: FeedRequest) -> FeedResponse:
 
 @router.post("/referral-link", response_model=ReferralLinkResponse, summary="换取推广链接(点抢时调)")
 def referral_link(req: ReferralLinkRequest) -> ReferralLinkResponse:
+    if not settings.mt_cps_configured:
+        return ReferralLinkResponse(link="", link_map={})
     try:
         raw = get_referral_link(
             product_view_sign=req.product_view_sign,

app/api/v1/order.py

@@ -0,0 +1,25 @@
+from fastapi import APIRouter
+
+from app.api.deps import CurrentUser, DbSession
+from app.repositories import savings as crud_savings
+from app.schemas.order import OrderReportOut, OrderReportRequest
+
+router = APIRouter(prefix="/api/v1/order", tags=["order"])
+
+
+@router.post(
+    "/report",
+    response_model=OrderReportOut,
+    summary="上报归因订单(比价后5分钟内点链接 + 支付金额与比价价相差≤1元)",
+)
+def report_order(req: OrderReportRequest, user: CurrentUser, db: DbSession) -> OrderReportOut:
+    # 记账唯一真相表是 savings_record(source='compare')。
+    rec, duplicated = crud_savings.create_from_report(db, user.id, req)
+    return OrderReportOut(
+        id=rec.id,
+        platform=rec.platform or req.platform,
+        pay_channel=rec.pay_channel or req.pay_channel,
+        compared_price_cents=rec.compared_price_cents or 0,
+        paid_amount_cents=rec.order_amount_cents,
+        duplicated=duplicated,
+    )

app/api/v1/report.py

@@ -0,0 +1,145 @@
+"""上报更低价 endpoint。
+
+路由前缀 `/api/v1/report`,需 Bearer 鉴权(上报绑登录用户)。
+  POST /         提交上报(multipart:comparison_record_id / reported_platform_id /
+                 reported_price(元) + images 1~4 张)
+  GET  /records  上报记录列表(?status= pending/approved/rejected 可选筛选)
+
+要点:
+- 截图复用 [app.core.media] 落盘到 /media/price_report/。
+- 原最低价由 comparison_record_id 反查比价记录 best_*(不信任客户端传的快照)。
+- 校验(D):上报价必须 < 原最低价,否则 400。
+- 提交一律 status=pending;通过发奖励是人工审核后台动作,不在此。
+"""
+from __future__ import annotations
+
+import logging
+
+from fastapi import APIRouter, File, Form, HTTPException, UploadFile
+
+from app.api.deps import CurrentUser, DbSession
+from app.core import media
+from app.models.comparison import ComparisonRecord
+from app.repositories import report as report_repo
+from app.schemas.report import (
+    ReportRecordCounts,
+    ReportRecordOut,
+    ReportRecordsOut,
+    ReportSubmitOut,
+)
+
+logger = logging.getLogger("shagua.report")
+
+router = APIRouter(prefix="/api/v1/report", tags=["report"])
+
+_MAX_IMAGES = 4
+_VALID_STATUS = ("pending", "approved", "rejected")
+
+# 上报平台(canonical id → 展示名),与原型 fb-platform-chip data-pf 一致
+_PLATFORM_NAMES = {
+    "meituan-waimai": "美团外卖",
+    "jd-waimai": "京东外卖",
+    "taobao-shanguang": "淘宝闪购",
+}
+
+
+def _dish_summary(items: list | None) -> str | None:
+    """把比价记录 items[{name,qty,...}] 拼成菜品摘要文案。"""
+    if not items:
+        return None
+    names = [str(it.get("name", "")).strip() for it in items if isinstance(it, dict)]
+    names = [n for n in names if n]
+    return "、".join(names) if names else None
+
+
+@router.post("", response_model=ReportSubmitOut, summary="提交上报更低价")
+async def submit_report(
+    user: CurrentUser,
+    db: DbSession,
+    comparison_record_id: int = Form(...),
+    reported_platform_id: str = Form(...),
+    reported_price: str = Form(..., description="用户填的更低价(元)"),
+    images: list[UploadFile] = File(default=[]),
+) -> ReportSubmitOut:
+    # 平台
+    reported_platform_id = reported_platform_id.strip()
+    platform_name = _PLATFORM_NAMES.get(reported_platform_id)
+    if platform_name is None:
+        raise HTTPException(status_code=400, detail="不支持的上报平台")
+
+    # 价格(元 → 分)
+    try:
+        price_yuan = float(reported_price)
+    except (TypeError, ValueError):
+        raise HTTPException(status_code=400, detail="价格格式不正确") from None
+    if price_yuan <= 0:
+        raise HTTPException(status_code=400, detail="价格必须大于 0")
+    reported_price_cents = round(price_yuan * 100)
+
+    # 反查比价记录(必须属于本人)→ 取原最低价快照
+    rec = db.get(ComparisonRecord, comparison_record_id)
+    if rec is None or rec.user_id != user.id:
+        raise HTTPException(status_code=404, detail="比价记录不存在")
+    original_price_cents = rec.best_price_cents
+
+    # D:上报价必须低于原最低价
+    if original_price_cents is not None and reported_price_cents >= original_price_cents:
+        raise HTTPException(
+            status_code=400,
+            detail=f"上报价需低于原最低价 ¥{original_price_cents / 100:.2f}",
+        )
+
+    # 截图(至少 1 张,最多 4 张)
+    files = [f for f in (images or []) if f is not None and f.filename]
+    if not files:
+        raise HTTPException(status_code=400, detail="请至少上传一张截图证明")
+    if len(files) > _MAX_IMAGES:
+        raise HTTPException(status_code=400, detail=f"最多上传 {_MAX_IMAGES} 张图片")
+    urls: list[str] = []
+    for f in files:
+        data = await f.read()
+        try:
+            urls.append(media.save_report_image(user.id, data))
+        except media.MediaError as e:
+            raise HTTPException(status_code=400, detail=str(e)) from e
+
+    rep = report_repo.create_report(
+        db,
+        user_id=user.id,
+        comparison_record_id=comparison_record_id,
+        store_name=rec.store_name,
+        dish_summary=_dish_summary(rec.items),
+        original_platform_id=rec.best_platform_id,
+        original_platform_name=rec.best_platform_name,
+        original_price_cents=original_price_cents,
+        reported_platform_id=reported_platform_id,
+        reported_platform_name=platform_name,
+        reported_price_cents=reported_price_cents,
+        images=urls,
+    )
+    logger.info("price_report id=%d user_id=%d images=%d", rep.id, user.id, len(urls))
+    return ReportSubmitOut.model_validate(rep)
+
+
+@router.get("/records", response_model=ReportRecordsOut, summary="上报记录列表")
+def list_report_records(
+    user: CurrentUser,
+    db: DbSession,
+    status: str | None = None,
+) -> ReportRecordsOut:
+    status = (status or "").strip() or None
+    if status and status not in _VALID_STATUS:
+        raise HTTPException(status_code=400, detail="无效的状态筛选")
+    rows = report_repo.list_reports(db, user.id, status)
+    # counts 始终基于全量(不受 status 筛选影响),供前端 chip 计数
+    all_rows = rows if status is None else report_repo.list_reports(db, user.id, None)
+    counts = ReportRecordCounts(
+        all=len(all_rows),
+        pending=sum(1 for r in all_rows if r.status == "pending"),
+        approved=sum(1 for r in all_rows if r.status == "approved"),
+        rejected=sum(1 for r in all_rows if r.status == "rejected"),
+    )
+    return ReportRecordsOut(
+        records=[ReportRecordOut.model_validate(r) for r in rows],
+        counts=counts,
+    )

app/api/v1/savings.py

@@ -0,0 +1,60 @@
+"""省钱 endpoint(profile 的「累计帮你省了」「省钱战绩」「省钱明细」)。
+
+路由前缀 `/api/v1/savings`:
+  GET  /summary    累计省下 + 订单数 + 平均每单省
+  GET  /battle     本周已省 + 超过百分比 + 连续省钱天数
+  GET  /records    省钱明细(游标分页)
+"""
+from __future__ import annotations
+
+import logging
+
+from fastapi import APIRouter, Query
+
+from app.api.deps import CurrentUser, DbSession
+from app.repositories import savings as crud_savings
+from app.schemas.welfare import (
+    SavingsBattleOut,
+    SavingsRecordOut,
+    SavingsRecordPage,
+    SavingsSummaryOut,
+)
+
+logger = logging.getLogger("shagua.savings")
+
+router = APIRouter(prefix="/api/v1/savings", tags=["savings"])
+
+
+@router.get("/summary", response_model=SavingsSummaryOut, summary="累计帮你省了")
+def summary(user: CurrentUser, db: DbSession) -> SavingsSummaryOut:
+    s = crud_savings.get_summary(db, user.id)
+    return SavingsSummaryOut(
+        total_saved_cents=s.total_saved_cents,
+        order_count=s.order_count,
+        avg_saved_cents=s.avg_saved_cents,
+    )
+
+
+@router.get("/battle", response_model=SavingsBattleOut, summary="省钱战绩")
+def battle(user: CurrentUser, db: DbSession) -> SavingsBattleOut:
+    b = crud_savings.get_battle(db, user.id)
+    return SavingsBattleOut(
+        week_saved_cents=b.week_saved_cents,
+        beat_percent=b.beat_percent,
+        streak_days=b.streak_days,
+        compare_count=b.compare_count,
+    )
+
+
+@router.get("/records", response_model=SavingsRecordPage, summary="省钱明细(游标分页)")
+def records(
+    user: CurrentUser,
+    db: DbSession,
+    limit: int = Query(20, ge=1, le=100),
+    cursor: int | None = Query(None, description="上一页末条 id"),
+) -> SavingsRecordPage:
+    items, next_cursor = crud_savings.list_records(db, user.id, limit=limit, cursor=cursor)
+    return SavingsRecordPage(
+        items=[SavingsRecordOut.model_validate(it) for it in items],
+        next_cursor=next_cursor,
+    )

app/api/v1/signin.py

@@ -0,0 +1,44 @@
+"""签到 endpoint。
+
+路由前缀 `/api/v1/signin`:
+  GET  /status    今日签到状态 + 7 天档位
+  POST /          执行今日签到
+"""
+from __future__ import annotations
+
+import logging
+
+from fastapi import APIRouter, HTTPException, status
+
+from app.api.deps import CurrentUser, DbSession
+from app.repositories import signin as crud_signin
+from app.schemas.welfare import SigninResultOut, SigninStatusOut
+
+logger = logging.getLogger("shagua.signin")
+
+router = APIRouter(prefix="/api/v1/signin", tags=["signin"])
+
+
+@router.get("/status", response_model=SigninStatusOut, summary="今日签到状态")
+def signin_status(user: CurrentUser, db: DbSession) -> SigninStatusOut:
+    st = crud_signin.get_status(db, user.id)
+    return SigninStatusOut.model_validate(st, from_attributes=True)
+
+
+@router.post("", response_model=SigninResultOut, summary="执行今日签到")
+def do_signin(user: CurrentUser, db: DbSession) -> SigninResultOut:
+    try:
+        record, balance = crud_signin.do_signin(db, user.id)
+    except crud_signin.AlreadySignedError as e:
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="already signed today") from e
+
+    logger.info(
+        "signin ok user_id=%d day=%d streak=%d coin=%d",
+        user.id, record.cycle_day, record.streak, record.coin_awarded,
+    )
+    return SigninResultOut(
+        coin_awarded=record.coin_awarded,
+        cycle_day=record.cycle_day,
+        streak=record.streak,
+        coin_balance=balance,
+    )

app/api/v1/tasks.py

@@ -0,0 +1,47 @@
+"""一次性任务 endpoint。
+
+路由前缀 `/api/v1/tasks`:
+  GET  /                    任务及领取状态(如"打开消息提醒")
+  POST /{task_key}/claim    领取任务奖励
+"""
+from __future__ import annotations
+
+import logging
+
+from fastapi import APIRouter, HTTPException, status
+
+from app.api.deps import CurrentUser, DbSession
+from app.repositories import task as crud_task
+from app.schemas.welfare import TaskClaimResultOut, TaskListOut, TaskOut
+
+logger = logging.getLogger("shagua.tasks")
+
+router = APIRouter(prefix="/api/v1/tasks", tags=["tasks"])
+
+
+@router.get("", response_model=TaskListOut, summary="任务及领取状态")
+def list_tasks(user: CurrentUser, db: DbSession) -> TaskListOut:
+    states = crud_task.list_tasks(db, user.id)
+    return TaskListOut(
+        items=[
+            TaskOut(task_key=s.task_key, coin=s.coin, claimed=s.claimed)
+            for s in states
+        ]
+    )
+
+
+@router.post(
+    "/{task_key}/claim",
+    response_model=TaskClaimResultOut,
+    summary="领取任务奖励",
+)
+def claim_task(task_key: str, user: CurrentUser, db: DbSession) -> TaskClaimResultOut:
+    try:
+        coin, balance = crud_task.claim_task(db, user.id, task_key)
+    except crud_task.UnknownTaskError as e:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="unknown task") from e
+    except crud_task.AlreadyClaimedError as e:
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="task already claimed") from e
+
+    logger.info("task claimed user_id=%d key=%s coin=%d", user.id, task_key, coin)
+    return TaskClaimResultOut(task_key=task_key, coin_awarded=coin, coin_balance=balance)

app/api/v1/user.py

@@ -1,38 +1,59 @@
+"""用户资料 endpoint。
+
+路由前缀 `/api/v1/user`,全部需 Bearer 鉴权(用户级数据,不同于 MVP 透传接口):
+  PATCH  /profile   修改昵称
+  POST   /avatar    上传头像(multipart,字段名 file)
+  DELETE /          注销账号(软删除 + 匿名化)
+
+昵称/头像后端持久化到 user 表,登录后经 /auth/me 与登录响应回传客户端——这才是
+"改完重登仍生效"的唯一数据源(此前客户端只存本地、退登即丢)。
+"""
 from __future__ import annotations
 
-import json
 import logging
 
-from fastapi import APIRouter, Query
+from fastapi import APIRouter, File, HTTPException, UploadFile
 
 from app.api.deps import CurrentUser, DbSession
-from app.crud import order_record as crud_order
-from app.schemas.order_record import OrderListResponse, OrderRecordOut
+from app.core import media
+from app.repositories import user as user_repo
+from app.schemas.auth import UserOut
+from app.schemas.user import OkResponse, ProfileUpdateRequest
 
-logger = logging.getLogger("shagua.api.user")
+logger = logging.getLogger("shagua.user")
 
 router = APIRouter(prefix="/api/v1/user", tags=["user"])
 
 
-@router.get("/records", response_model=OrderListResponse, summary="分页查询当前用户的订单记录")
-def list_records(
+@router.patch("/profile", response_model=UserOut, summary="修改昵称")
+def update_profile(req: ProfileUpdateRequest, user: CurrentUser, db: DbSession) -> UserOut:
+    updated = user_repo.update_nickname(db, user, nickname=req.nickname)
+    logger.info("update nickname user_id=%d", user.id)
+    return UserOut.model_validate(updated)
+
+
+@router.post("/avatar", response_model=UserOut, summary="上传头像")
+async def upload_avatar(
     user: CurrentUser,
     db: DbSession,
-    page: int = Query(1, ge=1),
-    size: int = Query(20, ge=1, le=100),
-) -> OrderListResponse:
-    rows, has_next = crud_order.get_records_page(db, user_id=user.id, page=page, size=size)
-    records = [
-        OrderRecordOut(
-            id=r.id,
-            platform=r.platform,
-            store_name=r.store_name,
-            dishes=json.loads(r.dishes) if r.dishes else [],
-            order_date=r.order_date,
-            price=r.price,
-            original_price=r.original_price,
-            savings=r.savings,
-        )
-        for r in rows
-    ]
-    return OrderListResponse(records=records, has_next=has_next, page=page)
+    file: UploadFile = File(..., description="头像图片(jpeg/png/webp,≤5MB)"),
+) -> UserOut:
+    data = await file.read()
+    try:
+        url = media.save_avatar(user.id, data)
+    except media.MediaError as e:
+        raise HTTPException(status_code=400, detail=str(e)) from e
+
+    old_url = user.avatar_url
+    updated = user_repo.set_avatar_url(db, user, avatar_url=url)
+    media.delete_avatar(old_url)  # 落库成功后再删旧文件,避免删了新的没存上
+    logger.info("update avatar user_id=%d url=%s", user.id, url)
+    return UserOut.model_validate(updated)
+
+
+@router.delete("", response_model=OkResponse, summary="注销账号(软删除)")
+def delete_account(user: CurrentUser, db: DbSession) -> OkResponse:
+    media.delete_avatar(user.avatar_url)
+    user_repo.soft_delete_account(db, user)
+    logger.info("delete account user_id=%d", user.id)
+    return OkResponse()

app/api/v1/wallet.py

@@ -0,0 +1,248 @@
+"""钱包 / 我的资产 endpoint。
+
+路由前缀 `/api/v1/wallet`:
+  GET  /account              金币 + 现金余额(我的资产卡)
+  GET  /coin-transactions    金币流水(游标分页)
+"""
+from __future__ import annotations
+
+import logging
+
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+
+from app.api.deps import CurrentUser, DbSession
+from app.core.config import settings
+from app.core.ratelimit import rate_limit
+from app.core.rewards import (
+    COIN_PER_CENT,
+    COIN_PER_YUAN,
+    MIN_EXCHANGE_COIN,
+    WITHDRAW_MAX_CENTS,
+    WITHDRAW_MIN_CENTS,
+)
+from app.repositories import wallet as crud_wallet
+from app.models.user import User
+from app.schemas.welfare import (
+    BindWechatRequest,
+    BindWechatResultOut,
+    CashTransactionOut,
+    CashTransactionPage,
+    CoinAccountOut,
+    CoinTransactionOut,
+    CoinTransactionPage,
+    ExchangeInfoOut,
+    ExchangeRequest,
+    ExchangeResultOut,
+    UnbindWechatResultOut,
+    WithdrawInfoOut,
+    WithdrawOrderOut,
+    WithdrawOrderPage,
+    WithdrawRequest,
+    WithdrawResultOut,
+    WithdrawStatusOut,
+)
+
+logger = logging.getLogger("shagua.wallet")
+
+router = APIRouter(prefix="/api/v1/wallet", tags=["wallet"])
+
+
+@router.get("/account", response_model=CoinAccountOut, summary="金币+现金余额")
+def get_account(user: CurrentUser, db: DbSession) -> CoinAccountOut:
+    acc = crud_wallet.get_or_create_account(db, user.id)
+    return CoinAccountOut.model_validate(acc)
+
+
+@router.get(
+    "/coin-transactions",
+    response_model=CoinTransactionPage,
+    summary="金币流水(游标分页)",
+)
+def coin_transactions(
+    user: CurrentUser,
+    db: DbSession,
+    limit: int = Query(20, ge=1, le=100),
+    cursor: int | None = Query(None, description="上一页末条 id"),
+) -> CoinTransactionPage:
+    items, next_cursor = crud_wallet.list_coin_transactions(
+        db, user.id, limit=limit, cursor=cursor
+    )
+    return CoinTransactionPage(
+        items=[CoinTransactionOut.model_validate(it) for it in items],
+        next_cursor=next_cursor,
+    )
+
+
+@router.get("/cash-transactions", response_model=CashTransactionPage, summary="现金流水(游标分页)")
+def cash_transactions(
+    user: CurrentUser,
+    db: DbSession,
+    limit: int = Query(20, ge=1, le=100),
+    cursor: int | None = Query(None, description="上一页末条 id"),
+) -> CashTransactionPage:
+    items, next_cursor = crud_wallet.list_cash_transactions(
+        db, user.id, limit=limit, cursor=cursor
+    )
+    return CashTransactionPage(
+        items=[CashTransactionOut.model_validate(it) for it in items],
+        next_cursor=next_cursor,
+    )
+
+
+@router.get("/exchange-info", response_model=ExchangeInfoOut, summary="金币兑现金汇率/规则")
+def exchange_info() -> ExchangeInfoOut:
+    return ExchangeInfoOut(
+        coin_per_yuan=COIN_PER_YUAN,
+        min_coin=MIN_EXCHANGE_COIN,
+        step_coin=COIN_PER_CENT,
+    )
+
+
+@router.post("/exchange", response_model=ExchangeResultOut, summary="金币兑现金")
+def exchange(req: ExchangeRequest, user: CurrentUser, db: DbSession) -> ExchangeResultOut:
+    try:
+        acc, cents = crud_wallet.exchange_coins_to_cash(db, user.id, req.coin_amount)
+    except crud_wallet.InvalidExchangeAmountError as e:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"coin_amount must be >= {MIN_EXCHANGE_COIN} and a multiple of {COIN_PER_CENT}",
+        ) from e
+    except crud_wallet.InsufficientCoinError as e:
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="insufficient coin balance") from e
+
+    logger.info("exchange ok user_id=%d coin=%d cents=%d", user.id, req.coin_amount, cents)
+    return ExchangeResultOut(
+        coin_amount=req.coin_amount,
+        cash_added_cents=cents,
+        coin_balance=acc.coin_balance,
+        cash_balance_cents=acc.cash_balance_cents,
+    )
+
+
+# ===== 提现(现金 → 微信零钱) =====
+
+
+@router.post(
+    "/bind-wechat",
+    response_model=BindWechatResultOut,
+    summary="微信授权 code 换 openid 并绑定",
+    dependencies=[Depends(rate_limit(10, 60, "bind-wechat"))],  # #6 同 IP 每分钟≤10 次
+)
+def bind_wechat(req: BindWechatRequest, user: CurrentUser, db: DbSession) -> BindWechatResultOut:
+    if not settings.wxpay_configured:
+        raise HTTPException(status_code=status.HTTP_503_SERVICE_UNAVAILABLE, detail="wechat pay not configured")
+    try:
+        info = crud_wallet.bind_wechat_openid(db, user.id, req.code)
+    except crud_wallet.WechatAlreadyBoundError as e:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT, detail="该微信已绑定其他账号"
+        ) from e
+    except ValueError as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e)) from e
+    logger.info(
+        "bind wechat ok user_id=%d openid=%s*** nickname=%r avatar=%s",
+        user.id, info["openid"][:6], info["nickname"], bool(info["avatar_url"]),
+    )
+    return BindWechatResultOut(
+        bound=True, wechat_nickname=info["nickname"], wechat_avatar_url=info["avatar_url"]
+    )
+
+
+@router.post("/unbind-wechat", response_model=UnbindWechatResultOut, summary="解绑微信(清空 openid)")
+def unbind_wechat(user: CurrentUser, db: DbSession) -> UnbindWechatResultOut:
+    crud_wallet.unbind_wechat_openid(db, user.id)
+    logger.info("unbind wechat ok user_id=%d", user.id)
+    return UnbindWechatResultOut(bound=False)
+
+
+@router.get("/withdraw-info", response_model=WithdrawInfoOut, summary="提现额度/绑定状态")
+def withdraw_info(user: CurrentUser, db: DbSession) -> WithdrawInfoOut:
+    u = db.get(User, user.id)
+    return WithdrawInfoOut(
+        min_cents=WITHDRAW_MIN_CENTS,
+        max_cents=WITHDRAW_MAX_CENTS,
+        wechat_bound=bool(u and u.wechat_openid),
+        wechat_nickname=u.wechat_nickname if u else None,
+        wechat_avatar_url=u.wechat_avatar_url if u else None,
+    )
+
+
+@router.post(
+    "/withdraw",
+    response_model=WithdrawResultOut,
+    summary="发起提现(扣款建单,待人工审核;审核通过后才打款)",
+    dependencies=[Depends(rate_limit(20, 60, "withdraw"))],  # #6 同 IP 每分钟≤20 次
+)
+def withdraw(req: WithdrawRequest, user: CurrentUser, db: DbSession) -> WithdrawResultOut:
+    # 提现发起本身不调微信(打款在审核通过后),但仍要求微信支付已配置——否则审核通过也打不了款,提前拦
+    if not settings.wxpay_configured:
+        raise HTTPException(status_code=status.HTTP_503_SERVICE_UNAVAILABLE, detail="wechat pay not configured")
+    try:
+        order = crud_wallet.create_withdraw(
+            db, user.id, req.amount_cents, user_name=req.user_name, out_bill_no=req.out_bill_no
+        )
+    except crud_wallet.InvalidWithdrawAmountError as e:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"amount_cents must be within [{WITHDRAW_MIN_CENTS}, {WITHDRAW_MAX_CENTS}]",
+        ) from e
+    except crud_wallet.WechatNotBoundError as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="wechat not bound") from e
+    except crud_wallet.InsufficientCashError as e:
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="insufficient cash balance") from e
+
+    acc = crud_wallet.get_or_create_account(db, user.id)
+    logger.info(
+        "withdraw submitted user_id=%d cents=%d bill=%s status=%s(待审核)",
+        user.id, req.amount_cents, order.out_bill_no, order.status,
+    )
+    # 此刻 status=reviewing,尚未打款 → 无 package_info;App 据 status 提示"已提交,等待审核"。
+    # 审核通过后客户端轮询 /withdraw/status 拿到 package_info(若需确认)再拉起微信确认页。
+    return WithdrawResultOut(
+        out_bill_no=order.out_bill_no,
+        status=order.status,
+        wechat_state=order.wechat_state,
+        amount_cents=order.amount_cents,
+        cash_balance_cents=acc.cash_balance_cents,
+        package_info=order.package_info,
+        mch_id=settings.WXPAY_MCH_ID,
+        app_id=settings.WECHAT_APP_ID,
+    )
+
+
+@router.get("/withdraw/status", response_model=WithdrawStatusOut, summary="查提现单状态(轮询)")
+def withdraw_status(
+    user: CurrentUser, db: DbSession, out_bill_no: str = Query(..., description="商户提现单号")
+) -> WithdrawStatusOut:
+    try:
+        # 用户从确认页返回后查单:仍 WAIT_USER_CONFIRM 视为放弃 → 撤销+退款
+        order = crud_wallet.refresh_withdraw_status(
+            db, user.id, out_bill_no, cancel_if_unconfirmed=True
+        )
+    except crud_wallet.WithdrawOrderNotFound as e:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="withdraw order not found") from e
+    return WithdrawStatusOut(
+        out_bill_no=order.out_bill_no,
+        status=order.status,
+        wechat_state=order.wechat_state,
+        amount_cents=order.amount_cents,
+        fail_reason=order.fail_reason,
+        # 审核通过后 status=pending 且可能带 package_info(WAIT_USER_CONFIRM):供 App 拉起微信确认页
+        package_info=order.package_info,
+        mch_id=settings.WXPAY_MCH_ID if order.package_info else None,
+        app_id=settings.WECHAT_APP_ID if order.package_info else None,
+    )
+
+
+@router.get("/withdraw-orders", response_model=WithdrawOrderPage, summary="提现单列表(游标分页)")
+def withdraw_orders(
+    user: CurrentUser,
+    db: DbSession,
+    limit: int = Query(20, ge=1, le=100),
+    cursor: int | None = Query(None, description="上一页末条 id"),
+) -> WithdrawOrderPage:
+    items, next_cursor = crud_wallet.list_withdraw_orders(db, user.id, limit=limit, cursor=cursor)
+    return WithdrawOrderPage(
+        items=[WithdrawOrderOut.model_validate(it) for it in items],
+        next_cursor=next_cursor,
+    )

app/core/ad_cooldown.py

@@ -0,0 +1,54 @@
+"""看激励视频冷却策略 —— 与发奖记录查询解耦的纯计算。
+
+当前策略:**每 N 次一轮,看满一轮后强制冷却若干秒**(N / 秒数 取自 [rewards] 常量)。
+[repositories.ad_reward.today_status] 只负责取数据(今日 granted 的 created_at 列表),
+把"本轮已看几次 + 冷却到几点"的策略判断委托到这里。
+
+⚠️ 这是临时策略,后续要调。换策略(间隔式 / 每日配额式 / 指数退避 …)**只改本文件**,
+repository 不碰——这就是把它独立出来的目的。保持 [compute_cooldown] 签名稳定即可。
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+
+from app.core.rewards import VIDEO_ROUND_COOLDOWN_SECONDS, VIDEO_ROUND_REQUIRED_COUNT
+
+
+@dataclass(frozen=True)
+class CooldownState:
+    """冷却策略的输出。"""
+
+    round_count: int  # 本轮已看次数 0..N-1(展示用)
+    cooldown_until: datetime | None  # 本轮冷却结束时间(UTC);None = 不在冷却
+
+
+def compute_cooldown(
+    granted_times_desc: list[datetime],
+    now: datetime,
+    *,
+    round_size: int = VIDEO_ROUND_REQUIRED_COUNT,
+    cooldown_seconds: int = VIDEO_ROUND_COOLDOWN_SECONDS,
+) -> CooldownState:
+    """按"每 round_size 次一轮、看满一轮后冷却 cooldown_seconds 秒"算本轮进度 + 冷却结束时间。
+
+    :param granted_times_desc: 今日 status=granted 记录的 created_at,**按时间倒序**(最新在前)。
+    :param now: 当前时间(UTC,带 tzinfo),用于判断冷却是否已过。
+    :param round_size / cooldown_seconds: 策略参数,默认取 rewards 常量,可注入便于测试/调参。
+
+    纯函数,不碰 DB。冷却派生算法:把今日 granted 倒序,跳过当前未完成轮的 round_count 条,
+    下一条即"上一轮最后一次"的时间,+ cooldown_seconds 仍 > now 则在冷却中。
+    SQLite 上 created_at 可能是 naive,按 UTC 解读再比较。
+    """
+    used = len(granted_times_desc)
+    round_count = used % round_size
+    cooldown_until: datetime | None = None
+    if used >= round_size:
+        # round_count 必 < round_size <= used,索引合法
+        last_round_end = granted_times_desc[round_count]
+        if last_round_end.tzinfo is None:
+            last_round_end = last_round_end.replace(tzinfo=timezone.utc)
+        cd_end = last_round_end + timedelta(seconds=cooldown_seconds)
+        if cd_end > now:
+            cooldown_until = cd_end
+    return CooldownState(round_count=round_count, cooldown_until=cooldown_until)

app/core/config.py

@@ -28,6 +28,9 @@ class Settings(BaseSettings):
     APP_NAME: str = "shaguabijia-app-server"
     APP_DEBUG: bool = True
 
+    # 接口限流开关(测试里关掉,避免内存计数跨用例累加误伤)
+    RATE_LIMIT_ENABLED: bool = True
+
     # ===== 数据库 =====
     DATABASE_URL: str = "sqlite:///./data/app.db"
 
@@ -37,6 +40,20 @@ class Settings(BaseSettings):
     JWT_ACCESS_TOKEN_EXPIRE_MINUTES: int = 120
     JWT_REFRESH_TOKEN_EXPIRE_DAYS: int = 30
 
+    # ===== Admin 后台 =====
+    # admin 用独立 JWT secret(≠ JWT_SECRET_KEY),App 用户 token 无法越权访问后台。
+    # 生产必须改成高熵随机串(同 JWT_SECRET_KEY 的要求)。
+    ADMIN_JWT_SECRET: str = "change-me-admin"
+    ADMIN_JWT_EXPIRE_MINUTES: int = 720  # admin 登录态 12 小时(无 refresh,过期重登)
+    # 可选 IP 白名单(逗号分隔),为空=应用层不限制(靠 nginx allow/deny 兜底)。
+    ADMIN_IP_ALLOWLIST: str = ""
+
+    @property
+    def admin_ip_allowlist(self) -> list[str]:
+        if not self.ADMIN_IP_ALLOWLIST.strip():
+            return []
+        return [ip.strip() for ip in self.ADMIN_IP_ALLOWLIST.split(",") if ip.strip()]
+
     # ===== 极光 =====
     JG_APP_KEY: str = ""
     JG_MASTER_SECRET: str = ""
@@ -48,14 +65,83 @@ class Settings(BaseSettings):
     SMS_MOCK: bool = True
     SMS_CODE_TTL_SEC: int = 300
     SMS_SEND_INTERVAL_SEC: int = 60
+    # 真实发送走极光短信 REST(自定义验证码模式:本服务生成 code,极光只负责发)。
+    # 复用极光一键登录的 JG_APP_KEY / JG_MASTER_SECRET(同一个极光应用)+ JG_REQUEST_TIMEOUT_SEC。
+    SMS_SEND_ENDPOINT: str = "https://api.sms.jpush.cn/v1/messages"
+    SMS_SIGN_ID: int = 31729       # 极光短信签名 ID(非机密,可被 .env 覆盖)
+    SMS_TEMPLATE_ID: int = 1       # 极光短信模板 ID(变量名 code,有效期 5 分钟)
+    SMS_CODE_LENGTH: int = 6       # 验证码位数(本服务生成;前端 code 字段 4-8 位兼容)
+    SMS_DAILY_LIMIT_PER_PHONE: int = 10   # 单手机号每日发送上限(防刷 + 控费)
+    SMS_MAX_VERIFY_ATTEMPTS: int = 5      # 单个验证码最多校验失败次数,超过即作废(防爆破)
 
     # ===== 美团联盟 CPS =====
+    # 未配置时所有 /api/v1/meituan/* 接口 200 返空(优雅降级),不影响登录/领券等其他业务。
     MT_CPS_APP_KEY: str = ""
     MT_CPS_APP_SECRET: str = ""
     MT_CPS_HOST: str = "https://media.meituan.com"
     MT_CPS_TIMEOUT_SEC: int = 15
     MT_CPS_DEFAULT_SID: str = "sgbjia"
 
+    @property
+    def mt_cps_configured(self) -> bool:
+        """美团 CPS 凭证齐全(缺则接口返空,而非 502)。"""
+        return bool(self.MT_CPS_APP_KEY and self.MT_CPS_APP_SECRET)
+
+    # ===== 微信支付(商家转账到零钱 / 提现)=====
+    # 真实凭证放 .env(已 gitignore),证书 .pem 放 secrets/。WECHAT_APP_ID 同时用于
+    # 微信登录(code 换 openid)与转账,必须与 App 端开放平台 appid 一致。
+    WECHAT_APP_ID: str = ""              # 开放平台移动应用 appid(wx 开头)
+    WECHAT_APP_SECRET: str = ""          # 开放平台 AppSecret,code 换 openid 用
+    WXPAY_MCH_ID: str = ""               # 微信支付商户号
+    WXPAY_MCH_SERIAL_NO: str = ""        # 商户 API 证书序列号
+    WXPAY_MCH_PRIVATE_KEY_PATH: str = "./secrets/apiclient_key.pem"   # 商户 API 私钥
+    WXPAY_PUBLIC_KEY_ID: str = ""        # 微信支付平台公钥 ID(PUB_KEY_ID_...)
+    WXPAY_PUBLIC_KEY_PATH: str = "./secrets/pub_key.pem"             # 微信支付平台公钥
+    WXPAY_TRANSFER_SCENE_ID: str = "1000"  # 转账场景 ID(1000=现金营销)
+    WXPAY_REQUEST_TIMEOUT_SEC: int = 10
+
+    @property
+    def wxpay_configured(self) -> bool:
+        """凭证是否齐全(缺则提现接口拒绝调用,而非启动时炸)。"""
+        return bool(
+            self.WECHAT_APP_ID
+            and self.WXPAY_MCH_ID
+            and self.WXPAY_MCH_SERIAL_NO
+            and self.WXPAY_PUBLIC_KEY_ID
+        )
+
+    # ===== 穿山甲激励视频(服务端发奖回调)=====
+    # 看完激励视频后穿山甲服务器回调本服务发金币(S2S,客户端被破解也刷不到)。
+    # PANGLE_REWARD_SECRET 是穿山甲后台配置的"奖励校验密钥",验签用,从后台取到后填 .env。
+    PANGLE_CALLBACK_ENABLED: bool = False
+    PANGLE_REWARD_SECRET: str = ""
+
+    # ⚠️ 仅本地联调:打开后开放 POST /api/v1/ad/test-grant,让(已登录的)客户端在没部署公网、
+    # 穿山甲 S2S 回调打不到本地时,直接触发一次发奖,验证"看广告→金币到账"全链路。
+    # 它让客户端能自助发奖 = 绕过反作弊,**生产必须保持 False**(默认 False;只在本地 .env 设 true)。
+    AD_REWARD_TEST_GRANT_ENABLED: bool = False
+
+    @property
+    def pangle_callback_configured(self) -> bool:
+        """回调开关打开且验签密钥已配,才接受发奖回调。"""
+        return bool(self.PANGLE_CALLBACK_ENABLED and self.PANGLE_REWARD_SECRET)
+
+    # ===== Pricebot 上游 (领券业务透传目标) =====
+    # pricebot-backend 默认跑在 8000。/api/v1/coupon/step 会透传到这里的 /api/coupon/step
+    PRICEBOT_BASE_URL: str = "http://localhost:8000"
+    # 领券一帧最多 wait 6s,加网络往返,timeout 给 30s 比较稳
+    PRICEBOT_REQUEST_TIMEOUT_SEC: int = 30
+    # 比价(intent/recognize + price/step)透传超时:意图识别是大上下文 LLM、
+    # price/step 每帧也是 LLM,可能 >30s;对齐客户端 agent ApiClient 的 60s 读超时。
+    PRICEBOT_COMPARE_TIMEOUT_SEC: int = 60
+
+    # ===== 媒体文件(用户头像上传)=====
+    # 落盘根目录(data/ 已 gitignore,上传不进库);对外经 StaticFiles 挂在 MEDIA_URL_PREFIX。
+    # 生产可改由 nginx 直接 serve MEDIA_ROOT,绕过应用进程。
+    MEDIA_ROOT: str = "./data/media"
+    MEDIA_URL_PREFIX: str = "/media"
+    AVATAR_MAX_BYTES: int = 5 * 1024 * 1024  # 头像最大 5MB
+
     # ===== CORS =====
     CORS_ALLOW_ORIGINS: str = ""
 

app/core/config_schema.py

@@ -0,0 +1,63 @@
+"""运营可配置项注册表:默认值(= 原 rewards 常量)+ 元信息(label/group/type)。
+
+配置项的 single source of truth:
+- 业务读配置时 fallback 到这里的 default(空 DB = 原行为不变)。
+- admin 配置页用它展示"有哪些可配项 + 当前值 + 默认值 + 说明"。
+新增可配项 = 这里加一条 + 业务处改用 app_config.get_value(db, key) 读。
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from app.core import rewards as r
+
+# type 约定(给前端渲染编辑控件用):int / int_list / dict_str_int
+CONFIG_DEFS: dict[str, dict[str, Any]] = {
+    "signin_rewards": {
+        "default": list(r.SIGNIN_REWARDS), "label": "签到 7 天金币档位",
+        "group": "签到", "type": "int_list",
+        "help": "第 1~7 天每天签到发的金币;断签重置回第 1 天。长度需为 7。",
+    },
+    "min_exchange_coin": {
+        "default": r.MIN_EXCHANGE_COIN, "label": "最低兑换金币",
+        "group": "钱包", "type": "int", "help": "金币兑现金的单次最低金币(10000 金币=1 元)。",
+    },
+    "withdraw_min_cents": {
+        "default": r.WITHDRAW_MIN_CENTS, "label": "提现最低额(分)",
+        "group": "钱包", "type": "int", "help": "单次提现最低;微信商家转账最低 10 分(0.1 元)。",
+    },
+    "withdraw_max_cents": {
+        "default": r.WITHDRAW_MAX_CENTS, "label": "提现最高额(分)",
+        "group": "钱包", "type": "int",
+    },
+    "task_rewards": {
+        "default": dict(r.TASK_REWARDS), "label": "一次性任务奖励",
+        "group": "任务", "type": "dict_str_int", "help": "task_key → 金币。",
+    },
+    "record_milestones": {
+        "default": list(r.RECORD_MILESTONES), "label": "比价里程碑金币档位",
+        "group": "里程碑", "type": "int_list",
+        "help": "累计成功比价第 1~N 档解锁发的金币。",
+    },
+    "ad_reward_coin": {
+        "default": r.AD_REWARD_COIN, "label": "看广告单次金币",
+        "group": "看广告", "type": "int",
+        "help": "看完一个激励视频发的金币;须与穿山甲后台代码位'奖励数量'保持一致。",
+    },
+    "ad_daily_limit": {
+        "default": r.DAILY_AD_REWARD_LIMIT, "label": "看广告每日上限(次)",
+        "group": "看广告", "type": "int",
+    },
+    "ad_max_coin": {
+        "default": r.MAX_AD_REWARD_COIN, "label": "看广告单次金币上限",
+        "group": "看广告", "type": "int", "help": "夹紧穿山甲回调里异常的 reward_amount,防刷爆。",
+    },
+    "ad_round_count": {
+        "default": r.VIDEO_ROUND_REQUIRED_COUNT, "label": "每轮看广告次数",
+        "group": "看广告", "type": "int", "help": "看完一轮触发冷却。",
+    },
+    "ad_cooldown_sec": {
+        "default": r.VIDEO_ROUND_COOLDOWN_SECONDS, "label": "每轮冷却(秒)",
+        "group": "看广告", "type": "int",
+    },
+}

app/core/media.py

@@ -0,0 +1,81 @@
+"""用户上传文件(头像 / 反馈截图)的本地落盘 + 对外 URL 构建。
+
+落盘到 `settings.MEDIA_ROOT/<子目录>/`,对外以 `settings.MEDIA_URL_PREFIX` 暴露
+(main.py 用 StaticFiles 挂载)。返回**相对路径** URL(如 `/media/avatars/xxx.jpg`),
+由客户端按自己的 BASE_URL 解析为绝对地址——服务端不知道客户端怎么访问到自己(dev 下
+可能是 10.0.2.2 / LAN IP),所以不返回绝对 URL。
+
+安全:不信任客户端给的 content-type / 文件名,改用魔数嗅探判定真实图片类型;
+文件名服务端随机生成,杜绝路径穿越与覆盖。
+"""
+from __future__ import annotations
+
+import secrets
+from pathlib import Path
+
+from app.core.config import settings
+
+
+class MediaError(Exception):
+    """上传文件不合法(类型/大小)。调用方转 400。"""
+
+
+def _media_dir(subdir: str) -> Path:
+    d = Path(settings.MEDIA_ROOT) / subdir
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def _sniff_ext(data: bytes) -> str | None:
+    """按魔数判定图片类型,返回扩展名;非支持类型返回 None。"""
+    if data[:3] == b"\xff\xd8\xff":
+        return ".jpg"
+    if data[:8] == b"\x89PNG\r\n\x1a\n":
+        return ".png"
+    if data[:4] == b"RIFF" and data[8:12] == b"WEBP":
+        return ".webp"
+    return None
+
+
+def _save_image(subdir: str, user_id: int, data: bytes) -> str:
+    """通用图片落盘:校验非空 / ≤上限 / 魔数为图片,随机文件名,返回相对 URL。"""
+    if not data:
+        raise MediaError("空文件")
+    if len(data) > settings.AVATAR_MAX_BYTES:
+        raise MediaError("图片过大(上限 5MB)")
+    ext = _sniff_ext(data)
+    if ext is None:
+        raise MediaError("仅支持 JPEG / PNG / WebP 图片")
+
+    fname = f"u{user_id}_{secrets.token_hex(8)}{ext}"
+    (_media_dir(subdir) / fname).write_bytes(data)
+    return f"{settings.MEDIA_URL_PREFIX}/{subdir}/{fname}"
+
+
+def save_avatar(user_id: int, data: bytes) -> str:
+    """保存头像,返回相对 URL(`/media/avatars/<file>`)。"""
+    return _save_image("avatars", user_id, data)
+
+
+def save_feedback_image(user_id: int, data: bytes) -> str:
+    """保存反馈截图,返回相对 URL(`/media/feedback/<file>`)。"""
+    return _save_image("feedback", user_id, data)
+
+
+def save_report_image(user_id: int, data: bytes) -> str:
+    """保存上报更低价截图,返回相对 URL(`/media/price_report/<file>`)。"""
+    return _save_image("price_report", user_id, data)
+
+
+def delete_avatar(url: str | None) -> None:
+    """删除本服务托管的旧头像文件;外部 URL(如微信头像)或空值不处理。"""
+    prefix = f"{settings.MEDIA_URL_PREFIX}/avatars/"
+    if not url or not url.startswith(prefix):
+        return
+    fname = url[len(prefix):]
+    if not fname or "/" in fname or "\\" in fname or ".." in fname:
+        return  # 防路径穿越
+    try:
+        (_media_dir("avatars") / fname).unlink(missing_ok=True)
+    except OSError:
+        pass

app/core/ratelimit.py

@@ -0,0 +1,59 @@
+"""轻量内存限流(固定窗口计数)。
+
+定位:防脚本刷接口的**安全网**,不是精确配额。局限——进程内存、单 worker 有效、重启清零、
+多 worker/多机不共享。上线放量后应换 Redis 后端 + 按用户维度。当前单 worker uvicorn 够用。
+
+用法:把 `rate_limit(limit, window_sec, scope)` 作为路由依赖挂上,默认按客户端 IP 计数。
+"""
+from __future__ import annotations
+
+import threading
+import time
+
+from fastapi import HTTPException, Request, status
+
+from app.core.config import settings
+
+# key -> (window_start_ts, count)
+_buckets: dict[str, tuple[float, int]] = {}
+_lock = threading.Lock()
+
+
+def _hit(key: str, limit: int, window_sec: float) -> bool:
+    """记一次访问。返回 True=放行,False=超限。"""
+    now = time.monotonic()
+    with _lock:
+        start, count = _buckets.get(key, (now, 0))
+        if now - start >= window_sec:  # 窗口过期,重置
+            start, count = now, 0
+        count += 1
+        _buckets[key] = (start, count)
+        # 顺手清理过期 key,防内存无限涨(低频访问足够)
+        if len(_buckets) > 10000:
+            for k in [k for k, (s, _) in _buckets.items() if now - s >= window_sec]:
+                _buckets.pop(k, None)
+    return count <= limit
+
+
+def _client_ip(request: Request) -> str:
+    # nginx 反代后真实 IP 在 X-Forwarded-For 首段;直连用 request.client
+    xff = request.headers.get("x-forwarded-for")
+    if xff:
+        return xff.split(",")[0].strip()
+    return request.client.host if request.client else "unknown"
+
+
+def rate_limit(limit: int, window_sec: float, scope: str):
+    """生成一个 FastAPI 依赖:同一 IP 在 window_sec 内对该 scope 超过 limit 次 → 429。"""
+
+    def _dep(request: Request) -> None:
+        if not settings.RATE_LIMIT_ENABLED:
+            return
+        key = f"{scope}:{_client_ip(request)}"
+        if not _hit(key, limit, window_sec):
+            raise HTTPException(
+                status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+                detail="操作过于频繁,请稍后再试",
+            )
+
+    return _dep

app/core/rewards.py

@@ -0,0 +1,174 @@
+"""福利 / 激励相关的业务常量与换算规则。
+
+集中放在这里,业务代码引用,避免数值散落各处。这些是**产品规则**(签到奖励、
+任务奖励、金币汇率)而非部署配置,所以不走环境变量;要调整直接改这里。
+"""
+from __future__ import annotations
+
+from datetime import date, datetime, timedelta, timezone
+
+# 业务时区:签到的"今天"按北京时间算,不能用 UTC。
+# 否则 UTC+8 的凌晨 0~8 点会被算成 UTC 的前一天,导致签到日期错位。
+CN_TZ = timezone(timedelta(hours=8))
+
+
+def cn_today() -> date:
+    """当前北京时间的日期,签到去重 / 连续判断都以此为准。"""
+    return datetime.now(CN_TZ).date()
+
+
+# ===== 签到:7 天循环,断签重置回第 1 天 =====
+# 第 1→7 天的金币奖励,签到逻辑用 cycle_day(1..7)索引。
+SIGNIN_REWARDS: tuple[int, ...] = (10, 20, 30, 50, 80, 120, 200)
+SIGNIN_CYCLE_LEN: int = len(SIGNIN_REWARDS)
+
+
+def signin_reward(cycle_day: int) -> int:
+    """cycle_day 取值 1..SIGNIN_CYCLE_LEN。"""
+    return SIGNIN_REWARDS[cycle_day - 1]
+
+
+# ===== 金币 → 现金 汇率 =====
+# 10000 金币 = 1 元 = 100 分。
+COIN_PER_YUAN: int = 10000
+CENTS_PER_YUAN: int = 100
+# 1 分对应多少金币 = 100。兑换金币数必须是它的整数倍,否则会出现不足 1 分的零头。
+COIN_PER_CENT: int = COIN_PER_YUAN // CENTS_PER_YUAN
+# 单次兑换最少 1 分(=COIN_PER_CENT;产品定:可兑 1 分起,与 step 同粒度)。早先为 1 元(=COIN_PER_YUAN),
+# 用户 2026-06 改为 1 分:让"换现金"小额即可用(也方便联调验证资产卡飞金币动画)。
+MIN_EXCHANGE_COIN: int = COIN_PER_CENT
+
+
+def coins_to_cents(coin_amount: int) -> int:
+    """金币换算成现金(分)。调用前应已校验 coin_amount 是 COIN_PER_CENT 的整数倍。"""
+    return coin_amount // COIN_PER_CENT
+
+
+# ===== 提现(现金 → 微信零钱)=====
+# 单次提现额度(分)。下限 0.1 元是微信商家转账的最低额,低于它(如 0.01 测试档)真转账会被拒。
+WITHDRAW_MIN_CENTS: int = 10
+WITHDRAW_MAX_CENTS: int = 5_000_000  # 5 万元
+
+
+# ===== 一次性任务(领一次,user_task 去重)=====
+TASK_ENABLE_NOTIFICATION = "enable_notification"
+
+# task_key -> 奖励金币
+# 打开消息提醒: 1000 金币(=¥0.1, 客户端原型展示口径; 量级与签到/里程碑相称)。
+# 注意: 不再 = 兑换下限(下限已降到 MIN_EXCHANGE_COIN=COIN_PER_CENT=100), test_exchange_flow 改走 grant_coins 直接供款。
+TASK_REWARDS: dict[str, int] = {
+    TASK_ENABLE_NOTIFICATION: 1000,
+}
+
+
+# ===== 比价战绩里程碑(累计成功比价 N 次,逐档解锁领金币)=====
+# 第 1→6 次的金币奖励(1-based:第 N 次比价解锁第 N 档)。值沿用客户端原型档位。
+# 数据源是 comparison_record 里 status='success' 的条数;每档领一次,
+# comparison_milestone_claim 去重(仿一次性任务)。要调档位/金额直接改这里。
+RECORD_MILESTONES: tuple[int, ...] = (120, 180, 300, 500, 800, 1200)
+RECORD_MILESTONE_COUNT: int = len(RECORD_MILESTONES)
+
+
+def record_milestone_reward(milestone: int) -> int:
+    """第 milestone 档(1..RECORD_MILESTONE_COUNT)的金币。越界抛 IndexError。"""
+    return RECORD_MILESTONES[milestone - 1]
+
+
+# ===== 看激励视频发金币(穿山甲 S2S 服务端回调发奖)=====
+# 看完一个激励视频发的金币(666 金币 ≈¥0.0666,汇率 10000 金币=1 元)。
+# 作用:① 回调缺/坏 reward_amount 时的回退值;② 客户端进度接口展示的"单次预告金币";
+#       ③ test-grant 本地联调的发奖额。
+# 真实发放以穿山甲回调带回的 reward_amount 为准(见 resolve_ad_reward_coin),后台应把
+# 代码位"奖励数量"配成与本值一致(=666),保证"广告内展示 / 进度预告 / 实际到账"三者一致。
+AD_REWARD_COIN: int = 666
+# 单次发奖金币上限:夹紧穿山甲回调里异常的 reward_amount(如后台多打一个 0),防刷爆余额。
+MAX_AD_REWARD_COIN: int = 1000
+# 每用户每日发奖次数上限——现作为"看广告时长上限"的**次数兜底**(防前端少报观看时长绕过时长闸)。
+# 主闸是 DAILY_AD_WATCH_SECONDS_LIMIT(50 分钟);次数兜底要 ≥ 时长闸内的"合理最大次数",
+# 否则会比主闸先掐、误伤看大量短广告的正常用户:50 分钟里若广告各 ~15s,理论可看 ~200 次,
+# 故取 200(≈时长闸的次数等价),正常用户先撞 50 分钟时长闸,仅前端时长全报 0 等异常时本闸才兜住。
+# 不要为"更严"而下调到 120 之类(会在 ~30 分钟就掐短广告用户);要更严应在客户端如实上报时长。
+DAILY_AD_REWARD_LIMIT: int = 200
+
+# ===== 看激励视频每日总时长上限(防刷主闸)=====
+# 用户每天最多看 50 分钟激励视频,超了不发奖 / 不给看。时长由前端 onAdClose 上报真实观看
+# 秒数累计(POST /api/v1/ad/watch-report → ad_watch_log 表 SUM)。前端不可信,故配合上面
+# DAILY_AD_REWARD_LIMIT 次数兜底一起防刷。要调上限直接改这里。
+DAILY_AD_WATCH_SECONDS_LIMIT: int = 50 * 60  # 3000 秒 = 50 分钟
+# 单次上报观看时长的合理上限(夹紧异常值):激励视频一般 15~60 秒,超 120 秒按 120 记,防刷大值。
+MAX_SINGLE_WATCH_SECONDS: int = 120
+# 一轮看 N 次激励视频,看完一轮强制 10 分钟冷却(reward-status 派生 cooldown_until 给客户端,
+# 客户端任务行 CTA 在冷却期间显示"MM:SS"且不可点)。冷却是 UX 约束,后端发奖只看 daily_limit,
+# 冷却期间穿山甲回调仍照常发奖,不另设拒发分支。
+VIDEO_ROUND_REQUIRED_COUNT: int = 3
+VIDEO_ROUND_COOLDOWN_SECONDS: int = 600
+
+
+def resolve_ad_reward_coin(db, reward_amount: str | int | None) -> int:  # noqa: ANN001
+    """把穿山甲回调的 reward_amount(后台代码位配的"奖励数量")解析成本次发放金币。
+
+    缺失 / 非数字 / ≤0 → 回退配置单次金币;超过配置单次上限 → 夹紧(均从 app_config 读)。
+    注:reward_amount 不参与穿山甲 sign(只签 trans_id),但伪造回调需先伪造合法 sign
+    (要 SecurityKey),故能过验签的 reward_amount 即视为可信,这里只防后台配错。
+    """
+    default_coin = get_ad_reward_coin(db)
+    try:
+        coin = int(reward_amount)  # type: ignore[arg-type]
+    except (TypeError, ValueError):
+        return default_coin
+    if coin <= 0:
+        return default_coin
+    return min(coin, get_ad_max_coin(db))
+
+
+# ===== 配置读取(运营后台可覆盖;app_config 表空时返回上面的常量默认 = 现状不变)=====
+# 业务处用这些 getter(传 db)取值,而非直接用常量,这样 admin 改 app_config 即生效。
+# 函数内延迟 import,避免 rewards ← app_config ← config_schema ← rewards 的模块级循环。
+
+def _cfg(db, key: str):  # noqa: ANN001
+    from app.repositories import app_config
+    return app_config.get_value(db, key)
+
+
+def get_signin_rewards(db) -> list[int]:  # noqa: ANN001
+    return list(_cfg(db, "signin_rewards"))
+
+
+def get_min_exchange_coin(db) -> int:  # noqa: ANN001
+    return int(_cfg(db, "min_exchange_coin"))
+
+
+def get_withdraw_min_cents(db) -> int:  # noqa: ANN001
+    return int(_cfg(db, "withdraw_min_cents"))
+
+
+def get_withdraw_max_cents(db) -> int:  # noqa: ANN001
+    return int(_cfg(db, "withdraw_max_cents"))
+
+
+def get_task_rewards(db) -> dict[str, int]:  # noqa: ANN001
+    return dict(_cfg(db, "task_rewards"))
+
+
+def get_record_milestones(db) -> list[int]:  # noqa: ANN001
+    return list(_cfg(db, "record_milestones"))
+
+
+def get_ad_reward_coin(db) -> int:  # noqa: ANN001
+    return int(_cfg(db, "ad_reward_coin"))
+
+
+def get_ad_daily_limit(db) -> int:  # noqa: ANN001
+    return int(_cfg(db, "ad_daily_limit"))
+
+
+def get_ad_max_coin(db) -> int:  # noqa: ANN001
+    return int(_cfg(db, "ad_max_coin"))
+
+
+def get_ad_round_count(db) -> int:  # noqa: ANN001
+    return int(_cfg(db, "ad_round_count"))
+
+
+def get_ad_cooldown_sec(db) -> int:  # noqa: ANN001
+    return int(_cfg(db, "ad_cooldown_sec"))

app/core/security.py

@@ -14,6 +14,7 @@ from __future__ import annotations
 from datetime import datetime, timedelta, timezone
 from typing import Any, Literal
 
+import bcrypt
 import jwt
 
 from app.core.config import settings
@@ -84,3 +85,24 @@ def issue_token_pair(user_id: int) -> dict[str, Any]:
         "expires_in": int((access_exp - _now()).total_seconds()),
         "refresh_expires_in": int((refresh_exp - _now()).total_seconds()),
     }
+
+
+# ===================== 密码 hash(admin 后台账号用)=====================
+# 用户侧是手机号+验证码登录,不存密码;仅 admin 账号用 username+password 登录。
+
+def hash_password(plain: str) -> str:
+    """bcrypt 加盐 hash,返回可入库的字符串。
+
+    bcrypt 限制明文 ≤72 字节,超出抛 ValueError(实测 bcrypt 5.0:25 个中文=75 字节即触发)。
+    统一截断到 72 字节(bcrypt 标准做法)——72 字节仍是强密码,verify 同样截断保证一致。
+    """
+    return bcrypt.hashpw(plain.encode("utf-8")[:72], bcrypt.gensalt()).decode("utf-8")
+
+
+def verify_password(plain: str, hashed: str) -> bool:
+    """校验明文与 bcrypt hash。明文同样截断 72 字节(与 hash_password 一致,否则超长密码永远不匹配);
+    hash 串损坏/格式非法时返回 False,不抛异常。"""
+    try:
+        return bcrypt.checkpw(plain.encode("utf-8")[:72], hashed.encode("utf-8"))
+    except (ValueError, TypeError):
+        return False

app/core/sms.py

@@ -1,68 +0,0 @@
-"""短信验证码服务。
-
-当前实现:**mock 模式**。
-  - send_code(): 不真发短信,仅 log。记录 phone → 发送时间(防 60s 内重复发)
-  - verify_code(): 任意 6 位数字均通过(配合前台 demo 行为)
-
-后续接真供应商(阿里云 / 腾讯云)时:
-  - send_code() 改为调供应商 API,把生成的 6 位码存到 cache(redis / sqlite)
-  - verify_code() 比对 cache 里的码,且验过即作废
-
-进程内存方案占坑期够用;切真实供应商时一并切 redis。
-"""
-from __future__ import annotations
-
-import logging
-import time
-from threading import Lock
-
-from app.core.config import settings
-
-logger = logging.getLogger("shagua.sms")
-
-# 进程内最近发送时间表:{phone: epoch_seconds},用于 60s 内拒发
-_last_sent: dict[str, float] = {}
-_lock = Lock()
-
-
-class SmsError(Exception):
-    """业务异常:发送过频 / 验证码不对。api 层 catch 后翻成 4xx。"""
-
-
-def send_code(phone: str) -> int:
-    """发送(或 mock 发送)验证码。
-
-    Returns: 距下一次可发的秒数(=0 表示刚刚已发,需等 SMS_SEND_INTERVAL_SEC 秒)
-    Raises: SmsError 如果上次发送在 SMS_SEND_INTERVAL_SEC 内
-    """
-    now = time.time()
-    with _lock:
-        last = _last_sent.get(phone, 0.0)
-        elapsed = now - last
-        if elapsed < settings.SMS_SEND_INTERVAL_SEC:
-            remain = int(settings.SMS_SEND_INTERVAL_SEC - elapsed)
-            raise SmsError(f"send too frequent, retry in {remain}s")
-        _last_sent[phone] = now
-
-    if settings.SMS_MOCK:
-        logger.info("[SMS-MOCK] send to %s****, code=any-6-digits", phone[:3])
-    else:
-        # TODO: 接真实短信供应商
-        logger.warning("[SMS] real provider not implemented yet, phone=%s****", phone[:3])
-        raise SmsError("sms provider not configured")
-
-    return settings.SMS_SEND_INTERVAL_SEC
-
-
-def verify_code(phone: str, code: str) -> bool:
-    """校验验证码。mock 模式下任意 6 位数字均通过。"""
-    if settings.SMS_MOCK:
-        if len(code) == 6 and code.isdigit():
-            logger.info("[SMS-MOCK] verify ok for %s****", phone[:3])
-            return True
-        logger.info("[SMS-MOCK] verify fail (need 6 digits) for %s****", phone[:3])
-        return False
-
-    # TODO: 比对供应商发出的真实验证码
-    logger.warning("[SMS] real provider not implemented yet, phone=%s****", phone[:3])
-    return False

app/crud/order_record.py

@@ -1,26 +0,0 @@
-from __future__ import annotations
-
-from sqlalchemy import func, select
-from sqlalchemy.orm import Session
-
-from app.models.order_record import OrderRecord
-
-
-def get_records_page(
-    db: Session,
-    *,
-    user_id: int,
-    page: int = 1,
-    size: int = 20,
-) -> tuple[list[OrderRecord], bool]:
-    offset = (page - 1) * size
-    stmt = (
-        select(OrderRecord)
-        .where(OrderRecord.user_id == user_id)
-        .order_by(OrderRecord.order_date.desc(), OrderRecord.id.desc())
-        .offset(offset)
-        .limit(size + 1)
-    )
-    rows = list(db.execute(stmt).scalars().all())
-    has_next = len(rows) > size
-    return rows[:size], has_next

app/db/base.py

@@ -4,7 +4,7 @@
 """
 from __future__ import annotations
 
-from sqlalchemy.orm import DeclarativeBase, MappedAsDataclass
+from sqlalchemy.orm import DeclarativeBase
 
 
 class Base(DeclarativeBase):

app/db/session.py

@@ -27,19 +27,25 @@ def _ensure_sqlite_dir(url: str) -> None:
 
 _ensure_sqlite_dir(settings.DATABASE_URL)
 
+_is_sqlite = settings.DATABASE_URL.startswith("sqlite")
+
 # SQLite 跨线程访问要 check_same_thread=False;PG/MySQL 不需要这个参数
 _connect_args: dict = {}
-if settings.DATABASE_URL.startswith("sqlite"):
+if _is_sqlite:
     _connect_args["check_same_thread"] = False
 
-engine = create_engine(
-    settings.DATABASE_URL,
-    connect_args=_connect_args,
+_engine_kwargs: dict = {
+    "connect_args": _connect_args,
     # echo 在 dev 下打 SQL,生产关掉
-    echo=settings.APP_DEBUG and not settings.is_prod,
-    future=True,
-    pool_pre_ping=True,
-)
+    "echo": settings.APP_DEBUG and not settings.is_prod,
+    "future": True,
+    "pool_pre_ping": True,
+}
+# SQLite 用单文件不需要池;PG/MySQL 必须显式池化 + recycle 防 idle 断连
+if not _is_sqlite:
+    _engine_kwargs.update(pool_size=10, max_overflow=20, pool_recycle=3600)
+
+engine = create_engine(settings.DATABASE_URL, **_engine_kwargs)
 
 SessionLocal = sessionmaker(bind=engine, autocommit=False, autoflush=False, expire_on_commit=False)
 

app/integrations/pangle.py

@@ -0,0 +1,44 @@
+"""穿山甲激励视频"服务端发奖回调"的验签。
+
+发奖闭环:激励视频播完 → 穿山甲服务器 GET 回调本服务(带 user_id / trans_id / sign 等)
+→ 本服务**验签**确认回调确实来自穿山甲(而非伪造请求) → 幂等发金币。
+客户端不参与发奖,被破解也刷不到钱。
+
+验签方案(穿山甲 GroMore「广告位 → 服务端激励回调」官方规范,见 supportcenter/26240。
+我们客户端是 useMediation(true) 融合,回调走 GroMore 广告位层级,**不是**联盟代码位层级):
+**sign = SHA256("{m-key}:{trans_id}")** 的十六进制串。注意:
+- 是**普通 SHA256**,不是 HMAC,也不是 RSA;
+- **只对 `m-key:trans_id` 这一个字符串**签名,user_id / reward_amount 等其余参数**不参与**签名
+  (它们的可信度由"能算出正确 sign = 知道 m-key"间接保证——伪造者没有 m-key 就连合法 sign
+  都造不出,自然也无法注入假 user_id/reward_amount)。
+m-key(安全密钥)在穿山甲后台「GroMore 聚合管理 → 搜广告位ID → 编辑」处获取,配到
+`settings.PANGLE_REWARD_SECRET`。(联盟代码位层级用的是另一套 Security Key + isValid 响应,我们不走那条。)
+"""
+from __future__ import annotations
+
+import hashlib
+import hmac
+
+
+def build_sign(trans_id: str, secret: str) -> str:
+    """按穿山甲规范计算 sign = SHA256("{SecurityKey}:{trans_id}") 的十六进制串。
+
+    secret 即后台的 Security Key。自验签测试 / 模拟回调脚本也用这一个函数,保证两端一致。
+    """
+    msg = f"{secret}:{trans_id}".encode("utf-8")
+    return hashlib.sha256(msg).hexdigest()
+
+
+def verify_callback_sign(params: dict[str, str], secret: str) -> bool:
+    """校验回调签名。`params` 是回调全部 query 参数(含 sign / trans_id)。
+
+    密钥为空或缺 trans_id 一律判失败。比较用定长比较防时序侧信道。
+    """
+    if not secret:
+        return False
+    trans_id = params.get("trans_id") or ""
+    if not trans_id:
+        return False
+    got = params.get("sign") or ""
+    expect = build_sign(trans_id, secret)
+    return hmac.compare_digest(got, expect)

app/integrations/sms.py

@@ -0,0 +1,211 @@
+"""短信验证码服务。
+
+两种运行模式由 `SMS_MOCK` 切换:
+  - **mock**(开发/测试,默认):不真发短信,验证码打到日志;校验**放行任意 N 位数字**
+    (测试/开发便利)。真实校验逻辑(比对存码 / 一次性 / 防爆破)由 real 分支 + 单测覆盖。
+  - **real**(生产 `SMS_MOCK=false`):本服务生成 N 位验证码 → 调极光短信 REST
+    `/v1/messages` 发送(自定义验证码模式,极光只负责发,code 由本服务生成/保管/
+    校验)→ 鉴权复用极光一键登录的 `JG_APP_KEY`/`JG_MASTER_SECRET`(同一极光应用)。
+
+验证码存储:**进程内存**(单 worker uvicorn 够用)。重启丢失(用户重发即可)。多
+worker / 多机时内存不共享 → 冷却、每日上限、校验都会失效,届时迁移到 DB/Redis。
+见 docs/待办与技术债.md。
+
+防刷三层(短信花钱 + `/sms/send` 在登录前无法 JWT 鉴权):
+  1. 单号 `SMS_SEND_INTERVAL_SEC` 冷却(本文件)
+  2. 单号每日 `SMS_DAILY_LIMIT_PER_PHONE` 条上限(本文件)
+  3. 单 IP 频控(api 层 rate_limit 依赖)+ 极光控制台 IP 白名单/防轰炸(运维侧)
+另:单码校验失败 `SMS_MAX_VERIFY_ATTEMPTS` 次即作废(防爆破),验过即作废(一次性)。
+"""
+from __future__ import annotations
+
+import base64
+import logging
+import secrets
+import time
+from dataclasses import dataclass
+from datetime import datetime
+from threading import Lock
+
+import httpx
+
+from app.core.config import settings
+
+logger = logging.getLogger("shagua.sms")
+
+
+class SmsError(Exception):
+    """业务异常。`status_code` 决定 api 层翻成哪个 HTTP 码:
+    过频/每日超限 = 429(客户端等会再来),供应商不可用 = 503,手机号无效 = 400。
+    """
+
+    def __init__(self, message: str, status_code: int = 429) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+@dataclass
+class _CodeRecord:
+    code: str
+    expires_at: float
+    attempts: int = 0
+
+
+# 进程内存(单 worker 有效;多 worker 不共享,见模块 docstring)
+_codes: dict[str, _CodeRecord] = {}            # phone -> 当前有效验证码
+_last_sent: dict[str, float] = {}              # phone -> 上次发送 epoch(冷却)
+_daily_count: dict[str, tuple[str, int]] = {}  # phone -> (date_str, 当日发送数)
+_lock = Lock()
+_GC_THRESHOLD = 10000  # 任一内存 dict 超此阈值,send 时顺手清过期项(防无限增长,仿 ratelimit)
+
+
+def _today() -> str:
+    return datetime.now().strftime("%Y-%m-%d")
+
+
+def _gen_code() -> str:
+    """生成 N 位数字验证码(用 secrets 而非 random;允许前导 0)。"""
+    return "".join(secrets.choice("0123456789") for _ in range(settings.SMS_CODE_LENGTH))
+
+
+def _gc(now: float) -> None:
+    """顺手清理过期内存项,防三个 dict 无限增长。仅在持锁时调用,且某 dict 超
+    _GC_THRESHOLD 才扫它(低频,开销可忽略)。"""
+    if len(_codes) > _GC_THRESHOLD:
+        for p in [p for p, r in _codes.items() if now > r.expires_at]:
+            _codes.pop(p, None)
+    if len(_last_sent) > _GC_THRESHOLD:
+        cutoff = now - settings.SMS_SEND_INTERVAL_SEC
+        for p in [p for p, ts in _last_sent.items() if ts < cutoff]:
+            _last_sent.pop(p, None)
+    if len(_daily_count) > _GC_THRESHOLD:
+        today = _today()
+        for p in [p for p, (d, _c) in _daily_count.items() if d != today]:
+            _daily_count.pop(p, None)
+
+
+def send_code(phone: str) -> int:
+    """发送验证码。
+
+    Returns: 距下次可发的秒数(= SMS_SEND_INTERVAL_SEC)
+    Raises: SmsError(过频 429 / 当日超限 429 / 供应商失败 503 / 手机号无效 400)
+    """
+    now = time.time()
+
+    # --- lock 内:防刷检查 + 预占(防并发重复发烧钱)---
+    with _lock:
+        _gc(now)  # 顺手清过期内存(超阈值才扫)
+        elapsed = now - _last_sent.get(phone, 0.0)
+        if elapsed < settings.SMS_SEND_INTERVAL_SEC:
+            remain = int(settings.SMS_SEND_INTERVAL_SEC - elapsed)
+            raise SmsError(f"发送过于频繁,请 {remain}s 后再试")
+
+        today = _today()
+        day, cnt = _daily_count.get(phone, ("", 0))
+        if day != today:
+            cnt = 0
+        if cnt >= settings.SMS_DAILY_LIMIT_PER_PHONE:
+            raise SmsError("今日验证码发送次数已达上限,请明天再试")
+
+        code = _gen_code()
+        # 预占:先记冷却/计数/存码,释放锁后再发网络(发失败保留冷却+计数,见下)
+        _last_sent[phone] = now
+        _daily_count[phone] = (today, cnt + 1)
+        _codes[phone] = _CodeRecord(code=code, expires_at=now + settings.SMS_CODE_TTL_SEC)
+
+    # --- lock 外:真正发送(网络 IO 不持锁)---
+    try:
+        if settings.SMS_MOCK:
+            logger.info("[SMS-MOCK] to %s**** code=%s (不真发)", phone[:3], code)
+        else:
+            _send_via_jiguang(phone, code)
+            logger.info("[SMS] sent to %s****", phone[:3])
+    except Exception as e:
+        # 发送失败:**保留冷却 + 每日计数**(失败也限速,挡住余额不足/签名失效时
+        # 前端重试狂打极光),只清掉没发出去的码(用户收不到,留着无意义且占内存)。
+        with _lock:
+            _codes.pop(phone, None)
+        if isinstance(e, SmsError):
+            raise
+        logger.exception("[SMS] send failed phone=%s****", phone[:3])
+        raise SmsError("验证码发送失败,请稍后重试", status_code=503) from e
+
+    return settings.SMS_SEND_INTERVAL_SEC
+
+
+def verify_code(phone: str, code: str) -> bool:
+    """校验验证码。
+
+    - **mock 模式**:放行任意 N 位数字(测试/开发便利,不真校验)。
+    - **real 模式**:比对本服务存的码,匹配即作废(一次性);失败累计到上限也作废(防爆破)。
+    """
+    if settings.SMS_MOCK:
+        ok = len(code) == settings.SMS_CODE_LENGTH and code.isdigit()
+        logger.info("[SMS-MOCK] verify %s for %s****", "ok" if ok else "fail", phone[:3])
+        return ok
+
+    with _lock:
+        rec = _codes.get(phone)
+        if rec is None:
+            return False
+        if time.time() > rec.expires_at:
+            _codes.pop(phone, None)
+            return False
+        if rec.attempts >= settings.SMS_MAX_VERIFY_ATTEMPTS:
+            _codes.pop(phone, None)  # 试错过多,作废
+            return False
+        if secrets.compare_digest(code.encode("utf-8"), rec.code.encode("utf-8")):
+            _codes.pop(phone, None)  # 验过即作废
+            return True
+        rec.attempts += 1
+        return False
+
+
+def _send_via_jiguang(phone: str, code: str) -> None:
+    """调极光短信 REST /v1/messages 发送(自定义验证码模式)。失败抛 SmsError。"""
+    if not settings.JG_APP_KEY or not settings.JG_MASTER_SECRET:
+        raise SmsError("短信服务未配置(缺 JG_APP_KEY/JG_MASTER_SECRET)", status_code=503)
+    if not settings.SMS_SIGN_ID or not settings.SMS_TEMPLATE_ID:
+        raise SmsError("短信服务未配置(缺 SMS_SIGN_ID/SMS_TEMPLATE_ID)", status_code=503)
+
+    auth_b64 = base64.b64encode(
+        f"{settings.JG_APP_KEY}:{settings.JG_MASTER_SECRET}".encode()
+    ).decode()
+    body = {
+        "mobile": phone,
+        "sign_id": settings.SMS_SIGN_ID,
+        "temp_id": settings.SMS_TEMPLATE_ID,
+        "temp_para": {"code": code},
+    }
+    try:
+        resp = httpx.post(
+            settings.SMS_SEND_ENDPOINT,
+            json=body,
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Basic {auth_b64}",
+            },
+            timeout=settings.JG_REQUEST_TIMEOUT_SEC,
+        )
+    except httpx.HTTPError as e:
+        raise SmsError(f"短信网关网络错误: {e}", status_code=503) from e
+
+    if resp.status_code == 200:
+        return  # {"msg_id": ...}
+
+    # 极光错误码映射(节选常见;完整码表见 docs/integrations/sms.md)
+    try:
+        err = resp.json().get("error", {})
+        ecode, emsg = err.get("code"), err.get("message", "")
+    except Exception:
+        ecode, emsg = None, resp.text[:200]
+    logger.error("[SMS] jiguang error http=%s code=%s msg=%s", resp.status_code, ecode, emsg)
+
+    if ecode == 50014:  # 余额不足:运维要立即告警充值
+        logger.critical("[SMS] 极光短信余额不足(50014),需充值!")
+        raise SmsError("短信服务暂不可用,请稍后重试", status_code=503)
+    if ecode == 50009:  # 极光侧超频
+        raise SmsError("发送过于频繁,请稍后再试", status_code=429)
+    if ecode == 50006:  # 手机号无效(schema 已挡格式,这里多是空号/停机)
+        raise SmsError("手机号无效", status_code=400)
+    raise SmsError(f"短信发送失败(code={ecode})", status_code=503)

app/integrations/wxpay.py

@@ -0,0 +1,201 @@
+"""微信支付 V3 —— 商家转账到零钱(提现)。
+
+移植自 elderhelper 的 wxpay.py,改成从 [app.core.config.settings] 读配置、密钥懒加载
+(文件缺失不在 import 时炸进程,只在真正调用转账时报错,与极光私钥同款策略)。
+
+只实现提现需要的两个接口:
+  - create_transfer:发起转账(商家转账到零钱)
+  - query_transfer :按商户单号查转账单状态
+签名用商户 API 私钥(RSA-SHA256/PKCS1v15),敏感字段(实名)用微信支付平台公钥 OAEP 加密。
+"""
+from __future__ import annotations
+
+import base64
+import json
+import time
+import uuid
+
+import httpx
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import padding
+from cryptography.hazmat.primitives.asymmetric.rsa import RSAPrivateKey, RSAPublicKey
+
+from app.core.config import settings
+
+_API_HOST = "https://api.mch.weixin.qq.com"
+_TRANSFER_PATH = "/v3/fund-app/mch-transfer/transfer-bills"
+
+# 懒加载缓存
+_private_key: RSAPrivateKey | None = None
+_public_key: RSAPublicKey | None = None
+
+
+class WxPayNotConfiguredError(Exception):
+    """微信支付凭证 / 证书缺失,无法调用。"""
+
+
+def _load_private_key() -> RSAPrivateKey:
+    global _private_key
+    if _private_key is None:
+        try:
+            with open(settings.WXPAY_MCH_PRIVATE_KEY_PATH, "rb") as f:
+                _private_key = serialization.load_pem_private_key(f.read(), password=None)
+        except FileNotFoundError as e:
+            raise WxPayNotConfiguredError(
+                f"商户私钥不存在: {settings.WXPAY_MCH_PRIVATE_KEY_PATH}"
+            ) from e
+    return _private_key
+
+
+def _load_public_key() -> RSAPublicKey:
+    global _public_key
+    if _public_key is None:
+        try:
+            with open(settings.WXPAY_PUBLIC_KEY_PATH, "rb") as f:
+                _public_key = serialization.load_pem_public_key(f.read())
+        except FileNotFoundError as e:
+            raise WxPayNotConfiguredError(
+                f"微信支付平台公钥不存在: {settings.WXPAY_PUBLIC_KEY_PATH}"
+            ) from e
+    return _public_key
+
+
+def _sign(message: str) -> str:
+    """RSA-SHA256 签名,base64 输出。"""
+    signature = _load_private_key().sign(
+        message.encode("utf-8"), padding.PKCS1v15(), hashes.SHA256()
+    )
+    return base64.b64encode(signature).decode("utf-8")
+
+
+def _build_authorization(method: str, url_path: str, body: str) -> str:
+    """构建 V3 Authorization 头(WECHATPAY2-SHA256-RSA2048)。"""
+    timestamp = str(int(time.time()))
+    nonce = uuid.uuid4().hex
+    sign_str = f"{method}\n{url_path}\n{timestamp}\n{nonce}\n{body}\n"
+    signature = _sign(sign_str)
+    return (
+        f'WECHATPAY2-SHA256-RSA2048 mchid="{settings.WXPAY_MCH_ID}",'
+        f'nonce_str="{nonce}",'
+        f'timestamp="{timestamp}",'
+        f'serial_no="{settings.WXPAY_MCH_SERIAL_NO}",'
+        f'signature="{signature}"'
+    )
+
+
+def encrypt_sensitive(plain_text: str) -> str:
+    """用微信支付平台公钥 OAEP(SHA1) 加密敏感信息(如实名)。"""
+    ciphertext = _load_public_key().encrypt(
+        plain_text.encode("utf-8"),
+        padding.OAEP(mgf=padding.MGF1(algorithm=hashes.SHA1()), algorithm=hashes.SHA1(), label=None),
+    )
+    return base64.b64encode(ciphertext).decode("utf-8")
+
+
+def create_transfer(
+    openid: str, amount_fen: int, out_bill_no: str, user_name: str | None = None
+) -> dict:
+    """发起商家转账到零钱。返回 {status_code, data}。
+
+    user_name(实名)在金额达微信阈值时必须传(加密)。这里沿用 elderhelper 阈值,
+    实际阈值以微信侧要求为准。
+    """
+    body = {
+        "appid": settings.WECHAT_APP_ID,
+        "out_bill_no": out_bill_no,
+        "transfer_scene_id": settings.WXPAY_TRANSFER_SCENE_ID,
+        "openid": openid,
+        "transfer_amount": amount_fen,
+        "transfer_remark": "金币提现",
+        "transfer_scene_report_infos": [
+            {"info_type": "活动名称", "info_content": "比价返现"},
+            {"info_type": "奖励说明", "info_content": "现金提现到微信零钱"},
+        ],
+    }
+    if user_name and amount_fen >= 30:
+        body["user_name"] = encrypt_sensitive(user_name)
+
+    body_str = json.dumps(body, ensure_ascii=False)
+    headers = {
+        "Authorization": _build_authorization("POST", _TRANSFER_PATH, body_str),
+        "Accept": "application/json",
+        "Content-Type": "application/json",
+        "Wechatpay-Serial": settings.WXPAY_PUBLIC_KEY_ID,
+    }
+    with httpx.Client() as client:
+        resp = client.post(
+            f"{_API_HOST}{_TRANSFER_PATH}",
+            content=body_str,
+            headers=headers,
+            timeout=settings.WXPAY_REQUEST_TIMEOUT_SEC,
+        )
+    return {"status_code": resp.status_code, "data": resp.json()}
+
+
+def query_transfer(out_bill_no: str) -> dict:
+    """按商户单号查转账单。返回 {status_code, data}。"""
+    path = f"{_TRANSFER_PATH}/out-bill-no/{out_bill_no}"
+    headers = {
+        "Authorization": _build_authorization("GET", path, ""),
+        "Accept": "application/json",
+    }
+    with httpx.Client() as client:
+        resp = client.get(
+            f"{_API_HOST}{path}", headers=headers, timeout=settings.WXPAY_REQUEST_TIMEOUT_SEC
+        )
+    return {"status_code": resp.status_code, "data": resp.json()}
+
+
+def cancel_transfer(out_bill_no: str) -> dict:
+    """撤销转账单(仅 WAIT_USER_CONFIRM/ACCEPTED 可撤)。用户没在确认页确认就离开时调用。
+    成功返回 {status_code:200, data:{state:'CANCELLING'|'CANCELLED', ...}}。"""
+    path = f"{_TRANSFER_PATH}/out-bill-no/{out_bill_no}/cancel"
+    headers = {
+        "Authorization": _build_authorization("POST", path, ""),
+        "Accept": "application/json",
+        "Content-Type": "application/json",
+    }
+    with httpx.Client() as client:
+        resp = client.post(
+            f"{_API_HOST}{path}", headers=headers, timeout=settings.WXPAY_REQUEST_TIMEOUT_SEC
+        )
+    return {"status_code": resp.status_code, "data": resp.json()}
+
+
+def code_to_userinfo(code: str) -> dict:
+    """code 换 access_token+openid,再拉 sns/userinfo 取昵称头像。
+    返回 {openid, nickname, avatar_url, raw}。失败抛 ValueError。
+    注意:微信隐私新政下,部分 app 的 sns/userinfo 可能返回脱敏值(昵称"微信用户"/灰头像);
+    nickname/avatar_url 可能为空,调用方需兜底。"""
+    r1 = httpx.get(
+        "https://api.weixin.qq.com/sns/oauth2/access_token",
+        params={
+            "appid": settings.WECHAT_APP_ID,
+            "secret": settings.WECHAT_APP_SECRET,
+            "code": code,
+            "grant_type": "authorization_code",
+        },
+        timeout=settings.WXPAY_REQUEST_TIMEOUT_SEC,
+    )
+    d1 = r1.json()
+    if "openid" not in d1 or "access_token" not in d1:
+        raise ValueError(f"微信授权失败: {d1.get('errmsg', d1)}")
+    openid = d1["openid"]
+
+    nickname = None
+    avatar_url = None
+    raw: dict = {}
+    # userinfo 拉取失败不应让绑定失败(openid 已拿到),吞掉异常只是没昵称头像
+    try:
+        r2 = httpx.get(
+            "https://api.weixin.qq.com/sns/userinfo",
+            params={"access_token": d1["access_token"], "openid": openid, "lang": "zh_CN"},
+            timeout=settings.WXPAY_REQUEST_TIMEOUT_SEC,
+        )
+        raw = r2.json()
+        nickname = raw.get("nickname") or None
+        avatar_url = raw.get("headimgurl") or None
+    except Exception:  # noqa: BLE001
+        pass
+
+    return {"openid": openid, "nickname": nickname, "avatar_url": avatar_url, "raw": raw}

app/main.py

@@ -8,12 +8,27 @@ import logging
 from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
 
+from pathlib import Path
+
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
+from fastapi.staticfiles import StaticFiles
 
+from app.api.v1.ad import router as ad_router
 from app.api.v1.auth import router as auth_router
+from app.api.v1.compare import router as compare_router
+from app.api.v1.compare_milestone import router as compare_milestone_router
+from app.api.v1.compare_record import router as compare_record_router
+from app.api.v1.coupon import router as coupon_router
+from app.api.v1.feedback import router as feedback_router
 from app.api.v1.meituan import router as meituan_router
+from app.api.v1.order import router as order_router
+from app.api.v1.report import router as report_router
+from app.api.v1.savings import router as savings_router
+from app.api.v1.signin import router as signin_router
+from app.api.v1.tasks import router as tasks_router
 from app.api.v1.user import router as user_router
+from app.api.v1.wallet import router as wallet_router
 from app.core.config import settings
 from app.core.logging import setup_logging
 
@@ -59,5 +74,26 @@ def health() -> dict[str, str]:
 
 
 app.include_router(auth_router)
-app.include_router(meituan_router)
 app.include_router(user_router)
+app.include_router(feedback_router)
+app.include_router(coupon_router)
+app.include_router(compare_router)
+app.include_router(compare_record_router)
+app.include_router(compare_milestone_router)
+app.include_router(meituan_router)
+app.include_router(wallet_router)
+app.include_router(signin_router)
+app.include_router(tasks_router)
+app.include_router(savings_router)
+app.include_router(ad_router)
+app.include_router(order_router)
+app.include_router(report_router)
+
+# 用户上传文件(头像)静态服务。生产可改由 nginx 直接 serve MEDIA_ROOT。
+_media_root = Path(settings.MEDIA_ROOT)
+_media_root.mkdir(parents=True, exist_ok=True)
+app.mount(
+    settings.MEDIA_URL_PREFIX,
+    StaticFiles(directory=str(_media_root)),
+    name="media",
+)

app/models/__init__.py

@@ -1,3 +1,20 @@
 """所有 ORM model 必须在这里 import 一次,Alembic / metadata 才能扫到。"""
+from app.models.ad_ecpm import AdEcpmRecord  # noqa: F401
+from app.models.ad_reward import AdRewardRecord  # noqa: F401
+from app.models.ad_watch_log import AdWatchLog  # noqa: F401
+from app.models.admin import AdminAuditLog, AdminUser  # noqa: F401
+from app.models.app_config import AppConfig  # noqa: F401
+from app.models.comparison import ComparisonRecord  # noqa: F401
+from app.models.comparison_milestone import ComparisonMilestoneClaim  # noqa: F401
+from app.models.feedback import Feedback  # noqa: F401
+from app.models.price_report import PriceReport  # noqa: F401
+from app.models.savings import SavingsRecord  # noqa: F401
+from app.models.signin import SigninRecord  # noqa: F401
+from app.models.task import UserTask  # noqa: F401
 from app.models.user import User  # noqa: F401
-from app.models.order_record import OrderRecord  # noqa: F401
+from app.models.wallet import (  # noqa: F401
+    CashTransaction,
+    CoinAccount,
+    CoinTransaction,
+    WithdrawOrder,
+)

app/models/ad_ecpm.py

@@ -0,0 +1,49 @@
+"""广告展示 eCPM 上报记录(内部收益统计/对账)。
+
+每条 = 客户端一次广告展示(`onAdShow`)后读到的 eCPM 信息。和发奖记录
+[ad_reward.AdRewardRecord] 是**两条独立的数据流**:
+- 发奖走穿山甲 S2S 回调(后端 → 有 trans_id、无 ecpm);
+- eCPM 走客户端上报(客户端 → 有 ecpm、无 trans_id)。
+两者没有公共键,无法逐条一一对应,所以本表用于**按用户/按天聚合收益**口径的对账,
+不做"这条发奖 = 这条 ecpm"的精确关联。穿山甲后台报表才是结算权威,本表是细粒度补充。
+
+⚠️ `ecpm_raw` 原样存客户端上报的字符串——eCPM 单位(分 / 元)截至 2026-05-31 尚未最终确认,
+确认后再加一列解析好的数值;在此之前对账按"待定单位"处理。
+"""
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import DateTime, ForeignKey, Integer, String, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db.base import Base
+
+
+class AdEcpmRecord(Base):
+    __tablename__ = "ad_ecpm_record"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    user_id: Mapped[int] = mapped_column(
+        Integer, ForeignKey("user.id"), index=True, nullable=False
+    )
+    # 广告类型:reward_video(激励视频) / draw(Draw 信息流) 等;不强行统一代码位,各类型各自上报
+    ad_type: Mapped[str] = mapped_column(String(32), nullable=False)
+    # 实际投放的 ADN(穿山甲 getShowEcpm().getSdkName(),如 pangle / gdt)
+    adn: Mapped[str | None] = mapped_column(String(32), nullable=True)
+    # 实际展示用的代码位(底层 mediation rit,非客户端配置位)
+    slot_id: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    # 客户端上报的 eCPM 原始字符串(单位待确认,原样存)
+    ecpm_raw: Mapped[str] = mapped_column(String(32), nullable=False)
+    # 北京时间日期串 'YYYY-MM-DD',按它等值做"按天聚合"(不在 SQL 里做跨时区 date 比较)
+    report_date: Mapped[str] = mapped_column(String(10), index=True, nullable=False)
+
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), index=True, nullable=False
+    )
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return (
+            f"<AdEcpmRecord user_id={self.user_id} {self.ad_type} "
+            f"ecpm={self.ecpm_raw} adn={self.adn}>"
+        )

app/models/ad_reward.py

@@ -0,0 +1,42 @@
+"""看激励视频发奖记录(穿山甲 S2S 回调)。
+
+每条 = 穿山甲一次发奖回调。`trans_id`(穿山甲交易号)唯一,做幂等键:穿山甲会重试回调,
+同号只发一次金币。`reward_date`(北京时间日期串)给"每日上限"计数用——按日期串等值查,
+不在 SQL 里做跨时区 date 比较(SQLite 上不可靠)。审计 / 对账时整张表可逐笔回溯。
+"""
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import DateTime, ForeignKey, Integer, String, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db.base import Base
+
+
+class AdRewardRecord(Base):
+    __tablename__ = "ad_reward_record"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    # 穿山甲交易号,幂等键(同号回调不重复发奖)
+    trans_id: Mapped[str] = mapped_column(String(64), unique=True, index=True, nullable=False)
+    user_id: Mapped[int] = mapped_column(
+        Integer, ForeignKey("user.id"), index=True, nullable=False
+    )
+    # 实发金币(capped 时为 0)
+    coin: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    # granted(已发) / capped(当日超限未发)
+    status: Mapped[str] = mapped_column(String(16), nullable=False, default="granted")
+    # 北京时间日期串 'YYYY-MM-DD',按它等值统计当日发奖次数
+    reward_date: Mapped[str] = mapped_column(String(10), index=True, nullable=False)
+    # 穿山甲上报的奖励名(参考,不作发奖依据)
+    reward_name: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    # 回调原始参数,审计排查用
+    raw: Mapped[str | None] = mapped_column(String(1024), nullable=True)
+
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), index=True, nullable=False
+    )
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return f"<AdRewardRecord trans_id={self.trans_id} user_id={self.user_id} {self.status} coin={self.coin}>"

app/models/ad_watch_log.py

@@ -0,0 +1,41 @@
+"""看激励视频观看时长记录(每日总时长防刷)。
+
+每条 = 客户端 onAdClose 上报的一次激励视频实际观看秒数。按 (user_id, watch_date) 聚合
+SUM(watch_seconds) 得当日总观看时长,用于"每天最多看 50 分钟激励视频"硬上限(超了不再发奖 /
+不给看,见 core.rewards.DAILY_AD_WATCH_SECONDS_LIMIT)。
+
+这是看广告的第三条数据流,与另两条并列、互不关联:
+- ad_reward(AdRewardRecord):穿山甲 S2S 回调发金币(后端,有 trans_id);
+- ad_ecpm(AdEcpmRecord):客户端上报展示收益(前端,有 ecpm);
+- ad_watch_log(本表):客户端上报观看时长(前端,有 watch_seconds)。
+前端上报的时长不可信 → 时长是防刷"主闸",配合 ad_reward 的每日次数上限(DAILY_AD_REWARD_LIMIT)
+做"次数兜底",前端少报时长也刷不过次数闸。
+"""
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import DateTime, ForeignKey, Integer, String, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db.base import Base
+
+
+class AdWatchLog(Base):
+    __tablename__ = "ad_watch_log"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    user_id: Mapped[int] = mapped_column(
+        Integer, ForeignKey("user.id"), index=True, nullable=False
+    )
+    # 本次激励视频实际观看秒数(前端 onAdShow→onAdClose);服务端已夹 [0, MAX_SINGLE_WATCH_SECONDS]
+    watch_seconds: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    # 北京时间日期串 'YYYY-MM-DD',按它等值做"当日总时长"聚合(不在 SQL 里跨时区比较)
+    watch_date: Mapped[str] = mapped_column(String(10), index=True, nullable=False)
+
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), index=True, nullable=False
+    )
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return f"<AdWatchLog user_id={self.user_id} sec={self.watch_seconds} {self.watch_date}>"

app/models/admin.py

@@ -0,0 +1,70 @@
+"""Admin 后台:管理员账号 + 操作审计日志。
+
+与 App 用户(user 表)完全隔离:admin 走独立 JWT secret、独立鉴权链(见 app/admin/)。
+- admin_user:账号密码(bcrypt)登录,带角色(super_admin / finance / operator)。
+- admin_audit_log:每个写操作落一条,记前后值,不可删,用于追溯"谁在何时改了谁的钱/状态"。
+  admin_username / target_id 冗余存字符串,即使关联对象被删/改名也能追溯。
+"""
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import JSON, DateTime, ForeignKey, Integer, String, func
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db.base import Base
+
+# PG 用 JSONB,SQLite(本地/测试)退化为通用 JSON(同 comparison_record.raw_payload)。
+_JSON = JSON().with_variant(JSONB(), "postgresql")
+
+
+class AdminUser(Base):
+    __tablename__ = "admin_user"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    username: Mapped[str] = mapped_column(String(64), unique=True, index=True, nullable=False)
+    password_hash: Mapped[str] = mapped_column(String(255), nullable=False)
+    # super_admin(全权+管账号)/ finance(钱:提现+金币)/ operator(用户+反馈+大盘)
+    role: Mapped[str] = mapped_column(String(20), nullable=False, default="operator")
+    # active / disabled
+    status: Mapped[str] = mapped_column(String(20), nullable=False, default="active")
+
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), nullable=False
+    )
+    last_login_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return f"<AdminUser id={self.id} username={self.username} role={self.role}>"
+
+
+class AdminAuditLog(Base):
+    __tablename__ = "admin_audit_log"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    admin_id: Mapped[int] = mapped_column(
+        Integer, ForeignKey("admin_user.id"), index=True, nullable=False
+    )
+    # 冗余存操作者用户名:admin 改名/禁用后仍可追溯是谁干的
+    admin_username: Mapped[str] = mapped_column(String(64), nullable=False)
+    # 操作类型,如 user.coins.grant / user.status.set / withdraw.refresh / feedback.handle
+    action: Mapped[str] = mapped_column(String(64), index=True, nullable=False)
+    # 被操作对象类型 + id(id 用字符串以兼容 out_bill_no 等非整型主键)
+    target_type: Mapped[str] = mapped_column(String(32), nullable=False)
+    target_id: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    # 上下文 + 前后值,如 {"amount": 1000, "reason": "...", "before": {...}, "after": {...}}
+    detail: Mapped[dict | None] = mapped_column(_JSON, nullable=True)
+    ip: Mapped[str | None] = mapped_column(String(64), nullable=True)
+
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), index=True, nullable=False
+    )
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return (
+            f"<AdminAuditLog id={self.id} admin={self.admin_username} "
+            f"action={self.action} target={self.target_type}:{self.target_id}>"
+        )

app/models/app_config.py

@@ -0,0 +1,32 @@
+"""运营可配置项(把 rewards.py 等硬编码规则挪到 DB,运营后台可改)。
+
+key 是配置标识(见 app.core.config_schema.CONFIG_DEFS),value 用 JSON 存任意值(int/list/dict)。
+表里没有的 key,业务读配置时 fallback 到 CONFIG_DEFS 默认值(= 原 rewards 常量),
+所以**空表 = 现有行为完全不变**。admin 改某项 → 写一行 → 业务下次读到新值(跨进程一致)。
+"""
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from sqlalchemy import JSON, DateTime, Integer, String, func
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db.base import Base
+
+_JSON = JSON().with_variant(JSONB(), "postgresql")
+
+
+class AppConfig(Base):
+    __tablename__ = "app_config"
+
+    key: Mapped[str] = mapped_column(String(64), primary_key=True)
+    value: Mapped[Any] = mapped_column(_JSON, nullable=False)
+    updated_by_admin_id: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), onupdate=func.now(), nullable=False
+    )
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return f"<AppConfig key={self.key}>"

app/models/comparison.py

@@ -0,0 +1,104 @@
+"""比价记录表。
+
+每完成一次比价(外卖/电商/领券),客户端在 done 帧后用带 JWT 的通道上报一条,落这里。
+是未来「我的比价记录」页的数据源,也沉淀用户级行为画像(哪个用户在哪两家之间比了什么)。
+
+与 savings_record 的区别:savings_record 是「省了多少钱」的视角(只有省到才有意义,当前由
+demo seeder 灌),本表是「每一次比价的完整明细」——不省钱、甚至失败的比价也照记一条。
+两表独立,互不影响。
+
+「越详细越好」的落地:结构化列给查询/排序/聚合用,raw_payload(JSONB)把客户端上报的
+原始 calibration + done.params 原样存一份,未来前端要展示什么都能拿到、不丢信息。
+"""
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import (
+    JSON,
+    Boolean,
+    DateTime,
+    ForeignKey,
+    Integer,
+    String,
+    UniqueConstraint,
+    func,
+)
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db.base import Base
+
+# PG 上用 JSONB(可建 GIN 索引),SQLite(本地/测试)退化为通用 JSON——
+# 否则 SQLite 无 JSONB,Base.metadata.create_all 编译报错(同 savings_record.dishes)。
+_JSON = JSON().with_variant(JSONB(), "postgresql")
+
+
+class ComparisonRecord(Base):
+    __tablename__ = "comparison_record"
+    __table_args__ = (
+        # 同一用户同一次比价(trace_id)只存一条:客户端重试/误点重复上报时幂等覆盖。
+        UniqueConstraint("user_id", "trace_id", name="uq_comparison_user_trace"),
+    )
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    user_id: Mapped[int] = mapped_column(
+        Integer, ForeignKey("user.id"), index=True, nullable=False
+    )
+    # 仍记录设备号(同一用户多设备的行为区分 / 与不鉴权期 device_id 数据对账)
+    device_id: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    # 业务类型:food(外卖,当前唯一接通)/ ecom(电商)/ coupon(领券)。预留扩展。
+    business_type: Mapped[str] = mapped_column(
+        String(16), nullable=False, default="food", index=True
+    )
+    # pricebot 侧 trace_id:关联调试落盘 + 幂等去重键
+    trace_id: Mapped[str] = mapped_column(String(64), nullable=False)
+
+    # ===== 源平台(发起比价的那家)=====
+    source_platform_id: Mapped[str | None] = mapped_column(String(32), nullable=True)
+    source_platform_name: Mapped[str | None] = mapped_column(String(32), nullable=True)
+    source_package: Mapped[str | None] = mapped_column(String(128), nullable=True)
+    source_price_cents: Mapped[int | None] = mapped_column(Integer, nullable=True)
+
+    # ===== 最优结果(全平台最便宜的一家,= comparison_results 里 rank=1)=====
+    best_platform_id: Mapped[str | None] = mapped_column(String(32), nullable=True)
+    best_platform_name: Mapped[str | None] = mapped_column(String(32), nullable=True)
+    best_price_cents: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    # 最优平台的商家/商品深链(客户端比价时从剪贴板采到 = collectedLinks[best_index]);
+    # 「再次比价」写剪贴板 + launch 该平台 App 直达。仅 2026-06 起新比价有,旧记录为 None。
+    best_deeplink: Mapped[str | None] = mapped_column(String(1024), nullable=True)
+    # 源价 - 最优价(可为 0 / 负:源平台本来就最便宜时没省到)
+    saved_amount_cents: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    # 源平台就是最便宜的一家(= 这次没省到钱)
+    is_source_best: Mapped[bool | None] = mapped_column(Boolean, nullable=True)
+
+    # ===== 订单概要 =====
+    store_name: Mapped[str | None] = mapped_column(String(128), nullable=True)
+    total_dish_count: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    skipped_dish_count: Mapped[int | None] = mapped_column(Integer, nullable=True)
+
+    # success(拿到有效对比)/ failed(出错或没采到目标价)
+    status: Mapped[str] = mapped_column(String(16), nullable=False, default="success")
+    # done 帧 information 文案。成功:"在美团找到同店,到手价 ¥X…";
+    # 失败:具体原因(如"美团、京东外卖均未找到该商品")。前端在比价失败时当原因展示。
+    information: Mapped[str | None] = mapped_column(String(256), nullable=True)
+
+    # ===== 明细(JSON,越详细越好)=====
+    # 下单菜品 [{name, qty, specs?}]
+    items: Mapped[list] = mapped_column(_JSON, nullable=False, default=list)
+    # 逐平台对比 [{platform_id, platform_name, package, price, is_source, rank, coupon_saved, coupon_name}](price/coupon_saved 单位:元,原样存;coupon_name=优惠来源名)
+    comparison_results: Mapped[list] = mapped_column(_JSON, nullable=False, default=list)
+    # 目标平台未找到、跳过的菜名
+    skipped_dish_names: Mapped[list] = mapped_column(_JSON, nullable=False, default=list)
+    # 客户端上报的原始 payload(calibration + done.params 全量),未来取数兜底
+    raw_payload: Mapped[dict | None] = mapped_column(_JSON, nullable=True)
+
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), index=True, nullable=False
+    )
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return (
+            f"<ComparisonRecord id={self.id} user_id={self.user_id} "
+            f"trace_id={self.trace_id} status={self.status}>"
+        )

app/models/comparison_milestone.py

@@ -0,0 +1,36 @@
+"""比价战绩里程碑领取记录表。
+
+「记录比价战绩」每档(第 1~6 次)只能领一次,领取后写一行,(user_id, milestone)
+唯一,防止重复领奖。解锁进度由 comparison_record 里 status='success' 的条数决定,
+不存进度本身——只在这里记"哪几档已领"。仿 user_task 的一次性领取模型。
+"""
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import DateTime, ForeignKey, Integer, UniqueConstraint, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db.base import Base
+
+
+class ComparisonMilestoneClaim(Base):
+    __tablename__ = "comparison_milestone_claim"
+    __table_args__ = (
+        UniqueConstraint("user_id", "milestone", name="uq_compare_milestone_user"),
+    )
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    user_id: Mapped[int] = mapped_column(
+        Integer, ForeignKey("user.id"), index=True, nullable=False
+    )
+    # 档位序号(1-based),见 app.core.rewards.RECORD_MILESTONES
+    milestone: Mapped[int] = mapped_column(Integer, nullable=False)
+    coin_awarded: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+
+    claimed_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), nullable=False
+    )
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return f"<ComparisonMilestoneClaim user_id={self.user_id} m={self.milestone}>"

app/models/feedback.py

@@ -0,0 +1,35 @@
+"""用户反馈表(帮助与反馈)。
+
+每条 = 用户一次提交。content 必填,contact 必填(微信/QQ/手机,便于回访),images 为可选的
+截图 URL 列表(/media/feedback/...,JSON 存)。status: new(待处理)/ handled(已处理)。
+"""
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import JSON, DateTime, ForeignKey, Integer, String, Text, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db.base import Base
+
+
+class Feedback(Base):
+    __tablename__ = "feedback"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    user_id: Mapped[int] = mapped_column(
+        Integer, ForeignKey("user.id"), index=True, nullable=False
+    )
+    content: Mapped[str] = mapped_column(Text, nullable=False)
+    contact: Mapped[str] = mapped_column(String(128), nullable=False)
+    # 截图 URL 列表(相对路径,如 ["/media/feedback/u1_ab12.jpg"]);无图为 None
+    images: Mapped[list[str] | None] = mapped_column(JSON, nullable=True)
+    # new(待处理) / handled(已处理)
+    status: Mapped[str] = mapped_column(String(16), nullable=False, default="new")
+
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), index=True, nullable=False
+    )
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return f"<Feedback id={self.id} user_id={self.user_id} status={self.status}>"