# 黄金矿工当前接入与交接说明

核对日期：2026-09-30；客户端 `7e14f661`，仓库后端协议 V1.7。[文档入口](CoinMadness前端开发说明.md) · [实现说明](../assets/coin_madness/README.md) · [后端协议](../server/laf-cloud/functions/goldMiner/FRONTEND-API.md)

## 环境与运行

- GoldMinerService 要求非 CC_PREVIEW 且存在 wx；普通 Creator 预览不会启动真实服务，也没有旧版首页模拟器。
- 开发版/体验版走 Utils.testHttpip，其他版本走 Utils.httpip。合入 main 后两者当前相同，独立测试环境未由此配置隔离。
- `tools/coin-madness/preview.cjs` 是独立界面夹具，使用预制体和模拟响应，不登录、不支付；需要 Creator 2.4.15 引擎和导入资源，不是游戏内测试入口。
- 游戏测试包、活动测试面板及诊断面板 API 已删除，正式恢复流程与支付控制台日志保留。

## 已实现

- 首页提前读取首份 info，之后继续日程、订单、奖励与补发恢复；并发完整刷新复用 Promise。
- 首页启动、回前台、打开面板、期次时间边界触发同步；没有每 30 秒全量轮询，0.5 秒入口检查主要是本地计算。
- 通关优先取公共日程有效期，回退到有效 info；没有有效期就不附带活动事件，不自行拼周四期号。
- 价格、商品和任务来自 info；前端不自行选择 VIP。任务行可扩展，未付费可累计；购买仅解锁权益。
- 普通领奖：claim → 保存金币总余额 → confirm_delivery → info。保存成功即启动动画，不等最后一次 info。
- 补发使用 settlements 的 rewards 授权，保存后 confirm_settlement_delivery，不调用过期 claim 或 ack_settlement。
- 账本键为 `goldMiner:v1:<服务端地址>:<uid>`。saved 只补确认，saving/uncertain 不直接重复加币。总余额保存和确认不是同一事务，多设备/重装仍有协议限制。
- 客服支付复用 Utils.GoKEFu，具体见[支付约定](CoinMadness支付联调当前约定.md)。

## 与 V1.7 待对齐

| 项目 | 当前客户端 | 最新协议及差异 |
| --- | --- | --- |
| 客服支付 | GoKEFu 本地生成订单并打开客服 | 协议采用 create_order 返回签名 sessionFrom；需确定部署端实际链路 |
| 再次购买 | 新 createRequestId，本地替换该期订单 | 后端有每玩家每期订单复用与渠道限制；新请求不保证新服务器订单 |
| iOS 错误码 16 | 回退 GoKEFu | 需验证订单关联、渠道限制和权益归属，会话打开不代表支付成功 |
| 补发分页 | 发送 limit=100；遇 settling 保留游标并立即退出 | V1.7 后端控制页大小，settling 有 nextCursor 也应继续，避免阻塞其他期 |
| 补发结束 | 空 items 且无 nextCursor 即结束，能处理 no_pending_rewards 的空结果 | 未将 no_pending_rewards 单独作为全部扫描完成判据 |
| 领取按钮 | 按解锁、累计次数、未领取和未到期判断，并防重复请求/动画 | V1.7 要求由 claimStatus 驱动；目前只直接将 claimed 视为已领，其他状态未完整区分 |
| VIP / pending_unlock | 使用返回价格和 tasks，未付费达标提示解锁 | 无独立 VIP 展示或 pending_unlock 分支；需验证六档十任务、报价变化和超出 maxTarget 的进度 |

仓库已有 [goldMiner 后端](../server/laf-cloud/functions/goldMiner/README.md)、[公共日程](../server/laf-cloud/functions/activityConfig/README.md) 和 Postman 集合；代码存在不证明线上版本一致。本次只修正文档，没有变更协议或客户端。

## 验证状态

2026-09-30 合并后通过的离线检查：

```text
node tools/coin-madness/check-api.cjs
node tools/coin-madness/check-home-entry-ready.cjs
node tools/coin-madness/check-popup-queue.cjs
```

清理时 check-first-display.cjs 也已通过。其余脚本按变更选择运行，存在不等于通过。

- 上次 check-types.cjs 报 Utils.ts 的 wx 声明诊断；它比较工作区与 HEAD，提交后基线变化，无新增不代表零错误。
- 上次 check-release-ui.cjs 的装饰器夹具无法构造组件；临时修正后还有解锁断言失败，修改已撤回，该检查待维护。
- 真机待验收：实际环境、Android/iOS 支付与客服回退、取消重试、跨期权益、VIP 十任务和任意达标档领取、补发跨页、断网重启、顶部金币同步。
- 本次文档核对未请求线上接口、支付或修改玩家资产。手工操作见 [Postman 指南](黄金矿工-Postman操作指南.md)。