这页的目标是带你 按最短路径跑通一条真实可验证链路：

1. HNCore 与 HNSignIn 能正常启动
2. 玩家能打开签到 GUI
3. 玩家能完成当日签到
4. 玩家能完成一次补签
5. 基础奖励与模板奖励能正常发放
6. 管理员能查到玩家当前状态

---

第 1 步：准备依赖

必需依赖

• HNCore
• HNSignIn

建议环境

• Paper 1.20.1
• Java 17

如果你要用扩展能力，还要额外保证：

• 使用 library-item 时，HNCore 已接入对应物品库来源，且目标来源当前可用
• 使用 item-spec 时，相关物品定义字段（如 identity / pdc）已按 HNCore 约定填写
• 使用补签 currency requirement 时，服务器已安装 HNEconomy
• 使用补签 warehouse 来源时，服务器已安装 HNWarehouse
• 想在其他插件里读取 %hncore_sign_*% 占位符时，服务器已安装 PlaceholderAPI

---

第 2 步：首次启动先确认这些点

启动服务器后，优先确认：

• plugins/HNSignIn/config.yml 已生成
• plugins/HNSignIn/gui/ 已生成默认界面配置
• plugins/HNSignIn/reward-groups/ 已生成默认奖励组示例
• 如果当前是 yaml 后端，plugins/HNSignIn/playerdata/ 已创建
• 如果当前是 database + sqlite，后续写入数据后会落到 plugins/HNSignIn/storage/hnsignin.db
• 控制台没有出现配置加载失败、依赖缺失或占位符/补签运行时 hook 异常

你还可以执行：

/hnsignin status

重点确认：

• 时区是否正确
• 业务日重置时间是否正确
• 当前存储后端是否符合预期（默认推荐 database）
• 补签策略 / 补签消耗摘要是否符合预期
• 周模板与月模板奖励数量是否符合预期

---

第 3 步：先跑通最基础的一次签到

玩家执行：

/signin

或：

/hnsignin
/hnsi

打开签到日历 GUI 后：

• 点击“今日可签到”格子
• 观察是否出现签到成功提示
• 观察背包 / 控制台命令结果 / 消息提示是否正确

你要验证的内容：

• 今日状态变成“已签到”
• 如果当前是 yaml 后端，playerdata/<uuid>.yml 里出现今天的签到记录
• 如果当前是 database 后端，query / status 与奖励行为能反映这次签到已落库
• 基础奖励已发放
• 如果配置了模板奖励，当次命中的模板奖励也已发放

开放测试阶段建议额外观察：

• 第一次打开 GUI 是否能正常完成异步加载
• 如果奖励动作失败，是否会留下待重试记录，而不是静默丢失
• reload 后重新打开 GUI，界面是否仍保持一致

---

第 4 步：再验证补签

如果当前业务日前面有漏签日期，可以直接在 GUI 中点击可补签日期。

补签是否可用，取决于：

• make-up.window-days
• make-up.allow-cross-month
• 当前业务日

如果开启了补签 requirement / 限制，还要验证：

• 条件满足时可以成功补签
• 货币 / 背包 / 仓库物品足够时会正确扣除
• 条件不满足、额度超限或依赖插件缺失时会给出正确提示

你要验证的内容：

• 漏签日期变成“已补签”
• 对应日期写入玩家 YAML
• 补签奖励发放正常
• 失败时不会把数据写坏

---

第 5 步：验证模板奖励

建议至少测试这三类：

固定 7 日周期

确认：

• 当前业务日属于哪个周期
• 当前是周期第几天
• 签到后是否命中 templates.weekly.fixed-cycle 对应奖励

个人 7 日循环

确认：

• 玩家第一次签到时循环进度推进为第 1 天
• 再次签到时会继续推进
• template-state.personal-cycle 会被持久化

月模板

确认：

• 当月指定日期奖励是否按日历日命中
• 月累计签到里程碑是否按本月签到数命中
• 月终奖是否按 required-days 命中

---

第 6 步：学会用查询命令看状态

管理员执行：

/hnsignin query <玩家>

建议重点核对：

• 当前业务日
• 当前连签 / 累计签到 / 本月签到
• 当前固定 7 日周期信息
• 个人七日循环轮次与进度
• 月终奖进度
• 当前周模板已领取项
• 当前月模板已领取项

这一步能帮助你快速判断：

• 是奖励没发
• 还是状态没记
• 还是命令发了但玩家没观察到

---

推荐的首版验证顺序

最建议按下面这个顺序来：

1. /hnsignin status
2. /signin
3. 当日签到成功
4. 查询玩家状态
5. 补签一次
6. 验证模板奖励
7. 测试 template-reset
8. 测试 template-grant

不要一开始就把所有模板和外部物品库一起打开。先跑通基础签到，再逐层叠加。

---

下一步看什么

• 想确认依赖、数据目录和首启行为：看 安装与首次启动
• 想核对配置结构：看 config.yml 配置说明
• 想理解模板奖励：看 奖励体系与模板机制