36 lines
3.4 KiB
Markdown
36 lines
3.4 KiB
Markdown
# Coin Madness 后端接口需求（待实现）
|
||
|
||
> 历史方案：用户已确认改按黄金矿工接口 V1.3 实现。以下“付费后才计数、每段清零、只计主线”等旧规则已被替代，不再作为开发依据。当前协议见 [GoldMiner-FRONTEND-API-v1.3.md](GoldMiner-FRONTEND-API-v1.3.md)，接入说明见 [GoldMiner接入说明.md](GoldMiner接入说明.md)。原 Word 确认单中的冲突规则同样以接口 V1.3 为准。
|
||
|
||
本轮只交付前端模拟版。后端代码已恢复原状，没有新接口或支付配置部署。以下为后续对接需求，接口名称可按现有体系调整。
|
||
|
||
## 已确认规则
|
||
|
||
- 同一期全体玩家统一结束，每人只能购买一次；一次付费解锁整期阶梯奖励，不分档、不立即赠送金币。
|
||
- 支付由服务端确认后才开始统计，付费前不累计、不补算。
|
||
- 各段独立计数，当前段领取成功才进入下一段；达标后等待领取期间的通关不结转。
|
||
- 只统计主线新关胜利；重复关、无限关、其他模式、批量补报不计入。以服务端收到有效结算时仍在活动期内为准。
|
||
- 到期仅补发已付费且已达标未领取奖励，未完成奖励失效；补发与手动领取并发不得重复发奖。
|
||
|
||
## 前端所需接口
|
||
|
||
| 操作 | 请求信息 | 返回信息与约束 |
|
||
| --- | --- | --- |
|
||
| 查询活动 | 登录鉴权 | 服务端时间、是否开放、活动配置、支付状态、当前段、当前段进度、已领状态、结束状态、余额/奖励凭证 |
|
||
| 创建订单 | periodId、请求幂等键 | 现有支付渠道所需订单参数；价格和商品由服务端配置，不能相信客户端金额 |
|
||
| 确认支付状态 | periodId、orderId | 以渠道验签及订单归属校验为准；客户端支付成功回调不能直接解锁 |
|
||
| 领取奖励 | periodId、stageId、请求幂等键 | 原子校验并发奖、推进阶段，返回最新活动快照与余额版本/奖励凭证 |
|
||
| 到期补发查询 | 登录或活动查询触发 | 已补发奖励及唯一凭证；重复查询不重复发奖 |
|
||
|
||
活动配置至少包含 periodId、title、startsAt、endsAt（UTC 毫秒）、priceCents、currency、productId、开启条件和有序 stages（stageId、wins、coins）。所有接口返回统一 code、msg、data；需区分未开放、过期、未支付、未达标、已领取、期次变更、请求重试和鉴权失效。
|
||
|
||
服务端接入现有主线结算流程，按唯一结算标识去重，并校验新关及支付确认时间。支付回调、领奖和到期补发需具备幂等和原子性，断线重试后可恢复状态。账户身份来自登录凭据。奖励必须进入现有权威钱包，禁止客户端自行累加后覆盖服务端余额。
|
||
|
||
## 策划与后端仍需定稿
|
||
|
||
活动日历、购买截止时间、跨截止支付回调处置（拒绝/退款/保障期）、价格币种与渠道商品、开启等级/人群、每段目标与奖励、是否允许晚进入、补发通知形式、展示文案和正式美术资源。模拟版的 7 天、99 分、5 段奖励仅用于交互测试，不代表正式配置。
|
||
|
||
## 联调验收
|
||
|
||
验证付费前零进度、支付回调重复、重复结算、等待领取不结转、重复/并发领取、截止时刻竞态、到期补发与手动领奖竞态、断网恢复、重登和换期隔离。模拟版使用本地时间且不能验签，不替代真实支付及服务端验收。
|