15 KiB
黄金矿工 Postman 环境模板中文说明
对应文件：环境模板、接口 Collection。下面覆盖模板中的全部变量，变量名保持英文，便于与 Postman 界面逐项对照。
不需要把所有变量填满。 先选择导入的环境，再按要执行的场景填写；自动变量保持空白，由请求脚本生成。表格中的“留空”是空字符串，不是填写 null 或“空”。变量值填在 Postman 环境的 Value 栏，通常不额外加引号；JSON 配置则填写完整 JSON 对象。
一、先看你要做什么
| 操作 | 最少需要填写 | 执行位置 |
|---|---|---|
| 查看所有活动日程 | baseUrl | 第 08 组，GET 或 POST 均可，无需登录 |
| 查看当前玩家的黄金矿工状态 | baseUrl、uid、token | 第 01 组第 01 项 |
| 临时开启一场 30 分钟活动 | baseUrl、adminToken；保留临时期默认参数 | 第 06 组第 04 项 |
| 发布未来正常周活动配置 | baseUrl、adminToken、configJson | 第 06 组第 02 项 |
| 测试主线通关统计 | 先查询活动及主线存档，再填 mainLevelAfterWin | 第 02 组第 01 项 |
| 测试无尽通关统计 | 先查询活动及主线存档，再填 mainLevelAfterWin、endlessSequence | 第 02 组第 02 项 |
| 测试领奖与金币保存 | 查询活动后填 claimPeriodId、claimTaskId；授权并读取余额后再填 coinAfterDelivery | 第 04 组按顺序执行 |
| 测试过期补发 | 查询补发并选择授权，读取余额后填 coinAfterDelivery，保存后确认 | 第 05 组配合第 04 组 |
不要一次运行整个 Collection：下单、领取、金币保存、过期场景分别有不同前置条件。具体顺序见 接口使用说明。
二、地址与身份信息
| 变量 | 中文含义 | 谁来填 / 何时需要 | 填写方式 |
|---|---|---|---|
baseUrl |
后端服务地址 | 手动，所有请求必填 | 填实际测试服域名，如 https://你的测试服域名；带 https，不带末尾 /，不拼接口路径。模板中的 <APPID> 必须替换 |
uid |
玩家 ID | 手动，玩家接口需要 | 从真实测试账号登录结果取得，对应 users 账号，不填 openid |
token |
玩家登录凭证 | 手动，玩家接口需要 | 填该 uid 当前有效的登录 token；过期后更新 |
adminToken |
管理员口令 | 手动，仅第 06 组管理接口需要 | 对应测试服服务端环境变量 ADMIN_TOKEN；不是玩家 token |
openid |
玩家微信标识 | 手动，无效支付签名测试或旧客服消息测试需要 | 填订单所属账号的真实 openid；必须与 uid 对应同一玩家 |
只查询 activityConfig/list 时，uid、token、adminToken 均可留空。发布临时期也不要求玩家 uid/token。
三、活动查询与通关测试
| 变量 | 中文含义 | 填写要求 / 默认值 | 示例或注意事项 |
|---|---|---|---|
expectedStatus |
期望的玩家活动状态 | 手动可选，默认留空 | 填 purchasable 会额外断言当前可购买；留空仅按真实状态检查结构 |
expectedProgressWins |
期望累计胜利数 | 手动可选，默认留空 | 如 0、3；填 0 表示要求进度确实为零，不等于留空 |
expectedListedPeriodId |
期望公共日程中存在的黄金矿工期 ID | 手动可选，第 08 组使用 | 复制目标期 ID；目标必须处于接口的当前或未来七天窗口。它不表示玩家已经解锁 |
mainLevelAfterWin |
本次胜利保存后的主线通关数 | 手动，通关测试需要 | 主线填 currentMainLevel + 1，例如 41 → 42；无尽填 currentMainLevel，保持主线数不变 |
endlessSequence |
无尽胜利序号 | 手动，无尽测试需要 | 正整数，例如 1；同账号同一期的新胜利不能复用已上报序号；原事件重试使用原请求 |
expectedProgressResult |
本次通关预期计数结果 | 默认 counted |
可选 counted、qualification、capped，含义见下表 |
expiredPeriodId |
用于测试截止规则的历史期 ID | 手动，过期通关或过期领奖测试需要 | 填一个确实已经结束的普通期或临时期 ID，原样复制，不填日期时间戳 |
expectedStatus 的取值：
| 值 | 中文含义 |
|---|---|
unavailable |
当前不开放，或没有适用配置 |
locked |
玩家还未达到参与门槛 |
purchasable |
玩家已达门槛、尚未付费，可购买 |
purchase_disabled |
玩家尚未付费，管理员停止了新购买；活动进度仍可累计 |
unlocked |
玩家本期付费权益已解锁 |
expectedProgressResult 的取值：
| 值 | 中文含义 | 使用条件 |
|---|---|---|
counted |
本次胜利计入活动 | 默认场景；已具备资格，且进度未封顶 |
qualification |
本次通过资格关，本关不计入活动 | 默认门槛 41 时，原存档为 40，本次主线保存为 41 |
capped |
活动进度已达上限，本次不增加 | 已完成最高目标，例如最高要求 10 次且现有进度已为 10 |
这些 expected 开头的变量只是 Postman 断言预期，不会修改服务端状态，也不会给玩家解锁或增加进度。切换测试场景时及时更新或清空。
四、支付测试
| 变量 | 中文含义 | 填写要求 / 默认值 | 示例或注意事项 |
|---|---|---|---|
expectedPaymentState |
期望订单支付状态 | 默认 pending |
未支付保持 pending；实际可信支付已确认后改为 paid |
expectedFulfillmentRoute |
期望权益履约路线 | 默认 current_period，paid 查单时使用 |
current_period 为解锁原活动期；settle_original 为延迟支付后结算原期；carry_next 为顺延到下一目标期 |
expectedTargetPeriodId |
期望实际解锁的目标期 ID | 手动，paid 查单时必填 | 正常支付/原期结算填原期 ID；顺延填实际下一期 ID，可能是正常周四期或指定临时期 |
allowCustomerMessage |
是否允许客服测试请求真实发送消息 | 默认 false |
只有主动准备测试客服发链接时改为 true；还需有效微信客服会话、openid 及服务端签发票据 |
把 expectedPaymentState 改为 paid 只会改变断言，不会使订单实际支付。支付需由真实支付流程和可信通知确认。Android、iOS 原生渠道与旧客服渠道应按各自场景选择，不能把不同渠道的同一期订单随意混用。
五、领取、金币保存与补发
| 变量 | 中文含义 | 谁来填 / 何时需要 | 填写方式 |
|---|---|---|---|
claimPeriodId |
本次处理奖励所属的期 ID | 活动内手动选择；补发选择请求会自动填入 | 从 info 或补发结果复制；可以是历史期，不会被新的 info 查询覆盖 |
claimTaskId |
本次处理的任务 ID | 活动内手动选择；补发选择请求会自动填入 | 从任务列表复制，例如 task_1，不是序号 1 |
coinAfterDelivery |
发放本次奖励后的金币总余额 | 手动，取得授权并读取余额后填写 | 原余额 500、本次奖励 100，则填 600；不是填奖励增量 100 |
settlementId |
本次处理的补发结算标识 | 从补发结果选择；05-05 会自动填入 | 使用接口返回的 settlementId，不是 periodId，也不是数据库文档的 _id |
活动内按“授权 → 读取余额 → 填总余额并保存 → 确认领取”执行。活动过期后从补发列表取得原 grantId，保存后使用 confirm_settlement_delivery 确认，不再调用普通 claim。
如果奖励已经由真实客户端发放，不要在 Postman 再加一次金币。保存超时也不能直接重复累加，应先核对余额与原授权。脚本保存的 gmSavedGrantId 用于阻止未保存就确认，不应手动伪造。
六、普通周配置管理
| 变量 | 中文含义 | 填写要求 | 填写方式 |
|---|---|---|---|
configJson |
普通周活动完整业务配置 | 手动，仅第 06-02 使用，默认空 | 填 JSON 对象，包含 configVersion、effectiveFromPeriodId、门槛、价格和 tasks；不要粘贴外层 action/adminToken/config 包装 |
adminPeriodId |
要调整购买开关的期 ID | 手动，第 06-03 使用 | 复制有效普通期或已发布临时期 ID |
purchaseEnabled |
是否允许该期新购买 | 手动，第 06-03 使用 | 填文本 true 或 false，脚本会转成 JSON 布尔值；不填“是/否”或 1/0 |
configJson 可以参考 普通周配置请求示例，只复制其中 config 对象，并把生效期改为未来周四。普通周配置必须提前发布；立即测试使用下一节的临时期参数。
七、测试临时期配置
用于第 06-04。测试服必须在服务端同时配置 PAYMENT_APP_ENV=test、GOLD_MINER_TEST_PERIODS_ENABLED=true；在 Postman 新建同名环境变量不能开启服务端功能。
| 变量 | 中文含义 | 填写要求 / 默认值 | 示例或注意事项 |
|---|---|---|---|
tempPeriodId |
临时期的唯一 ID | 默认空，首次自动生成；也可手填 | 如 goldMiner:test:debug01。发布后重复发送复用该 ID |
tempStartsAt |
临时期开始时间 | 默认空，首次使用本机当前时间并保存 | 手填 Unix 毫秒整数，不填日期字符串或秒数；允许早于发布时间，以便立即开启 |
tempEndsAt |
临时期结束时间 | 默认空，首次按开始时间加持续分钟数生成并保存 | 必须晚于开始时间；新发布时也必须晚于服务端当前时间 |
tempDurationMinutes |
自动计算结束时间时的持续分钟数 | 默认 30，正整数 |
仅 tempEndsAt 留空时生效；改为 10 不会覆盖已经保存的结束时间 |
tempNextPeriodId |
延迟支付的顺延目标期 | 可选，默认空 | 留空使用本期结束时或之后的第一个正常周四；指定临时期时，须先发布下一期且其开始时间不早于本期结束时间 |
tempConfig |
临时期完整业务配置 JSON | 模板已填默认配置，可发送前修改 | 资格 41 关、价格 100 分、目标 1/2/3 次胜利、奖励 100/200/300 金币；不含外层 action/adminToken |
tempDraftBaseUrl |
自动生成临时配置时的服务器地址 | 自动维护，首次留空 | 用于阻止切换服务器后误用旧期次；不要手填来跳过检查 |
默认只填 baseUrl/adminToken，再发送 06-04，就会生成一场持续 30 分钟的测试活动。生成的 ID 和时间写回环境，重试不会自动换一期。自动时间来自本机，本机时钟应与服务器同步。
要新开另一场，使用新的 ID 与不重叠的起止时间；或在旧场结束后清空 tempPeriodId/tempStartsAt/tempEndsAt 再自动生成。已发布期的时间、奖励和顺延目标不能改。更换测试服建议复制一份新环境；手工清理时还需清空 tempDraftBaseUrl。
八、脚本自动维护的变量
以下变量首次导入时都应留空。它们用于保存接口结果、去重参数和发货凭证，不是用来手工初始化玩家数据的。
| 变量 | 中文含义 | 由哪一步生成 / 用途 |
|---|---|---|
gmContext |
当前测试上下文 | 记录 baseUrl 和 uid，用于发现应用或账号切换并清理旧状态 |
gmInfo |
完整的玩家活动查询结果 | 第 01-01 info 成功后保存，供通关、下单等脚本检查前置状态 |
periodId |
当前玩家活动期 ID | info 自动保存；不是临时期发布时用的 tempPeriodId，也不是历史领奖目标 claimPeriodId |
productId |
活动商品 ID | 从 info 取得，例如 gold_miner，用于下单 |
priceFen |
活动解锁价格，单位分 | 从 info 取得，用于检查服务端下单价格是否一致 |
firstTaskId |
第一档任务 ID | 从 info 的任务数组取得 |
secondTaskId |
第二档任务 ID | 从 info 取得；只有一档时为空 |
currentMainLevel |
当前已保存的主线通关数 | 第 01-02 读取主线存档后保存，计算下一关测试值前应重新读取 |
gmWinBefore |
本次通关前的活动进度 | 新胜利请求准备时保存，用于检查进度是否增加 1 |
gmWinBody |
本次通关的完整原始请求 JSON | 新胜利请求生成，用于复用 eventId、期 ID、模式及序号；含玩家 token，属于敏感数据 |
gmWinAfter |
本次通关后的活动进度 | 通关返回后保存，原事件重试时据此检查没有重复增加 |
outTradeNo |
当前测试订单号 | 下单或旧客服预下单成功后保存，用于查单和转单 |
orderPeriodId |
当前订单所属期 ID | 下单时保存；活动切换后也不能用新期替换旧订单所属期 |
gmGrant |
当前选择的奖励授权及状态 | claim 成功或选择补发奖励后生成，含原授权 ID、奖励和所属任务信息 |
grantId |
当前奖励授权 ID | 从 claim 或补发结果取得；保存与确认必须使用同一授权 |
coinBeforeDelivery |
本次发奖前读取的金币总余额 | 第 04-03 读取金币后保存，用于校验 coinAfterDelivery |
gmSavedGrantId |
已成功保存金币的授权 ID | 第 04-04 保存成功且金额匹配后写入；确认请求检查它与当前 grantId 一致 |
settlementCursor |
补发查询下一页游标 | 每次成功响应时更新（包括 settling）；为空时本轮无下一页，仍有待处理状态时重新查询第一页；no_pending_rewards 时结束 |
legacySessionFrom |
旧客服支付会话票据 | 客服预下单成功后取得，用于客服请求；属于敏感数据 |
gmActivitySchedule |
完整的公共活动日程缓存 | 第 08 组成功且结构校验通过后保存；失败保留原缓存，不覆盖玩家 periodId 或领奖凭证 |
其中 gmActivitySchedule 是公共日程，gmInfo 是玩家私有状态。列表出现活动不等于该玩家已经达到门槛、付费或可以领奖。
九、常见填写问题
- 普通配置与临时配置放错位置：configJson 用于普通周配置，tempConfig 用于临时期。两者都只填业务配置对象，不能把整个管理请求粘进去。
- 把预期当成修改操作：expectedStatus、expectedPaymentState 等只影响测试断言，不能改变玩家或订单状态。
- 临时期仍然是旧时间：tempStartsAt/tempEndsAt 已被首次请求保存。重复 Send 是重试原期；新建期须更换 ID 和时间。
- 接口被跳过：前置脚本缺少变量，或检测到切换应用/账号时，会停止发送。查看 Postman Console 提示；跳过不代表接口测试通过。切换后重新查询活动和存档。
- 人民币与金币混淆：priceFen=100 表示 1 元解锁价；items 中 count=100 表示奖励 100 金币；coinAfterDelivery 则是发完奖励后的金币总余额。
- 分享环境文件：token/adminToken/gmWinBody/legacySessionFrom 被标记为 secret，但运行后的环境仍可能含实际凭证。分享前清空敏感值，最好分享仓库中的空白模板。
完整请求步骤、接口参数和返回字段见 Postman 接口使用说明。