主题
这页专门说明 HNSignIn 的奖励是怎么命中的。
当前版本可以把奖励分成两大类：
- 基础奖励
- 模板奖励
一、基础奖励
1. daily
每次成功签到 / 补签都会发放。
这是最稳定、最基础的一层奖励。
2. streak-tiers
当玩家连续签到从较低值跨过某个阈值时发放。
例如：
- 之前连签 2 天，今天签到后变 3 天，会触发 3 天档位
- 之前连签 6 天，今天签到后变 7 天，会触发 7 天档位
3. total-tiers
累计签到达到阈值后，不会自动发放，而是玩家在 GUI 中手动点击领取。
这意味着它适合做：
- 玩家主动领取的阶段奖励
- 长线养成奖励
二、模板奖励
模板奖励用于表达“周期性”或“结构化”的奖励规则。
1. 周固定 7 日周期：weekly.fixed-cycle
这是一个 全服共享的 7 日循环表。
它依赖：
anchor-date- 当前业务日
来推导：
- 当前属于哪一期周期
- 当前是这一期的第几天
然后根据第几天发放对应奖励。
适合场景
- 全服一周签到活动
- 每周轮播签到表
- 希望全服同一天拿到同一类奖励
2. 玩家个人 7 日循环：weekly.personal-cycle
这是 每个玩家自己的独立 7 日循环。
特点：
- 每次成功签到推进一格
- 不依赖自然周
- 玩家 A 与玩家 B 可以在不同进度
- 进度持久化在玩家数据里
适合场景
- 新玩家第 1~7 次签到成长奖励
- 长线个人循环签到
- 不希望玩家被全服日历绑定
3. 周期累计签到：weekly.period-accumulate
它也是基于固定 7 日周期，但发奖依据不是“第几天”，而是：
- 这一期内累计签到达到多少次
比如：
- 本周期签满 1 天
- 本周期签满 3 天
- 本周期签满 5 天
- 本周期签满 7 天
适合场景
- 本周累计签到达标奖励
- 运营活动中的阶段奖励
4. 月指定日历天：monthly.calendar-days
这类奖励直接看 日历日。
例如：
- 每月 1 号
- 每月 7 号
- 每月 15 号
- 每月 28 号
只要玩家在对应日期成功签到 / 补签，就会命中对应奖励。
5. 月累计里程碑：monthly.milestones
看的是：
- 当前业务月内，玩家已签到多少天
达到指定门槛时自动发放。
例如：
- 本月累计签到 5 天
- 本月累计签到 10 天
- 本月累计签到 20 天
6. 月终奖：monthly.final-reward
它是月模板里最“总奖励”的一层。
命中条件：
- 本月签到数达到
required-days
当前实现中，达到后会 自动发放。
当前奖励执行链路补充
当前版本里，奖励已经不再是“命中后立刻直接执行完就算结束”，而是更偏向一条可追踪链路：
- 先登记奖励投递记录
- 再执行真实发奖动作
- 如果失败，则保留待处理状态
- 后续通过自动或手动重试补发
这意味着：
- 模板奖励、基础奖励、手动补发奖励的行为模型已经更统一
- 开放测试时不应只看“玩家背包有没有东西”，也要同时看是否产生了待重试记录
- 当奖励动作失败时，优先使用
query和retry-rewards排查，而不是直接手改数据
三、奖励动作类型
无论是基础奖励还是模板奖励，最终都由 actions 执行。
command
执行控制台命令。
适合：
- 发原版物品
- 触发其他插件命令
- 发放积分、货币、头衔等外部能力
message
向玩家发送消息。
适合：
- 强化反馈
- 告知奖励来源
- 展示当前命中的模板信息
library-item
通过 HNCore 共享物品库解析物品并发放。
适合：
- 发 MythicItems / NeigeItems / 其他已接 HNCore 的物品
- 避免把复杂物品写成笨重命令
item-spec
通过 HNCore ItemSpecParser + ItemSpecResolver 在运行时构造物品并发放。
适合：
- 需要直接在签到奖励里定义
material / display-name / lore / identity / pdc - 想给奖励物品自动生成唯一
serial - 想统一复用 HNCore 的物品身份与 ItemSpec 语义
常见约定：
identity.serial: auto：自动生成唯一序列号serial-prefix：给自动序列号增加前缀，支持占位符- 仍可配合
give-mode控制进背包 / 掉落语义
奖励组与内联奖励
当前奖励定义既可以直接内联，也可以通过 reward-group 引用目录中的奖励组。
更推荐在下面场景使用奖励组：
- 同一奖励在
daily / streak / templates多处复用 - 想把复杂
random-pool或item-spec配置从主业务配置里拆出去 - 想让运营只维护奖励内容，而不是同时碰业务规则
四、模板奖励什么时候算“已领”
当前实现中，模板奖励一旦命中并写入玩家数据，就会记录到：
claimed-template-rewards.weeklyclaimed-template-rewards.monthly
也就是说，系统会尽量避免在同一模板节点上重复发奖。
这意味着什么
- 如果你改了模板配置但不重置状态，玩家可能不会再次拿到同一节点奖励
- 如果你需要回放测试，应该用
template-reset - 如果你需要手动补偿，应该用
template-grant
五、常见理解误区
1. 固定周期和个人循环不是一回事
fixed-cycle：全服共享一套周表personal-cycle：每个玩家自己推进
2. 月指定日奖励与月累计奖励不是一回事
calendar-days：看日历日milestones：看本月签到总数
3. 月终奖不是 GUI 手动领
当前实现里：
total-tiers是手动领取monthly.final-reward是自动发放
六、推荐配置策略
如果你第一次配置模板体系，建议：
轻量方案
dailyweekly.fixed-cyclemonthly.final-reward
成长方案
dailyweekly.personal-cyclemonthly.milestones
运营方案
dailyweekly.fixed-cycleweekly.period-accumulatemonthly.calendar-daysmonthly.final-reward
不要第一轮就把所有层都堆上去，先选一种清晰的奖励哲学更好维护。