主题
1. 为什么玩家凌晨签到，却提示今天已经签过了？
通常不是重复签到，而是 业务日还没切换。
请检查：
reset.hourreset.minutereset.timezone
如果当前时间还没过重置点，那么系统仍然把“今天”视为上一业务日。
2. 为什么某个漏签日期不能补签？
优先检查：
- 是否早于当前业务日
- 是否超出
make-up.window-days - 是否被
allow-cross-month: false挡住 - 是否命中了补签
conditions / limits / rules - 是否缺少货币、背包物品或仓库物品
- 对应软依赖（
HNEconomy/HNWarehouse）是否可用
3. 为什么玩家补签成功了，但奖励和预期不一样？
先区分三种情况：
- 基础奖励没发
- 模板奖励没发
- 奖励动作执行了，但玩家没看到结果
排查建议：
- 用
/hnsignin query <玩家>看状态是否已写入 - 看模板奖励是否已经记录为已领
- 如果用了
command，单独测试那条命令是否能执行 - 如果用了
library-item，确认来源与 key 是否有效 - 如果用了
item-spec，确认spec / identity / pdc结构是否有效
4. 为什么模板奖励不再重复发？
因为系统会记录模板领奖状态。
记录位置：
claimed-template-rewards.weeklyclaimed-template-rewards.monthly
如果你要回放测试，请使用：
text
/hnsignin template-reset <玩家> ...不要误以为“配置还在，所以每次都应重复发”。
5. fixed-cycle 和 personal-cycle 有什么区别？
fixed-cycle
- 全服共享周期
- 基于
anchor-date - 同一天所有玩家看见的是同一个周期日序
personal-cycle
- 每个玩家独立推进
- 不依赖全服日期表
- 更适合个人成长奖励
6. monthly.final-reward 是手动领取还是自动发放？
当前实现里：
rewards.total-tiers：手动点击领取templates.monthly.final-reward：自动发放
这两类不要混淆。
7. library-item 奖励为什么没到账？
常见原因：
source写错- 该物品库来源当前不可用
key不存在amount非法inventory模式下背包放不下
建议先确认：
HNCore对应来源是否可用- 同一个
source:key能否在别处成功解析
8. item-spec 奖励为什么没到账或序列号不对？
常见原因：
spec结构写错，HNCore 无法解析identity.serial没写成auto/@auto/generateserial-prefix使用了空占位符，导致前缀不是你预期的值inventory模式下背包放不下
建议先确认：
- 同一份
spec是否能被 HNCore 正常解析 identity与pdc字段是否按 HNCore 约定填写- 奖励配置里是否误把
name/display-name、id/item-id写混
9. 我应该优先用 template-reset 还是手改 YAML？
优先用：
querytemplate-resettemplate-grant
只有在这些命令不够表达，或者玩家文件已经损坏时，再考虑手改 YAML。
10. template-grant 为什么要求玩家在线？
因为当前补发逻辑是直接对在线玩家执行奖励发放流程。
这尤其影响：
message动作- 背包类发奖
library-item发奖
如果你要离线补偿，更适合：
- 用外部命令补偿
- 或等后续版本增加离线补偿链路
11. query 看起来没问题，但玩家仍反馈奖励不对，怎么办？
最稳的顺序是：
query看状态与待重试奖励数量- 判断是状态问题还是动作问题
- 如果只是奖励动作失败，优先
retry-rewards - 必要时
template-reset current-weekly/current-monthly - 必要时
template-grant - 最后才手改 YAML
这样最不容易把真实问题掩盖掉。
12. 为什么有些占位符第一次会返回 0 或空字符串？
这是当前版本的刻意设计。
当签到快照缓存 miss 时，HNSignIn 不再让 Placeholder 请求同步冷读仓储，而是：
- 本次先返回安全默认值
- 同时异步预热快照
- 下一次请求通常就会命中缓存
当前默认降级大致是：
- 计数类：
0 - 日期 / 时间类：空字符串
这样做的目的是降低记分板、菜单、HUD 等高频占位符请求把主线程重新拖进冷路径的风险。
13. 为什么 reload 后有些旧任务不继续执行？
这是当前实现故意加的 generation 防护。
它的取向是：
- 宁可丢弃旧的过期异步任务
- 也不要让旧 service 在 reload 后继续回写快照、继续落库或继续发奖
所以如果你在测试时看到“reload 前发起的旧动作没有继续完成”，优先把它理解为保护行为，而不是直接理解为 bug。
14. pending-rollbacks.yml 是什么，什么时候会出现？
这是离线补签背包回滚的恢复文件。
它通常出现在：
- 玩家补签扣掉了背包物品
- 后续保存失败，需要回滚
- 但玩家已经离线，背包不能立即返还
- 插件此时又发生了 disable / reload
当前实现会把这类待补偿动作持久化，等下次启动恢复，再在玩家上线时继续返还。
所以：
- 看到这个文件不一定是坏事
- 更常见的含义是：插件在尽量避免静默丢失补偿
15. retry-rewards 和 template-grant 有什么区别？
区别很明确：
retry-rewards：重试已经登记过、但尚未完成的奖励投递template-grant：人为追加一次新的模板奖励补发动作
推荐顺序通常是：
- 先
query - 如果看到待重试奖励，先
retry-rewards - 确认并不是“已有记录但动作失败”后，再考虑
template-grant