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

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

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

---

1. 这个后端是干什么的

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

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

本服务自身没有"比价"实现——名字叫比价,实质是:登录态 + 美团券聚合分佣 + 给真正的领券/比价核心(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(外部) / repositories(数据) → models / db。

app/
├── main.py                  # FastAPI 入口:注册 3 个 router、CORS、/health、lifespan
├── api/
│   ├── deps.py              # 共享依赖:get_current_user(鉴权)、get_db(注入 session)
│   └── v1/
│       ├── auth.py          # 登录 6 个端点
│       ├── coupon.py        # 领券透传 /coupon/step(转发 pricebot,唯一需鉴权的业务接口)
│       └── meituan.py       # 美团 3 个端点 + feed 拼接逻辑(_interleave / _TOPIC_ROUNDS)
├── schemas/                 # Pydantic:API 收发的数据契约(与客户端对齐字段看这里)
│   ├── auth.py
│   └── meituan.py
├── integrations/            # 外部服务客户端(2026-05 从 core 拆出)
│   ├── jiguang.py           # 极光 REST 验 token + RSA 解密(多 padding 试错)
│   ├── meituan.py           # 美团 CPS 网关签名 + query_coupon / get_referral_link
│   └── sms.py               # 短信验证码(mock,进程内存冷却表)
├── core/                    # 基础设施(仅保留)
│   ├── config.py            # pydantic-settings
│   ├── security.py          # JWT 签发/校验
│   └── logging.py
├── repositories/            # 数据访问(2026-05 由 crud 改名)
│   └── user.py              # get_user_by_id / get_user_by_phone / upsert_user_for_login
├── models/user.py           # ORM:user 表结构
└── db/
    ├── base.py              # DeclarativeBase
    └── session.py           # engine + get_db

alembic/                     # 数据库迁移(versions/ 目前仅 init_user_table)
deploy/                      # systemd(.service) + nginx(.conf)
secrets/                     # 极光 RSA 私钥(不入 git,仅 .gitkeep 占位)
tests/                       # pytest(conftest + test_auth + test_health)
run.sh                       # 本地启动脚本
docs/api/                    # API 接口文档(索引 README + 一接口一文件)

命名说明:api/v1/ 的 v1 用于 URL 版本化(移动端无法强制即时升级,需新旧版本并存能力);integrations 装外部集成、repositories 装数据访问,与 core(基础设施)分离。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  (Bearer access_token + 任意 JSON body)
  → coupon.py:get_current_user 校验 JWT(唯一需鉴权的业务接口)
  → async httpx 把 body 原样 POST 到 PRICEBOT_BASE_URL/api/coupon/step
  → 把 pricebot 的响应原样返回

• 不做 schema 校验:body 原样透传,pricebot 自己校验(后端仅读 trace_id/step 打日志)。
• 错误:body 非合法 JSON → 400;pricebot 不可达或返回 5xx → 502。
• 配置:PRICEBOT_BASE_URL(默认 http://localhost:8000)、PRICEBOT_REQUEST_TIMEOUT_SEC(默认 30s,因领券单帧最多 wait 6s)。
• 现状:接口已挂载可用,但前端 ComparingScreen 仍是动画 demo、尚未对接此接口;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。

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. 本地联调(真机)

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/,以代码为准。