guke
37fd51a498
背景 / 目标
客户端埋点从「采集」到「上报落库」全链路存在丢失(采集端丢帧、网络丢包、上报失败),现有 analytics_event(行为事件)无法度量这条链路的健康度。本 MR 引入一条与行为埋点完全独立的自报计数(selfstat)链路:客户端周期上报「自 epoch 起算的累计计数」,服务端只 append 存原始快照,admin 查询时在 Python 侧差分聚合出两段成功率(埋点成功率 / 上报成功率),支持总览 / 按天趋势 / 按维度下钻。
改动概览
① App 侧 — 上报接入(不强制登录)
新增 POST /api/v1/analytics/selfstat:一份快照 = 设备头 + N 条 event 累计计数,单事务落库,返回 snapshot_id。
稳态兜底:落库异常不裸奔 500,logger.exception 后回 503(计数链路要稳,不阻塞端上主流程)。
events 允许空列表(某次只报设备级计数也合法),上限 200 条/次;与行为埋点 min_length=1 有意不同。
② Admin 侧 — 健康度聚合(只读,需 admin 鉴权)
新增 GET /admin/api/analytics-health/{overview,trend,breakdown}。
差分聚合:原始累计快照按 (device_id, epoch_id, event) 分区、created_at 升序做相邻差分;分区首行增量=累计值,负值(epoch 重置 / 乱序)夹 0;每条增量按其快照 created_at 归入北京天桶。
基线行:取 date_from 左侧每分区最后一条快照,保证区间第一条增量正确(参与差分后丢弃)。
两段率(分母为 0 → null):
埋点成功率 track_success_rate = (attempted − drop_capture) / attempted
上报成功率 report_success_rate = delivered / (delivered + drop_undelivered)
breakdown 维度限 event | app_ver | oem(路由正则校验);结果按上报成功率升序(最差在前,None 垫底)。
③ 数据模型 / 基建
新表 analytics_selfstat(快照头 + 设备维度 app_ver/oem/os + 设备级诊断量 batches_attempted/ok/fail、retries、queue_depth、端 sent_at + 服务端权威 created_at)与 analytics_selfstat_event(四类累计计数,FK → 快照头)。
Alembic 迁移 11c44afbea58(down_revision admin_user_plain_password):建两表 + 索引。
模型登记进 app/models/__init__.py(供 Alembic 发现);路由挂进 app/admin/main.py。
关键设计取舍
只存原始累计、查询时 Python 差分:admin 低频、量级小,跨 PG/SQLite 无方言坑(与 cps.py/coupon_data.py 同款约定)。
选「最新一条」用 max(id) 而非 max(created_at):id 严格单调,规避 SQLite 秒级时间戳撞车的歧义。
tz 口径统一:SQLite 返回 naive UTC、PG 返回 aware UTC,过滤前统一转 naive UTC 再比较。
基线子查询无下界:扫 date_from 左侧全量(spec §7 已接受的取舍;量级变大再上物化 rollup)。
测试(+14,全绿)
tests/test_analytics_selfstat.py(3):正常落库 / 空 events / 落库异常回 503。
tests/test_analytics_health.py(11):差分逻辑(首行=累计值、相邻差、epoch 重置换分区、乱序夹 0、同时间戳按 id 定序)、两段率公式、零分母→None、北京天边界、端点(overview 鉴权 / overview / breakdown)。
迁移 / 部署注意
部署需执行 alembic upgrade head(建两张新表)。纯新增表,无回填、无破坏性改动,向后兼容。
客户端需按约定 payload(snake_case、累计语义)对接 /api/v1/analytics/selfstat;admin 前端(独立仓 shaguabijia-admin-web)消费三个 analytics-health 端点,不在本 MR 范围。
---------
Co-authored-by: guke <guke@autohome.com.cn>
Reviewed-on: #127
shaguabijia-app-server
傻瓜比价正式 App 后端 — FastAPI + SQLAlchemy + JWT。
覆盖:账号体系(极光一键登录 / 短信登录 + JWT)、福利钱包(金币 / 现金 / 签到 / 任务 / 省钱战绩)、微信提现(商家转账到零钱)、看广告发奖(穿山甲 GroMore S2S 回调)、美团 CPS(领券透传 / 比价推荐)。
占坑期的试验后台
shaguabijia-server是无状态 mock;本项目是正式版,引入账号体系、JWT 登录态、Alembic 迁移,SQLite 起步可平滑切 PostgreSQL。
文档导航(都在 docs/):
- docs/api/ — 接口契约(索引 + 一接口一文件)
- docs/integrations/ — 集成层(SDK 签名 / 加解密 / 协议细节)
- docs/后端技术实现.md — 架构与链路(分层、登录、CPS、数据模型)
- docs/数据库迁移.md — 数据库迁移(Alembic 怎么建表 / 升级)
技术栈
| 维度 | 选型 | 说明 |
|---|---|---|
| 语言 | Python 3.11+ | |
| Web | FastAPI 0.115+ | |
| ASGI | uvicorn[standard] | |
| ORM | SQLAlchemy 2.0 | Mapped / DeclarativeBase 新风格 |
| 迁移 | Alembic | render_as_batch 兼容 SQLite |
| DB | SQLite 起步 | 切 PostgreSQL 只改 DATABASE_URL |
| Auth | JWT (PyJWT) | access(2h) + refresh(30d) |
| 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 入口:注册全部 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)
│ │ ├── security.py JWT 签发 / 校验 / token 对
│ │ ├── 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/ 数据库迁移(versions/ 9 个迁移;文件名已去 hex 前缀,链靠文件内 down_revision)
├── alembic.ini
├── 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
API 接口
完整契约见 docs/api/README.md(总览表 + 一接口一文件)。按组速览:
| 组 | 前缀 | 端点数 | 鉴权 |
|---|---|---|---|
| 健康检查 | /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 | 无 |
登录类接口响应统一是 TokenWithUser(access/refresh token 对 + user);金额字段一律以分为单位(*_cents)。APP_ENV 非 prod 时开 http://localhost:8770/docs(Swagger UI)。
本地开发
1. 装依赖
cd shaguabijia-app-server
python3.11 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
2. 配置
cp .env.example .env
# 至少改 JWT_SECRET_KEY;测美团填 MT_CPS_*;测提现填 WXPAY_*/WECHAT_*;测看广告填 PANGLE_*
测极光一键登录把 RSA 私钥放到 ./secrets/jverify_rsa_private.pem(没放也不影响其他接口,只是 jverify-login 返 502)。
3. 建表 / 升级数据库
mkdir -p data # SQLite 库目录
alembic upgrade head # 按迁移链建到最新(幂等)
详见 docs/数据库迁移.md。只想迁移不启服务:
bash scripts/migrate.sh。
4. 跑起来
./run.sh # 监听 0.0.0.0:8770,自动先跑迁移;改代码自动重启
# 或手动: uvicorn app.main:app --reload --port 8770
冒烟:
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"}'
curl http://localhost:8770/api/v1/auth/me -H "Authorization: Bearer <access_token>"
5. 测试
pytest -q
部署(生产)
部署到 app-api.shaguabijia.com(参考 deploy/):
# 后续更新
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 "
cd /opt/shaguabijia-app-server &&
.venv/bin/pip install --quiet -e . &&
.venv/bin/alembic upgrade head &&
systemctl restart shaguabijia-app-server
"
详见 deploy/。看广告发奖上线前对照 docs/看广告赚金币上线清单.md(GroMore 回调配置、清理调试脚手架、端到端验收)。
与试验后台的差异(为什么不直接复用 shaguabijia-server)
| 维度 | 试验后台 (shaguabijia-server) | 本项目 (shaguabijia-app-server) |
|---|---|---|
| 数据库 | stdlib sqlite3,无 ORM | SQLAlchemy 2.0 + Alembic |
| 业务 | mock parse(无账号体系) | 账号 + 钱包 / 提现 / 签到 / 看广告 / CPS |
| 登录态 | 无,客户端发 phone 当 ID | JWT access + refresh |
| 配置 | 硬编码 | pydantic-settings + .env |
| 域名 | api.shaguabijia.com(试验) | app-api.shaguabijia.com(正式) |
极光一键登录的实现(REST 调用、RSA padding 试错顺序)参考自试验后台,逻辑等价。