231 lines
16 KiB
Markdown
231 lines
16 KiB
Markdown
# 黄金矿工 PRD
|
||
|
||
版本：V1.1
|
||
|
||
日期：2026-09-18
|
||
|
||
状态：产品规则已通过需求问答对齐；首期商业数值待配置，工程方案待实现验证。
|
||
|
||
配套文档：[黄金矿工后端整体设计](goldMiner-backend-design.md)
|
||
|
||
本次修订：进度去重与玩家每期数据合并，不建设进度恢复机制；金币继续由前端发放、后端保存，暂不调整通用金币协议。因此离线补发改为后台保留待发清单，玩家下次上线自动发货并保存，替代 V1.0 的后台离线直接入账。
|
||
|
||
## 1. 产品目标与交付范围
|
||
|
||
黄金矿工是每周开放四天的付费闯关奖励活动。符合资格的玩家在活动期间完成主线或无尽关卡，累计推进同一条任务奖励链；单次购买解锁当期全部任务的领奖资格，玩家按任务顺序领取已达标奖励。
|
||
|
||
本次交付为 PRD 和后端整体设计，不实施客户端、后端代码或线上配置变更。文档中的接口、集合与后台任务均为拟建设内容。客户端展示状态与后续接入要求属于需求说明，不代表本次修改前端。
|
||
|
||
核心目标：提高活动期内通关参与和付费转化；允许先积累、后购买；保留已付款玩家的已达标奖励，支持后续领取和常见请求重试去重。跨设备与异常中断的到账限制见第 6 节。
|
||
|
||
## 2. 已确认规则
|
||
|
||
| 项目 | 确认口径 |
|
||
| --- | --- |
|
||
| 购买范围 | 一次付费仅解锁一期；下一期正常需要重新购买，延迟支付顺延资格除外 |
|
||
| 活动周期 | 北京时间每周四 00:00:00 至周日 23:59:59；全服统一截止 |
|
||
| 资格门槛 | 通过主线第 41 关后获得资格；第 41 关本身不累计活动进度 |
|
||
| 自动参与 | 达到资格后无需打开活动页面、报名或付费，活动期间即可累计 |
|
||
| 有效玩法 | 主线与无尽关卡均可累计；一次有效成功结算增加 1 |
|
||
| 任务进度 | 全部任务共享当期累计通关数，领取顺序不阻止后续任务累计 |
|
||
| 未购买 | 可以累计并展示已达标奖励，不能领取 |
|
||
| 领取顺序 | 必须先领前一任务，才能领取下一任务 |
|
||
| 奖励类型 | 首期仅金币；数量可配置，结构保留其他道具扩展能力 |
|
||
| 配置项 | 任务数、各档目标、金币数量、单期价格可配置，首期数值待定 |
|
||
| 配置生效 | 开期时冻结全期配置；修改下一期生效 |
|
||
| 到期处理 | 已购买且达标未领取的奖励自动补发；未达标失效；未购买不能过期新购 |
|
||
| 离线处理 | 后台固定待发奖励，下次上线由前端自动发放并保存到后端，离线不直接加金币 |
|
||
| 发货方式 | 前端发货、后端保存；本期不改造通用金币协议 |
|
||
| 进度去重 | 合并在玩家每期记录中，与计数同时更新；不建设后台进度恢复机制 |
|
||
| 数据留存 | 每个玩家每期独立保存活动数据，并冗余当期配置和奖励快照 |
|
||
|
||
## 3. 周期与参与资格
|
||
|
||
### 3.1 时间定义
|
||
|
||
服务端统一使用北京时间（Asia/Shanghai，UTC+8）计算活动周期，持久化时间使用 UTC 毫秒时间戳。
|
||
|
||
程序判断采用半开区间：`startsAt <= serverAcceptedAt < endsAt`。`endsAt` 为紧接周日之后的周一 00:00:00，避免漏掉周日最后一秒内的毫秒。
|
||
|
||
示例：2026-09-17 周四 00:00 开始，2026-09-21 周一 00:00 截止；下一期 2026-09-24 周四 00:00 开始。周一至周三不累计活动进度、不新建活动购买订单。
|
||
|
||
- 周六才达到资格的玩家，仍在本周日结束，没有个人额外四天。
|
||
- 活动开始前开局、活动期间有效提交成功结算，可以计入。
|
||
- 活动结束后才提交成功结算，不补记到原期；也不能把旧局重试转记到下一期。
|
||
- 客户端时钟、客户端声称的完成时间不能延长活动时间。
|
||
- 活动内已成功保存的计数，重复请求不再增加。只收到请求但活动进度写入失败时，不视为计数成功；可以在活动内重试，结束后不恢复或补记失败进度。
|
||
|
||
### 3.2 门槛与起点
|
||
|
||
门槛为已通过第 41 关，即现有后端 `users.levelAmount >= 41` 的语义。
|
||
|
||
- 活动内刚通过第 41 关：获得资格，活动进度为 0。
|
||
- 随后有效通过第 42 关：活动进度为 1。
|
||
- 活动开放前已通过第 41 关：开放后第一笔有效通关开始累计，不追溯历史通关。
|
||
- 通过 41 关本身发生在周一至周三：只获得后续参与资格，不产生本期累计。
|
||
- 正常失败、退出或复活不增加、不扣减已有进度；复活后最终胜利只算一次成功。
|
||
|
||
## 4. 任务与奖励
|
||
|
||
### 4.1 共享累计进度
|
||
|
||
设当期有效累计通关数为 `P`，任务 i 的目标为 `T[i]`：
|
||
|
||
```text
|
||
任务 i 达标 = P >= T[i]
|
||
任务 i 展示进度 = min(P, T[i]) / T[i]
|
||
任务 i 可领取 = 本期已购买 AND 活动未结束 AND 任务达标
|
||
AND 任务未领取 AND 全部前置任务已领取
|
||
```
|
||
|
||
示例仅解释规则：目标为 3、5、10 时，累计通关 10 次即全部达标，不需要累计 18 次。玩家尚未领取第一档时，后两档仍可达到 100%，但不能跳领。
|
||
|
||
任务数量不固定为 5；目标必须是正整数、按任务顺序严格递增。首期只配置正整数金币奖励。最后一档达标后活动展示进度封顶，不产生额外奖励；一般关卡统计不受影响。
|
||
|
||
### 4.2 主线与无尽
|
||
|
||
活动累计是“当期有效成功次数”，不能用主线等级差代替。无尽模式达到主线上限后，主线等级不再增长，仍须每次成功增加 1。
|
||
|
||
无尽中再次抽到同一关卡模板是正常的新一局，可以累计；同一局的重复结算、重试上报、重复回包只能累计一次。去重依据应为局/结算标识，不能使用关卡模板 ID。
|
||
|
||
当前成功结果仍由客户端上报，后端负责资格、活动时间、数据格式、连续性及去重校验。本活动不宣称实现了服务端模拟对局或完整反作弊。
|
||
|
||
### 4.3 任务展示状态
|
||
|
||
后端同时返回进度、购买状态、领取状态和不可领取原因，不能只返回一个百分比。
|
||
|
||
| 场景 | 状态/展示要求 |
|
||
| --- | --- |
|
||
| 未达标 | 显示进度，不能领取 |
|
||
| 达标但未购买 | 显示已达标、购买后可领取 |
|
||
| 已购买且达标，但前置任务未领 | 显示 100%，提示需先领取前一档 |
|
||
| 已购买、达标且前置已领 | 可领取 |
|
||
| 已获领取授权、前端保存尚未确认 | 发货处理中，重试原凭证，下一档暂不可领取 |
|
||
| 已领取 | 显示已领取，不可重复领取 |
|
||
| 到期已达标未领 | 待自动补发、发货处理中或已补发，不能重新生成一份普通领取奖励 |
|
||
| 到期未达标 | 已失效 |
|
||
|
||
首期按单档领取设计，不新增玩家“一键领取全部”功能。后台到期结算生成有序待发清单；玩家在线时由前端逐档发放、保存和确认，保留每档明细，可以汇总展示结果。
|
||
|
||
## 5. 购买与延迟支付
|
||
|
||
### 5.1 正常购买
|
||
|
||
- 已有资格、活动开放、尚未购买且无顺延权益时，允许购买。
|
||
- 所有任务均达标但尚未购买的玩家，在活动截止前仍可购买。
|
||
- 服务端按当期冻结配置定价；客户端不得决定商品价格或奖励。
|
||
- 以服务端支付确认和权益落库为准，客户端支付成功提示不能自行解锁。
|
||
- 购买成功只解锁领奖资格，不自动发放全部奖励。活动内由玩家按顺序领取。
|
||
- 同一期已解锁后隐藏购买按钮，后端同时禁止重复购买。
|
||
- 首期价格尚未确定，不将示例价格作为上线值。
|
||
|
||
### 5.2 延迟支付的业务口径
|
||
|
||
适用前提：订单在原期活动内合法创建，但活动结束后服务端才完成有效支付确认及权益处理。无论实际付款发生在截止前还是截止后，均按下述规则处理。活动结束后不能创建新订单。
|
||
|
||
| 原期截止时的情况 | 处理 |
|
||
| --- | --- |
|
||
| 存在已达标、尚未领取的奖励 | 解锁并固定原期这些待发奖励，由前端在线时补发保存；未达标部分失效，不再顺延 |
|
||
| 没有已达标、尚未领取的奖励 | 不结算原期奖励，将该订单权益预绑定到紧接的下一期 |
|
||
|
||
注意：正常在活动内完成权益解锁的玩家，即使最后一档都未完成，也不适用延迟支付顺延规则。已经决定并执行原期结算的订单，即便重复回调时已无剩余奖励，也不能改成顺延。
|
||
|
||
### 5.3 下一期自动解锁
|
||
|
||
- “下一期”是原期之后紧接的下一个周四开始的活动期，不是从补偿时间起重新计四天。
|
||
- 顺延资格在间隔的周一至周三登记为待生效；这一时段不开放下一期购买。
|
||
- 到下一期开期时立即生效：玩家状态为已购买，不显示购买按钮；服务端购买接口也必须检查并拒绝重复购买。
|
||
- 下一期进度从 0 开始，采用下一期冻结的完整任务与奖励配置，不补收或退还期与期之间的价格差。资格按“解锁一整期”解释，不作为现金余额。
|
||
- 顺延资格仅使用一次。顺延期结束后按普通已购买规则结算，即使未达标，也不再向第三期顺延。
|
||
- 不引入可囤积、可选期使用或自动寻找更远活动期的通用兑换券。
|
||
|
||
工程异常：需通过开期前查单、开期权益检查降低支付确认跨越三天间隔的风险。若异常订单直至目标期已购买或结束后才确认，保留订单并告警，进入人工核对；不静默丢单、不重复解锁、不擅自转移到第三期。正常产品流程不提供此类选择界面。
|
||
|
||
## 6. 到期结算与补发
|
||
|
||
到期即停止进度累计、新购和新的普通领取授权。服务端以当期记录中已成功保存的进度冻结结果，不等待或重放独立通关事件。活动内已经固定的领取凭证可以在到期后完成前端保存和确认。
|
||
|
||
1. 已购买：找出达标但未完成领取的任务，按顺序生成待发清单；已在发货中的任务复用原领取凭证。
|
||
2. 未购买：不发奖励；保留截止进度以处理已有订单的延迟确认。
|
||
3. 未达标任务失效，不因补发、回调或登录继续累计。
|
||
4. 前端按稳定领取凭证去重发货，再将发放后的余额保存至后端；保存成功后确认该档已领取。保存失败只重试保存，不重新加币；确认失败只重试确认。
|
||
5. 玩家离线时金币余额不变，后台保留待发奖励；下次登录自动执行前端发货、后端保存并展示明细。关闭展示弹窗不能代替发货确认。
|
||
6. 原期补发明细与下一期活动同时存在，旧期通知不能覆盖或阻止新期累计。
|
||
|
||
领取授权、前端发货、余额保存和领取确认需区分状态，不能在仅生成待发清单时显示已到账。正常同设备重试应保证不重复加币。
|
||
|
||
本期沿用前端发货与余额整值保存，暂不解决通用金币同步。清除本地记录、跨设备并发或发货后异常中断时，仍可能出现重复发放、漏保存或余额覆盖，不能承诺跨设备严格一次到账；须保留领取凭证和处理状态供核对。该限制不通过后台再次直接加币处理。
|
||
|
||
## 7. 页面与接口层面的产品要求
|
||
|
||
本节描述将来的客户端接入行为，本次不实现页面和前端代码。
|
||
|
||
- 未达到门槛：不提供购买和领取操作。
|
||
- 活动开放：展示周期倒计时、任务链、各档金币和累计进度。
|
||
- 未购买：展示服务端价格；已购买或顺延自动解锁：不展示购买按钮。
|
||
- 间隔期：不购买下一期、不累计下一期；允许查询旧期补发结果。
|
||
- 前端取得后端固定的领取凭证及奖励后，按凭证去重增加本地金币，保存余额成功再确认领取；重复响应不再次增加金币。
|
||
- 请求超时后查询或重试同一请求，不能以超时判断“未购买/未领取”。
|
||
- 活动倒计时以 `serverTime` 和 `endsAt` 校准；倒计时归零后刷新状态。
|
||
|
||
首页入口美术、动效、自动弹窗频率和具体文案不在本次定稿范围；不以这些尚未设计的表现阻塞后端规则设计。
|
||
|
||
## 8. 配置与运营
|
||
|
||
| 配置 | 要求 |
|
||
| --- | --- |
|
||
| 活动开关 | 支持停止新增购买；不得删除已付款权益和历史结算数据 |
|
||
| 门槛 | 首期为已通过 41 关；若支持配置修改，同样从后续期生效 |
|
||
| 时区/周期 | 首期固定北京时间、周四至周日 |
|
||
| 任务数组 | 数量可配置，序号连续，目标严格递增 |
|
||
| 奖励数组 | 首期每档金币数量独立配置；统一 `items[]` 保留道具扩展 |
|
||
| 商品/价格 | 服务端商品映射与正整数分金额，首期待定 |
|
||
| 配置版本 | 每期固定一份版本和完整内容，不能引用会原地修改的配置 |
|
||
|
||
数值未确定或配置校验失败时不得开放销售。运营查看应能区分未购买、购买、顺延、手动领取、自动补发和异常订单。
|
||
|
||
## 9. 玩家每期数据冗余
|
||
|
||
每名实际参与的玩家，每期有独立记录；未购买但累计过进度的玩家也要记录，不能只保存付费玩家。
|
||
|
||
至少包含：玩家标识、期标识、起止时间、资格获得时间、配置版本及完整任务奖励快照、累计进度及去重信息、截止进度、每档领取授权/发货确认状态、金额/时间/渠道、购买状态、订单引用、资格来源、原期与顺延期关联、待发清单与通知状态。
|
||
|
||
记录须能够独立回答“玩家参加哪一期、当时承诺什么奖励、付了哪笔款、达标多少、领了什么、是否顺延”。不得在下一期开启时复用一条记录清空覆盖；不得仅保留配置 ID 后依赖当前配置还原历史。
|
||
|
||
## 10. 统计与验收
|
||
|
||
建议事件：活动曝光、首次累计、下单、支付确认、权益解锁、任务达标、手动领取、自动补发、资格顺延、顺延生效、结算失败。携带 `periodId`、`configVersion`、订单/任务标识和资格来源；支付回调、事件重试需去重。
|
||
|
||
统计口径应区分当期新购收入与前期订单顺延权益，不将顺延生效再次算作一笔支付。
|
||
|
||
| 验收场景 | 预期 |
|
||
| --- | --- |
|
||
| 活动中通过第 41 关 | 获得资格，进度为 0 |
|
||
| 再通过一关主线或一关无尽 | 进度增加 1 |
|
||
| 未打开活动、未购买时成功通关 | 同样累计 |
|
||
| 无尽两次新局抽到同一模板 | 累计 2；重复提交其中一局不再增加 |
|
||
| 目标 3/5/10，累计 10 | 三档全部达标，第一档未领时不能领取第二档 |
|
||
| 未购买但全达标，截止前购买 | 可依次领取全部 |
|
||
| 活动前开局、活动内提交胜利 | 计入 |
|
||
| 活动内完成、结束后首次提交 | 不计入 |
|
||
| 活动进度写入失败 | 普通关卡存档不受阻断；活动内可重试，结束后不补记失败进度 |
|
||
| 周一普通通关 | 不增加原期或下一期活动进度 |
|
||
| 周日截止时已购、达标未领且离线 | 后台保留待发清单，余额不变；下次上线前端按顺序发放并保存 |
|
||
| 同时手动领取与到期补发 | 共用同一档领取凭证，正常同设备处理只发一次 |
|
||
| 延迟支付、原期有达标奖励 | 结算原期，无顺延 |
|
||
| 延迟支付、原期零可领奖励 | 预绑定紧接的下一期，开期自动已购且无购买按钮 |
|
||
| 正常支付但整期无达标奖励 | 本期结束，不顺延 |
|
||
| 顺延期结束仍无达标奖励 | 结束，不延至第三期 |
|
||
| 原期结算后重复支付回调 | 返回既有处理结果，不能再顺延 |
|
||
| 下一期开期与玩家下单并发 | 已有顺延资格先生效，下单被拒绝 |
|
||
| 配置中途调整 | 原期目标/奖励/价格不变，下期使用新配置 |
|
||
| 新期开启后查询历史 | 旧期完整快照、待发清单和领取凭证仍可追溯 |
|
||
| 前端发货后的余额保存失败 | 保留本地待保存状态，重试保存，不再次加币 |
|
||
| 余额保存成功后确认领取超时 | 重试原凭证确认，不重复发货；异常跨设备场景保留记录核对 |
|
||
|
||
## 11. 尚未确定的上线输入
|
||
|
||
首期任务数量、目标序列、每档金币、价格、正式商品 ID、首次启用日期需运营提供。它们是配置输入，不改变本 PRD 已确认的规则。
|
||
|
||
发布前还需验证玩家期记录的条件更新、支付对账、调度运行环境，以及客户端通关去重和前端发货保存流程。通用金币协议改造、后台直接入账和进度恢复队列不属于本期上线条件。仅部署活动后端仍不代表完整客户端接入已完成。
|