OuYingJun1024
c61997b876
- 新增 docs/数据库迁移.md: clone 后如何建表(alembic upgrade head)、日常升级、 新增迁移、迁移文件名 vs revision id 的关系与去前缀注意事项、当前 9 条迁移链 - 新增 scripts/migrate.sh: 只做迁移不启服务(部署/CI 用),run.sh 已自动包含 - 后端技术实现.md 目录树: crud 并入 repositories、alembic 文件名去 hex 说明、 补 docs/数据库迁移.md;接口层"调 repositories/integration"措辞同步 - README.md / docs/integrations 残留 crud 提法同步为 repositories Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2.2 KiB
2.2 KiB
穿山甲激励视频发奖回调 — 验签（pangle）
文件:
app/integrations/pangle.py| 关联接口:ad-pangle-callback | ← 集成索引
作用
穿山甲激励视频播完后，穿山甲服务器会 GET 回调我们的 /api/v1/ad/pangle-callback（带 user_id / trans_id / sign 等 query）。本模块负责验签，确认回调真来自穿山甲而非伪造请求；验签通过后由数据层（repositories/ad_reward）幂等发金币。客户端不参与发奖，被破解也刷不到钱。
验签方案（关键）
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。 - 这是穿山甲 GroMore「广告位 → 服务端激励回调」官方规范（supportcenter/26240）。我们客户端是
useMediation(true)融合，回调走 GroMore 广告位层级，不是联盟代码位层级。
函数
| 函数 | 说明 |
|---|---|
build_sign(trans_id, secret) -> str |
计算 SHA256("{secret}:{trans_id}") hex。自验签测试 / 模拟回调脚本共用，保证两端一致 |
verify_callback_sign(params, secret) -> bool |
校验回调签名。密钥空 / 缺 trans_id 一律失败；比较用 hmac.compare_digest 定长比较防时序侧信道 |
配置
| 配置项 | 说明 |
|---|---|
PANGLE_REWARD_SECRET |
m-key（安全密钥）。后台「GroMore 聚合管理 → 搜广告位 ID → 编辑」处获取 |
踩坑
- 别用联盟代码位那套：联盟代码位层级用的是另一套 Security Key +
isValid响应体，与 GroMore 广告位层级不通用。我们走 GroMore，别接错。 - 验签失败时 api 层返
403（留给真请求重试）；验签过但参数缺/坏或 user 不存在，则受理不发奖、不让穿山甲重试。 - 本地无公网、回调打不到时，用 ad-test-grant 模拟（仅联调，开关控制）。