123 lines
9.0 KiB
Markdown
123 lines
9.0 KiB
Markdown
# 黄金矿工 Postman 操作指南
|
||
|
||
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. 导入文件
|
||
|
||
在 Postman 点击 Import，导入仓库内这两个文件（避免继续使用下载目录中的旧副本）：
|
||
|
||
- [gold-miner.postman_collection.json](../server/laf-cloud/functions/goldMiner/postman/gold-miner.postman_collection.json)：接口及测试脚本。
|
||
- [gold-miner.postman_environment.json](../server/laf-cloud/functions/goldMiner/postman/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，其余按场景逐条执行。
|
||
|
||
## 后端原始说明
|
||
|
||
- [接口与测试场景说明](../server/laf-cloud/functions/goldMiner/postman/gold-miner.README.md)
|
||
- [环境变量完整中文说明](../server/laf-cloud/functions/goldMiner/postman/gold-miner.environment.zh-CN.md)
|
||
|
||
本指南按仓库集合和当前 V1.7 协议核对，没有代替用户发送请求或修改服务器。
|