97 lines
7.9 KiB
Markdown
97 lines
7.9 KiB
Markdown
# 测试环境临时期
|
||
|
||
用于在周一至周三联调，或把一期缩短到几分钟测试到期补发。不会修改正式周历，也不会修改服务器时钟。只有同时设置以下服务端环境变量才启用：
|
||
|
||
```text
|
||
PAYMENT_APP_ENV=test
|
||
GOLD_MINER_TEST_PERIODS_ENABLED=true
|
||
```
|
||
|
||
缺失任意一个条件，管理发布返回 `TEST_PERIOD_DISABLED`，活动信息和公共日程不选取临时期；临时期的进度、领奖、确认、支付履约也会拒绝。客户端传同名参数不能打开功能。测试服使用独立数据库和支付配置，`PAYMENT_APP_ENV=test` 是本项目的订单环境标识，不会自动把微信支付变成沙箱支付或免付费。
|
||
|
||
## 发布
|
||
|
||
请求：`POST /goldMiner/admin`，`Content-Type: application/json`，需提供该环境管理接口配置的管理员口令。完整请求体见 [test-period.publish.example.json](test-period.publish.example.json)。示例时间为北京时间 **2026-09-21 10:00—11:00**，使用时按实际测试时间修改。
|
||
|
||
| 请求字段 | 必填 | 说明 |
|
||
| --- | --- | --- |
|
||
| action | 是 | 固定 `publish_test_period` |
|
||
| adminToken | 是 | 管理口令，仅供运维使用 |
|
||
| periodId | 是 | `goldMiner:test:` 加 1～60 位字母、数字、下划线或连字符；每期使用独立 ID |
|
||
| startsAt | 是 | Unix 毫秒整数；允许早于发布时间，以便立即开启 |
|
||
| endsAt | 是 | Unix 毫秒整数，严格晚于 startsAt；新发布时也必须晚于服务器当前时间 |
|
||
| nextPeriodId | 否 | 延迟支付无达标奖励时的顺延目标；默认是本期结束时或之后的第一个正常周四。可指定已发布、且开始时间不早于本期结束时间的另一临时期 |
|
||
| config | 是 | 配置对象，包含下表中的商品、门槛、任务参数 |
|
||
|
||
`config` 沿用普通配置校验：
|
||
|
||
| 字段 | 含义 |
|
||
| --- | --- |
|
||
| configVersion | 本次测试配置版本标识 |
|
||
| unlockPassedLevel | 通过多少主线关卡后获得资格，例如 41 |
|
||
| timezone / currency | 固定 `Asia/Shanghai` / `CNY` |
|
||
| productId / priceFen | 商品 ID 和分单位价格，例如 `gold_miner` / 100 |
|
||
| tasks | 按 sequence 从 1 连续排列的任务；targetWins 严格递增；items 为正整数金币奖励 |
|
||
|
||
临时期不需要传 `effectiveFromPeriodId`、`publishedAt`，服务端分别使用临时期 ID 和真实发布时间。完整配置直接冻结在临时期中，不依赖提前发布普通周配置。
|
||
|
||
成功返回 `code:1`，data 包括 `periodId/startsAt/endsAt/nextPeriodId/nextStartsAt/configVersion/configSnapshot/configHash`。`configSnapshot.publishedAt` 是实际发布时间，开始时间早于发布时不会伪造发布时间。
|
||
|
||
同一 ID、同一内容重复发布返回原记录；修改已发布的时间、奖励或顺延目标会被拒绝。新临时期不能与已有临时期重叠，相邻期可以首尾相接；并发发布也做原子重叠检查。需要测试新的奖励组合时，创建不重叠的新期。测试排期最多保留 100 期，达到上限后使用新的独立测试数据库，不能删除仍有关联订单/补发的历史期记录。
|
||
|
||
## 立即开一场 30 分钟测试
|
||
|
||
可直接导入独立的 [Postman Collection](postman/gold-miner-test-period.postman_collection.json) 和 [环境模板](postman/gold-miner-test-period.postman_environment.json)，用法见 [Postman 说明](postman/gold-miner-test-period.README.md)。文件内已包含自动生成时间、重试复用和响应断言，无需手动粘贴下面的脚本。
|
||
|
||
在 Postman 为一个独立管理请求添加下面的 Pre-request Script，把 Body 设为 raw JSON `{{goldMinerTemporaryBody}}`。环境中先填写 `adminToken`。脚本首次生成并缓存请求体，后续重试复用相同时间和期 ID；要新建另一场，先等旧场结束，再清除环境变量 `goldMinerTemporaryBody`。本机时间应与服务器同步。
|
||
|
||
```javascript
|
||
if (!pm.environment.get('goldMinerTemporaryBody')) {
|
||
const startsAt = Date.now();
|
||
pm.environment.set('goldMinerTemporaryBody', JSON.stringify({
|
||
action: 'publish_test_period',
|
||
adminToken: pm.environment.get('adminToken'),
|
||
periodId: 'goldMiner:test:' + startsAt,
|
||
startsAt,
|
||
endsAt: startsAt + 30 * 60 * 1000,
|
||
config: {
|
||
configVersion: 'temporaryV1', unlockPassedLevel: 41,
|
||
timezone: 'Asia/Shanghai', currency: 'CNY',
|
||
productId: 'gold_miner', priceFen: 100,
|
||
tasks: [1, 2, 3].map((targetWins, i) => ({
|
||
taskId: 'task_' + (i + 1), sequence: i + 1, targetWins,
|
||
items: [{type: 'coin', count: (i + 1) * 100}]
|
||
}))
|
||
}
|
||
}));
|
||
}
|
||
```
|
||
|
||
缓存请求体含管理口令，仅保留在本地测试环境，不要分享或提交导出的含密钥环境文件。
|
||
|
||
## 运行与验证
|
||
|
||
- 临时期开放区间为 `startsAt <= 服务端当前时间 < endsAt`。它生效时优先于普通周活动，结束后恢复正常周历选期；周一至周三没有其他临时期时恢复 unavailable。正常周期开关和已有玩家记录保持独立。
|
||
- `activityConfig/list` 返回临时期公共日程；临时期正在开放时隐藏同一时刻的普通周活动条目，避免列表和 info 选择不同。开始/结束边界要求重新获取日程。临时期结束后，info 可能返回普通周期或 unavailable，补发仍通过 settlements 查询。
|
||
- 前端必须把服务端返回的 `periodId` 当作完整标识原样传回；不要自行按日期计算、截取或校验成周四格式。主线/无尽通关仍通过 userLevel 提交，资格关卡本身不计入，没有付费也照常累计。
|
||
- 两种支付渠道都冻结本期的自定义时间。测试模式不跳过鉴权、支付验签、商品金额或付费解锁。旧渠道订单的购买开关按订单所属期检查。
|
||
- 到 endsAt 停止新进度、新下单和手动领奖；手动领取返回 `PERIOD_SETTLEMENT_REQUIRED`。已有发货授权仍按原 grantId 确认，未完成部分进入补发。
|
||
- goldMiner/jobs 仍每分钟处理到期状态，不保证截止瞬间完成结算。客户端先查询 settlements，pending_delivery 时按未确认奖励发货并确认；有 nextCursor 就继续翻页（包括 settling），扫描结束后从第一页复查，仍在 settling 时稍后重查；no_pending_rewards 表示当前无待发或待结算记录。前端不传 limit；金币协议不变。
|
||
- 延迟支付有达标奖励时结算原临时期；无达标奖励时顺延一次。要联调短周期顺延，**先发布下一临时期，再发布当前期并指定 nextPeriodId**。下一临期开启后立即激活预留资格，不再展示购买按钮。
|
||
- 等所有临时期订单、顺延和补发处理完成后再关闭临时期开关，否则未完成的临时期处理会被拒绝。不得修改或删除已有排期来提前结束活动；需要测试到期时，发布前设定较短时长。
|
||
|
||
## 存储与部署
|
||
|
||
仍只使用 `activityConfigs` 和 `goldMinerPlayerPeriods`，不新增集合。测试排期在 activityConfigs 中使用 `activityId=goldMiner, recordType=testSchedule` 的独立记录，以 revision 原子追加；不会被普通 version 查询选中。玩家期、订单和发货标识沿用原结构。
|
||
|
||
本次需发布的函数：
|
||
|
||
1. `goldMiner/config` → 新增内部模块 `goldMiner/testPeriods`（连同 YAML，methods 为空）。
|
||
2. `goldMiner/service`、`goldMiner/payment`、`goldMiner/merchant`、`goldMiner/legacyPayment`、`goldMiner/admin`。
|
||
3. `activityConfig/list`，使首页公共活动日程与玩法选期同步。
|
||
|
||
已有 goldMiner/index、userLevel、各支付入口和 goldMiner/jobs 通过共享模块使用新逻辑；保持每分钟触发器有效。本次不需要迁移已有数据或新增索引，不自动部署或启用测试服开关。
|
||
|
||
|
||
测试临时期发布请求也支持顶层布尔值 enabled，默认 true，保存于 testSchedule.periods 中对应期条目的外层。false 阻止新参与，保留已参与者和已分配付费权益；不替代 PAYMENT_APP_ENV / GOLD_MINER_TEST_PERIODS_ENABLED 两个测试环境开关。
|