shaguabijia-app-server/docs/后端技术实现.md

# 傻瓜比价 App Server — 后端技术方案

> 域名:`app-api.shaguabijia.com`(HTTPS,nginx 反代)
> 仓库:`shaguabijia-app-server`
> 接口协议详见 [`docs/api/`](./api/)(索引 + 一接口一文件)
> 最后更新:2026-05-27

---

## 1. 这个后端是干什么的

为正式版 App(`shaguabijia-app-android`,包名 `com.jishisongfu.shaguabijia`)提供三块能力:

| 能力 | 说明 |
|---|---|
| **账号与登录** | 极光一键登录 + 短信验证码登录(mock)→ 签发 JWT |
| **美团 CPS 选品** | 透传美团联盟优惠券(外卖/到店)、点击换取推广链接(分佣) |
| **领券透传** | `/coupon/step` 透传到 pricebot-backend(一键领券核心,MVP 不鉴权,前端已接通) |

**本服务自身没有"比价"实现**——名字叫比价,实质是:登录态 + 美团券聚合分佣 + 给真正的领券/比价核心(pricebot-backend,另一个 repo)做"透传壳"。无爬虫、无 LLM、无积分/提现/钱包,数据模型仅一张 `user` 表(美团数据与领券请求均实时透传不落库)。

---

## 2. 技术栈

| 维度 | 选型 | 说明 |
|---|---|---|
| 语言 | Python ≥3.10 | 本地开发用 conda 环境 `price` |
| Web | FastAPI 0.115+ | OpenAPI 自动生成(非 prod 开 `/docs`) |
| ASGI | uvicorn[standard] | 生产 `--host 127.0.0.1 --port 8770` |
| ORM | SQLAlchemy 2.0(Mapped 风格) | |
| 迁移 | Alembic | |
| DB | SQLite 起步 | 改 `DATABASE_URL` 可切 PostgreSQL,无 Redis |
| Auth | PyJWT(HS256) | access + refresh |
| 极光 | httpx + cryptography | REST 验 token + RSA 解密手机号 |
| 美团 / pricebot | httpx(含 async) | 美团 S-Ca 网关签名;领券 async 透传 |
| 配置 | pydantic-settings | `.env` 加载 |
| 测试 | pytest + httpx TestClient | |

---

## 3. 分层架构与目录结构

标准 FastAPI 分层,一个请求自上而下穿过:**api(薄,收发) → integrations(外部 SDK) / repositories(数据) → models / db**。重逻辑(SDK 签名/加解密/外部 HTTP)落 `integrations`,集成层细节见 [docs/integrations/](./integrations/README.md)。

```
app/
├── main.py                  # FastAPI 入口:注册全部 router、CORS、/health、lifespan
├── api/
│   ├── deps.py              # 共享依赖:get_current_user(鉴权)、get_db(注入 session)
│   └── v1/                  # 接口层(薄):解析请求 → 调 repositories/integration → 组装响应 + HTTP 错误码
│       ├── auth.py          # 登录 6 端点(极光一键登录 / 短信 send+login / refresh / me / logout)
│       ├── coupon.py        # 领券透传 /coupon/step(转发 pricebot,MVP 不鉴权)
│       ├── compare.py       # 外卖比价透传 /intent/recognize + /price/step(转发 pricebot,MVP 不鉴权)
│       ├── meituan.py       # 美团 3 端点 + feed 拼接(_interleave / _TOPIC_ROUNDS)
│       ├── wallet.py        # 钱包/提现 11 端点(余额/流水/兑换/绑微信/提现/查单)
│       ├── signin.py        # 签到 2 端点(状态 / 执行签到)
│       ├── tasks.py         # 一次性任务 2 端点(列表 / 领取)
│       ├── savings.py       # 省钱 3 端点(汇总 / 战绩 / 明细)
│       └── ad.py            # 看广告发奖 3 端点(穿山甲 S2S 回调 / 进度 / 联调发奖)
├── schemas/                 # Pydantic:API 收发的数据契约(与客户端对齐字段看这里)
│   ├── auth.py
│   ├── meituan.py
│   ├── welfare.py           # 钱包/签到/任务/省钱 收发模型
│   └── ad.py                # 看广告发奖收发模型
├── integrations/            # 外部服务/SDK 客户端(重逻辑:签名/加解密/外部 HTTP)
│   ├── jiguang.py           # 极光 REST 验 token + RSA 解密(多 padding 试错)
│   ├── meituan.py           # 美团 CPS 网关签名 + query_coupon / get_referral_link
│   ├── sms.py               # 短信验证码(mock,进程内存冷却表)
│   ├── pangle.py            # 穿山甲激励视频发奖回调验签(SHA256,2026-05 从 core 移入)
│   └── wxpay.py             # 微信支付 V3 商家转账(提现)+ code 换 openid(2026-05 从 core 移入)
├── core/                    # 基础设施(无外部业务集成)
│   ├── config.py            # pydantic-settings
│   ├── security.py          # JWT 签发/校验
│   ├── ratelimit.py         # 同 IP 滑动窗口限流依赖
│   ├── rewards.py           # 发奖/兑换/提现额度等业务常量与换算
│   └── logging.py
├── repositories/            # 数据访问 + 事务(早期叫 crud,2026-05 统一并入此目录)
│   ├── user.py              # get_user_by_id / get_user_by_phone / upsert_user_for_login
│   ├── wallet.py            # 账户/流水/兑换/提现单(调 integrations/wxpay)
│   ├── signin.py            # 签到记录 / 连续天数 / 档位
│   ├── task.py              # 一次性任务领取
│   ├── savings.py           # 省钱汇总 / 战绩 / 明细
│   └── ad_reward.py         # 看广告发奖(按 trans_id 幂等 + 每日上限)
├── models/                  # ORM 表结构
│   ├── user.py              # user(含微信 openid/nickname/avatar)
│   ├── wallet.py            # 金币账户 / 金币流水 / 现金流水 / 提现单
│   ├── signin.py            # 签到记录
│   ├── task.py              # 任务领取记录
│   ├── savings.py           # 省钱明细 / 店铺菜品
│   └── ad_reward.py         # 看广告发奖记录
└── db/
    ├── base.py              # DeclarativeBase
    └── session.py           # engine + get_db

alembic/                     # 数据库迁移(versions/ 9 个迁移;文件名已去 hex 前缀,链靠文件内 down_revision)
deploy/                      # systemd(.service) + nginx(.conf)
secrets/                     # 极光 RSA 私钥 / 微信支付证书(不入 git,仅 .gitkeep 占位)
scripts/                     # 运维脚本(migrate 迁移 / 对账 / 重置签到 / 重置福利 / 模拟穿山甲回调)
tests/                       # pytest(auth / health / welfare / withdraw / ad_reward / coupon_proxy)
run.sh                       # 本地启动脚本(自动先跑迁移再起服务)
docs/api/                    # API 接口文档(索引 README + 一接口一文件)
docs/integrations/           # 集成层实现文档(SDK 签名/加解密/协议细节)
docs/数据库迁移.md           # Alembic 迁移指南(如何建表/升级/新增迁移)
```

> **命名说明**:`api/v1/` 的 `v1` 用于 URL 版本化(移动端无法强制即时升级,需新旧版本并存能力);`integrations` 装外部 SDK 集成、`repositories` 装数据访问、`core` 装基础设施,三者分离。**数据访问层统一在 `repositories/`**(早期叫 `crud/`,2026-05 已整体并入,`crud/` 不再存在)。`coupon.py` 是领券透传,勿与 `meituan.py` 里的 `coupons`(券列表)混淆。

---

## 4. 登录链路

### 4.1 极光一键登录(主路径)

```
Android SDK loginAuth → 客户端拿到 loginToken
  → POST /api/v1/auth/jverify-login  { login_token, operator }
  → 后端 POST 极光 loginTokenVerify (Basic Auth = AppKey:MasterSecret)
  → 极光返回 RSA 公钥加密的手机号(base64)
  → 后端用配套私钥解密 → 明文手机号
  → upsert_user_for_login(phone 唯一) → 签 JWT → 返回 TokenWithUser
```

**RSA 解密**(`integrations/jiguang.py` 的 `_decrypt_phone`):极光文档未明示 padding,代码按 **OAEP-SHA1 → OAEP-SHA256 → PKCS1v15** 依次试,解出 11 位纯数字手机号即采用(PKCS1v15 对错误密文会"假成功"返回非 UTF-8 垃圾,据此跳过)。

**关键配置**(须与 Android 端一致):

| 项 | 值 |
|---|---|
| 包名 | `com.jishisongfu.shaguabijia` |
| 极光 AppKey | `966b451a8d9cfe12d173ea9d`(`JG_APP_KEY`) |
| RSA 公钥 | 极光控制台「加密公钥」(**1024-bit**,极光限制 ≤220 字符) |
| RSA 私钥 | `secrets/jverify_rsa_private.pem`(PKCS#8,不入 git,`JG_PRIVATE_KEY_PATH` 指定,懒加载) |

> **密钥对配对关系是关键**:极光用控制台上传的公钥加密,后端必须用**配对的私钥**解密。私钥不配对时 `jverify-login` 报 502 `all RSA paddings failed`(密钥不对,非 padding 问题);私钥文件缺失则报 502 `private key not found`。
> **2026-05-27 现状**:历史遗留的两套本地密钥均**不配对**当前 AppKey 公钥,已重新生成一对 1024-bit/PKCS#8 密钥,公钥需在极光控制台更新。⚠️ 该 AppKey 公钥为全局配置,若占坑版后端仍在用同一 AppKey,换公钥会使其旧私钥失效,需同步部署新私钥。

### 4.2 短信登录(mock 路径)

```
POST /api/v1/auth/sms/send   { phone }       → 60s 冷却,不真发(SMS_MOCK=true)
POST /api/v1/auth/sms/login  { phone, code } → 任意 6 位通过 → upsert → 签 JWT
```

短信冷却表存进程内存(`--workers 1` 下够用,多 worker/重启即失效)。

### 4.3 Token 与刷新

- access(2h)+ refresh(30d),HS256 自包含,payload 含 `sub`/`typ`/`iat`/`exp`,**无 session 表、无 jti 黑名单**。
- `refresh` 校验 token + 查库确认用户 active 后,签发**全新一对**。
- 客户端 OkHttp `Authenticator` 在 401 时自动调 `/refresh` 续期重放。
- `logout` 为占位(服务端不吊销 token)。

---

## 5. 美团 CPS

### 5.1 网关签名(`integrations/meituan.py` 的 `_sign` / `_call`)

类阿里云 S-Ca 网关签名,**stringToSign 只有 4 段**:`METHOD\n + Content-MD5\n + 排序后的 signed_headers + path`,**不含 Accept / Content-Type / Date 行**(加了签名失败)。头:`S-Ca-App`(=appkey)、`S-Ca-Timestamp`、`S-Ca-Signature`、`S-Ca-Signature-Headers`。配置项 `MT_CPS_APP_KEY` / `MT_CPS_APP_SECRET` / `MT_CPS_DEFAULT_SID`(默认 `sgbjia`)。

> 美团请求字段 `listTopiId`(少个 c)是官方拼写,非笔误。经纬度 `*1_000_000` 取整。

### 5.2 三个接口

- `query_coupon`:底层取数,被 `coupons` 路由和 `feed` 路由共用。
- `coupons` 路由:对外的搜索/榜单接口,**客户端暂未接入**。
- `feed` 路由:首页推荐流,每页并发拉外卖(platform=1)+ 到店(platform=2,到餐)各一次,按 **2 外卖 + 1 到店** 交叉去重(`_interleave`);榜单组合写死 3 页(`_TOPIC_ROUNDS`:爆款 / 今日必推 / 外卖精选+到店限时),第 3 页 `has_next=false`、第 4 页返空。
- `referral-link`:换推广链接,客户端取 `link_map["3"]`(deeplink)优先跳美团 App。

### 5.3 风险点

- **三接口无鉴权**:任何人可调,消耗你的美团 appkey 能力/配额。
- **`sid` 可被客户端覆盖**:他人可借接口刷自己渠道分佣,建议服务端锁定。
- **`feed` 静默吞异常**:`_fetch_topic` 对美团错误 `except 返回 []` 且不打日志,导致美团失败时 `feed` 返回"200 + 空 items"无声失败。排查时改用 `coupons`(它以 502 暴露错误)。

---

## 6. 领券透传(coupon/step)

产品"一键领券"的核心接入点,但**真正的领券逻辑不在本服务**——在另一个 repo `pricebot-backend`(GoalEngine + 事件驱动)。本服务只做"透传壳"。

```
客户端 → POST /api/v1/coupon/step  (任意 JSON body,含 device_id/trace_id/step)
  → coupon.py:不做 schema 校验,仅读 device_id/trace_id/step 打日志
  → async httpx 把 body 原样 POST 到 PRICEBOT_BASE_URL/api/coupon/step
  → 把 pricebot 的响应原样返回
```

- **MVP 不鉴权**:已去掉 `CurrentUser` 依赖。`device_id` 透传给 pricebot 区分设备,但后端拿不到 `user_id` → 领券行为暂时绑不到登录用户(采集不到用户级画像)。待补 JWT,见 `待办与技术债.md` P1。
- **不做 schema 校验**:body 原样透传,pricebot 自己校验。
- **错误**:body 非合法 JSON → 400;pricebot 不可达或返回 5xx → 502。
- **配置**:`PRICEBOT_BASE_URL`(默认 `http://localhost:8000`)、`PRICEBOT_REQUEST_TIMEOUT_SEC`(默认 30s,因领券单帧最多 wait 6s)。
- **现状**:**前端已接通**——首页「去领取」→ `CouponPromptDialog` → 权限检查 → 无障碍引擎 `startCouponClaim` → 循环调本接口,逐张券下发 launch/wait/done。pricebot-backend 不在本目录。

---

## 7. 数据模型

仅一张 `user` 表(`models/user.py`):

| 字段 | 类型 | 说明 |
|---|---|---|
| id | INTEGER PK | 自增 |
| phone | VARCHAR(20) UNIQUE | 登录主键,唯一索引 `ix_user_phone` |
| register_channel | VARCHAR(20) | `jverify` / `sms` |
| nickname | VARCHAR(64) NULL | 预留,**无接口可写,恒为 null** |
| avatar_url | VARCHAR(512) NULL | 同上 |
| status | VARCHAR(20) | `active` / `disabled` / `deleted`,仅 active 可登录/鉴权 |
| created_at / last_login_at | DATETIME(tz) | |

`upsert_user_for_login`:phone 存在则更新 `last_login_at`,不存在则注册(注册即登录)。Alembic 实际库里另有框架表 `alembic_version`。

---

## 8. 配置与部署

配置见 `core/config.py`(pydantic-settings 读 `.env`)。分组:环境、`DATABASE_URL`、JWT、极光(`JG_*`)、短信(`SMS_MOCK` 默认 true)、美团(`MT_CPS_*`)、**pricebot 上游(`PRICEBOT_BASE_URL` / `PRICEBOT_REQUEST_TIMEOUT_SEC`)**、CORS。

**生产部署**:systemd `shaguabijia-app-server.service`(WorkingDirectory `/opt/shaguabijia-app-server`,`EnvironmentFile=.env`,uvicorn 监听 `127.0.0.1:8770`,`--workers 1`)+ nginx 443 反代 → 8770。**无 Docker**。

```bash
rsync -avz --exclude='.venv' --exclude='__pycache__' --exclude='data' --exclude='secrets/*.pem' ./ server:/opt/shaguabijia-app-server/
scp secrets/jverify_rsa_private.pem server:/opt/shaguabijia-app-server/secrets/   # 私钥单独传,不入 git
ssh server "cd /opt/shaguabijia-app-server && .venv/bin/alembic upgrade head && systemctl restart shaguabijia-app-server"
```

**生产 checklist(均为上线必查)**:

- [ ] `JWT_SECRET_KEY` 改为高熵随机串——默认值 `change-me` 可被伪造 token
- [ ] `SMS_MOCK=false` 并接真实短信供应商——mock 下任意 6 位码可登录任意手机号
- [ ] `MT_CPS_APP_KEY` / `MT_CPS_APP_SECRET` 已填(否则美团接口 502)
- [ ] `PRICEBOT_BASE_URL` 指向真实 pricebot-backend(否则领券 502)
- [ ] RSA 私钥就位且与极光控制台公钥**配对**,权限 600
- [ ] `APP_ENV=prod`、`APP_DEBUG=false`、nginx SSL 有效、`alembic upgrade head` 已执行

---

## 9. 本地联调(真机)

```bash
conda activate price          # 首次:pip install -e .
./run.sh                       # 校验 .env → alembic 建表 → uvicorn 监听 0.0.0.0:8770
```

真机两种连法(详见前端文档):
- **adb reverse**(推荐):`adb reverse tcp:8770 tcp:8770`,前端 `debug.api.host=127.0.0.1`,USB 直连不依赖 WiFi。
- **局域网 IP**:前端 `debug.api.host=<开发机 LAN IP>`,手机电脑同 WiFi。

前端 debug 包对明文 HTTP 整体放行(`src/debug` 的 network_security_config),换 IP 只改 `local.properties`、无需改 xml。

---

## 10. 已知问题与后续

| 项 | 说明 |
|---|---|
| logout 无服务端失效 | 靠客户端清 token;后续加 jti 黑名单表 |
| 美团接口无鉴权 + sid 可覆盖 | 评估加鉴权/锁定 sid(注意首页要求未登录可见) |
| feed 静默吞异常 | 建议给 `_fetch_topic` 加日志,避免无声失败 |
| 领券依赖 pricebot | `coupon/step` 仅透传,真正逻辑在 pricebot-backend;前端已接通领券链路 |
| SMS 为 mock | 上线接真实供应商 + `SMS_MOCK=false` |
| 短信冷却存内存 | 扩 worker 前需迁移到 Redis |
| SQLite | 流量上来切 PostgreSQL,只改 `DATABASE_URL` |

> 完整接口协议(11 个)见 [`docs/api/`](./api/),以代码为准。