157 lines
15 KiB
Markdown
157 lines
15 KiB
Markdown
# 黄金矿工 Postman 环境模板中文说明
|
||
|
||
对应文件：[环境模板](gold-miner.postman_environment.json)、[接口 Collection](gold-miner.postman_collection.json)。下面覆盖模板中的全部变量，变量名保持英文，便于与 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：下单、领取、金币保存、过期场景分别有不同前置条件。具体顺序见 [接口使用说明](gold-miner.README.md)。
|
||
|
||
## 二、地址与身份信息
|
||
|
||
| 变量 | 中文含义 | 谁来填 / 何时需要 | 填写方式 |
|
||
| --- | --- | --- | --- |
|
||
| `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.publish.example.json)，只复制其中 `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 接口使用说明](gold-miner.README.md)。
|