主题
HNSignIn v0.1.0-SNAPSHOT
当前阶段：0.1.0-SNAPSHOT（2026-04-08 里程碑整理）
- 当前阶段标识：
0.1.0-SNAPSHOT - 里程碑日期：2026-04-08
- 关键提交：
95cd86b、272b4d2 - 阶段定位：从"可运行的签到 MVP"继续推进到"具备运维、扩展与 HNCore 统一协议对接能力的签到模块"
阶段定位
如果只看最早阶段，HNSignIn 的重点是：
- 玩家能签到
- 玩家能补签
- GUI 能展示
- 奖励能发
而到这一轮之后，它开始明显从"单体可用插件"往"可维护、可迁移、可扩展的业务模块"演进，主要变化集中在：
- 存储后端不再只剩 YAML
- 迁移、校验、报告导出开始成为正式运维链路
- 补签不再只是简单扣一件物品
- 奖励不再只剩命令 / 消息 / 物品库三板斧
- 对外占位符、周期计算、物品发放开始统一复用 HNCore 1.1 能力
这意味着：
- 对服主来说，签到系统开始更适合正式服长期运营
- 对维护者来说，排障和迁移不再只能靠手改文件
- 对二开来说，HNSignIn 逐步能站到 HNCore 的统一协议上，而不是自己继续重复造一套底层逻辑
本轮重点新增 / 调整
1. 基础签到主链路成型
来源提交：8be1a25（Add HNSignIn plugin implementation）
这一阶段先把插件主链路搭出来了：
- 玩家可通过
/hnsignin//signin打开签到 GUI - 支持按业务日进行每日签到
- 支持最近窗口内补签
- 提供基础奖励、连签奖励、累计奖励
- 提供周模板与月模板奖励
- 提供查询、模板重置、模板补发等管理命令
如果没有这一层，后续的双后端、周期工具、占位符、ItemSpec 都没有落脚点。这一阶段相当于把签到业务本身先跑通。
2. 双后端存储与迁移运维链路补齐
来源提交：95cd86b（Add switchable storage backends and migration tooling）
这一轮最大的提升之一，是把存储从"只有 YAML 文件"推进到了"YAML / database 双后端可切换"：
- 支持
storage.type: yaml - 支持
storage.type: database - database 下支持
sqlite / mysql - 新增
/hnsignin migrate-storage preview - 新增
/hnsignin migrate-storage validate - 新增双向迁移命令与
confirm保护 - 新增迁移报告导出能力
这一步的意义不只是"能换个存储"，而是 HNSignIn 开始具备正式运维能力：
- 你可以先预览，不必盲迁
- 你可以做双向校验，而不是靠猜
- 你可以回看报告，而不是只看一屏命令输出
对于从测试服走向正式服的场景，这一步很关键。
3. 补签系统从"固定物品扣除"升级为完整 requirement / policy 体系
来源提交：272b4d2（对接 HNCore 1.1 签到服务与奖励能力）中的补签相关改动
这一轮之后，补签不再只是：
- 开 / 关
- 扣一件固定材质物品
而是升级成：
conditions：权限 / 等级 / PAPI 数值前置条件formula-variables：公式变量映射limits：总次数 / 月 / 周 / 日 限制limits.rules：高级限制表达式cost.requirements：默认 requirement 列表cost.groups：分组价格 / 免费组 / 条件组currency/item/warehouse运行时 requirement
这代表 HNSignIn 的补签机制开始从"演示功能"走向"可表达真实运营规则"的层级。
4. 默认存储推荐切换到 database，YAML 退到 legacy 位
来源提交：272b4d2
当前实现里，文档与默认配置已经开始明确表达：
database是当前推荐的正式后端yaml继续保留，但更偏向 legacy 兼容与迁移通道
同时：
- 启动时若仍使用 YAML，会给出 legacy 提示
status命令里也会明确提醒当前仍处于 legacy YAML 模式
这意味着项目已经开始对"正式运维默认姿势"给出更清晰导向，而不是继续把 YAML 当唯一主线。
5. 周期、占位符与消息渲染切换到 HNCore 1.1 公共能力
来源提交：272b4d2
这一轮把几块底层能力切到了 HNCore 1.1：
SignPeriodService接管业务日、周周期、月周期计算MessageService切到 HNCorePlaceholderService- 新增
SignPlaceholderProvider - GUI、奖励、消息开始走统一占位符链路
这一步的意义是：
- HNSignIn 不再单独维护一套时间边界与占位符体系
- 后续和其他 HN 模块的行为语义更容易保持一致
- 配置里的动态文本能力开始真正站到 HNCore 的统一协议上
6. 新增对外 %hncore_sign_*% 占位符
来源提交：272b4d2
当前已经提供：
%hncore_sign_signed_today%%hncore_sign_streak%%hncore_sign_total%%hncore_sign_month_total%%hncore_sign_last_sign_date%%hncore_sign_last_sign_time%
这意味着服主和二开现在可以更方便地把签到状态接到：
- 记分板
- 菜单插件
- HUD / 面板
- 条件判断插件
对于"签到数据想给别的系统看"这类需求，这一步非常实用。
7. 奖励动作扩展到 item-spec，并接入 HNCore 统一物品链路
来源提交：272b4d2
这一轮之前，奖励动作主要是：
commandmessagelibrary-item
这一轮之后，新增：
item-spec
并且它不是随便新增一个配置分支，而是直接接到了 HNCore 1.1 的统一物品能力上：
ItemSpecParserItemSpecResolverItemDeliveryServiceSerialGenerator
所以现在你可以在签到奖励里：
- 直接定义
material / display-name / lore - 定义
identity / pdc - 使用
identity.serial: auto - 通过
serial-prefix生成唯一奖励物品
这让签到奖励开始能承载更复杂、更规范的业务物品，而不是只靠外部命令或外部物品库曲线实现。
8. GUI Flow V1 接入继续收口
来源提交：272b4d2 与此前 GUI 迁移阶段共同形成当前状态
当前 HNSignIn 的 GUI 已经明确站在 HNCore GUI Flow V1 上：
- 主日历通过
BaseChestScreen承载 - 补签确认通过标准确认弹窗流转
GuiSession承接跨页状态CalendarService主要负责渲染，而不再是老式直接拼 Inventory 的单体入口
9. 奖励一致性、补偿重试与主线程性能开始收口
来源提交：当前 0.1.0-SNAPSHOT 阶段后续优化整理
这一轮虽然还没变更版本号，但已经补了几块很关键的"稳定性内功"：
- 签到 / 补签 / 累签领取 /
template-grant改为先登记奖励投递记录，再执行真实发奖 - 奖励失败时不会再无痕丢失，而是保留
PENDING / FAILED状态 - 新增
/hnsignin retry-rewards <player>手动重试命令 - 玩家再次打开签到 GUI 时，会自动尝试补发未完成奖励
query会显示奖励投递总数与待重试数量- 日历页面改成单次 render context，减少重复加载与重复 preview
migrate-storage迁移 / 校验 / 预览改为后台异步执行- database 后端保存从"全量删后重写"收敛到按差异增量同步
signplaceholder 增加短 TTL 快照缓存，MakeUpPolicyService缓存 PAPI 反射入口
这几项的意义不在"多了几个配置项"，而在：
- 玩家资产与签到状态的一致性更可靠
- GUI 打开与高频占位符读取更轻
- 管理员做迁移和校验时更不容易卡主线程
- database 后端开始更像真正的数据库实现，而不是 YAML 快照镜像
这意味着未来如果要继续加：
- 多月翻页
- 奖励详情页
- 模板预览页
- 更多危险操作确认流
现在的底座已经比早期实现稳很多。
10. 开放测试前的稳定性收口（近期提交整理）
来源提交：9720298、484869a
这一轮虽然仍然没有单独变更对外版本号，但做了非常多"准备开放测试前必须收口"的调整：
- 补签成本回滚从旧的
Consumer<Player>升级为带上下文的 rollback action HNWarehouse从整页快照回放改成 delta 回滚，降低跨模块数据回退风险- 货币补签成本支持更宽松的离线身份退款尝试
- 背包补签成本在玩家离线时可延期恢复，并在 disable 时持久化到
pending-rollbacks.yml SignInService为快照 preload、异步加载、completion 与发奖链路补上 generation / epoch 防护- reload 后旧 service 不再继续落库、回写缓存或执行过期奖励投递
- Placeholder cache miss 不再同步冷读仓储，而是返回默认值并异步预热快照
- GUI 非法日期点击前置短路，未来日期 / 不可补签日期不再进入无意义异步补签链路
CalendarService的补签预览改为分批跨 tick 构建，降低主线程尖峰- 新增针对
SignPlaceholderProvider、CalendarService、PlayerStateListener与异步入口的直接回归测试
这一步的意义非常直接：
- 不是继续单纯堆功能
- 而是把"开放测试时最容易炸的数据一致性与边界链路"先尽量压稳
如果你正准备把 HNSignIn 放给测试服，这一轮内容值得优先关注。
升级提醒
如果你是服主
这一轮最重要的认知变化不是"多了几个配置项"，而是：
- 默认运维姿势开始偏向
database - 补签能力大幅增强，也意味着配置复杂度上升
- 奖励物品链路开始可以走更规范的 ItemSpec 方案
- 签到状态现在更适合对外暴露给其他展示层消费
也就是说，这一轮之后更像是一套可以长期运营的签到系统，而不只是简单签到插件。
如果你是运维 / 配服人员
升级后最需要注意：
- 不要只改
storage.type就以为数据会自动迁过去 - 补签问题要学会从
conditions / limits / requirement / 依赖插件多层排查 - 如果开始启用
item-spec，要理解它和library-item的边界不同 - 如果面板要读签到状态，应该开始用
%hncore_sign_*%
如果你是二开开发者
升级后最值得关注的是：
- 尽量复用 HNCore 的周期、占位符、物品定义与物品发放能力
- 不要再自己绕过流程去直接改玩家 YAML 或自行拼一套奖励物品逻辑
- 读取签到状态优先用
HNSignInAPI + SignInStatusSnapshot - 展示层联动优先考虑
%hncore_sign_*%
升级后建议检查
建议在这轮能力升级后，至少做下面几类回归：
状态检查
/hnsignin status- 确认业务日、存储后端、补签策略、补签消耗摘要是否正确
主链路检查
- 玩家打开
/signin - 完成一次签到
- 完成一次补签
- 用
/hnsignin query <玩家>核对状态
- 玩家打开
存储检查
- 如果使用
database，确认状态写入正常 - 如果从 YAML 切换过来，执行
preview / validate / confirm的完整迁移链路
- 如果使用
补签规则检查
- 校验条件满足 / 不满足两侧行为
- 校验限额超限行为
- 校验
HNEconomy / HNWarehouse依赖缺失时是否给出明确反馈
奖励检查
- 校验
command/message/library-item/item-spec四种动作 - 校验
inventory / inventory_or_drop / drop三种 give-mode - 校验
identity.serial: auto是否符合预期
- 校验
展示层检查
- 如果安装了
PlaceholderAPI，确认%hncore_sign_*%读取正常 - 确认 GUI 文本里的业务占位符正常渲染
- 如果安装了