这页面向 想从别的插件读取或调用 HNSignIn 能力的开发者。

---

当前公开入口

当前对外公开的入口类是：

• com.github.hnplugins.hnsignin.api.HNSignInAPI

它提供：

• HNSignInAPI.getSignInService()：获取签到服务接口（返回 ISignInService）

注意：从 HNCore 2.0.0 迁移后，API 已重构为接口优先设计：

• ✅ 返回 ISignInService 接口而非实现类
• ❌ 不再提供 HNSignInAPI.get() 方法（不暴露插件实例）
• ✅ 符合团队 API 架构规范

---

可以做什么

通过当前 API，你已经可以：

• 拿到 ISignInService 接口
• 查询玩家当前签到快照
• 读取业务日相关状态
• 读取连签、累签、模板状态等信息

例如，你可以基于它做：

• 其他插件里的签到检测
• 自定义活动判断
• 管理面板展示
• 对接你自己的 GUI 或统计页

示例代码：

import com.github.hnplugins.hnsignin.api.HNSignInAPI;
import com.github.hnplugins.hnsignin.api.ISignInService;
import com.github.hnplugins.hnsignin.domain.SignInStatusSnapshot;

// 获取签到服务
ISignInService signInService = HNSignInAPI.getSignInService();

// 查询玩家签到状态
SignInStatusSnapshot snapshot = signInService.getSnapshot(player.getUniqueId(), player.getName());

// 读取状态
boolean signedToday = snapshot.signedToday();
int currentStreak = snapshot.currentStreak();
int totalSignedDays = snapshot.totalSignedDays();

---

典型读取方式

思路通常是：

1. 拿到 ISignInService 接口
2. 传入玩家 UUID 与名称
3. 获取 SignInStatusSnapshot
4. 从快照中读取状态

你通常会关心：

• today()
• signedToday()
• currentStreak()
• totalSignedDays()
• currentMonthSignedDays()
• currentFixedCycleKey()
• currentFixedCycleDayIndex()
• personalCycleProgress()
• personalCycleRound()
• monthlyFinalRewardProgress()
• claimedCurrentWeeklyTemplateRewardIds()
• claimedCurrentMonthlyTemplateRewardIds()

---

关于写操作的建议

虽然当前 ISignInService 内部有完整写逻辑，但从外部插件接入角度，建议你：

• 优先做"读取状态"而不是直接替玩家写数据
• 如果一定要做写入，最好让玩家通过原生 GUI / 命令走完整流程
• 不要绕过内部流程直接改玩家数据文件

原因是 HNSignIn 的写入不只是记一条签到，还会联动：

• 连签
• 累签
• 模板奖励命中
• 模板领奖状态持久化
• 个人循环推进

绕过这些流程，很容易只改了一半状态。

---

与 HNCore 的关系

HNSignIn 当前依赖 HNCore 3.0.6+ 的公共能力，尤其是：

• DatabaseService / ConfigService：统一数据库和配置管理（2.0.0+ 接口化设计）
• ResetClock / ResetRule：统一业务日、周周期、月周期计算
• PlaceholderService：统一消息、GUI、奖励占位符渲染
• ItemDeliveryService：统一物品投递语义
• 外部物品库解析（library-item）
• ItemSpecParser / ItemSpecResolver / SerialGenerator：支持 item-spec 奖励与自动序列号
• GUI Flow V1：签到页面与确认弹窗流转

如果你在别的插件里也想复用这些能力，可以直接看 HNCore 的对应入口，而不必通过 HNSignIn 间接调用。

---

GUI Flow V1 接入现状

HNCore 现在已经开放了一套可复用的 GUI Flow V1，核心包括：

• GuiNavigator
• ScreenContext
• GuiSession
• BaseChestScreen
• ConfirmDialog

并推荐下游按下面的方式接入：

• 普通页面优先继承 BaseChestScreen
• 页面跳转统一走 open / push / replace / back / close
• 跨页状态统一放进 GuiSession
• 如果自定义 Screen，务必绑定 context.closeHandler()

HNSignIn 当前是否已经迁移？

已经完成首轮迁移。

当前 HNSignIn 已经使用：

• GuiNavigator 作为签到入口与页面刷新枢纽
• BaseChestScreen 承载单页签到日历
• GuiSession 预留当前页面状态，便于后续扩展
• CalendarService 作为渲染辅助服务，而不是直接构建 Inventory

也就是说，当前的签到 GUI 已经切到 GUI Flow V1，但仍然保持“单页日历”的交互复杂度。

这对下游意味着什么？

如果你只是读取签到状态或通过 HNSignInAPI 做业务联动，这与旧版没有本质差异。

但如果你准备：

• 给 HNSignIn 增加多月翻页
• 增加奖励详情页 / 模板预览页
• 增加危险操作确认弹窗
• 把签到 GUI 演进成多步骤页面流

那么现在已经可以直接沿着现有 Flow V1 结构继续扩展，而不需要再维护旧的 Holder + Listener 模式。

---

PlaceholderAPI / HNCore 占位符接入

当前插件已注册 sign 命名空间，可通过 HNCore / PlaceholderAPI 使用：

• %hncore_sign_signed_today%
• %hncore_sign_streak%
• %hncore_sign_total%
• %hncore_sign_month_total%
• %hncore_sign_last_sign_date%
• %hncore_sign_last_sign_time%

这意味着你可以很方便地把签到状态接到：

• 记分板
• 菜单插件
• 条件判断插件
• 其他支持 PlaceholderAPI 的展示层

如果服务器未安装 PlaceholderAPI，HNSignIn 本体仍可正常运行，只是 %hncore_sign_*% 不会对外暴露给其他插件消费。

---

当前 API 的边界

当前版本更偏向：

• 查询服务已可用
• 业务集成可做
• 深度二开接口还不算特别丰富

也就是说，它已经足够拿来做：

• 显示层整合
• 条件判断
• 运营联动

但如果你想做“完全接管签到流程”，目前仍建议以源码集成为主，而不是把它当成熟 SDK 使用。

---

推荐接入姿势

如果你只是想判断玩家今天签没签

直接读取快照即可。

如果你想按连签给别的插件加成

读取：

• currentStreak()

如果你想按月签到进度做活动

读取：

• currentMonthSignedDays()
• monthlyFinalRewardProgress()
• monthlyFinalRewardTarget()

如果你想知道当前模板状态

读取：

• claimedCurrentWeeklyTemplateRewardIds()
• claimedCurrentMonthlyTemplateRewardIds()

---

实战建议

如果你是下游插件开发者，最稳的路径是：

1. 把 HNSignIn 当作“签到状态源”
2. 用 SignInStatusSnapshot 读状态
3. 把你自己的逻辑构建在快照之上
4. 不直接入侵它的玩家 YAML

这样兼容性最好，也最不容易在后续版本更新时出问题。