yangzhao/MatchMaster
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: align Gold Miner documentation with current client and V1.7 gaps

Browse Source
This commit is contained in:
keke 2026-09-30 20:05:20 +08:00
parent 7e14f66170
commit 490cc0b1da
10 changed files with 147 additions and 141 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
assets/coin_madness/README.md
View File

@ -1,6 +1,8 @@
# CoinMadness（黄金矿工）活动前端说明 # CoinMadness（黄金矿工）活动前端说明
更新日期：2026-09-23。本文描述当前客户端实际实现；后续修改接口或流程时，请同步更新本文。请求示例省略真实账号和 token。 核对日期：2026-09-30，客户端基准 `7e14f661`。本文描述实际实现，不代表完整兼容仓库后端 V1.7 或已完成线上验收。[文档入口](../../docs/CoinMadness前端开发说明.md) · [接入差异与验证状态](../../docs/GoldMiner接入说明.md)。请求示例省略真实账号和 token。
活动预制体、图片和面板脚本在 coin_madness 分包；Host、GoldMinerService、BrownLoadingSpinner 在主包侧，入口图在 resources。游戏测试包、活动测试面板及演示场景已移除。普通 Creator 预览不启动真实活动；独立预览夹具仍在 tools/coin-madness。
## 1. 代码分工 ## 1. 代码分工
@ -32,6 +34,8 @@ CoinMadnessPanel（用户操作）
活动请求使用 POST JSON。Utils.serverUrl 根据微信版本选择服务器：开发版/体验版使用 testHttpip，其余使用 httpip。具体地址以 Utils.ts 为准，不在本文重复硬编码。 活动请求使用 POST JSON。Utils.serverUrl 根据微信版本选择服务器：开发版/体验版使用 testHttpip，其余使用 httpip。具体地址以 Utils.ts 为准，不在本文重复硬编码。
当前两个地址相同：合入 main 后，开发版/体验版也会请求同一正式服。账本隔离依据实际 URL 和 uid，不依据版本名称。
GoldMinerService.post 为认证请求补充 uid；Utils.POSTJSON 补充 token。activityConfig/list 使用非认证请求。 GoldMinerService.post 为认证请求补充 uid；Utils.POSTJSON 补充 token。activityConfig/list 使用非认证请求。
共涉及 8 个主要后端地址。goldMiner/index 是同一个地址，通过 action 区分业务。 共涉及 8 个主要后端地址。goldMiner/index 是同一个地址，通过 action 区分业务。
@ -44,7 +48,6 @@ GoldMinerService.post 为认证请求补充 uid；Utils.POSTJSON 补充 token。
| goldMiner/index | confirm_delivery | 确认普通奖励已保存到账 | GoldMinerService.deliver | | goldMiner/index | confirm_delivery | 确认普通奖励已保存到账 | GoldMinerService.deliver |
| goldMiner/index | settlements | 查询往期补发清单 | GoldMinerService.settle | | goldMiner/index | settlements | 查询往期补发清单 | GoldMinerService.settle |
| goldMiner/index | confirm_settlement_delivery | 确认补发奖励已保存到账 | GoldMinerService.deliver | | goldMiner/index | confirm_settlement_delivery | 确认补发奖励已保存到账 | GoldMinerService.deliver |
| goldMiner/index | create_order | 旧版 iOS 客服支付下单 | GoldMinerService.purchase |
| userLevel | save | 保存关卡，并携带 goldMiner 胜利事件 | Utils.setUserLevel | | userLevel | save | 保存关卡，并携带 goldMiner 胜利事件 | Utils.setUserLevel |
| userCoin | save | 保存领取/补发后的金币总余额 | GoldMinerService.deliver | | userCoin | save | 保存领取/补发后的金币总余额 | GoldMinerService.deliver |
| wx/orderPaySig | 无 | Android 原生支付下单，返回支付参数 | GoldMinerService.purchase | | wx/orderPaySig | 无 | Android 原生支付下单，返回支付参数 | GoldMinerService.purchase |
@ -101,9 +104,9 @@ offset = serverTime - Date.now()
到期时活动面板退出：已有到账通知则切换结算窗口；否则关闭并触发同步，补发处理成功后再展示通知。 到期时活动面板退出：已有到账通知则切换结算窗口；否则关闭并触发同步，补发处理成功后再展示通知。
settlements 返回 settling 或补发请求失败会设置重试标记。Host 使用 5、15、30 秒的间隔，最多追加 3 次重试。未完成订单查单失败也可能让完整刷新进入重试。 settlements 返回 settling、补发失败或查单失败会设置重试标记。Host 的重试间隔依次为 2、3、5、7、10、15、25、30、50 秒，当前计数未重置时最多追加 9 次。回前台等 resumeSync 会重置计数。
因此单次触发正常查询一次、需重试时通常最多四轮；这不是整个会话总上限：重新进入首页、回前台、测试操作、其他到期触发都可能增加请求。分页时每页各请求一次。 恢复标记触发 retryRecovery，只查未完成订单与补发；订单有变化或通知金额改变时才读取 info，不重读日程或重放普通领奖。完整同步抛错则重试完整 refresh。重新进入首页、回前台或期次边界可触发新一轮；重试次数不是整个会话的总请求上限。
已知边界： 已知边界：
@ -163,11 +166,11 @@ Panel.run('purchase')
| --- | --- | --- | --- | | --- | --- | --- | --- |
| Android 原生 | wx/orderPaySig | wx.requestMidasPaymentGameItem | wx/getPayInfo | | Android 原生 | wx/orderPaySig | wx.requestMidasPaymentGameItem | wx/getPayInfo |
| iOS 原生 | wx/iosorderPaySig | wx.requestMidasPaymentGameItem | wx/iosgetPayInfo | | iOS 原生 | wx/iosorderPaySig | wx.requestMidasPaymentGameItem | wx/iosgetPayInfo |
| 旧版 iOS 客服 | goldMiner/index，create_order | wx.openCustomerServiceConversation | wx/iosgetPayInfo | | 当前 iOS 客服 | Utils.GoKEFu 本地生成订单及会话参数 | wx.openCustomerServiceConversation | wx/iosgetPayInfo |
微信支付 API 与 wx.showToast 是客户端 API，不是本项目后端地址。支付窗口关闭不等于后端确认成功。 微信支付 API 与 wx.showToast 是客户端 API，不是本项目后端地址。支付窗口关闭不等于后端确认成功。
queryOrder 验证 pay_state=2、rewardDelivery='goldMiner.claim' 和 goldMiner 权益数据。购买后最多连续尝试查询四次；pending 之外的异常会提前退出。仍未确认时提示“支付结果确认中”。 queryOrder 验证 pay_state=2、rewardDelivery='goldMiner.claim' 和 goldMiner 权益数据。支付客户端调用成功后最多尝试查单四次，间隔 1.5、3、4.5 秒；PAYMENT_PENDING 和 NETWORK_UNKNOWN 可快速重试，其他异常提前退出。仍未确认时提示“支付结果确认中”。每次有效购买生成新 createRequestId；iOS 原生明确返回错误码 16 且非取消时回退 GoKEFu。当前客服链路不同于后端 V1.7 的 create_order 签名票据，见接入差异。
提示使用 wx.showToast：购买成功、已取消支付、购买失败或支付结果确认中。购买只解锁权益，不自动发放全部任务金币。跨期承接权益可能分配给下一期，不等于当前期立即解锁。 提示使用 wx.showToast：购买成功、已取消支付、购买失败或支付结果确认中。购买只解锁权益，不自动发放全部任务金币。跨期承接权益可能分配给下一期，不等于当前期立即解锁。
@ -179,17 +182,16 @@ Panel.run('claim')
→ Service.request → deliver → Service.request → deliver
→ claim：取得奖励授权 → claim：取得奖励授权
→ userCoin/save：保存增加后的总余额 → userCoin/save：保存增加后的总余额
→ confirm_delivery：确认该档到账 → onSaved：立即启动金币动画，飞到顶部后释放数字显示等待
→ confirm_delivery：确认该档到账（不等待动画）
→ info：读取最新任务状态 → info：读取最新任务状态
→ 播放金币动画
→ 飞到顶部后更新金币数字
``` ```
以余额 1000、奖励 300 为例，userCoin/save 上传 coinAmount=1300，不能上传 300。 以余额 1000、奖励 300 为例，userCoin/save 上传 coinAmount=1300，不能上传 300。
正常首次领取通常四次请求。当前仍等待最后一次 info 返回才播放动画；没有固定的领取前等待秒数，但网络、串行排队会造成等待。 正常首次领取通常四次请求。金币保存确认成功后就播放动画，无须等待 confirm_delivery 或最后一次 info；服务端确认失败时仍保留恢复凭证。网络和串行队列可能造成保存前等待。
金币余额实际保存早于动画，只有数字显示被延迟。金币飞行约 1.51 秒到达目标后释放显示等待；关闭面板也会恢复余额显示。飞行金币已放大两倍。 金币余额实际保存早于动画，只有数字显示被延迟。当前每档动画产生 16 枚金币，约 0.935 秒后释放显示等待，再过 0.24 秒清理动画层；并发动画全部到达后刷新顶部数字。关闭面板也会恢复显示。
已保存但未确认的奖励恢复时只重试确认；已确认奖励不重复加金币。具体取决于本地交付记录和后端响应。 已保存但未确认的奖励恢复时只重试确认；已确认奖励不重复加金币。具体取决于本地交付记录和后端响应。
@ -235,7 +237,7 @@ confirm_settlement_delivery 请求携带 settlementId、grantIds；当前逐档
如果一页有三档待补发奖励，核心流程通常是：查询一次 + 保存三次 + 确认三次，完整 refresh 还包含其他查询。 如果一页有三档待补发奖励，核心流程通常是：查询一次 + 保存三次 + 确认三次，完整 refresh 还包含其他查询。
limit=100 是一页最多查询的记录数，不是金币数量。nextCursor 非空时用 afterId 翻页；即使当前页 items 为空也继续翻页。 客户端仍发送 limit=100，但 V1.7 已改为服务器控制页大小，不能依赖这个参数决定返回数量。非 settling 响应中，nextCursor 非空时用 afterId 翻页，即使 items 为空也继续。当前遇 settling 会立即退出，即使有 nextCursor；这与 V1.7 要求继续扫描其他期的规则不同，尚待对齐。no_pending_rewards 的空列表、空游标可自然结束本轮。
返回 settling 时表示尚未生成可处理清单，不表示没有奖励，也不表示到账。 返回 settling 时表示尚未生成可处理清单，不表示没有奖励，也不表示到账。
@ -266,9 +268,9 @@ limit=100 是一页最多查询的记录数，不是金币数量。nextCursor
每次完整 refresh 都遍历本地订单：有订单号、未标记 done、且不是 cancelled 的订单都会查。因此历史未付款或失败订单可能反复出现。 每次完整 refresh 都遍历本地订单：有订单号、未标记 done、且不是 cancelled 的订单都会查。因此历史未付款或失败订单可能反复出现。
查单失败也会设置 refreshNeedsRetry，下一轮完整刷新会再查这些订单。多个订单意味着一轮多个 getPayInfo。这是查单，不是重复下单或扣款。 查单失败设置 refreshNeedsRetry，下一轮恢复重试会再查这些订单。多个期次订单意味着一轮多个 getPayInfo。这是查单，不是重复下单或扣款；同一期本地只保留最近一次购买记录，旧记录被替换后不再由该账本恢复。
当前读取界面、订单恢复、领奖恢复和补发仍在同一个 refresh 中。首屏优化只是提前展示第一次 info，不代表这些后台请求已经拆开。后续若优化请求数量，应明确拆分触发职责，不直接删除交付确认。 完整 refresh 包括首屏、订单、领奖恢复和补发；retryRecovery 已单独用于恢复重试。首屏提前返回第一次 info，后台完整刷新仍会继续。
## 11. 排查与验证 ## 11. 排查与验证
@ -293,6 +295,6 @@ node tools/coin-madness/check-settlement-entry.cjs
node tools/coin-madness/check-types.cjs node tools/coin-madness/check-types.cjs
``` ```
类型检查比较现有基线；“无新增错误”不代表整个项目零错误。界面实际布局、微信支付及真机网络仍需开发版/体验版验证。 上面列出的是可运行的现有脚本，不代表全部已通过。上次 check-types 报 Utils.ts 的 wx 声明问题，check-release-ui 的夹具及断言待维护；通过记录和真机待验项见接入说明。类型检查以 HEAD 为基线，提交后基线随之改变，“无新增”不等于零错误。
补充协议资料：[v1.5 变更](../../docs/GoldMiner-API-v1.5-changes.md)、[接入说明](../../docs/GoldMiner接入说明.md)。旧 v1.3 文档中的补发 _id/taskIds、ack_settlement 不再是当前客户端补发流程，应以 v1.5 与现行代码为准。 最新仓库协议：[后端 V1.7](../../server/laf-cloud/functions/goldMiner/FRONTEND-API.md)；当前兼容边界：[接入说明](../../docs/GoldMiner接入说明.md)。V1.3/V1.5 只作历史参考，不能据此认定客户端已完成 V1.7 接入。

38
docs/CoinMadness前端开发说明.md
View File

@ -1,19 +1,35 @@
# Coin Madness 前端模拟版 # 黄金矿工（CoinMadness）文档入口
> 2026-09-20：已增加真实接口路径，以下为历史模拟版说明。现在仅编辑器预览使用模拟数据；微信开发／体验版连接测试服，正式版连接现有正式服，入口由后端活动状态控制。正式规则、恢复流程和验收见 [GoldMiner接入说明.md](GoldMiner接入说明.md)。 核对日期：2026-09-30。客户端基准：`codex/coin-madness` 的 `7e14f661`，已合入 main `44901f1e`。本次文档核对不代表线上部署或真机支付已验收。
入口挂在首页，编辑器预览及微信开发/体验版显示，正式版不展示模拟活动。打开后加载 `coin_madness` Asset Bundle，关闭销毁节点并在绘制帧后 releaseAll/removeBundle；加载途中离开也清理迟到资源。平台磁盘缓存和已注册脚本不承诺被物理删除。 ## 阅读入口
界面、阶段规则与模拟接口均在新 Bundle 内。常驻部分只有入口/生命周期桥接和轻量本地通关计数；旧业务仅增加 JiaZai 挂载和 GameTool 主线胜利通知，没有改登录、支付上传或后端业务。关闭时无需保留活动 UI 资源，购买后真实主线通关仍可累计模拟进度。 | 内容 | 文档 | 定位 |
| --- | --- | --- |
| 客户端流程、代码位置、资源加载 | [活动实现说明](../assets/coin_madness/README.md) | 当前实际实现 |
| 环境、验证和协议差异 | [接入说明](GoldMiner接入说明.md) | 联调交接入口 |
| 后端字段和请求 | [后端接口 V1.7](../server/laf-cloud/functions/goldMiner/FRONTEND-API.md) | 仓库最新协议，不代表全部已接入 |
| 下单、查单、客服回退 | [支付约定](CoinMadness支付联调当前约定.md) | 客户端行为 |
| 需要前后端确认的事项 | [接口对齐清单](CoinMadness后端接口需求.md) | 替代早期模拟版需求 |
| 手工联调与集合下载 | [Postman 指南](黄金矿工-Postman操作指南.md) | 操作入口 |
| VIP 六档礼包 | [VIP 配置说明](../server/laf-cloud/functions/goldMiner/VIP-TIERS.md) | 后端配置，前端按返回值展示 |
模拟数据按 uid 本地隔离，独立测试余额，不扣款、不增加真实金币、不修改真实关卡。提供购买、通关、领取、到期补发、重置和下一次接口失败按钮，点击底部联调提示展开工具。 ## 当前状态
界面现为完整预制体 `assets/coin_madness/prefab/CoinMadness.prefab`。在 Creator 中双击即可编辑 Card 下的背景、标题、时间、购买区、任务列表与按钮。图片及 SpriteFrame 子资源都位于分包的 texture 下；主程序只按需加载预制体，其依赖由引擎加载，不再额外预加载整个图片目录。 - 已接入真实活动查询、通关、支付、领奖和补发，不再是“模拟版待接入”。
- `assets/coin_madness` 是活动分包；Host、GoldMinerService、公共加载动画和 resources 入口图在分包外。
- 游戏测试包、活动测试面板、首页测试按钮和两个演示场景已删除。离线回归脚本与独立界面预览工具保留。
- 开发版/体验版选 testHttpip，其他版本选 httpip；当前两个地址相同，不能据版本名认定请求进入独立测试服。
- 未付费可累计进度，主线与无尽胜利使用服务端有效期 ID。任务按全期累计进度展示，已解锁且达标的未领取任务可选择领取，最终由后端授权。
- 客户端尚未完全对齐仓库 V1.7，详见接入说明；不能将协议新功能直接写成已交付。
`CoinMadnessPanel.ts` 只绑定数据、切换节点状态及处理交互；`CoinMadnessDigits.ts` 替换预制体已有数字槽位的图片，不创建数字节点。预制体预设五行，配置超过五行时复制第一行模板并刷新数据。已有行刷新不销毁、不重建。正式活动参数仍待策划定稿。 ## 历史资料
日常布局以 Creator 内的预制体为准；一次性历史布局生成器已移除。 | 文件 | 用途 |
| --- | --- |
| [V1.3 协议副本](GoldMiner-FRONTEND-API-v1.3.md) | 历史字段参考，不能覆盖 V1.7 |
| [V1.5 接入记录](GoldMiner-API-v1.5-changes.md) | 补发授权、公共日程等阶段性变更 |
| [PRD V1.1](goldMiner-PRD.md)、[设计 V1.1](goldMiner-backend-design.md) | 原产品和设计记录，后续变更看当前协议与配置 |
| [原策划确认单](CoinMadness活动策划确认单.docx) | 保留原始确认记录，不作为当前规则或接口验收单 |
测试：`node tools/coin-madness/check-api.cjs`；`node tools/coin-madness/check-types.cjs`。Cocos 实机组件夹具：运行 `node tools/coin-madness/preview.cjs`，访问 `http://127.0.0.1:8765/?open=1`；安装 Playwright 后运行 `check-preview.cjs`。预览夹具需要本地 Cocos Creator 2.4.15 和项目已导入的内置资源。 旧“付费后才计数、每段清零、只统计主线、必须依次领取、每 30 秒全量刷新”不适用于当前客户端。后续维护更新实现说明与接入差异，不再复制完整后端协议到 docs。
未来将 Bundle 内模拟请求替换为真实接口适配，并移除模拟入口控制台及本地计数，按《CoinMadness后端接口需求》接入现有支付、结算和权威钱包；本轮不实施该部分。

43
docs/CoinMadness后端接口需求.md
View File

@ -1,35 +1,22 @@
# Coin Madness 后端接口需求（待实现） # 黄金矿工前后端接口对齐清单
> 历史方案：用户已确认改按黄金矿工接口 V1.3 实现。以下“付费后才计数、每段清零、只计主线”等旧规则已被替代，不再作为开发依据。当前协议见 [GoldMiner-FRONTEND-API-v1.3.md](GoldMiner-FRONTEND-API-v1.3.md)，接入说明见 [GoldMiner接入说明.md](GoldMiner接入说明.md)。原 Word 确认单中的冲突规则同样以接口 V1.3 为准。 核对日期：2026-09-30。替代早期模拟版“待实现”需求；旧稿保留在 Git 历史。
本轮只交付前端模拟版。后端代码已恢复原状，没有新接口或支付配置部署。以下为后续对接需求，接口名称可按现有体系调整。 字段以 [后端 V1.7](../server/laf-cloud/functions/goldMiner/FRONTEND-API.md) 为准，实际客户端行为见 [实现说明](../assets/coin_madness/README.md)，二者差异见 [接入说明](GoldMiner接入说明.md)。本次没有部署后端。
## 已确认规则 ## 已调用接口
- 同一期全体玩家统一结束，每人只能购买一次；一次付费解锁整期阶梯奖励，不分档、不立即赠送金币。 - goldMiner/index：info、claim、confirm_delivery、settlements、confirm_settlement_delivery。
- 支付由服务端确认后才开始统计，付费前不累计、不补算。 - activityConfig/list：公共日程；userLevel/save：附带 goldMiner 通关事件；userCoin/save：保存金币总余额。
- 各段独立计数，当前段领取成功才进入下一段；达标后等待领取期间的通关不结转。 - wx/orderPaySig、wx/iosorderPaySig：原生下单；wx/getPayInfo、wx/iosgetPayInfo：确认权益。
- 只统计主线新关胜利；重复关、无限关、其他模式、批量补报不计入。以服务端收到有效结算时仍在活动期内为准。 - 客服当前使用 Utils.GoKEFu，不调用协议中的 create_order；这不代表后端 create_order 已废弃。
- 到期仅补发已付费且已达标未领取奖励，未完成奖励失效；补发与手动领取并发不得重复发奖。
## 前端所需接口 ## 优先确认
| 操作 | 请求信息 | 返回信息与约束 | 1. 部署端实际版本和请求环境：当前 testHttpip 与 httpip 相同。
| --- | --- | --- | 2. 客服支付采用 GoKEFu 还是服务端签名票据；同期订单复用、错误码 16 回退、取消重试和跨期权益。
| 查询活动 | 登录鉴权 | 服务端时间、是否开放、活动配置、支付状态、当前段、当前段进度、已领状态、结束状态、余额/奖励凭证 | 3. V1.7 补发分页：服务器控页大小，settling 继续可用游标，扫描结束后有限重试，no_pending_rewards 表示无待处理记录。
| 创建订单 | periodId、请求幂等键 | 现有支付渠道所需订单参数；价格和商品由服务端配置，不能相信客户端金额 | 4. claimStatus 驱动按钮，验证 VIP 六档十任务、pending_unlock 和任意达标档领取；金币保存仍须串行。
| 确认支付状态 | periodId、orderId | 以渠道验签及订单归属校验为准；客户端支付成功回调不能直接解锁 | 5. 保留授权—保存总余额—确认的恢复边界。保存结果不明需核对，不重复加币，不能承诺重装/多设备严格只发一次。
| 领取奖励 | periodId、stageId、请求幂等键 | 原子校验并发奖、推进阶段，返回最新活动快照与余额版本/奖励凭证 |
| 到期补发查询 | 登录或活动查询触发 | 已补发奖励及唯一凭证；重复查询不重复发奖 |
活动配置至少包含 periodId、title、startsAt、endsAt（UTC 毫秒）、priceCents、currency、productId、开启条件和有序 stages（stageId、wins、coins）。所有接口返回统一 code、msg、data；需区分未开放、过期、未支付、未达标、已领取、期次变更、请求重试和鉴权失效。 示例价格、目标和周期不能替代已发布配置。验收包括外层成功而活动子结果失败、重复通关、保存成功但确认失败、补发分页、到期竞态和换账号恢复。
服务端接入现有主线结算流程，按唯一结算标识去重，并校验新关及支付确认时间。支付回调、领奖和到期补发需具备幂等和原子性，断线重试后可恢复状态。账户身份来自登录凭据。奖励必须进入现有权威钱包，禁止客户端自行累加后覆盖服务端余额。
## 策划与后端仍需定稿
活动日历、购买截止时间、跨截止支付回调处置（拒绝/退款/保障期）、价格币种与渠道商品、开启等级/人群、每段目标与奖励、是否允许晚进入、补发通知形式、展示文案和正式美术资源。模拟版的 7 天、99 分、5 段奖励仅用于交互测试，不代表正式配置。
## 联调验收
验证付费前零进度、支付回调重复、重复结算、等待领取不结转、重复/并发领取、截止时刻竞态、到期补发与手动领奖竞态、断网恢复、重登和换期隔离。模拟版使用本地时间且不能验签，不替代真实支付及服务端验收。

29
docs/CoinMadness支付联调当前约定.md
View File

@ -1,12 +1,25 @@
# CoinMadness 支付联调当前约定 # CoinMadness 支付联调当前约定
2026-09-22，依据用户在本次联调中明确确认的规则更新客户端。以下条款覆盖旧 V1.3 文档中对应的下单和取消重试说明，不修改后端原始文档。 核对日期：2026-09-30，客户端基准 7e14f661。[接入差异](GoldMiner接入说明.md) · [仓库后端 V1.7](../server/laf-cloud/functions/goldMiner/FRONTEND-API.md)
- 下单商品取最新 `info.productId`，价格取最新 `info.priceFen`（分）；显式传 `itemCount: 1`、`itemPrice: info.priceFen`，不写死商品或金额。 ## 客户端实际行为
- 首次下单生成并保存 `createRequestId`，保存后台返回的 `outTradeNo` 后调用微信支付。
- 按用户最新要求，每次有效点击购买都创建新的下单请求编号、重新下单，并使用返回的订单及签名拉起支付。购买入口不先查询旧订单，不受旧订单取消、失败、待确认状态影响，不要求返回旧订单号。保留活动资格检查及界面防连点。
- 本期本地订单记录更新为本次尝试；支付后查询本次订单。自动刷新仍可查询当前保存的未完成且非取消订单，但不负责恢复被后续购买替换的历史订单。
- 已观测到的 `code: 0, data.pay_state: 1, msg: 充值未成功` 且没有 `errorCode` 的查单响应，按支付待确认处理；显式错误码优先，不自动变成支付成功。
- 微信成功回调只触发查询；活动支付确认仍要求 `pay_state: 2`、`rewardDelivery: goldMiner.claim` 和 `goldMiner` 元数据。尚未取得实际成功查单响应，不猜测其他格式，也不将普通礼包付款直接当作活动解锁。
验证：`check-payment-retry.cjs`、`check-api.cjs`、`check-api-v15.cjs`、`check-test-tools.cjs` 均为本地模拟检查。真实微信弹窗、付款及活动权益确认仍需真机联调。 - 每次有效购买先读取 info，验证期次、purchasable 和有效 priceFen。商品取 productId，数量 1，价格单位为分。
- 原生下单走 wx/orderPaySig 或 wx/iosorderPaySig，携带新的 createRequestId、itemid、itemCount、itemPrice；验证返回 outTradeNo、signData、signature、paySig 后原样拉起微信支付。
- 每次有效购买生成新请求编号，本地同一期订单被本次尝试替换。服务端可能复用该期订单，新请求不保证新的服务器订单；被替换的旧本地记录不再参与自动恢复。
- iOS 且 iosCanPay=false 时走 Utils.GoKEFu。它本地生成订单号和 sessionFrom，传 price、payment_name、payment_count 打开客服；GoldMinerService 收到生成订单号后单独持久化。当前不调用 goldMiner/index 的 create_order。
- iOS 原生明确返回错误码 16 且非取消时，重新校验活动后回退 GoKEFu；Android、其他错误、超时和客服失败不循环回退。
- 微信客户端成功回调或客服会话打开，只会启动查单。成功须后端返回 pay_state=2、rewardDelivery=goldMiner.claim 和 goldMiner 权益元数据。
- 无 errorCode 且 code=0、data.pay_state=1、msg=充值未成功的响应按 PAYMENT_PENDING 处理。显式错误码优先。
- 支付后最多查四次，快速重试间隔为 1.5/3/4.5 秒，限 PAYMENT_PENDING 或 NETWORK_UNKNOWN。未确认时保留恢复状态；切后台、关闭面板会停止高频查单。
- 自动恢复只查询当前账本中未完成、非 cancelled 的订单。购买仅解锁，不直接加金币；跨期权益不一定解锁当前期。
## 需要与部署端确认
仓库后端 V1.7 的客服链路要求 create_order 返回签名 sessionFrom；当前 GoKEFu 与之不同。后端还存在同期订单复用和 PAYMENT_CHANNEL_CONFLICT 约束。应验证客服转单关联、错误码 16 回退、取消重试及跨期权益，不能将前端路径存在视为线上已兼容。
当前 testHttpip 与 httpip 相同。真机测试前确认实际请求环境和支付签名环境，不能按开发版/体验版名称判断隔离。
## 验证
check-api.cjs 在 2026-09-30 合并后通过；check-payment-retry.cjs、check-api-v15.cjs、check-ios-payment-fallback.cjs 是现存离线检查入口，本次文档核对未重跑。真实付款、客服交互和线上权益确认尚需真机验收。已删除的 check-test-tools.cjs 不再作为验证入口。

19
docs/GoldMiner-API-v1.5-changes.md
View File

@ -1,13 +1,12 @@
# 黄金矿工接口更新接入 # 黄金矿工 V1.5 接入记录（历史）
依据用户提供的「黄金矿工」Postman 集合及 README（V1.5）。玩家补发采用 V1.4 新协议。 2026-09-30 校注：本文件记录阶段性变更。仓库最新协议为 [V1.7](../server/laf-cloud/functions/goldMiner/FRONTEND-API.md)，当前接入程度见 [接入说明](GoldMiner接入说明.md)。
- 到期清单使用 `settlementId/periodId/rewards`，每个 reward 自带 `taskId/grantId/items`。不再依赖 `_id/taskIds`，不再对过期任务调用 claim。 - 补发改为 settlementId/periodId/rewards；reward 自带 taskId/grantId/items，不再按旧 _id/taskIds 对过期任务 claim。
- 保存金币后调用 `confirm_settlement_delivery`，传 `settlementId/grantIds`；验证 confirmedGrantIds 后落本地确认状态。新流程不调用 ack_settlement。 - 保存金币后 confirm_settlement_delivery，传 settlementId/grantIds 并验证 confirmedGrantIds，不再调用 ack_settlement。
- 复用原有发货日志：已保存金币的凭证只补确认；保存结果不明仍阻止重复加币。金币保存与领奖确认依然不是一个后端事务。 - 复用本地交付记录：saved 只补确认，结果不明不重复加币；总余额保存与确认仍不是同一事务。
- settlements 返回 settling 时停止本轮处理，保留当前页，下一次刷新重试；空页仍按 nextCursor 翻页。 - 接入 activityConfig/list，保留成功日程，失败不覆盖；通关原样使用有效服务端期 ID，包括临时期，不再自行计算周四 ID。
- 接入 activityConfig/list，保留成功日程，失败不覆盖。诊断快照 activitySchedule 可查看。日程不替代玩家 info 状态及入口资格判断。 - 当时 settling 退出并重试的行为仍在客户端；V1.7 已要求继续可用游标扫描其他期，尚待对齐。
- 通关使用后端返回的当前期 ID，支持 goldMiner:test: 临时期及任意星期；不再自行计算周四期号。locked 玩家可借公共日程上报资格关。 - 管理发布、初始化索引、支付回调仍属于后端，不加入玩家客户端。
- 管理发布临时期、索引初始化及支付回调仍由后台处理，不加入玩家端。
验证：check-api.cjs、check-api-v15.cjs、check-test-tools.cjs；这些是本地模拟协议检查，真实支付和云端定时结算仍需测试服联调。 离线脚本 check-api.cjs、check-api-v15.cjs 保留；旧测试面板及 check-test-tools.cjs 已删除。该记录不能作为线上支付、部署或 V1.7 全量验收证明。

4
docs/GoldMiner-FRONTEND-API-v1.3.md
View File

@ -1,5 +1,7 @@
# 黄金矿工前端接口文档 V1.3 # 黄金矿工前端接口文档 V1.3
> 历史协议副本（2026-09-30 标注）：仓库最新协议为 [V1.7](../server/laf-cloud/functions/goldMiner/FRONTEND-API.md)。正文保留历史内容，附属链接已修复并指向仓库当前资料；顺序领奖、旧补发等条款不能覆盖当前协议。客户端差异见 [接入说明](GoldMiner接入说明.md)。
更新时间：2026-09-18。依据当前 `local` 分支实现编写，包含精简后的 `info` 协议。示例价格、目标和金币仅用于联调，页面必须使用接口返回值。部署环境需具有相同版本的后端代码。 更新时间：2026-09-18。依据当前 `local` 分支实现编写，包含精简后的 `info` 协议。示例价格、目标和金币仅用于联调，页面必须使用接口返回值。部署环境需具有相同版本的后端代码。
## 1. 接入约定与接口总览 ## 1. 接入约定与接口总览
@ -616,4 +618,4 @@ data.settlementId 为 string，data.acknowledged 为 boolean，成功固定 true
不要将 info 的 claimable 状态当作后端永久承诺；点击后的 claim 才是实际领取判定。页面倒计时归零、切回前台、支付完成及奖励确认后均应刷新状态。 不要将 info 的 claimable 状态当作后端永久承诺；点击后的 claim 才是实际领取判定。页面倒计时归零、切回前台、支付完成及奖励确认后均应刷新状态。
联调文件：[Postman 使用说明](postman/gold-miner.README.md)、[Collection](postman/gold-miner.postman_collection.json)、[环境模板](postman/gold-miner.postman_environment.json)。内部维护与部署细节见 [后端说明](README.md) 和 [客服支付接入说明](LEGACY-PAYMENT.md)。 联调文件：[Postman 使用说明](../server/laf-cloud/functions/goldMiner/postman/gold-miner.README.md)、[Collection](../server/laf-cloud/functions/goldMiner/postman/gold-miner.postman_collection.json)、[环境模板](../server/laf-cloud/functions/goldMiner/postman/gold-miner.postman_environment.json)。内部维护与部署细节见 [后端说明](../server/laf-cloud/functions/goldMiner/README.md) 和 [客服支付接入说明](../server/laf-cloud/functions/goldMiner/LEGACY-PAYMENT.md)。

91
docs/GoldMiner接入说明.md
View File

@ -1,71 +1,52 @@
# Coin Madness 真实接口接入 # 黄金矿工当前接入与交接说明
2026-09-20：按用户确认接入黄金矿工接口 V1.3。协议副本见 [GoldMiner-FRONTEND-API-v1.3.md](GoldMiner-FRONTEND-API-v1.3.md)。旧后端需求和 Word 策划确认单的冲突规则已作废。 核对日期：2026-09-30；客户端 `7e14f661`，仓库后端协议 V1.7。[文档入口](CoinMadness前端开发说明.md) · [实现说明](../assets/coin_madness/README.md) · [后端协议](../server/laf-cloud/functions/goldMiner/FRONTEND-API.md)
## 运行方式与规则 ## 环境与运行
- Creator 编辑器预览继续使用原本地模拟器，便于美术检查，不请求后端、不修改真实资产；模拟器仍保留原有自由领取测试行为，不作为正式顺序领奖验收依据。 - GoldMinerService 要求非 CC_PREVIEW 且存在 wx；普通 Creator 预览不会启动真实服务，也没有旧版首页模拟器。
- 微信开发版和体验版使用 `Utils.testHttpip`，正式版使用 `Utils.httpip`，与现有登录环境一致。交付和订单记录按环境、账号隔离。 - 开发版/体验版走 Utils.testHttpip，其他版本走 Utils.httpip。合入 main 后两者当前相同，独立测试环境未由此配置隔离。
- 真实入口根据 `info.status` 展示：可购买、暂停购买、已解锁时可见；未达资格或未开放时隐藏。尚有补发到账通知时保留入口。 - `tools/coin-madness/preview.cjs` 是独立界面夹具，使用预制体和模拟响应，不登录、不支付；需要 Creator 2.4.15 引擎和导入资源，不是游戏内测试入口。
- 付费前累计进度；任务目标为全期累计值；主线新关及无尽胜利按协议上报；失败、配置跳关、其他模式不附带活动胜利。 - 游戏测试包、活动测试面板及诊断面板 API 已删除，正式恢复流程与支付控制台日志保留。
- 按后端 `claimStatus` 顺序领取，上一档确认到账后下一档才能领取。价格、目标、金币、商品、期次与时间均来自后端。
- 首次回首页、回到前台、每 30 秒在首页、打开活动、支付和领奖后刷新；倒计时归零刷新，网络失败时限制刷新频率。
## 代码入口 ## 已实现
`assets/Script/coin_madness/GoldMinerService.ts` 为常驻协议服务，不引用活动 Bundle 的资源或组件。负责 JSON 请求、服务端时间偏移、状态转换、订单恢复、领奖交付记录、补发分页和事件记录。记录使用 `goldMiner:v1:<服务端地址>:<uid>` 命名空间写入本地存储。 - 首页提前读取首份 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)。
`CoinMadnessHost.ts` 保留原首页入口、弹窗队列及 Bundle 生命周期，注入异步 request 给面板。保留“测试”和“活动测试”入口，仅微信开发版/体验版连接独立测试服时显示。旧 mock 已移除。现有预制体布局及领奖动画保留。只在确认补发到账后展示补发通知，关闭通知后清除本地展示记录。 ## 与 V1.7 待对齐
`GameTool.addLevel` 在现有胜利保存调用上附带活动事件。`Utils.setUserLevel` 仅在附带事件时切换 JSON，主线省略 `isWuXian`，无尽传字符串 `"true"`。读取 `data.goldMiner.code` 时不把活动失败当成普通关卡失败，不重复推进关卡。 | 项目 | 当前客户端 | 最新协议及差异 |
| --- | --- | --- |
| 客服支付 | 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 的进度 |
跨期或尚未取得可用 info 时，事件期次按协议约定的北京时间周四日历生成；有有效 info 时优先使用其期次和服务端时间偏移。最终是否计入始终由后端判断。事件 ID、关号或无尽序号在发请求前持久化；无尽序号使用毫秒时间加随机尾数并维持本地单调递增，可降低跨设备冲突概率，但不提供服务端全局序号保证。 仓库已有 [goldMiner 后端](../server/laf-cloud/functions/goldMiner/README.md)、[公共日程](../server/laf-cloud/functions/activityConfig/README.md) 和 Postman 集合；代码存在不证明线上版本一致。本次只修正文档，没有变更协议或客户端。
`Utils.POSTJSON` 为新增 JSON 通道，不改变其他旧接口的表单格式。`Utils.withCoinSave` 将活动金币保存和现有 `setUserCoin` 上传串行化；普通上传在执行时读取最新余额，避免队列里残留旧余额覆盖奖励。 ## 验证状态
## 支付和交付 2026-09-30 合并后通过的离线检查：
支付沿用现有项目选择：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 ```text
node tools/coin-madness/check-api.cjs node tools/coin-madness/check-api.cjs
node tools/coin-madness/check-game-test.cjs node tools/coin-madness/check-home-entry-ready.cjs
node tools/coin-madness/check-types.cjs node tools/coin-madness/check-popup-queue.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 转译有既有解析问题，因此协议测试仅加载该方法前的真实网络／金币模块部分。 清理时 check-first-display.cjs 也已通过。其余脚本按变更选择运行，存在不等于通过。
测试服仍需联调：确认 V1.3 已部署（尤其 iosorderPaySig）、微信请求域名配置、有效登录、两个支付渠道、到期补发、跨期支付路线、真机杀进程恢复及金币 UI 同步。原生签名 env=0 可能真实扣费，本地自动化未发起支付。 - 上次 check-types.cjs 报 Utils.ts 的 wx 声明诊断；它比较工作区与 HEAD，提交后基线变化，无新增不代表零错误。
- 上次 check-release-ui.cjs 的装饰器夹具无法构造组件；临时修正后还有解锁断言失败，修改已撤回，该检查待维护。
日常界面调整以 Creator 预制体为准。一次性历史布局生成器已移除。 - 真机待验收：实际环境、Android/iOS 支付与客服回退、取消重试、跨期权益、VIP 十任务和任意达标档领取、补发跨页、断网重启、顶部金币同步。
- 本次文档核对未请求线上接口、支付或修改玩家资产。手工操作见 [Postman 指南](黄金矿工-Postman操作指南.md)。

2
docs/goldMiner-PRD.md
View File

@ -1,5 +1,7 @@
# 黄金矿工 PRD # 黄金矿工 PRD
> 历史产品记录（2026-09-30 标注）：下文状态和规则属于 V1.1 时点。当前客户端、VIP 礼包和接口差异请从 [文档入口](CoinMadness前端开发说明.md) 阅读，不将本文件当作最新版验收单。
版本：V1.1 版本：V1.1
日期：2026-09-18 日期：2026-09-18

2
docs/goldMiner-backend-design.md
View File

@ -1,5 +1,7 @@
# 黄金矿工后端整体设计 # 黄金矿工后端整体设计
> 历史设计记录（2026-09-30 标注）：下文“尚未实现”等状态属于原编写时点。仓库已有 [后端实现](../server/laf-cloud/functions/goldMiner/README.md)，不代表线上已部署；当前状态见 [文档入口](CoinMadness前端开发说明.md)。
版本：V1.1 版本：V1.1
日期：2026-09-18 日期：2026-09-18

26
docs/黄金矿工-Postman操作指南.md
View File

@ -1,13 +1,15 @@
# 黄金矿工 Postman 操作指南 # 黄金矿工 Postman 操作指南
适用：本次后端提供的 V1.5 测试包。请求名称按包内 Collection 编写。 2026-09-30 核对：仓库集合已对应 V1.7，入口见 [集合说明](../server/laf-cloud/functions/goldMiner/postman/gold-miner.README.md) 和 [接口协议](../server/laf-cloud/functions/goldMiner/FRONTEND-API.md)。本指南保留操作顺序，具体请求名称、分组与断言以导入的仓库集合为准。游戏内测试面板已删除，Postman 是独立工具。
当前客户端 testHttpip 与 httpip 相同；手工测试需单独核对 baseUrl，不能直接据开发版配置判断为独立测试服。当前客户端兼容差异见 [接入说明](GoldMiner接入说明.md)。
## 1. 导入文件 ## 1. 导入文件
在 Postman 点击 Import，导入下载目录「黄金矿工」中的两个文件： 在 Postman 点击 Import，导入仓库内这两个文件（避免继续使用下载目录中的旧副本）：
- `gold-miner.postman_collection.json`：接口及测试脚本。 - [gold-miner.postman_collection.json](../server/laf-cloud/functions/goldMiner/postman/gold-miner.postman_collection.json)：接口及测试脚本。
- `gold-miner.postman_environment.json`：环境变量模板。 - [gold-miner.postman_environment.json](../server/laf-cloud/functions/goldMiner/postman/gold-miner.postman_environment.json)：环境变量模板。
选择导入的「黄金矿工 - 环境模板」作为当前环境。不要只导入 Collection，也不要继续使用旧版环境中遗留的领奖凭证。 选择导入的「黄金矿工 - 环境模板」作为当前环境。不要只导入 Collection，也不要继续使用旧版环境中遗留的领奖凭证。
@ -74,10 +76,10 @@ periodId 必须原样使用后端返回值，包括 `goldMiner:test:...`，不
## 7. 活动期间领奖 ## 7. 活动期间领奖
前置条件：已解锁、目标已达成、前一档已确认。以下是会实际修改金币的测试流程；使用独立账号，避免游戏或另一设备同时改余额。游戏已经发过的奖励不要再手工加币。 前置条件：已解锁、该任务 claimStatus=claimable。V1.7 允许任意选择达标任务，不要求前一档确认；未付费达标为 pending_unlock。以下流程会修改金币，需独立账号，避免另一设备同时改余额。游戏已经发过的奖励不要再手工加币。
1. 查询 info，填写 claimPeriodId 和 claimTaskId。 1. 查询 info，填写 claimPeriodId 和 claimTaskId。
2. 「04 顺序领取与客户端保存」→「01 获取奖励授权」，得到 grantId 和 items。授权本身不加金币。 2. 「04 任意档位领取与客户端保存」→「01 获取奖励授权」，得到 grantId 和 items。授权本身不加金币。
3. 同组「03 读取金币总余额」。 3. 同组「03 读取金币总余额」。
4. 人工填写 coinAfterDelivery = 当前总余额 + 此次授权金币。例如当前 880、奖励 100，应填 980，不是 100。 4. 人工填写 coinAfterDelivery = 当前总余额 + 此次授权金币。例如当前 880、奖励 100，应填 980，不是 100。
5. 同组「04 模拟客户端发货后保存总余额」。 5. 同组「04 模拟客户端发货后保存总余额」。
@ -89,12 +91,12 @@ periodId 必须原样使用后端返回值，包括 `goldMiner:test:...`，不
## 8. 到期补发（本次更新重点） ## 8. 到期补发（本次更新重点）
1. 「05 到期补发」→「01 清单第一页」。 1. 「05 到期补发」→「01 清单第一页」。
2. status=settling：后台还在结算，稍后用当前页参数重试，不推进游标。 2. status=settling：后台还有待结算期；V1.7 返回 nextCursor 时继续扫描其他期，不能仅因 settling 阻塞后续页。完成本轮扫描后再有限重试。
3. status=pending_delivery：查看 items 和 nextCursor；空 items 仍可能有下一页。 3. status=pending_delivery：查看 items 和 nextCursor；空 items 仍可能有下一页。
4. 「05 查询并选择首个待补发奖励（不调用 claim）」自动选择第一页首项，保存 settlementId、grantId 和奖励。如果目标在后续页，按对应返回值选择，不能误用第一页凭证。 4. 「05 查询并选择首个待补发奖励（不调用 claim）」自动选择第一页首项，保存 settlementId、grantId 和奖励。如果目标在后续页，按对应返回值选择，不能误用第一页凭证。
5. 执行第 04 组「03 读取金币总余额」，填写 coinAfterDelivery，再执行「04 模拟客户端发货后保存总余额」。 5. 执行第 04 组「03 读取金币总余额」，填写 coinAfterDelivery，再执行「04 模拟客户端发货后保存总余额」。
6. 保存成功后，执行第 05 组「06 保存金币后确认补发（重复安全）」。 6. 保存成功后，执行第 05 组「06 保存金币后确认补发（重复安全）」。
7. 再查询清单，已确认奖励应消失；逐项处理其余奖励。 7. 再查询清单，逐项处理其余奖励。页大小由后端控制，不传 limit；空页有 nextCursor 仍继续。扫描结束后从第一页复查，no_pending_rewards 表示本轮无待处理记录，持续 settling 时稍后重试，不立即无限循环。
结束后使用清单里的原 grantId，不再调用普通 claim。新确认接口是 confirm_settlement_delivery，参数是 settlementId 和 grantIds；settlementId 不是 periodId，也不是 `_id`。第 05 组旧的 ack_settlement 用例不属于新补发步骤。 结束后使用清单里的原 grantId，不再调用普通 claim。新确认接口是 confirm_settlement_delivery，参数是 settlementId 和 grantIds；settlementId 不是 periodId，也不是 `_id`。第 05 组旧的 ack_settlement 用例不属于新补发步骤。
@ -106,7 +108,7 @@ periodId 必须原样使用后端返回值，包括 `goldMiner:test:...`，不
| 修改 expectedStatus 后活动仍不开放 | 它只改变断言；需后端发布有效配置 | | 修改 expectedStatus 后活动仍不开放 | 它只改变断言；需后端发布有效配置 |
| 日程有活动，玩家仍 locked | 检查玩家主线资格；日程不代表玩家已达标 | | 日程有活动，玩家仍 locked | 检查玩家主线资格；日程不代表玩家已达标 |
| 切换账号/地址后第一次请求跳过 | 脚本清理旧上下文，重新发送并查询活动 | | 切换账号/地址后第一次请求跳过 | 脚本清理旧上下文，重新发送并查询活动 |
| 领取失败 | 检查付费、目标、前档确认及是否已到期 | | 领取失败 | 检查该档 claimStatus、付费、目标、凭证及是否已到期，不要求前档确认 |
| 到期后持续 settling | 后端检查 goldMiner/jobs 部署与每分钟触发器 | | 到期后持续 settling | 后端检查 goldMiner/jobs 部署与每分钟触发器 |
| 金币保存成功但确认失败 | 保留原凭证重试确认，不再次加币 | | 金币保存成功但确认失败 | 保留原凭证重试确认，不再次加币 |
@ -114,7 +116,7 @@ periodId 必须原样使用后端返回值，包括 `goldMiner:test:...`，不
## 后端原始说明 ## 后端原始说明
- [接口与测试场景说明](C:/Users/fanxi/Downloads/黄金矿工/gold-miner.README.md) - [接口与测试场景说明](../server/laf-cloud/functions/goldMiner/postman/gold-miner.README.md)
- [环境变量完整中文说明](C:/Users/fanxi/Downloads/黄金矿工/gold-miner.environment.zh-CN.md) - [环境变量完整中文说明](../server/laf-cloud/functions/goldMiner/postman/gold-miner.environment.zh-CN.md)
本指南依据这两个文件及当前 Collection 整理，没有代替用户发送请求或修改服务器。 本指南按仓库集合和当前 V1.7 协议核对，没有代替用户发送请求或修改服务器。