MatchMaster/docs/黄金矿工-Postman操作指南.md

黄金矿工 Postman 操作指南

2026-09-30 核对：仓库集合已对应 V1.7，入口见 集合说明 和 接口协议。本指南保留操作顺序，具体请求名称、分组与断言以导入的仓库集合为准。游戏内测试面板已删除，Postman 是独立工具。

当前客户端 testHttpip 与 httpip 相同；手工测试需单独核对 baseUrl，不能直接据开发版配置判断为独立测试服。当前客户端兼容差异见 接入说明。

1. 导入文件

在 Postman 点击 Import，导入仓库内这两个文件（避免继续使用下载目录中的旧副本）：

• gold-miner.postman_collection.json：接口及测试脚本。
• gold-miner.postman_environment.json：环境变量模板。

选择导入的「黄金矿工 - 环境模板」作为当前环境。不要只导入 Collection，也不要继续使用旧版环境中遗留的领奖凭证。

2. 填环境变量

打开 Environments，选中上述环境，在变量的值栏填写并保存。不同 Postman 版本可能显示 Value 或 Current Value；以当前请求实际使用的本地值为准。

变量	填什么
baseUrl	后端提供的测试服地址，包含 https，不带末尾 /，不拼 /goldMiner/index
uid	测试玩家的 uid，不是 openid
token	该玩家当前有效的登录 token
adminToken	仅管理操作需要，向后端取得测试服管理员口令；不是玩家 token

其余变量先保持模板默认值或留空。查询接口会自动保存 periodId、productId 等。不要公开 token、adminToken 或运行后的环境导出文件。

3. 先确认活动是否开放

1. 打开「08 公共活动日程」→「01 公共活动日程（GET，无需登录）」，点击 Send。
2. 查看 data.activities，找 activityId=goldMiner、phase=active 的条目。upcoming 是未来活动，空数组表示当前查询窗口内没有日程。
3. 打开「01 基础查询与鉴权」→「01 活动信息并保存当期变量」，点击 Send。
4. 查看 data.status，并查看 Tests/Test Results 是否通过。

status	含义
unavailable	当前不开放或没有适用配置
locked	玩家未达到参与门槛
purchasable	可购买
purchase_disabled	暂停新购买
unlocked	本期权益已解锁

HTTP 200 不代表业务成功，还要看响应 code。code:1 且 status=unavailable 是有效业务结果。负向用例故意传错参数，返回拒绝可能正是预期，需看断言。

expectedStatus 等 expected 开头的变量只设置“预期结果”，不会改变服务器状态。仅查询时可留空。

4. 临时开一场测试活动（需管理员权限）

让后端确认测试服已设置 PAYMENT_APP_ENV=test 和 GOLD_MINER_TEST_PERIODS_ENABLED=true。

填写 baseUrl、adminToken，打开「06 管理操作」→「04 发布测试临时期（默认立即开启 30 分钟）」。发送前检查配置：模板默认门槛 41、价格 100 分，累计 1/2/3 次胜利奖励 100/200/300 金币。

发送成功后，重新查询公共日程和玩家 info。第一次生成的临时期 ID、时间会保存在环境中；重复 Send 复用它们。修改 tempDurationMinutes 不会重算已有结束时间。另开一场需使用新 ID 和不重叠时间；需要重新生成时清空 tempPeriodId/tempStartsAt/tempEndsAt。

periodId 必须原样使用后端返回值，包括 goldMiner:test:...，不要自行改成日期。发布活动不会替玩家付费，也不会提升玩家关卡。

5. 通关进度

推荐先在游戏真实通关，再查询 info，检查 progressWins。手工验证接口时使用独立测试账号：

1. 查询活动，再发送「01」组的「02 读取主线存档」。
2. 主线测试：mainLevelAfterWin 填 currentMainLevel + 1，发送「02 通关进度」→「01 主线新胜利」。
3. 无尽测试：mainLevelAfterWin 填 currentMainLevel；endlessSequence 填本账号本期未使用过的正整数，再发送「02 无尽新胜利」。
4. 检查外层 code 和 data.goldMiner 子结果，再查询活动确认进度。

默认门槛 41 时，从 40 通到 41 是资格关，本关不计入活动；对应 expectedProgressResult=qualification。普通计数使用 counted，封顶场景使用 capped。不要用跳关覆盖存档准备数据。旧存档统计不一定支持幂等，勿把“原事件重试”当成新胜利反复发送。

6. 支付

先确认 status=purchasable。最方便的联调方式是在游戏完成真实支付，再查询 info 是否 unlocked。

手工测下单时，第 03 组按设备选 Android 或原生 iOS 创建订单；这两项故意携带错误价格，用于验证后端定价。仅创建订单不会付款。未支付时 expectedPaymentState 保持 pending；可信支付完成后设为 paid，并填写 expectedTargetPeriodId，再调用对应查单请求。

旧 iOS 客服渠道使用第 07 组；checkIos 返回 true 只代表转单关联成功，不代表支付成功。不要混用不同支付渠道创建同一期订单。客服消息请求会实际发送消息，默认 allowCustomerMessage=false，不属于日常只读查询。

7. 活动期间领奖

前置条件：已解锁、该任务 claimStatus=claimable。V1.7 允许任意选择达标任务，不要求前一档确认；未付费达标为 pending_unlock。以下流程会修改金币，需独立账号，避免另一设备同时改余额。游戏已经发过的奖励不要再手工加币。

1. 查询 info，填写 claimPeriodId 和 claimTaskId。
2. 「04 任意档位领取与客户端保存」→「01 获取奖励授权」，得到 grantId 和 items。授权本身不加金币。
3. 同组「03 读取金币总余额」。
4. 人工填写 coinAfterDelivery = 当前总余额 + 此次授权金币。例如当前 880、奖励 100，应填 980，不是 100。
5. 同组「04 模拟客户端发货后保存总余额」。
6. 保存明确成功后，同组「05 保存后确认领取（可原请求重试）」。
7. 再查询 info，确认对应任务 claimStatus=claimed。

若保存超时或结果不明，先核对余额和原 grantId，不能重新累加一次奖励。授权、金币保存、领取确认仍是独立请求。

8. 到期补发（本次更新重点）

1. 「05 到期补发」→「01 清单第一页」。
2. status=settling：后台还有待结算期；V1.7 返回 nextCursor 时继续扫描其他期，不能仅因 settling 阻塞后续页。完成本轮扫描后再有限重试。
3. status=pending_delivery：查看 items 和 nextCursor；空 items 仍可能有下一页。
4. 「05 查询并选择首个待补发奖励（不调用 claim）」自动选择第一页首项，保存 settlementId、grantId 和奖励。如果目标在后续页，按对应返回值选择，不能误用第一页凭证。
5. 执行第 04 组「03 读取金币总余额」，填写 coinAfterDelivery，再执行「04 模拟客户端发货后保存总余额」。
6. 保存成功后，执行第 05 组「06 保存金币后确认补发（重复安全）」。
7. 再查询清单，逐项处理其余奖励。页大小由后端控制，不传 limit；空页有 nextCursor 仍继续。扫描结束后从第一页复查，no_pending_rewards 表示本轮无待处理记录，持续 settling 时稍后重试，不立即无限循环。

结束后使用清单里的原 grantId，不再调用普通 claim。新确认接口是 confirm_settlement_delivery，参数是 settlementId 和 grantIds；settlementId 不是 periodId，也不是 _id。第 05 组旧的 ack_settlement 用例不属于新补发步骤。

9. 常见问题

现象	检查方式
提示变量缺失、请求跳过	检查右上角环境及变量值；跳过不算测试通过
修改 expectedStatus 后活动仍不开放	它只改变断言；需后端发布有效配置
日程有活动，玩家仍 locked	检查玩家主线资格；日程不代表玩家已达标
切换账号/地址后第一次请求跳过	脚本清理旧上下文，重新发送并查询活动
领取失败	检查该档 claimStatus、付费、目标、凭证及是否已到期，不要求前档确认
到期后持续 settling	后端检查 goldMiner/jobs 部署与每分钟触发器
金币保存成功但确认失败	保留原凭证重试确认，不再次加币

不要运行整个 Collection。第 01、08 组可分别使用 Runner，其余按场景逐条执行。

后端原始说明

• 接口与测试场景说明
• 环境变量完整中文说明

本指南按仓库集合和当前 V1.7 协议核对，没有代替用户发送请求或修改服务器。