主题
这页聚焦 部署 HNSignIn 时第一次启动会发生什么，以及你应该确认哪些点。
依赖关系
必需依赖
HNCore
HNSignIn 在 plugin.yml 中将 HNCore 标为硬依赖，因此：
- 没有
HNCore时不会正常工作 HNCore必须先完成启用
可选依赖
HNSignIn 当前声明了以下软依赖，只有在你启用对应能力时才需要：
HNEconomy：补签currencyrequirementHNWarehouse：补签warehouse物品来源PlaceholderAPI：给其他插件 / 菜单 / 记分板暴露%hncore_sign_*%占位符
除此之外，如果你在奖励里用了：
library-item- 某些控制台命令
那对应的物品库来源或命令执行目标也必须已可用。
首次启动会创建什么
首次启动后，通常会出现：
text
plugins/HNSignIn/
├─ config.yml
├─ gui/
│ ├─ calendar.yml
│ └─ confirm-dialogs.yml
└─ reward-groups/
└─ default-groups.yml说明：
config.yml：主配置文件gui/：签到主界面与确认弹窗配置reward-groups/：奖励组目录，便于主配置按组复用奖励定义
如果当前使用 yaml 后端，还会维护：
text
plugins/HNSignIn/playerdata/<uuid>.yml如果当前使用 database + sqlite，实际数据会写入：
text
plugins/HNSignIn/storage/hnsignin.db启动阶段做了哪些初始化
当前实现里，插件启动时会完成：
- 读取
config.yml - 同步默认
gui/与reward-groups/资源 - 解析业务日重置配置与存储后端
- 初始化
playerdata目录（仅yaml模式）或 database 运行环境 - 构建消息、签到周期、奖励、模板、补签策略与签到服务
- 注册
sign命名空间占位符提供器 - 初始化签到 GUI 的
GuiNavigator - 注册主命令
/hnsignin - 注册玩家生命周期监听器，用于处理快照预热、离线补偿恢复与临时状态清理
- 初始化
HNSignInAPI
如果启动失败，通常会集中在：
- 配置项写错导致加载异常
playerdata路径不可创建HNCore未正确启用
首启后建议立即执行的命令
1. 查看状态
text
/hnsignin status建议核对：
- 插件版本
- Debug 是否开启
- 业务时区
- 业务日重置时间
- 当前存储后端与连接 / 目录信息
- 补签窗口
- 补签策略摘要与补签消耗摘要
- 基础奖励数量
- 周模板 / 月模板数量
2. 打开签到界面
玩家执行：
text
/signin确认：
- GUI 能正常打开
- 没有点击异常
- 标题、日期、统计区显示正常
如果你启用了扩展奖励动作
library-item
请额外确认：
HNCore对应共享物品库来源可用source写法正确key对应物品真实存在
如果来源不可用，HNSignIn 不会因为这个直接阻断启动，但相关奖励在发放时会失败并记录日志。
item-spec
请额外确认：
spec结构符合 HNCore ItemSpec 语义- 如果用了
identity.serial: auto，理解它会在运行时生成唯一序列号 give-mode是否符合你的发奖预期
热重载能做什么
管理员可以使用：
text
/hnsignin reload当前会重建：
- 配置对象
- 奖励组注册表
- 业务日周期服务
- 占位符服务绑定
- 奖励服务
- 模板服务
- 补签 requirement / policy 服务
- 签到服务
- GUI 服务
同时，当前版本会对旧的异步任务施加 generation 防护。也就是说：
- reload 后旧 service 不应继续回写快照、落库或继续发奖
- 如果你在 reload 瞬间看到部分旧异步结果被直接丢弃，这属于当前设计预期
- 这类保护的优先级高于“强行完成旧任务”，目的是降低状态污染风险
这意味着大部分配置改动都可以通过重载生效。
但如果你同时改了：
- 外部物品库来源
- 依赖插件启用状态
- 服务器时区 / 核心环境
更稳的做法仍然是完整重启服务器。
首启后最常见的观察点
1. GUI 打不开
优先检查：
- 玩家是否有
hnsignin.command.open - 插件是否启用成功
- 控制台是否有初始化失败日志
2. 点签到没奖励
优先检查：
rewards.daily是否配置有效- 奖励动作是否拼写正确
- 如果是
library-item，对应来源是否可用 - 如果是
command，命令本身能否单独执行成功
3. 状态和你理解的不一致
优先检查：
- 当前业务日到底是哪一天
- 当前重置时间是否已经跨过
query命令显示的周期与模板状态
下一步看什么
想快速跑通一轮验证：看 快速开始
想核对配置项：看 config.yml 配置说明
想排查数据与运维：看 数据存储与运维 �
想快速跑通一轮验证：看 快速开始
想核对配置项：看 config.yml 配置说明
想排查数据与运维：看 数据存储与运维