OuYingJun1024
9a2599bc3a
- README.md 翻新: 从 v0.1.0 登录模块版更新到当前(钱包/提现/签到/省钱/看广告/CPS); 目录结构按现状重写(integrations 含 pangle/wxpay、repositories 含全部数据访问、 core 含 ratelimit/rewards);API 改为按组速览 + 链 docs/api;建表步骤改为 alembic upgrade head(原步骤是过时的 autogenerate init);部署补微信支付证书同步 - docs/ad_reward_golive_checklist.md → docs/看广告赚金币上线清单.md(改中文名) - docs/README.md 文档库导航补 integrations/ + 数据库迁移.md + 看广告上线清单 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
5.8 KiB
5.8 KiB
「看广告赚金币」上线 Checklist
跨两个仓库:
shaguabijia-app-server(后端发奖)+shaguabijia-app-android(客户端看广告)。 截至 2026-05-26:本地 + debug 包已端到端验证通过(出广告 → 发奖 → 金币到账 → 明细显示「看广告奖励」), 但尚未在生产上线。本文件记录上线前必须做的事,尤其是一堆"仅本地/debug 用、上线前必须清理"的脚手架。
设计要点(别改坏)
- 发奖只走服务端:激励视频播完,穿山甲服务器 S2S 回调后端
/api/v1/ad/pangle-callback发金币。 客户端不发奖,onRewardArrived只触发"去后端刷余额"。客户端被破解也刷不到钱。 - 后端发奖幂等(按
trans_id去重)+ 每日上限(DAILY_AD_REWARD_LIMIT,按北京时间)。 - 关键常量:
app/core/rewards.py→AD_REWARD_COIN=100、DAILY_AD_REWARD_LIMIT=10(占位值,上线前按 eCPM 实测收益重定)。
A. ⚠️ 上线前必须清理的"测试/调试专用"脚手架
这些是为了"没部署公网也能本地验证"加的,带到生产 = 体验差 / 绕过反作弊 / 引入废弃工具,务必清理。
A1. 后端:本地模拟发奖接口
.env删除 / 设为 false:AD_REWARD_TEST_GRANT_ENABLED=false(默认就是 false;它一开,已登录客户端就能自助发奖)- (可选)确认生产
.env没这行;/api/v1/ad/test-grant在 false 时返回 404 - 涉及:
app/api/v1/ad.py的test_grant、app/core/config.py的AD_REWARD_TEST_GRANT_ENABLED
A2. 客户端:test-grant 调用
WelfareViewModel.onAdRewardEarned()里if (BuildConfig.DEBUG) { repo.adTestGrant() }—— release 包(BuildConfig.DEBUG=false)本就跳过,确认 release 构建不含该调用即可(结构上已隔离,无需改码;打 release 包验一次)- 涉及:
WelfareViewModel.kt、WelfareRepository.adTestGrant()、WelfareApi.adTestGrant、TestGrantDto(留着无害,只要 release 不调用 + 后端 404)
A3. 客户端:穿山甲测试工具(广告预览)
app/build.gradle.kts:移除debugImplementation(files("libs/tools-release.aar"))- 删除
app/libs/tools-release.aar gradle.properties:移除android.enableJetifier=true(仅为兼容 tools-release.aar 的旧 support 库而开,Jetifier 已废弃)- 删除
app/src/debug/.../ad/TestToolLauncher.kt+app/src/release/.../ad/TestToolLauncher.kt(空桩) WelfareScreen.kt:移除「【调试】唤起穿山甲测试工具」入口(if (BuildConfig.DEBUG){...}那段)+TestToolLauncherimport- 注:这些都 debug-only,不影响 release 功能;清掉是为了不留废弃依赖
B. 生产真正发奖链路(S2S)—— 阻塞于穿山甲后台
已确认走 GroMore 广告位层级回调(客户端 useMediation(true);规范 supportcenter/26240), 不是联盟代码位层级(5416)。验签算法 / 响应格式 / reward_amount 解析代码已按 GroMore 规范实现 (2026-05-27),剩下的是后台配置 + 填密钥。
- GroMore 后台配回调:GroMore 聚合管理 → 搜广告位ID → 编辑 → 勾选「服务端激励回调」→
回调 URL 填
https://app-api.shaguabijia.com/api/v1/ad/pangle-callback(用域名,别用 IP)。 ⚠️ 广告位层级配了就别再在代码位层级重复配(会导致发奖出问题)。 - 拿 m-key(安全密钥):就在上面"编辑广告位"页获取,填到生产
.env的PANGLE_REWARD_SECRET。 (注:这是 GroMore 广告位的 m-key,不是联盟代码位那个 Security Key。) 换验签:app/integrations/pangle.py已实现sign = SHA256("{m-key}:{trans_id}")(GroMore 真实算法)。响应格式:已返回 GroMore 要求的{"is_verify": bool, "reason": int}。reward_amount:回调按reward_amount发金币(rewards.resolve_ad_reward_coin,带回退/夹紧); 后台广告位"奖励数量"须配成与AD_REWARD_COIN(=100)一致,保证"广告内展示/进度预告/到账"三者一致。透传 user_id:客户端已setUserID(userId)+setMediaExtra("uid:...")。- 生产
.env:PANGLE_CALLBACK_ENABLED=true+PANGLE_REWARD_SECRET=<m-key>(配齐才不返 503)
C. 部署 + 包名
- 后端部署到公网(由服务器管理员;
/opt/shaguabijia-app-server,uvicorn 127.0.0.1:8770,nginx 反代) - 跑迁移:
alembic upgrade head(建ad_reward_record表,迁移c8d9e0f1a2b3) - 包名定稿:当前
com.jishisongfu.shaguabijia。穿山甲(APP_ID 5830519)、极光、微信都绑"包名 + 签名",定了再上,别再换- 微信提现链路当前因复用 elderhelper 的 appid + 包名切换已 dead,要恢复需申请傻瓜比价自己的微信 appid(另见客户端 build.gradle 注释)
- (可选,提升真实填充)集成 MSA OAID SDK:申请证书(绑包名、审核几天)。App 侧当前
getDevOaid=null,有 OAID 后投放匹配 + 填充会明显改善
D. 提现对账(顺带,与本功能独立但同属上线必做)
- 生产给
scripts/reconcile_withdraws.py挂 cron / systemd timer(每 5~10 分钟跑一次)- 否则"扣款后微信无回调"的孤儿提现单没人兜底退款(客户端已加 ON_RESUME 无条件查单,但 cron 是最后防线)
E. 端到端验收(生产链路通后)
- 真机看完一条真实激励视频 → 穿山甲 S2S 回调 → 后端发奖 → 客户端余额真到账
- 幂等:同一
trans_id不重复发 - 每日上限:超过
DAILY_AD_REWARD_LIMIT返回 capped、不发币、按钮显示「已达上限」 - 中途退出广告 → 客户端提示「未看完视频，本次没有奖励哦」,且不发奖
- 收益明细显示「看广告奖励」(biz_type=
ad_reward)
关键阻塞链
B(拿验签方案/配回调)→ E(端到端验收);A(清理)可随时做;C(部署)与 B 并行。