622 lines
36 KiB
Markdown
622 lines
36 KiB
Markdown
# 黄金矿工前端接口文档 V1.3
|
||
|
||
> 历史协议副本（2026-09-30 标注）：仓库最新协议为 [V1.7](../server/laf-cloud/functions/goldMiner/FRONTEND-API.md)。正文保留历史内容，附属链接已修复并指向仓库当前资料；顺序领奖、旧补发等条款不能覆盖当前协议。客户端差异见 [接入说明](GoldMiner接入说明.md)。
|
||
|
||
更新时间：2026-09-18。依据当前 `local` 分支实现编写，包含精简后的 `info` 协议。示例价格、目标和金币仅用于联调，页面必须使用接口返回值。部署环境需具有相同版本的后端代码。
|
||
|
||
## 1. 接入约定与接口总览
|
||
|
||
所有下列请求均使用 **POST + JSON Body**，请求头为 `Content-Type: application/json`。地址前缀 `{{baseUrl}}` 替换为后端提供的测试服或正式服域名；不要将两个环境的账号、订单和 token 混用。部分通用函数配置也允许 GET，但实现读取 `ctx.body`，前端统一使用 POST。
|
||
|
||
| 用途 | 地址 | action |
|
||
| --- | --- | --- |
|
||
| 活动信息、任务状态 | `/goldMiner/index` | `info` |
|
||
| 客服渠道创建活动订单 | `/goldMiner/index` | `create_order` |
|
||
| 申请领取单档奖励 | `/goldMiner/index` | `claim` |
|
||
| 确认客户端已保存奖励 | `/goldMiner/index` | `confirm_delivery` |
|
||
| 查询往期补发列表 | `/goldMiner/index` | `settlements` |
|
||
| 确认补发记录已处理 | `/goldMiner/index` | `ack_settlement` |
|
||
| 通关上报、读取主线进度 | `/userLevel` | `save` / `read` |
|
||
| 保存、读取金币余额 | `/userCoin` | `save` / `read` |
|
||
| 原生支付下单 | `/wx/orderPaySig`；iOS 入口 `/wx/iosorderPaySig` | 不传 |
|
||
| 查询支付及活动权益 | `/wx/getPayInfo`、`/wx/iosgetPayInfo` | 不传 |
|
||
| 兼容旧订单领取入口 | `/wx/getOrderReward` | 不传 |
|
||
| 外部支付页转单 | `/wx/checkIos` | 不传 |
|
||
|
||
`iosorderPaySig.ts` 在仓库中没有配套 YAML，使用该入口前需后端确认测试服已发布同名 POST 云函数；不能仅凭源码存在判断线上可调用。
|
||
|
||
### 公共参数与类型
|
||
|
||
除支付页票据鉴权方式外，游戏端请求均在 Body 中携带以下字段：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| uid | string | 是 | 当前登录玩家 ID，使用 `users` 账号 |
|
||
| token | string | 是 | 当前登录 token；过期后按游戏登录流程刷新 |
|
||
| action | string | 按接口 | `/goldMiner/index`、`userLevel`、`userCoin` 必填 |
|
||
|
||
黄金矿工不支持 `gameName: "iaa"`，游戏端不传此值。无需在 Authorization Header 中重复传 token。
|
||
|
||
时间戳均为 Unix **毫秒**；日期安排按北京时间 `Asia/Shanghai`。活动周四 00:00 开始，下周一 00:00 结束，结束时间为不包含的边界。金额 `priceFen` 单位为分，显示元时除以 100。数量及进度使用整数，布尔值使用 JSON boolean。
|
||
|
||
`periodId` 格式为 `goldMiner:YYYY-MM-DD`，日期必须是该期周四，例如 `goldMiner:2026-09-17`。游戏优先使用服务端返回的期 ID。`eventId`、`requestId`、`createRequestId` 等标识支持 1～100 位英文字母、数字、下划线、冒号及连字符；可使用 UUID。生成后必须随原操作保存，重试时复用。
|
||
|
||
### 返回包装
|
||
|
||
活动接口及黄金矿工支付分支成功结构：
|
||
|
||
```json
|
||
{"code":1,"data":{},"msg":"成功"}
|
||
```
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| code | number | `1` 为业务成功，`0` 为业务失败；不能仅依靠 HTTP 状态判断 |
|
||
| data | object / null | 各接口业务数据；活动标准失败时为 null |
|
||
| msg | string | 提示信息，不作为程序状态判断依据 |
|
||
| errorCode | string | 活动标准失败时返回，用于程序分支 |
|
||
|
||
```json
|
||
{"code":0,"data":null,"errorCode":"NOT_PAID","msg":"NOT_PAID"}
|
||
```
|
||
|
||
例外：`wx/checkIos` 直接返回 `true` / `false`；通用接口的前置校验可能只有 `code/data/msg`、没有 `errorCode`。`userLevel` 和 `userCoin` 的无效 action 返回 `{ "code":400, "message":"无效的操作类型，请使用 save 或 read" }`。网络错误、空响应也需单独处理。
|
||
|
||
## 2. 获取活动信息：info
|
||
|
||
**POST `{{baseUrl}}/goldMiner/index`**
|
||
|
||
请求只有公共参数，`action` 固定为 `info`，不传 periodId。
|
||
|
||
```json
|
||
{"action":"info","uid":"USER_ID","token":"LOGIN_TOKEN"}
|
||
```
|
||
|
||
### data 字段
|
||
|
||
| 字段 | 类型 | 返回条件 | 含义 |
|
||
| --- | --- | --- | --- |
|
||
| serverTime | number | 总是 | 服务器时间，辅助校正倒计时 |
|
||
| status | string | 总是 | 下表中的活动状态 |
|
||
| periodId | string | 总是 | 当前日历对应的活动期 ID |
|
||
| startsAt | number | 除 locked 外 | 该期开始时间 |
|
||
| endsAt | number | 除 locked 外 | 该期结束边界，倒计时到此结束 |
|
||
| configVersion | string | 可展示活动时 | 本期冻结的配置版本，可用于日志排查 |
|
||
| priceFen | number | 可展示活动时 | 本期单次解锁价格，单位分 |
|
||
| productId | string | 可展示活动时 | 下单使用的商品 ID，不要写死 |
|
||
| progressWins | number | 可展示活动时 | 本期累计有效胜利数，上限为 maxTarget |
|
||
| maxTarget | number | 可展示活动时 | 最后一档累计目标 |
|
||
| tasks | array | 总是 | 按领取顺序排好的任务；locked/unavailable 时为空 |
|
||
|
||
“可展示活动时”指 `purchasable`、`purchase_disabled`、`unlocked`。缺省字段不是 0 或 false，不能用上一期缓存填充。
|
||
|
||
| status | 含义 | 前端处理 |
|
||
| --- | --- | --- |
|
||
| unavailable | 非开放时段、无有效配置，或请求期间活动已结束 | 关闭当期购买和领取；往期补发仍可单独查询 |
|
||
| locked | 活动开放，但未满足主线资格门槛 | 不展示可购买任务页；按产品要求展示入口门槛提示 |
|
||
| purchasable | 已获资格，未付费，允许购买 | 展示价格和购买按钮；未付费也累计进度 |
|
||
| purchase_disabled | 已获资格，未付费，本期暂停购买 | 隐藏/禁用购买按钮；仍展示和累计进度 |
|
||
| unlocked | 本期资格已解锁 | 隐藏购买按钮，按任务状态展示领取操作 |
|
||
|
||
默认通过主线第 41 关后获得资格；门槛可由后端配置。info 不返回具体门槛数值，如需显示门槛文案应与活动配置保持一致。`unlocked` 包含正常购买及延期支付顺延生效；前端不需区分来源。
|
||
|
||
### tasks[] 字段
|
||
|
||
| 字段 | 类型 | 含义 |
|
||
| --- | --- | --- |
|
||
| taskId | string | 档位 ID，领取时原样传回；不能拿数组下标替代 |
|
||
| targetWins | number | 本期累计通关目标，例如 3、5、7、9、10 |
|
||
| itemsSnapshot | array | 本档奖励快照，元素字段见下表 |
|
||
| claimStatus | string | locked / claimable / issuing / claimed |
|
||
| completed | boolean | 累计胜利是否达到该档目标，与是否付费、是否可领取无关 |
|
||
| progress | number | `min(progressWins, targetWins)`，是通关数，不是百分比 |
|
||
|
||
| itemsSnapshot[] 字段 | 类型 | 含义 |
|
||
| --- | --- | --- |
|
||
| type | string | 道具类型，当前配置仅支持 `coin`（金币） |
|
||
| count | number | 道具数量，正整数 |
|
||
|
||
保留数组结构以便以后扩展道具。出现客户端暂不支持的道具类型时，不应静默跳过并确认已到账。
|
||
|
||
| claimStatus | 含义 | 操作 |
|
||
| --- | --- | --- |
|
||
| locked | 未付费、目标未达成，或前一档尚未完成到账确认 | 不能领取；即便 completed=true 也可能处于此状态 |
|
||
| claimable | 已付费、已达标且前序档位已确认 | 调用 claim |
|
||
| issuing | 已取得奖励授权，但尚未确认客户端保存成功 | 对同一 periodId/taskId 再调用 claim，恢复原 grantId 的流程 |
|
||
| claimed | 本档客户端到账已经确认 | 展示已领取，不再增加金币 |
|
||
|
||
任务顺序由后端保证，无需 sequence。第一档未领取不阻止后续档累积进度，但第一档完成 `confirm_delivery` 前不能领取第二档。
|
||
|
||
完整示例：本期尚未购买，但已通关 3 次。
|
||
|
||
```json
|
||
{
|
||
"code": 1,
|
||
"data": {
|
||
"serverTime": 1789723456450,
|
||
"status": "purchasable",
|
||
"periodId": "goldMiner:2026-09-17",
|
||
"startsAt": 1789574400000,
|
||
"endsAt": 1789920000000,
|
||
"configVersion": "gold_miner_test_20260917_v1",
|
||
"priceFen": 100,
|
||
"productId": "gold_miner",
|
||
"progressWins": 3,
|
||
"maxTarget": 10,
|
||
"tasks": [
|
||
{"taskId":"task_1","targetWins":3,"itemsSnapshot":[{"type":"coin","count":100}],"claimStatus":"locked","completed":true,"progress":3},
|
||
{"taskId":"task_2","targetWins":5,"itemsSnapshot":[{"type":"coin","count":200}],"claimStatus":"locked","completed":false,"progress":3},
|
||
{"taskId":"task_3","targetWins":7,"itemsSnapshot":[{"type":"coin","count":300}],"claimStatus":"locked","completed":false,"progress":3},
|
||
{"taskId":"task_4","targetWins":9,"itemsSnapshot":[{"type":"coin","count":400}],"claimStatus":"locked","completed":false,"progress":3},
|
||
{"taskId":"task_5","targetWins":10,"itemsSnapshot":[{"type":"coin","count":500}],"claimStatus":"locked","completed":false,"progress":3}
|
||
]
|
||
},
|
||
"msg": "成功"
|
||
}
|
||
```
|
||
|
||
未达门槛时的完整 data：
|
||
|
||
```json
|
||
{"serverTime":1789723456450,"status":"locked","periodId":"goldMiner:2026-09-17","tasks":[]}
|
||
```
|
||
|
||
不可用时的完整 data（示例为周一休息期）：
|
||
|
||
```json
|
||
{"serverTime":1789920000000,"status":"unavailable","periodId":"goldMiner:2026-09-17","startsAt":1789574400000,"endsAt":1789920000000,"tasks":[]}
|
||
```
|
||
|
||
不可用状态下的日期来自活动日历，不能据此认定活动已启用或计算下一期购买资格。
|
||
|
||
## 3. 通关上报：userLevel/save
|
||
|
||
**POST `{{baseUrl}}/userLevel`**。在现有关卡保存请求中附带 `goldMiner`，不要依赖玩家是否打开活动页面或是否付费。每次有效胜利上报一个事件，黄金矿工每个事件加 1，不按 levelAmount 的差值一次增加多关。
|
||
|
||
| 参数 | 类型 | 必填 | 含义 |
|
||
| --- | --- | --- | --- |
|
||
| action | string | 是 | `save` |
|
||
| uid / token | string | 是 | 公共鉴权参数 |
|
||
| levelAmount | number | 是 | 本次保存后的主线通关整值；无尽模式保持现有主线值 |
|
||
| isWuXian | string | 无尽必填 | 无尽传字符串 `"true"`；主线省略。沿用旧协议字符串形式 |
|
||
| goldMiner | object | 活动统计必填 | 不携带则只保存普通关卡，不增加活动进度 |
|
||
| goldMiner.periodId | string | 是 | 本次胜利首次上报对应的活动期；重试不更换 |
|
||
| goldMiner.eventId | string | 是 | 本次胜利的唯一事件 ID；重试保持不变 |
|
||
| goldMiner.outcome | string | 是 | 固定 `win`，失败、放弃不报活动胜利 |
|
||
| goldMiner.mode | string | 是 | `main` 或 `endless`，必须与 isWuXian 对应 |
|
||
| goldMiner.clearedMainLevel | number | 主线必填 | 本次通过的主线关号，正整数且须等于 levelAmount |
|
||
| goldMiner.endlessSequence | number | 无尽必填 | 无尽成功结算序号，正整数；同一胜利重试相同，新胜利使用新序号 |
|
||
|
||
主线示例：
|
||
|
||
```json
|
||
{"action":"save","uid":"USER_ID","token":"LOGIN_TOKEN","levelAmount":42,"goldMiner":{"periodId":"goldMiner:2026-09-17","eventId":"win-main-42","outcome":"win","mode":"main","clearedMainLevel":42}}
|
||
```
|
||
|
||
无尽示例（1000 仅是假设的当前主线通关值）：
|
||
|
||
```json
|
||
{"action":"save","uid":"USER_ID","token":"LOGIN_TOKEN","levelAmount":1000,"isWuXian":"true","goldMiner":{"periodId":"goldMiner:2026-09-17","eventId":"win-endless-123","outcome":"win","mode":"endless","endlessSequence":123}}
|
||
```
|
||
|
||
无尽序号需持久化，并避免同一账号多设备生成冲突序号；不能使用循环复用的关卡模板号。同一期按 eventId 和“模式 + 关号/序号”两层去重：换 eventId 重报同一关也不会再加活动进度。
|
||
|
||
### 返回字段
|
||
|
||
```json
|
||
{"code":1,"data":{"goldMiner":{"code":1,"activityCounted":true,"duplicate":false,"progressWins":1},"IP":"127.0.0.1","address":"其他","rank":-1,"levelAmount":42,"film":42,"timestamp":1789723456450},"msg":"用户数据更新成功"}
|
||
```
|
||
|
||
| data 字段 | 类型 | 含义 |
|
||
| --- | --- | --- |
|
||
| goldMiner | object，可缺省 | 活动处理结果；仅请求携带活动事件时返回 |
|
||
| IP / address | string | 原关卡接口的请求 IP / 地址信息 |
|
||
| rank | number | 原排行处理结果，默认 -1；活动 UI 不依赖 |
|
||
| levelAmount | number | 已保存的主线通关值 |
|
||
| film | number | 原关卡进度相关字段，不是活动进度 |
|
||
| timestamp | number | 本次响应时间 |
|
||
|
||
| data.goldMiner 字段 | 类型 | 含义 |
|
||
| --- | --- | --- |
|
||
| code | number | 活动处理独立结果：1 成功、0 失败 |
|
||
| activityCounted | boolean | 成功时是否新增了 1 次活动胜利 |
|
||
| duplicate | boolean，可缺省 | 成功时是否命中历史事件；资格关分支没有此字段 |
|
||
| progressWins | number | 活动处理成功后的累计胜利数 |
|
||
| reason | string，可缺省 | `qualification_level` 表示本次关号不高于资格门槛，不计入活动 |
|
||
| data / errorCode / msg | null / string / string | 活动失败时使用标准失败包装字段 |
|
||
|
||
活动失败仍可能出现外层 code=1，表示主线保存成功。例如 `data.goldMiner={"code":0,"data":null,"errorCode":"PERIOD_ENDED","msg":"PERIOD_ENDED"}`，不能因此重复推进普通关卡。
|
||
|
||
- 通过第 41 关获得资格，但该次胜利不计；从后续胜利开始计数。开放前的胜利不追溯。
|
||
- 开放前开局、开放期间胜利并成功上报可计；结束后才到达服务端的新事件不补记。已记录事件结束后重试可返回 duplicate=true，但不会新增进度。
|
||
- 达到 maxTarget 后 activityCounted=false；它不一定意味着 duplicate=true。
|
||
- 旧 userLevel 会在与已存主线值相差超过 10 时提前结束，可能没有正常 JSON 返回；应按既有关卡保存约束调用。
|
||
- 活动事件去重不等于整个 userLevel 幂等：重试无尽 save 仍可能影响旧的生涯统计。按现有通关队列管理重试，不能把该接口当作纯活动重试入口无限重放。
|
||
|
||
读取普通主线进度可传 `{"action":"read","uid":"USER_ID","token":"LOGIN_TOKEN"}`；成功 data 为 `levelAmount:number, film:number, timestamp:number`，不返回黄金矿工状态。刷新活动使用 info。
|
||
|
||
## 4. 支付下单与查询
|
||
|
||
### 4.1 原生支付下单
|
||
|
||
**POST `/wx/orderPaySig`** 或 **POST `/wx/iosorderPaySig`**，按项目支付入口选择。
|
||
|
||
| 参数 | 类型 | 必填 | 含义 |
|
||
| --- | --- | --- | --- |
|
||
| uid / token | string | 是 | 公共鉴权参数 |
|
||
| itemid | string | 是 | info.productId，注意参数名为小写 itemid |
|
||
| createRequestId | string | 是 | 本次创建订单请求标识，重试复用 |
|
||
|
||
```json
|
||
{"uid":"USER_ID","token":"LOGIN_TOKEN","itemid":"gold_miner","createRequestId":"buy-20260917-001"}
|
||
```
|
||
|
||
不需传 periodId、价格或数量，后端绑定当前开放期、冻结价格和数量 1。即使传入 itemPrice/itemCount，也不能修改活动价格或数量。
|
||
|
||
| 成功 data 字段 | 类型 | 含义 |
|
||
| --- | --- | --- |
|
||
| outTradeNo | string | 后端订单号，持久化用于查询和恢复 |
|
||
| signData | string | 原生支付签名原文，是 JSON 字符串；完整保留，不修改或解析后重新序列化 |
|
||
| signature | string | 玩家会话签名，交给现有原生支付流程 |
|
||
| paySig | string | 支付签名，交给现有原生支付流程 |
|
||
|
||
返回结构示例（签名内容仅为占位，不能用于实际支付）：
|
||
|
||
```json
|
||
{"code":1,"data":{"outTradeNo":"ORDER_NO_FROM_CREATE","signData":"SIGNED_JSON_STRING_FROM_SERVER","signature":"SESSION_SIGNATURE_FROM_SERVER","paySig":"PAY_SIGNATURE_FROM_SERVER"},"msg":"成功"}
|
||
```
|
||
|
||
测试服与正式服隔离不等于免费支付沙箱；当前原生签名使用支付环境 env=0，联调支付应使用后端确认的测试商品和金额。
|
||
|
||
同环境、账号、期次只创建一个稳定订单；重试或更换 createRequestId 不会创建第二笔活动订单。不要在重试时切换原生/客服渠道，已有另一渠道订单会报 PAYMENT_CHANNEL_CONFLICT。
|
||
|
||
### 4.2 客服渠道下单
|
||
|
||
**POST `/goldMiner/index`**。
|
||
|
||
```json
|
||
{"action":"create_order","channel":"legacy_ios","uid":"USER_ID","token":"LOGIN_TOKEN","itemid":"gold_miner","createRequestId":"buy-20260917-001"}
|
||
```
|
||
|
||
参数与原生下单相同，另外必填 `action:"create_order"` 和 `channel:"legacy_ios"`。成功 data：
|
||
|
||
| 字段 | 类型 | 含义 |
|
||
| --- | --- | --- |
|
||
| outTradeNo | string | 本期稳定订单号 |
|
||
| periodId | string | 订单所属期 |
|
||
| priceFen | number | 订单价格，分 |
|
||
| productId | string | 商品 ID |
|
||
| quantity | number | 固定 1 |
|
||
| channel | string | 固定 legacy_ios |
|
||
| expiresAt | number | 本次客服票据到期时间，最长 15 分钟且不超过活动结束 |
|
||
| sessionFrom | string | 已签名的客服入口参数字符串，原样传入现有 `wx.openCustomerServiceConversation` 的 sessionFrom |
|
||
|
||
返回结构示例（sessionFrom 为不可手工生成的占位字符串）：
|
||
|
||
```json
|
||
{"code":1,"data":{"outTradeNo":"ORDER_NO_FROM_CREATE","periodId":"goldMiner:2026-09-17","priceFen":100,"productId":"gold_miner","quantity":1,"channel":"legacy_ios","expiresAt":1789724356450,"sessionFrom":"SIGNED_SESSION_FROM_SERVER"},"msg":"成功"}
|
||
```
|
||
|
||
不要自己拼接 sessionFrom、修改内部字段或把登录 token 放进支付页 URL。票据到期且活动仍开放时，可重新调用 create_order 获取新票据，订单号保持稳定。客服网关处理后给玩家发送支付页链接；游戏端不直接调用 `wx/KeFu` 模拟客服事件。
|
||
|
||
### 4.3 查询支付结果和权益
|
||
|
||
**POST `/wx/getPayInfo`** 或 **POST `/wx/iosgetPayInfo`**。兼容入口 **POST `/wx/getOrderReward`** 对黄金矿工也返回同一协议，不直接发金币。
|
||
|
||
```json
|
||
{"uid":"USER_ID","token":"LOGIN_TOKEN","outTradeNo":"ORDER_NO_FROM_CREATE"}
|
||
```
|
||
|
||
三个参数均为必填 string，不需 action。原生支付以已验证的服务端通知为依据；客服渠道还会按后端节流策略主动查单。客户端支付成功回调只用于触发查询，不能代替服务端确认。
|
||
|
||
| 成功 data 字段 | 类型 | 含义 |
|
||
| --- | --- | --- |
|
||
| pay_state | number | 黄金矿工成功固定为 2，表示支付及权益已确认，不表示所有任务已领奖 |
|
||
| rewardDelivery | string | 固定 `goldMiner.claim`，后续逐档领取 |
|
||
| goldMiner | object | 当前订单的活动元数据，完整字段见下面两表 |
|
||
|
||
`goldMiner` 目前为订单快照直出，比 info 字段多。前端主要使用 `fulfillmentRoute` 和 `targetPeriodId`，其余字段供核对日志，不用于自行计算领取资格。
|
||
|
||
| goldMiner 字段 | 类型 | 含义 |
|
||
| --- | --- | --- |
|
||
| schemaVersion | number | 当前 1 |
|
||
| uid / accountScope | string | 所属玩家 / 固定 users |
|
||
| paymentChannel | string | native 或 legacy_ios |
|
||
| periodId | string | 原购买期 |
|
||
| startsAt / endsAt | number | 原购买期时间边界 |
|
||
| configVersion / configHash | string | 订单绑定配置版本 / 哈希 |
|
||
| productSnapshot | object | `productId:string`、`priceFen:number`，订单冻结商品信息 |
|
||
| createRequestId | string | 首次建单请求标识 |
|
||
| confirmedAt | number | 服务端确认支付的毫秒时间 |
|
||
| fulfillmentStatus | string | 成功响应中为 fulfilled；处理中/失败通过错误响应表示 |
|
||
| fulfillmentRoute | string | current_period / settle_original / carry_next，见下表 |
|
||
| targetPeriodId | string | 实际分配权益的目标期 |
|
||
| revision | number | 内部版本字段，前端无需参与维护 |
|
||
| entitlementId | string | 已分配权益记录 ID |
|
||
| fulfilledAt | number | 权益处理完成时间 |
|
||
| lastErrorCode | string，可缺省 | 曾经处理失败的原因，成功后可能仍保留，不能覆盖当前成功结论 |
|
||
| nextRetryAt | number，可缺省 | 曾设置的后端重试时间，同样可能是历史值 |
|
||
|
||
客服订单还可能携带以下字段；按实际存在读取，前端不需回传：
|
||
|
||
| goldMiner 字段 | 类型 | 含义 |
|
||
| --- | --- | --- |
|
||
| merchantSnapshot | object | `mchid/appid/notifyUrl/pageUrl/checkUrl` 均为 string：商户及接入地址快照 |
|
||
| prepayState | string | created / creating / ready / paid / closed；成功支付后为 paid |
|
||
| prepayId / prepayExpiresAt | string / number | 预支付 ID / 到期时间，可缺省 |
|
||
| ioLeaseUntil / ioLeaseToken | number / string | 后端并发处理锁信息，token 可缺省，不是玩家鉴权 token |
|
||
| nextQueryAt / queryAttempts | number | 后端下次查单时间 / 查单次数 |
|
||
| lastQueryError | string / null | 最近查单错误，可缺省 |
|
||
| transactionId | string | 微信交易号 |
|
||
| paidAt | number | 支付平台记录的支付成功时间 |
|
||
| confirmationSource | string | merchant_notify 或 merchant_query，支付确认来源 |
|
||
|
||
| fulfillmentRoute | 含义 | 前端下一步 |
|
||
| --- | --- | --- |
|
||
| current_period | 权益分配到原购买期 | 重新 info；若此时已结束则查询 settlements |
|
||
| settle_original | 延迟支付确认时原期已结束，存在达标奖励 | 查询 settlements，按原期逐档补发 |
|
||
| carry_next | 延迟支付确认时原期无可结算奖励，资格顺延下一期 | 提示目标期生效；目标期开放后 info 返回 unlocked，无需再买 |
|
||
|
||
原生订单正常解锁的完整响应示例（标识和哈希为占位）：
|
||
|
||
```json
|
||
{
|
||
"code": 1,
|
||
"data": {
|
||
"pay_state": 2,
|
||
"rewardDelivery": "goldMiner.claim",
|
||
"goldMiner": {
|
||
"schemaVersion": 1,
|
||
"uid": "USER_ID",
|
||
"accountScope": "users",
|
||
"paymentChannel": "native",
|
||
"periodId": "goldMiner:2026-09-17",
|
||
"startsAt": 1789574400000,
|
||
"endsAt": 1789920000000,
|
||
"configVersion": "gold_miner_test_20260917_v1",
|
||
"configHash": "CONFIG_HASH_FROM_SERVER",
|
||
"productSnapshot": {"productId":"gold_miner","priceFen":100},
|
||
"createRequestId": "buy-20260917-001",
|
||
"confirmedAt": 1789723456450,
|
||
"fulfillmentStatus": "fulfilled",
|
||
"fulfillmentRoute": "current_period",
|
||
"targetPeriodId": "goldMiner:2026-09-17",
|
||
"revision": 0,
|
||
"entitlementId": "ENTITLEMENT_ID_FROM_SERVER",
|
||
"fulfilledAt": 1789723456500
|
||
}
|
||
},
|
||
"msg": "活动权益已确认"
|
||
}
|
||
```
|
||
|
||
权益只顺延到紧邻的下一期，不无限滚动。查询成功不代表应一次发放全部任务金币。遇到 PAYMENT_PENDING 可间隔重试原订单查询；网络失败也保存订单号，登录恢复后继续查询，不能直接重新付款。建议有限次数退避轮询，离开支付流程后停止高频请求。
|
||
|
||
### 4.4 外部支付页转单：checkIos
|
||
|
||
**POST `/wx/checkIos`**。由现有 order3.html 处理，普通活动页面通常无需主动调用。
|
||
|
||
支付页票据方式：
|
||
|
||
```json
|
||
{"openid":"ORDER_OWNER_OPENID","time":"HANDOFF_TICKET_FROM_PAYMENT_LINK","outTradeNo":"ORDER_NO_FROM_CREATE"}
|
||
```
|
||
|
||
| 参数 | 类型 | 必填 | 含义 |
|
||
| --- | --- | --- | --- |
|
||
| openid | string | 票据方式必填 | 支付页链接携带的订单所属 openid |
|
||
| time | string | 票据方式必填 | 链接携带的 handoff 签名票据，不是时间戳，不是 sessionFrom 中的客服票据 |
|
||
| outTradeNo | string | 是 | 原订单号 |
|
||
| uid / token | string | 游戏鉴权方式必填 | 游戏端也可只用 uid、token、outTradeNo 调用，替代 openid/time |
|
||
|
||
返回 JSON boolean：`true` 表示订单关联/兼容转单成功，`false` 表示校验或处理失败；不返回 code。**true 不表示已支付，更不表示已发奖**。之后仍由游戏端调用支付查询接口。支付通知接口 `goldMiner/merchantNotify`、原生支付回调和管理接口不属于前端调用范围。
|
||
|
||
## 5. 奖励申请、金币保存与确认
|
||
|
||
### 5.1 申请奖励：claim
|
||
|
||
**POST `/goldMiner/index`**。
|
||
|
||
```json
|
||
{"action":"claim","uid":"USER_ID","token":"LOGIN_TOKEN","periodId":"goldMiner:2026-09-17","taskId":"task_1","requestId":"claim-20260917-task1"}
|
||
```
|
||
|
||
| 参数 | 类型 | 必填 | 含义 |
|
||
| --- | --- | --- | --- |
|
||
| action | string | 是 | claim |
|
||
| uid / token | string | 是 | 公共鉴权参数 |
|
||
| periodId | string | 是 | 奖励所属期，补发必须使用旧期 ID |
|
||
| taskId | string | 是 | info 或补发记录提供的档位 ID |
|
||
| requestId | string | 是 | 本次领取请求标识，重试复用 |
|
||
|
||
```json
|
||
{"code":1,"data":{"grantId":"GRANT_ID_FROM_SERVER","taskId":"task_1","items":[{"type":"coin","count":100}],"claimStatus":"issuing","claimedThrough":0,"requiresClientDelivery":true},"msg":"成功"}
|
||
```
|
||
|
||
| data 字段 | 类型 | 含义 |
|
||
| --- | --- | --- |
|
||
| grantId | string | 服务端稳定的本档发奖标识，用它对客户端到账去重 |
|
||
| taskId | string | 本次档位 |
|
||
| items | array | 本次授权道具，元素为 type:string、count:number；金币数量以此为准 |
|
||
| claimStatus | string | issuing 或 claimed，与 info 的四态枚举范围不同 |
|
||
| claimedThrough | number | 已按顺序完成到账确认的档位数；此接口仍保留 |
|
||
| requiresClientDelivery | boolean | true 表示服务端尚未确认到账；false 表示已确认，不再加金币 |
|
||
|
||
同账号、期次和档位重复 claim 返回同一 grantId，更换 requestId 也不会产生第二份授权。`requiresClientDelivery=true` 不代表客户端肯定还未加金币，也可能是金币已保存但确认请求失败，必须结合本地交付记录恢复。
|
||
|
||
### 5.2 金币保存：userCoin
|
||
|
||
**POST `/userCoin`**。继续沿用游戏现有金币流程，后端不直接加金币。
|
||
|
||
| 参数 | 类型 | 必填 | 含义 |
|
||
| --- | --- | --- | --- |
|
||
| action | string | 是 | read 或 save |
|
||
| uid / token | string | 是 | 公共鉴权参数 |
|
||
| coinAmount | number | save 必填 | 保存后的金币总余额，非奖励增量；传 100 表示余额变为 100 |
|
||
|
||
```json
|
||
{"action":"read","uid":"USER_ID","token":"LOGIN_TOKEN"}
|
||
```
|
||
|
||
```json
|
||
{"action":"save","uid":"USER_ID","token":"LOGIN_TOKEN","coinAmount":1600}
|
||
```
|
||
|
||
read/save 成功均返回 `data.coinAmount:number`（当前/已保存余额）和 `data.timestamp:number`（用户记录/保存响应时间）。save 示例：
|
||
|
||
```json
|
||
{"code":1,"data":{"coinAmount":1600,"timestamp":1789723456450},"msg":"用户数据更新成功"}
|
||
```
|
||
|
||
协议是整值覆盖，不支持 grantId 或原子增量；负值会被旧接口归零。不得把奖励数量直接当总余额上传，也不能让多条金币写入并发覆盖。按现有金币管理队列串行保存，成功后再确认本档到账。
|
||
|
||
### 5.3 确认到账：confirm_delivery
|
||
|
||
**POST `/goldMiner/index`**。
|
||
|
||
```json
|
||
{"action":"confirm_delivery","uid":"USER_ID","token":"LOGIN_TOKEN","periodId":"goldMiner:2026-09-17","taskId":"task_1","grantId":"GRANT_ID_FROM_SERVER"}
|
||
```
|
||
|
||
所有字段必填，均为 string；action 固定 confirm_delivery，periodId/taskId 与 claim 一致，grantId 必须为 claim 返回值。无需 requestId，也不传金币数量。
|
||
|
||
```json
|
||
{"code":1,"data":{"grantId":"GRANT_ID_FROM_SERVER","claimStatus":"claimed","claimedThrough":1},"msg":"成功"}
|
||
```
|
||
|
||
| data 字段 | 类型 | 含义 |
|
||
| --- | --- | --- |
|
||
| grantId | string | 已确认的授权 ID |
|
||
| claimStatus | string | 固定 claimed |
|
||
| claimedThrough | number | 当前已确认的连续档位数 |
|
||
|
||
同一授权重复确认成功且不重复推进顺序。只有本接口成功后，下一档才可能变为 claimable。确认接口不会再修改金币余额。
|
||
|
||
### 5.4 客户端恢复顺序
|
||
|
||
1. 调用 claim，持久化 uid、periodId、taskId、grantId、items 和交付阶段。
|
||
2. 若服务端已 claimed / requiresClientDelivery=false，不再加金币；若本地记录该 grantId 已保存金币，也跳过加币。
|
||
3. 尚未保存时，交由游戏金币模块执行一次到账并保存总余额，记录该 grantId 的保存结果。不要每次重试都重新做“当前余额 + 奖励”。
|
||
4. 保存确定成功后调用 confirm_delivery；确认失败只重试确认。成功后刷新 info 或继续补发下一档。
|
||
|
||
当前 userCoin/save 与 confirm_delivery **不是同一个事务**，服务端也不验证金币保存凭证。断线、重装或多设备并发时，仅靠 grantId 不能保证金币端严格只到账一次；余额保存结果不明时，需要沿用游戏已有恢复机制核对，不能仅根据 issuing 自动再次加币，也不能未发奖就提前确认。这是现有金币协议的限制，本次文档不改变该协议。
|
||
|
||
## 6. 往期补发
|
||
|
||
活动结束后，已付费且达标的未领取档位进入补发流程；未达标奖励失效。未付费不能在结束后补买，已有订单的延迟确认按支付路由处理。补发不依赖当前 info 是否可用。
|
||
|
||
### 6.1 查询列表：settlements
|
||
|
||
**POST `/goldMiner/index`**。
|
||
|
||
```json
|
||
{"action":"settlements","uid":"USER_ID","token":"LOGIN_TOKEN","limit":20}
|
||
```
|
||
|
||
| 参数 | 类型 | 必填 | 含义 |
|
||
| --- | --- | --- | --- |
|
||
| action | string | 是 | settlements |
|
||
| uid / token | string | 是 | 公共鉴权参数 |
|
||
| limit | number | 否 | 默认 20，范围 1～100；限制每次扫描的历史玩家期记录数 |
|
||
| afterId | string | 否 | 上一页返回的 nextCursor；首次省略，不能使用 settlementId 替代 |
|
||
|
||
```json
|
||
{"code":1,"data":{"items":[{"_id":"SETTLEMENT_ID_FROM_SERVER","uid":"USER_ID","periodId":"goldMiner:2026-09-17","taskIds":["task_1","task_2"],"itemsSummary":[{"type":"coin","count":300}],"deliveryStatus":"pending","clientSavedAt":null,"revision":5,"createdAt":1789920000000,"acknowledgedAt":null}],"nextCursor":null},"msg":"成功"}
|
||
```
|
||
|
||
| data 字段 | 类型 | 含义 |
|
||
| --- | --- | --- |
|
||
| items | array | 本页扫描得到的结算记录，可能为空 |
|
||
| nextCursor | string / null | 下一页游标；非 null 时继续请求，直到 null |
|
||
|
||
| items[] 字段 | 类型 | 含义 |
|
||
| --- | --- | --- |
|
||
| _id | string | 结算记录 ID，ack_settlement 时映射为 settlementId |
|
||
| uid | string | 所属玩家 |
|
||
| periodId | string | 奖励所属的旧活动期 |
|
||
| taskIds | string[] | 本结算覆盖档位，已按领取顺序排列 |
|
||
| itemsSummary | array | 本结算覆盖奖励的合计，元素 type/count；不是“剩余待发数量” |
|
||
| deliveryStatus | string | pending：均未确认；partial：部分确认；client_saved：全部确认 |
|
||
| clientSavedAt | number / null | 全部确认后的最后确认时间，未全部完成为 null |
|
||
| revision | number | 内部投影版本，前端无需修改 |
|
||
| createdAt | number | 该期进度被关闭、生成结算的时间，可能晚于实际结束时刻 |
|
||
| acknowledgedAt | number / null | 客户端确认结算记录已处理的时间，尚未确认时为 null |
|
||
|
||
分页扫描历史玩家期记录，并非仅扫描待发记录，所以 `items=[]` 但 `nextCursor!=null` 时仍需翻页。已完成、已确认记录也可能返回，前端按 deliveryStatus/acknowledgedAt 过滤待处理展示。
|
||
|
||
对 pending/partial 记录，按 taskIds 顺序逐一执行 **claim → 保存金币 → confirm_delivery**；使用记录中的 periodId。重试已发档位时 claim 会返回 claimed，不再加币。itemsSummary 仅供展示，不要汇总加币后又逐档加币。
|
||
|
||
### 6.2 确认结算已处理：ack_settlement
|
||
|
||
**POST `/goldMiner/index`**。
|
||
|
||
```json
|
||
{"action":"ack_settlement","uid":"USER_ID","token":"LOGIN_TOKEN","settlementId":"SETTLEMENT_ID_FROM_SERVER"}
|
||
```
|
||
|
||
所有参数必填且为 string。settlementId 来自记录的 `_id`；全部档位确认到账后调用。
|
||
|
||
```json
|
||
{"code":1,"data":{"settlementId":"SETTLEMENT_ID_FROM_SERVER","acknowledged":true},"msg":"成功"}
|
||
```
|
||
|
||
data.settlementId 为 string，data.acknowledged 为 boolean，成功固定 true。重复调用安全；deliveryStatus 尚不是 client_saved 时返回 DELIVERY_PENDING。此操作只确认处理完成，不发金币，也不删除结算记录。
|
||
|
||
## 7. 错误码与处理
|
||
|
||
以下错误码可能来自活动或黄金矿工支付分支；通用接口前置错误及 checkIos 的返回例外见第 1 节。
|
||
|
||
| errorCode | 含义与前端处理 |
|
||
| --- | --- |
|
||
| UNAUTHORIZED | 登录或订单归属校验失败；刷新登录并核对账号，不跨账号重试订单 |
|
||
| INVALID_ACTION / INVALID_INPUT / INVALID_PERIOD | action、参数或期 ID 不合法；修正请求 |
|
||
| INVALID_TASK / INVALID_GRANT | 档位或授权不匹配；重新读取任务/原领取结果，不伪造 ID |
|
||
| NOT_FOUND | 活动记录、订单快照或结算不存在；核对账号、期和 ID |
|
||
| NOT_QUALIFIED | 未满足活动门槛；刷新 info |
|
||
| PERIOD_ENDED | 活动不在可操作时间或事件属于旧期；停止新购买/进度补记，刷新 info；补发走 settlements |
|
||
| PURCHASE_DISABLED | 本期暂停新购买；刷新 info |
|
||
| ALREADY_UNLOCKED | 已有权益或订单已确认；继续原订单查询并刷新 info，不再次付款 |
|
||
| NOT_PAID | 本期未解锁；恢复支付查询或展示购买 |
|
||
| TARGET_NOT_REACHED | 任务目标未达成；刷新进度 |
|
||
| PREVIOUS_NOT_CLAIMED | 前序档位未确认到账；先恢复并确认前序档位 |
|
||
| DELIVERY_PENDING | 补发尚未全部确认；继续逐档处理 |
|
||
| EVENT_PAYLOAD_CONFLICT | 同一个事件 ID 对应不同胜利内容；检查持久化队列，不能改 ID 来绕过校验 |
|
||
| INVALID_PRODUCT | 商品与本期配置不符；使用最新 info.productId |
|
||
| PAYMENT_PENDING | 尚无可信支付确认；保留原订单并退避查询，不等同确定支付失败 |
|
||
| PAYMENT_CHANNEL_DISABLED | 客服支付渠道未启用；提示暂不可用，交后端确认渠道配置 |
|
||
| PAYMENT_CHANNEL_CONFLICT | 本期已有其他渠道订单；继续原渠道 |
|
||
| ORDER_CLOSED | 订单已关闭或无法继续支付；停止拉起该支付页并刷新状态 |
|
||
| ORDER_ENVIRONMENT_MISMATCH | 订单/商户环境不一致；停止重试并核对部署环境 |
|
||
| ORDER_SNAPSHOT_CONFLICT / PAYMENT_CONFLICT | 订单快照或交易号冲突；保留订单号交后端排查 |
|
||
| ENTITLEMENT_CONFLICT / MANUAL_REVIEW | 资格分配冲突或进入人工核对；不要重付，交后端核对 |
|
||
| CONFIG_UNAVAILABLE / PAYMENT_CONFIG_UNAVAILABLE | 活动或支付配置缺失/异常；提示暂不可用，交后端处理 |
|
||
| CUSTOMER_SERVICE_UNAVAILABLE | 客服消息发送失败；保留订单，由原流程恢复 |
|
||
| INVALID_PAYMENT / INVALID_PAYMENT_SIGNATURE | 支付响应或签名校验失败；不能按成功处理，交后端排查 |
|
||
| MERCHANT_* | 商户请求相关错误，后缀来自商户响应；保留原订单，查询类暂时故障退避恢复 |
|
||
| RETRYABLE | 暂时失败或并发冲突；复用原请求标识退避重试，并遵守金币/关卡恢复约束 |
|
||
|
||
服务端订单元数据内的 lastErrorCode/lastQueryError 可能保留历史错误，不等同本次接口 errorCode。未知错误码按失败处理并保留日志，不能默认支付或领奖成功。
|
||
|
||
## 8. 前端接入顺序与版本迁移
|
||
|
||
1. 登录/回到游戏后恢复未完成订单查询及奖励交付记录，拉取 info 和 settlements。
|
||
2. 游戏胜利保存关卡时附带活动事件；未打开活动页、未付费仍正常上报。结束后停止新事件补记。
|
||
3. 页面直接按 tasks 返回顺序展示，以 status 控制购买，以 claimStatus 控制档位领取；不根据 completed 单独开放按钮。
|
||
4. 购买后查询到权益确认，重新读取 info；按 fulfillmentRoute 处理往期结算或下期资格。
|
||
5. 每档金币保存并 confirm_delivery 成功后再处理下一档；断线恢复原 grantId，补发同样逐档执行。
|
||
|
||
本版精简仅作用于 **info 的展示响应**：
|
||
|
||
| 旧字段 | 当前用法 |
|
||
| --- | --- |
|
||
| availability / qualified / purchasable / entitlement.status | 使用 status 五态 |
|
||
| entitlement.source | 删除，前端只判断本期是否 unlocked |
|
||
| nextStartsAt / nextPeriodId / currency | info 不返回；金额单位在协议中约定 |
|
||
| tasks[].sequence | 删除，使用数组顺序 |
|
||
| tasks[].claimed / issuing / claimable / blockReason | 删除，使用 claimStatus 四态 |
|
||
| info.claimedThrough | 删除，按任务 claimStatus 展示；claim 和 confirm_delivery 仍返回 claimedThrough |
|
||
|
||
不要将 info 的 claimable 状态当作后端永久承诺；点击后的 claim 才是实际领取判定。页面倒计时归零、切回前台、支付完成及奖励确认后均应刷新状态。
|
||
|
||
联调文件：[Postman 使用说明](../server/laf-cloud/functions/goldMiner/postman/gold-miner.README.md)、[Collection](../server/laf-cloud/functions/goldMiner/postman/gold-miner.postman_collection.json)、[环境模板](../server/laf-cloud/functions/goldMiner/postman/gold-miner.postman_environment.json)。内部维护与部署细节见 [后端说明](../server/laf-cloud/functions/goldMiner/README.md) 和 [客服支付接入说明](../server/laf-cloud/functions/goldMiner/LEGACY-PAYMENT.md)。
|