72 lines
7.6 KiB
Markdown
72 lines
7.6 KiB
Markdown
# Coin Madness 真实接口接入
|
||
|
||
2026-09-20：按用户确认接入黄金矿工接口 V1.3。协议副本见 [GoldMiner-FRONTEND-API-v1.3.md](GoldMiner-FRONTEND-API-v1.3.md)。旧后端需求和 Word 策划确认单的冲突规则已作废。
|
||
|
||
## 运行方式与规则
|
||
|
||
- Creator 编辑器预览继续使用原本地模拟器，便于美术检查，不请求后端、不修改真实资产；模拟器仍保留原有自由领取测试行为，不作为正式顺序领奖验收依据。
|
||
- 微信开发版和体验版使用 `Utils.testHttpip`，正式版使用 `Utils.httpip`，与现有登录环境一致。交付和订单记录按环境、账号隔离。
|
||
- 真实入口根据 `info.status` 展示：可购买、暂停购买、已解锁时可见；未达资格或未开放时隐藏。尚有补发到账通知时保留入口。
|
||
- 付费前累计进度；任务目标为全期累计值；主线新关及无尽胜利按协议上报；失败、配置跳关、其他模式不附带活动胜利。
|
||
- 按后端 `claimStatus` 顺序领取，上一档确认到账后下一档才能领取。价格、目标、金币、商品、期次与时间均来自后端。
|
||
- 首次回首页、回到前台、每 30 秒在首页、打开活动、支付和领奖后刷新；倒计时归零刷新，网络失败时限制刷新频率。
|
||
|
||
## 代码入口
|
||
|
||
`assets/Script/coin_madness/GoldMinerService.ts` 为常驻协议服务，不引用活动 Bundle 的资源或组件。负责 JSON 请求、服务端时间偏移、状态转换、订单恢复、领奖交付记录、补发分页和事件记录。记录使用 `goldMiner:v1:<服务端地址>:<uid>` 命名空间写入本地存储。
|
||
|
||
`CoinMadnessHost.ts` 保留原首页入口、弹窗队列及 Bundle 生命周期，注入异步 request 给面板。保留“测试”和“活动测试”入口，仅微信开发版/体验版连接独立测试服时显示。旧 mock 已移除。现有预制体布局及领奖动画保留。只在确认补发到账后展示补发通知，关闭通知后清除本地展示记录。
|
||
|
||
`GameTool.addLevel` 在现有胜利保存调用上附带活动事件。`Utils.setUserLevel` 仅在附带事件时切换 JSON，主线省略 `isWuXian`，无尽传字符串 `"true"`。读取 `data.goldMiner.code` 时不把活动失败当成普通关卡失败，不重复推进关卡。
|
||
|
||
跨期或尚未取得可用 info 时，事件期次按协议约定的北京时间周四日历生成；有有效 info 时优先使用其期次和服务端时间偏移。最终是否计入始终由后端判断。事件 ID、关号或无尽序号在发请求前持久化；无尽序号使用毫秒时间加随机尾数并维持本地单调递增，可降低跨设备冲突概率，但不提供服务端全局序号保证。
|
||
|
||
`Utils.POSTJSON` 为新增 JSON 通道，不改变其他旧接口的表单格式。`Utils.withCoinSave` 将活动金币保存和现有 `setUserCoin` 上传串行化；普通上传在执行时读取最新余额，避免队列里残留旧余额覆盖奖励。
|
||
|
||
## 支付和交付
|
||
|
||
支付沿用现有项目选择：iOS 且 `iosCanPay` 为 false 时使用后端 create_order 返回的签名 sessionFrom 打开客服；其他情况调用对应原生下单入口并传原样签名到 requestMidasPaymentGameItem。不复用旧 GoKEFu 拼接订单方式。
|
||
|
||
iOS 原生支付明确返回错误码 16（且非取消）时，会重新校验活动并请求一次 `legacy_ios` 订单，拿到后端签名票据后自动打开客服会话。其他错误码、结果超时和 Android 不触发回退，客服失败也不会循环重试。客服订单后续仍通过 `wx/iosgetPayInfo` 确认活动权益，不直接发金币。
|
||
|
||
后端兼容条件：V1.3 文档规定已有原生订单时禁止切换渠道（`PAYMENT_CHANNEL_CONFLICT`）。如果部署端仍实行这一限制，前端只能提示服务端不允许切换，并保留原订单供恢复查询；后端需要安全核验原生订单未支付后支持切换，才能完成错误码 16 的客服回退。仓库未提供该活动支付后端实现，需测试服联调确认。回归脚本：`node tools/coin-madness/check-ios-payment-fallback.cjs`。
|
||
|
||
活动订单独立持久化，不覆盖商城全局订单。创建请求重试复用 createRequestId，有订单先查原订单，不自行切换渠道。只有服务端确认 pay_state=2、rewardDelivery=goldMiner.claim 后才认为权益已确认。有限次退避查单，关闭面板或切后台停止高频轮询，之后恢复查询。支付本身不加金币。
|
||
|
||
每档交付顺序：
|
||
|
||
1. 持久化领取请求标识，调用 claim，保存 grantId、奖励和阶段。
|
||
2. 通过金币保存队列增加本地金币并上传总余额，记录为 saved。
|
||
3. 调用 confirm_delivery，成功后记录 confirmed 并刷新任务。
|
||
|
||
重复领取、确认失败重试、关面板后重新打开均复用同一记录。saved 阶段只重试确认，confirmed 不重复加币。未知道具不发放也不确认。
|
||
|
||
补发独立于本期是否开放：持续翻页直到 nextCursor=null，即使中间 items 为空；按旧期次及 taskIds 顺序走相同交付流程，最后 ack_settlement。itemsSummary 只作信息，绝不直接作为额外金币发放。
|
||
|
||
## 已知协议限制
|
||
|
||
- 金币总余额保存和确认领取仍不是服务端事务，客户端不能保证重装／多设备下严格只到账一次。本地保存结果未知时保留 saving 阶段并停止再次加币或确认，提示联系客服核对。发现当期 issuing 且本地无交付记录时同样停止盲目重发。
|
||
- 往期补发没有逐档 issuing 状态可供预先读取，重装后丢失记录的情形仍受后端协议限制；依赖后端幂等入账才能彻底解决。
|
||
- 旧 userLevel/save 整体不幂等。失败或结果不明的事件留存本地供核对，不在重登时无限重放整个关卡保存，避免重复累加无尽生涯统计。离线胜利及截止后的新事件不承诺补计。
|
||
- 金币队列只能约束当前客户端经过 setUserCoin 的上传，不能防止其他设备或其他直接修改钱包的后端接口覆盖余额。
|
||
- 本次未更换说明页图片。正式上线前需人工核对图片中的规则文案与 V1.3 一致，并确认正式价格、任务、奖励、活动日历与门槛配置。
|
||
|
||
## 验证
|
||
|
||
测试服提供白色小字“活动测试”入口，可查看实际接口网址、请求响应、使用值和活动本地记录，并进行查询、恢复和有保护的缓存清理。UI 位于 `assets/coin_madness/test`，具体操作见 [测试面板说明](../assets/coin_madness/test/README.md)。
|
||
|
||
```text
|
||
node tools/coin-madness/check-api.cjs
|
||
node tools/coin-madness/check-game-test.cjs
|
||
node tools/coin-madness/check-types.cjs
|
||
node tools/coin-madness/preview.cjs
|
||
node tools/coin-madness/check-preview.cjs
|
||
node tools/coin-madness/check-api-preview.cjs
|
||
```
|
||
|
||
浏览器检查需 Playwright 和 Edge，可通过 PLAYWRIGHT_MODULE 指向已安装模块，PORT 指向预览端口。协议测试使用内存服务端，界面检查使用真实 Cocos 预制体和异步模拟响应，均不触发真实支付。类型检查与 HEAD 基线比较；当前仓库已有诊断不等于本次新增问题。Utils 旧抽卡方法名含 U+200C，独立 TypeScript 转译有既有解析问题，因此协议测试仅加载该方法前的真实网络／金币模块部分。
|
||
|
||
测试服仍需联调：确认 V1.3 已部署（尤其 iosorderPaySig）、微信请求域名配置、有效登录、两个支付渠道、到期补发、跨期支付路线、真机杀进程恢复及金币 UI 同步。原生签名 env=0 可能真实扣费，本地自动化未发起支付。
|
||
|
||
日常界面调整以 Creator 预制体为准。一次性历史布局生成器已移除。
|