server/laf-cloud/functions/goldMiner/FRONTEND-API.md

黄金矿工前端接口文档 V1.7

更新时间：2026-09-24。依据当前 local 分支实现编写，包含精简后的 info 协议与服务器到期结算协议。示例价格、目标和金币仅用于联调，页面必须使用接口返回值。部署环境需具有相同版本的后端代码。V1.7 增加 VIP 六档礼包和 pending_unlock 状态，允许任意领取达标任务。补发查询：分页大小由后端控制，新增 no_pending_rewards 状态，未完成结算的期不再阻塞其他期奖励。配置/资格/发奖存储为两个集合；配置示例和迁移见 公共配置说明。

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	confirm_settlement_delivery
兼容：确认补发通知已处理	/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。测试环境临时期使用 goldMiner:test:标识，起止时间由服务端配置。客户端必须原样使用服务端返回的期 ID 和起止时间，不要自行按周历生成或截取期 ID；其他请求和返回结构不变。详见 临时期说明。eventId、requestId、createRequestId 等标识支持 1～100 位英文字母、数字、下划线、冒号及连字符；可使用 UUID。生成后必须随原操作保存，重试时复用。

返回包装

活动接口及黄金矿工支付分支成功结构：

{"code":1,"data":{},"msg":"成功"}

字段	类型	说明
code	number	1 为业务成功，0 为业务失败；不能仅依靠 HTTP 状态判断
data	object / null	各接口业务数据；活动标准失败时为 null
msg	string	提示信息，不作为程序状态判断依据
errorCode	string	活动标准失败时返回，用于程序分支

{"code":0,"data":null,"errorCode":"NOT_PAID","msg":"本期尚未解锁，请先完成支付并确认活动权益"}

配置校验失败时，msg 返回首个不合法字段的完整路径及约束；数组下标从 0 开始。例如：

{"code":0,"data":null,"errorCode":"CONFIG_UNAVAILABLE","msg":"config.tasks[1].targetWins 必须大于前一档目标（3）"}

普通/临时期发布和运行时配置校验使用同一规则；任务 ID 重复、序号不连续、不支持的奖励类型、金额类型错误等均有对应提示。临时期时间冲突会指出冲突期 ID 和窗口；支付配置错误会指出不合法的服务端环境变量名，不返回密钥值。errorCode、code、data 的结构不变，前端继续使用 errorCode 分支，msg 用于展示及联调排查，不应匹配具体文案。未知系统异常仍返回 RETRYABLE 和重试提示，不直接透传内部异常。

例外：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。

{"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，不要写死
vipLevel	number	使用 VIP 配置且可展示活动时	当前礼包档位 0～5；旧单档配置不返回
progressWins	number	可展示活动时	本期累计有效胜利数；VIP 升降档前保留累计值，可能超过当前 maxTarget，见 2.3
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 / pending_unlock / claimable / issuing / claimed
completed	boolean	累计胜利是否达到该档目标，与是否付费、是否可领取无关
progress	number	min(progressWins, targetWins)，是通关数，不是百分比

itemsSnapshot[] 字段	类型	含义
type	string	道具类型，当前配置仅支持 coin（金币）
count	number	道具数量，正整数

保留数组结构以便以后扩展道具。出现客户端暂不支持的道具类型时，不应静默跳过并确认已到账。

claimStatus	含义	操作
locked	目标未达成	不能领取
pending_unlock	已达标，但尚未付费解锁	展示“已达标待解锁”，支付成功后刷新
claimable	已付费、已达标，不受其他任务领取状态影响	调用 claim
issuing	已取得奖励授权，但尚未确认客户端保存成功	活动内对同一 periodId/taskId 再调用 claim；活动结束后从 settlements 恢复原 grantId
claimed	本档客户端到账已经确认	展示已领取，不再增加金币

任务展示顺序由后端保证，无需 sequence。已付费后，任意已达标任务均可申请领取和确认；第一档未领取不阻止领取后续档。

完整示例：本期尚未购买，但已通关 3 次。

{
  "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":"pending_unlock","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：

{"serverTime":1789723456450,"status":"locked","periodId":"goldMiner:2026-09-17","tasks":[]}

不可用时的完整 data（示例为周一休息期）：

{"serverTime":1789920000000,"status":"unavailable","periodId":"goldMiner:2026-09-17","startsAt":1789574400000,"endsAt":1789920000000,"tasks":[]}

不可用状态下的日期来自活动日历，不能据此认定活动已启用或计算下一期购买资格。

2.3 VIP 礼包选择

配置使用 vipTiers 时，后端读取 users.vip_level（VIP0～VIP5），只返回匹配档位的 priceFen/productId/tasks/maxTarget，并返回 vipLevel 表示本期礼包档位。前端不提交 VIP 值，也不自行选择价格或奖励。旧版单档配置继续使用原协议，不返回 vipLevel。

VIP 缺失、无效或超出 0～5 时使用 VIP0；VIP0 即使已付费或不符合首次付费资格，也照常展示和购买 VIP0，不做首次付费资格拦截。本规则以本次业务确认口径为准。

未创建订单时，玩家 VIP 更新可刷新本期礼包，已有累计进度保留。创建订单时锁定报价和奖励；未付款订单重试和已付款礼包都保持原快照，不因 VIP 更新改变。页面信息过期导致 itemid 不匹配时返回 INVALID_PRODUCT，刷新 info 后使用新 productId 重新下单；不得改传价格绕过校验。已付费顺延权益保留原购买档位。

未锁定报价前，进度最多累计至配置中最高 VIP 的最终目标，以便 VIP 升档时不丢失已完成通关。因此 progressWins 可能大于当前礼包 maxTarget；maxTarget 是该礼包领满目标，任务 progress 仍限制到本任务 targetWins。未付费达标返回 pending_unlock；付费后所有达标未领取任务同时为 claimable。多档奖励可任意选择，但金币整值保存仍需串行执行，防止余额覆盖。

当前周期和计数口径保持原实现：普通周活动周四至周日，测试临时期使用指定窗口，未付费也累计。不采用支付后 168 小时或支付后才计数。六档完整发布示例见 VIP 配置，部署及配置说明见 VIP 礼包说明。

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	无尽必填	无尽成功结算序号，正整数；同一胜利重试相同，新胜利使用新序号

主线示例：

{"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 仅是假设的当前主线通关值）：

{"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 重报同一关也不会再加活动进度。

返回字段

{"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	是	本次创建订单请求标识，重试复用

{"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	支付签名，交给现有原生支付流程

返回结构示例（签名内容仅为占位，不能用于实际支付）：

{"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。

{"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 为不可手工生成的占位字符串）：

{"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 对黄金矿工也返回同一协议，不直接发金币。

{"uid":"USER_ID","token":"LOGIN_TOKEN","outTradeNo":"ORDER_NO_FROM_CREATE"}

三个参数均为必填 string，不需 action。原生支付以已验证的服务端通知为依据；客服渠道还会按后端节流策略主动查单。客户端支付成功回调只用于触发查询，不能代替服务端确认。

成功 data 字段	类型	含义
pay_state	number	黄金矿工成功固定为 2，表示支付及权益已确认，不表示所有任务已领奖
rewardDelivery	string	固定 goldMiner.claim，活动内逐档 claim，结束后查询 settlements
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，无需再买

原生订单正常解锁的完整响应示例（标识和哈希为占位）：

{
  "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 处理，普通活动页面通常无需主动调用。

支付页票据方式：

{"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。

{"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	是	活动内奖励所属期；过期后此接口不再用于补发
taskId	string	是	info 或补发记录提供的档位 ID
requestId	string	是	本次领取请求标识，重试复用

{"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 也不会产生第二份授权。活动结束时起，所有 claim（包括旧授权重试）统一返回 PERIOD_SETTLEMENT_REQUIRED 和“活动已结束，服务器正在结算奖励，请查询补发清单”；该提示引导前端查询，不表示后台一定尚未完成结算，实际状态以 settlements 为准。到期校验覆盖数据库写入边界，跨零点请求不能新建普通领奖授权。requiresClientDelivery=true 不代表客户端肯定还未加金币，也可能是金币已保存但确认请求失败，必须结合本地交付记录恢复。

5.2 金币保存：userCoin

POST /userCoin。继续沿用游戏现有金币流程，后端不直接加金币。

参数	类型	必填	含义
action	string	是	read 或 save
uid / token	string	是	公共鉴权参数
coinAmount	number	save 必填	保存后的金币总余额，非奖励增量；传 100 表示余额变为 100

{"action":"read","uid":"USER_ID","token":"LOGIN_TOKEN"}

{"action":"save","uid":"USER_ID","token":"LOGIN_TOKEN","coinAmount":1600}

read/save 成功均返回 data.coinAmount:number（当前/已保存余额）和 data.timestamp:number（用户记录/保存响应时间）。save 示例：

{"code":1,"data":{"coinAmount":1600,"timestamp":1789723456450},"msg":"用户数据更新成功"}

协议是整值覆盖，不支持 grantId 或原子增量；负值会被旧接口归零。不得把奖励数量直接当总余额上传，也不能让多条金币写入并发覆盖。按现有金币管理队列串行保存，成功后再确认本档到账。

5.3 确认到账：confirm_delivery

POST /goldMiner/index。

{"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，也不传金币数量。

{"code":1,"data":{"grantId":"GRANT_ID_FROM_SERVER","claimStatus":"claimed","claimedThrough":1},"msg":"成功"}

data 字段	类型	含义
grantId	string	已确认的授权 ID
claimStatus	string	固定 claimed
claimedThrough	number	当前已确认的连续档位数

同一授权重复确认成功且不重复发放。任务可任意顺序确认，不影响其他已达标任务的 claimable 状态。确认接口不会再修改金币余额。到期前已经取得的授权，结束后仍允许用此接口确认；新补发流程统一使用 confirm_settlement_delivery，两者共用同一奖励状态，不重复推进档位。

5.4 客户端恢复顺序

1. 调用 claim，持久化 uid、periodId、taskId、grantId、items 和交付阶段。
2. 若服务端已 claimed / requiresClientDelivery=false，不再加金币；若本地记录该 grantId 已保存金币，也跳过加币。
3. 尚未保存时，交由游戏金币模块执行一次到账并保存总余额，记录该 grantId 的保存结果。不要每次重试都重新做“当前余额 + 奖励”。
4. 保存确定成功后调用 confirm_delivery；确认失败只重试确认。成功后刷新 info 或继续补发下一档。

当前 userCoin/save 与发货确认（confirm_delivery / confirm_settlement_delivery）不是同一个事务，服务端也不验证金币保存凭证。断线、重装或多设备并发时，仅靠 grantId 不能保证金币端严格只到账一次；余额保存结果不明时，需要沿用游戏已有恢复机制核对，不能仅根据 issuing 自动再次加币，也不能未发奖就提前确认。这是现有金币协议的限制，本次文档不改变该协议。

6. 服务器到期结算与前端补发

活动结束后不再允许通过 claim 申请奖励。服务器冻结进度，为已付费、达标且尚未确认发货的奖励生成稳定授权；前端只查询结果、发放资源并确认。未达标奖励失效，未付费不能结束后补买；已有订单的延迟支付确认仍按原支付路由处理。

goldMiner/jobs 按部署的每分钟触发器分批处理；延迟支付履约也可生成结算。查询接口不触发结算、不加金币。必须部署更新后的 service/index/jobs 及触发器；没有触发器时不能依赖查询自动补建清单。历史旧数据应先按 迁移说明 完成集合合并；后台再处理未结算状态，保留已有 grantId。

6.1 查询所有已结束活动的未确认奖励：settlements

POST /goldMiner/index。

{"action":"settlements","uid":"USER_ID","token":"LOGIN_TOKEN"}

参数	类型	必填	含义
action	string	是	settlements
uid / token	string	是	公共鉴权参数
afterId	string	否	上一页 nextCursor；首次省略，不是 settlementId 或 periodId

查询覆盖该玩家所有已结束活动，不限最近日历期或最后参与的一期。跨期未发完的奖励不会被较新的活动记录遮蔽。分页使用稳定的内部 ID 顺序，每期 rewards 按档位顺序排列。前端无需传 limit，后端固定每页扫描 20 条历史玩家期记录（兼容忽略旧客户端的 limit），不是限制奖励档位数量。

{
  "code": 1,
  "data": {
    "status": "pending_delivery",
    "items": [{
      "settlementId": "SETTLEMENT_ID_FROM_SERVER",
      "periodId": "goldMiner:2026-09-17",
      "rewards": [
        {"taskId":"task_1","grantId":"GRANT_ID_1","items":[{"type":"coin","count":100}]},
        {"taskId":"task_2","grantId":"GRANT_ID_2","items":[{"type":"coin","count":200}]}
      ]
    }],
    "nextCursor": null
  },
  "msg": "成功"
}

data 字段	类型	含义
status	string	pending_delivery、settling 或 no_pending_rewards，见下表
items	array	本页需要补发的结算单；只含尚未确认奖励，整单发完后不再返回
nextCursor	string / null	非空时作为 afterId 继续翻页，settling 时也可翻页；为空表示本轮扫描结束，仍有待处理状态时从第一页复查

status 与列表	含义及操作
pending_delivery，items 非空	优先处理本页已准备好的奖励；其他期仍在结算不会隐藏这些奖励，有 nextCursor 时继续翻页
pending_delivery，items=[]	本页无可发奖励，但玩家其他位置仍有可发奖励；有 nextCursor 时继续翻页，否则从第一页复查
settling，items=[]	本页没有可发奖励，但仍有未完成结算的记录；有 nextCursor 时继续翻页寻找已准备好的奖励，扫描结束后稍后从第一页重查
no_pending_rewards，items=[]	后端已按玩家范围检查，当前环境下所有已结束期均无待发或待结算记录；nextCursor=null，结束本轮检查

没有历史记录，或所有已结束期均已完成结算且无未确认达标奖励时，返回以下状态。这个判断不受 afterId 限制；未付费但尚未完成后台结算的记录仍可能使状态为 settling：

{"code":1,"data":{"status":"no_pending_rewards","items":[],"nextCursor":null},"msg":"成功"}

正在结算的例子：

{"code":1,"data":{"status":"settling","items":[],"nextCursor":null},"msg":"成功"}

items[] 字段	类型	含义
settlementId	string	本期结算单 ID，确认时原样回传
periodId	string	奖励所属的已结束活动期
rewards	array	本期尚未确认发货的奖励，按任务顺序返回
rewards[].taskId	string	档位标识
rewards[].grantId	string	稳定发奖标识；到期前已申请过的奖励继续使用原标识
rewards[].items	array	授权道具列表，元素 type:string、count:number，当前 type=coin

清单表示服务端尚未确认发货，不保证客户端从未加过金币。 前端按 grantId 查本地记录：已保存金币的只补确认，未发放的才加金币并保存。不要再对清单调用 claim，也不要根据当前 info 配置计算旧期金币。

查询是当时的快照；与另一端确认并发时，返回的奖励可能已经被确认。客户端仍需通过稳定 grantId 与现有资源交付机制去重。新支付确认可能在本次查询之后产生补发，回到游戏、支付恢复后应从第一页重新查询。

6.2 确认补发奖励已保存：confirm_settlement_delivery

POST /goldMiner/index。

{"action":"confirm_settlement_delivery","uid":"USER_ID","token":"LOGIN_TOKEN","settlementId":"SETTLEMENT_ID_FROM_SERVER","grantIds":["GRANT_ID_1","GRANT_ID_2"]}

参数	类型	必填	含义
action	string	是	confirm_settlement_delivery
uid / token	string	是	公共鉴权参数
settlementId	string	是	查询返回的结算单 ID，必须属于当前玩家
grantIds	string[]	是	本次已保存成功的授权 ID；1～100 个，不允许重复，全部属于同一结算单

可一次确认一项，也可在全部保存成功后批量确认多项。可选择任意已授权任务，允许跳过前一档或非连续批量确认。批量请求校验和状态更新在同一玩家期记录中原子完成；任一授权不合法时，本次不会只更新前半部分。

{"code":1,"data":{"settlementId":"SETTLEMENT_ID_FROM_SERVER","confirmedGrantIds":["GRANT_ID_1","GRANT_ID_2"],"deliveryStatus":"client_saved"},"msg":"成功"}

data 字段	类型	含义
settlementId	string	已处理的结算单
confirmedGrantIds	string[]	本次确认的授权 ID，含安全重试中已经确认的 ID
deliveryStatus	string	partial：该结算单仍有未确认项；client_saved：整单全部确认

此接口只记录客户端已保存成功，不增加金币。同一授权重复确认安全，金币保存成功但接口超时只能重试确认；不能再次加金币。与 confirm_delivery 共用原任务发货状态，因此旧的在途确认和新的补发确认不会生成两份奖励。

确认成功后重新查询，已确认项自动消失；整单为空时整单不再返回。当前金币整值保存协议的断线、多设备限制仍见第 5.4 节。

6.3 兼容旧展示确认：ack_settlement（新流程可不调用）

POST /goldMiner/index。

{"action":"ack_settlement","uid":"USER_ID","token":"LOGIN_TOKEN","settlementId":"SETTLEMENT_ID_FROM_SERVER"}

所有参数必填且为 string。只有整单发货确认完成后可调用；成功 data 为 settlementId:string, acknowledged:true。重复调用安全，未完成时返回 DELIVERY_PENDING。它只保留旧版展示确认功能，不是新发货确认接口，也不决定奖励是否从查询中消失。

6.4 推荐执行顺序

1. 从第一页查询 settlements，不传 limit。no_pending_rewards 表示本轮无需补发，可以结束。
2. 按每期 rewards 顺序，使用 grantId 恢复已有交付记录；未发的交给金币模块发放并保存。
3. 对确定保存成功的奖励调用 confirm_settlement_delivery；确认失败复用原 settlementId/grantIds。
4. 不论 pending_delivery 还是 settling，有 nextCursor 就继续翻页，避免某期未结算阻塞后续期。扫描结束后从第一页复查；如果仍在 settling，稍后再查，不要立即无限轮询。直到 no_pending_rewards 才确认当前无待处理奖励。没有奖励时不展示补发动画。

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
PERIOD_SETTLEMENT_REQUIRED	普通 claim 已到期，提示服务器结算，改查 settlements，不重试普通 claim
SETTLEMENT_NOT_READY	补发确认对应期尚未结束或结算未准备好；重新查询 settlements
PURCHASE_DISABLED	本期暂停新购买；刷新 info
ALREADY_UNLOCKED	已有权益或订单已确认；继续原订单查询并刷新 info，不再次付款
NOT_PAID	本期未解锁；恢复支付查询或展示购买
TARGET_NOT_REACHED	任务目标未达成；刷新进度
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；到期后从 settlements 取得原 grantId，保存金币后 confirm_settlement_delivery。

本版精简仅作用于 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 使用说明、Collection、环境模板。内部维护与部署细节见 后端说明 和 客服支付接入说明。