这个插件解决的是「让站里有个固定时间点会热闹一下」这件事。一版一版跟下来，v1.3.0 是三件事凑到一起的版本：红包雨从「掉下来」改成「一屏铺开、点开哪个算哪个」；开抢时间从代码里搬进了模块，站长在页面上点几下就能改；场次到点会自动弹窗，用户不用守在模块前面等。

先说最容易被误解的一点：红包雨现在是真的要点。一场的额度在你点「开抢」那一刻就由服务端算好并占住，然后把这份额度随机拆成 20 到 40 份铺满一屏，全部显示「?」。你点开哪一个，那一个的数字才亮，那一份才归你；没点开的那部分，结算时原数退回奖池，别人还能抢。所以能拿多少仍然有上限（就是开场时定好的那一份），但要拿到手，得手快、还得点。

限时抢还是老样子：名额先到先得，抢到就是固定的一笔。两个玩法共用同一套积分、日额度和记录体系，装一次就都有了。

一、v1.3.1 这次到底改了什么

如果你装过早期版本，直接看这张表；第一次装的话，这张表就是「这版为什么值得装」：

二、两个玩法，都是「限时开场」

面板分三页：红包雨、限时抢、战绩。三页共用同一套积分与记录体系。

默认节奏是这样（全部可调，见第六节和第十四节）：

注意最后一行：日额度是两种玩法共用的。红包雨抢够了 500，限时抢也一起到顶，反之亦然。这是故意的，防止有人两边来回薅。

三、红包雨：一屏铺开，点开哪个算哪个

这是 v1.3.0 变化最大的地方，值得单独说清楚。整个流程是这样的：

1. 你点「开抢」：服务端当场决定这一把你最多能拿多少——先算你还剩多少日额度、本场池子还剩多少、单人上限是多少，取三者里最小的那个，作为本场的额度；然后把这个额度随机拆成 20 到 40 份（额度不够就少拆几份，每份至少 1 分），存进你自己的场次会话里，同时把这份额度当场从奖池里扣掉（防止并发超发）。
2. 红包铺满一屏：这些份数会先打乱顺序再铺开，界面上全部显示「?」——你只知道有几个包，不知道哪个大。
3. 你点开红包：点哪一个，哪一个当场翻出数字，那一份就算你的。进度条上会写「已开 12 / 37」。
4. 结算才发分：时间到、点满最后一个（会自动收尾）、或者你点「结束本场」，都会触发结算。服务端只按你真点开的那几份发分，剩下的原数退回本场奖池，后面的人还能抢。

所以两个结论：一是「能拿多少」有天花板（就是开场时定好的那一份额度，点满就是全拿）；二是「实际拿到多少」看你点开了几个——一场只有 60 秒，一屏几十个红包，点不完的那部分就退回池子了。这就是这个玩法的手速与取舍。

顺序为什么要打乱？因为拆包的算法天然是「先取的几份偏大、越往后越收窄」。如果原样铺开，用户只要从前往后顺着点，就总能吃到大的——红包就变成一道排序题，不是手速题了。打乱之后，你只能凭运气和手速，一个一个点。

金额为什么干脆下发了？下发了不就能挑肥拣瘦吗？点开要当场翻牌，前端必须知道每份是多少，这是没有别的办法的。但下发金额不会让人多拿：顺序已经打乱，看不出规律；而且你能拿的上限本来就是所有份之和，全点完就是全拿，多知道金额也变不出额外收益。所以这里的思路是「把上限锁死在服务端，把呈现交给客户端」，而不是「把金额藏起来」。

四、每一次拆包，都像真红包一样有大有小

「把 200 分拆成 37 份」如果不讲究，最省事的做法就是平均分，每份约 5 分。那样拆出来的一屏红包一眼假：三十几个一模一样的格子，一点都不像过年。

所以这里的拆法是这样的（每份至少 1 分，加起来必须恰好等于额度，不会多也不会少）：

设：总额 total，要拆成 parts 份（parts 默认在 20 ~ 40 之间随机）

对第 i 份：
  slots = 还没拆的份数
  avg   = floor(剩余总额 / slots)          ← 剩余部分的平均值
  cap   = max(1, floor(avg × 1.7))          ← 单份软上限：均值的 1.7 倍
  max   = min(cap, 剩余总额 − (slots − 1))  ← 再留够后面每份至少 1 分
  take  = 在 [1, max] 里随机取一个
  这一份 = take，剩余总额 −= take

最后一份直接拿走剩下的全部（保证不剩零头）

效果就是：前面几份可能偏大，越到后面自然收窄，偶尔蹦出一个特别大的、也偶尔蹦出一个特别小的——和拆真红包那种「手气好、手气差」的感觉一致。而且因为每步都留了「后面每份至少 1 分」的余量，绝不会出现拆到一半没钱了的情况，总额守恒是写死在算法里的。

还要补一句：额度小的时候会少拆几份。比如本场你只剩 7 分的额度，那就拆 7 份、每份 1 分——不会硬凑 20 份，也不会出现「0 分的红包」。

五、限时抢：名额先到先得，抢到就是你的

红包雨是「人人有份、各点各的」，限时抢反过来：名额是有数的，谁先点谁拿，抢完就等下一场。

顺序上有个讲究：先占名额，再写积分。名额是竞争资源，如果先给钱再扣名额，两个请求同时进来就可能双双超发；反过来先占名额再写积分，万一写积分这一步失败了，系统会把这笔钱记进一个「待补发」的清单，你下次打开页面读数据的时候自动给你补上——名额已经占住了，就绝不会吞掉你这一份。这一点在第十一节还会再展开。

六、开抢时间，现在站长在页面上自己定

这是 v1.3.0 最实用的一处改动。以前改开抢节奏得用带密钥的接口发一条 GraphQL，对不写代码的站长很不友好。现在模块底部会多一个「设置开抢时间」的入口（只有站点管理员看得见），点开是一个抽屉：

抽屉里还写着两句提醒，是有实际含义的：

• 「只在上面这些时刻开场；秒数盖到下一个时刻会被自动收窄，太密的时刻会被丢掉。」——比如你排了 12:00 和 12:01 两个时刻，每场又要持续 300 秒，那这一对首尾就接上了：上一场还没结算，下一场就开了，界面会同时出现两场，统计也会串。所以服务端会把太密的时刻剔掉、把时长自动压到「下一个时刻之前」。
• 「从 0 点起等间隔开场，时间点会对齐到间隔的整数倍。」——间隔模式不是「你保存后 30 分钟开一场」，而是按当天 0 点起等分。所以改完间隔，下一场的时刻会立刻重算。

抽屉底部有两个按钮：「保存」写完立刻全站生效；「马上开一场」不改任何配置，只临时开一场应景——适合节日、整点活动。手动开的这一场优先级高于定时场，也高于「已暂停」，并且只在进行中有效，过期自动失效，不会污染你的常规节奏。

七、到点自动弹窗，不用守着模块

限时玩法最怕「用户不知道到点了」。所以 v1.3.0 加了一个到点自动弹窗：场次一开，页面上直接弹出抢包窗，里面已经在等着你了。

但它不是无脑弹，而是在这四件事都成立时才弹：

1. 场次确实正在进行；
2. 你本场还没参与过；
3. 今天还有额度（没到每日上限）；
4. 本场池子还没被抢空。

四条缺一条都不弹。原因很简单：弹了也抢不了——后台发起的开抢会被服务端按「已参与 / 额度用完 / 已抢完」拒掉，那用户看到的就只是一个「点了没反应」的窗，比不弹更糟。

另外两处细节：同一场次只弹一次（记在浏览器本地，刷新页面不会反复弹）；如果场次散了窗还开着（用户一直没点），会自动帮你把这场的额度结掉、退回奖池——不补这一刀，那笔额度会白占到会话超时（300 秒），谁也拿不到。

不想要自动弹窗的话，去 builder 的模块设置里把它关掉即可，用户从模块上的「开抢」按钮自己点。

八、场次引擎：算出来的，不是存出来的

「场次」是这个插件里另一个值得说的设计。没有「当前场次」这么一条记录存在数据库里——那样的话全站的人同时开场就要抢着写同一条数据，很别扭。

间隔模式的做法是「算出来的，不是存出来的」：

场次号 = 玩法名 + ":" + floor(当前时间 ÷ 场次间隔) × 场次间隔

举例（红包雨，间隔 30 分钟 = 1800 秒）：
  现在时间 1793282420
  → floor(1793282420 ÷ 1800) × 1800 = 1793282400
  → 场次号 = "rain:1793282400"

这个 1793282400 就是「本场开始的时间戳」，加 60 秒就是本场结束点。

好处是：任何人、任何时刻、在世界的哪个地方算出来，结果都一模一样。所以「全站共享同一场」这件事是天然成立的，不需要任何同步，也不会因为并发写坏了时序。

「每天固定时刻」模式稍微多一步：时刻表存的是「当天第几分钟」（0 ~ 1439），具体哪一天要等到算场次时才结合站点时区决定。这样你填的 12:00 就是「你后台时区的 12:00」，用户在世界哪个角落看到的都是同一个绝对时刻。跨天取下一场时会往后找一天，所以晚上最后一场结束后，倒计时能正确指向第二天第一场。

场次的区间是左闭右开：从开始的这一秒算在内，到「开始 + 时长」那一秒结束。时长必须短于间隔（这条在服务端是强制的），否则场次首尾相接，就失去「限时」的意义了。

还有一处专门兜过的坑：如果选了「每天固定时刻」却一个合法时刻都没排出来，服务端会退回「间隔模式」，而不是静默停办。因为后者意味着用户那头永远等不到场次，而界面上看不出任何异常——这是最难排查的一类故障。

九、防作弊：客户端在钱这件事上一个字都说不上

这类「抢福利」的玩法，最怕的就是被人当提款机。这里的闸门是这么设的：

十、界面上你会看到什么

模块拖进页面后长这样（自上而下）：

游客看到的是「登录后就能抢红包，抢到的积分直接进账户」和一个「去登录」按钮，点了会拉起站点自己的登录弹窗，不会跳走。

十一、发钱失败也不会吞你一分

「先到先得」最怕的是抢到了名额、钱却没到账。所以这里做了三层兜底：

1. 占位顺序：限时抢一定是先占名额，再写积分。名额占住了，说明这一份已经是你的了。
2. 待补发清单：写积分失败（比如某个账户写入出错）时，把这笔钱连同玩法、场次号挂进一个清单，并且当场告诉用户「积分这会儿没记上，稍后会自动补上」——不糊弄。
3. 读状态时自动补发：只要用户下次打开页面读一次数据，系统顺手把清单里属于他的那几条重新发一遍，发成功就移出清单，没成功继续挂着。发的时候同样带固定 source_key，所以补发一百次也不会重复发。

红包雨那边是另一种保障：开抢时那份额度是当场算好并占住奖池的，结算失败只会提示「再点一次结算」，而且发放的 source_key 是固定的，所以反复重试不会重复到账，也绝不会因为你手抖点快了点慢了就少发。

还有一条容易忽略的：你没点开的那部分会原数退回奖池。所以「点了一半就不玩了」不会让这些分凭空消失，后面的人还能抢到——这对全站的总量账是干净的。

十二、安装（按顺序做）

拿到安装包：guaqi-rain-arena-1.3.0.zip（68.1 KB）。

1. 上传：进 WordPress 后台的瓜奇插件管理页上传 ZIP。首次上传只安装，不自动启用。
2. 开开关：在插件列表里，把「红包雨 · 限时抢」在你要用的那个前端网站上启用（按前端网站独立启停）。
3. 拖到页面上：进 builder，从模块里把「红包雨 · 限时抢」拖进任意页面（模块型插件，不是表单型，首页、文章页、侧栏区块都能放）。
4. 点发布：这一步务必别漏——builder 里改完必须点「发布」，前台才会生效。
5. 验收：见下一节。

升级也一样：直接上传新版本覆盖安装即可。配置和场次进度存在服务端（选项表），个人记录、会话、战绩存在各自用户身上，不会丢数据。

十三、装完怎么验收

用带密钥的调试接口一次看完全部体检信息（当前配置、当前 / 下一场的起止时间、场次进度表、手动场、你的会话与战绩）：

mutation {
  gqRainDebug(input: { key: "gqrain-diag-3e9b47a1c52d", action: "status" }) {
    result
  }
}

action 还支持四个运维动作，省得你去数据库里手动改：

想临时插一场红包雨、60 秒、总额 500 分，一句话就够：

mutation {
  gqRainDebug(input: {
    key: "gqrain-diag-3e9b47a1c52d"
    action: "open"
    game: "rain"
    duration: 60
    pool: 500
    perUser: 100
  }) {
    result
  }
}

前端调用的接口一共六个，都不需要密钥，走正常的登录身份校验：

其中只有开抢 / 结算 / 抢这三种动作接受一个可选的 requestId，此外不接受任何业务参数——金额相关的东西一律不进请求体。

Config 型动作有句话要说在前头：调试接口改完配置后，本次请求内还是旧值（配置在单次请求里被记忆化了），下一次请求才生效。这不是 bug，是为了避免「改一半的配置被用到一半」。用抽屉改的话没这个问题，保存完拿到的就是新值。

十四、什么能调，什么不能调

这里有个刻意的分工，关系到你的站会不会被人钻空子：

为什么钱规则不给抽屉改？因为模块设置和表单是浏览器可以伪造的。如果总池、名额、奖励从页面上传过来，任何人改一下请求参数就能把自己的单场额度调到天上、把名额调成无限。所以「发多少」这五个参数一律只认服务端配置，而且读出来之后还要再夹一次天花板（上面表里那些上限）——就算有人能改数据库，也不可能把奖励调到把站里积分掏空。抽屉能改的只有「什么时候开、开多久」，以及四个展示开关。

想用代码接管规则也可以，挂过滤器即可（服务端仍会再夹一次天花板）：

add_filter('guaqi_rain_rules', function ($rules) {
    $rules['rainPool']    = 8000;   // 每场总池（服务端仍会夹到 100000）
    $rules['rainPerUser'] = 300;    // 单人单场上限（仍会夹到 2000，且不超过总池）
    $rules['grabStock']   = 50;     // 每场名额（仍会夹到 500）
    $rules['dailyCap']    = 800;    // 每人每日上限（仍会夹到 5000）
    return $rules;
});

十五、常见问题

Q：装了但页面上什么都没有？
按顺序查三步：插件在你这个前端网站上是不是启用状态 → builder 里模块有没有拖进页面 → builder 有没有点「发布」。三步缺一步都不显示。

Q：红包雨一直没开场，是不是坏了？
先看场次卡上的倒计时。默认红包雨是每 30 分钟一场、每场只有 60 秒，所以大部分时间都在「下一场」状态，这是正常的。想验证效果，用抽屉里的「马上开一场」立刻来一场，或者用调试接口 action: "open"。

Q：一场铺了几十个红包，我要一个个点吗？点不完怎么办？
要一个个点——这就是这个玩法的乐趣和压力所在。点不完没关系：没点开的那部分会原数退回奖池，后面的人还能抢，不会浪费。点满最后一个会自动帮你结算。

Q：我点开第一屏就跑了，会不会亏？
会少拿，但不会亏到别处去——你只拿你点开的那几份，没点开的回池子里；本场那次机会也已经用掉了（显示「本场已抢过」）。所以建议是：开抢之后尽量把这一屏点完。

Q：为什么抢到的红包有大有小？
这是设计好的。每次拆包都会在「剩余平均值」附近随机，单份的软上限是平均值的 1.7 倍，所以会出现偏大或偏小的几份，像拆真红包一样。但整场总额是守恒的，不会多也不会少。顺序还是打乱的，所以不能靠「从前往后点」来挑大的。

Q：能不能靠改参数多拿点？
改不了。客户端能提交的只有一个可选的 requestId，以及「点开了哪几份」的下标；能拿的上限本来就是开场时定好的那一份额度，多报拿不到额外好处。

Q：结算时提示「积分这会儿没记上」怎么办？
红包雨再点一次「结算」即可；限时抢会显示「稍后会自动补上」，你下次打开页面读数据时会自动补发。两种情况都用固定的发放标识，重复重试不会重复到账，也不会丢掉这一份。

Q：想搞整点活动怎么办？
两种做法：一是去抽屉里选「每天固定时刻」，把 12:00 / 20:00 / 22:00 填进去，长期生效；二是临时用「马上开一场」，优先级高于定时场、只在进行中有效，过期自动失效，不会污染你的常规节奏。

Q：我不想让用户被弹窗打扰？
去 builder 的模块设置里把「场次到点自动弹窗」关掉，用户就从模块上的「开抢」按钮自己点。

Q：游客点「去登录」没反应？
已确认这个按钮会真的拉起站点登录弹窗（沿用平台标准登录桥）。如果你的前端域名和源站不是同一个域，需要在 nginx 上把 /graphql 反代到源站——这是本站踩过的坑，写在这里省你一轮排查。

Q：升级会不会丢数据？
不会。配置和场次进度存在服务端（选项表），个人记录、会话、战绩存在各自用户身上，覆盖安装新版本即可。

十六、给站长的两句实话

第一，它是「定时定点热闹一下」的工具，不是常驻小游戏。红包雨一场只有 60 秒、限时抢更是一场最多 30 个名额，它的价值在于制造「整点有人抢」的节奏感，而不是让人天天泡在里面。建议把它放在首页显眼位置，并且在社区发个帖子告诉大家「几点几点有红包」——有人守着倒计时，这个玩法才成立。

第二，既然开抢时间能自己改了，就别一次改太勤。用户会记住你的节奏：今天是 12:00 / 20:00，明天突然变成每 10 分钟一场，他们会觉得规则不稳。比较稳的做法是固定两三个整点时刻长期不变，节日再用「马上开一场」加菜。

额度上还是那句老话：宁可先小后大。默认配置（红包雨每场 3000 分、限时抢每场 30 个名额、日上限 500 分）是偏保守的起步值，几乎不会让积分体系失速。先跑一两周看数据，再决定要不要把总池或日上限往上抬——抬容易，收回来难，用户会记得你调低过。

合规提醒：这个玩法的积分只能靠站内行为获得，不可提现、不可兑换现金、不可转让；页面上的规则（开抢时刻、总额、名额、每日上限、抢完即止）建议保持可见；红包雨的机制（额度开场即定、点开的那几份才算、没点到的退回奖池）也建议在页面上讲清楚，省得用户误会。积分透明 + 没有现金出口 + 规则公示，这三条能挡掉绝大多数麻烦。