联动

OnlineRewards 模块通过 Capability 注册、EventBus 事件发布、跨服通道同步等机制与其他模块和子系统联动。

Capability 注册

模块在启动时注册以下 Capability，供其他模块通过 getCapability() 获取并调用：

OnlineRewardsQueryable

提供在线奖励的查询与操作能力（公开 capability，@PublicCapability），接口定义位于 xuanmo.arcartxsuite.api.capability.OnlineRewardsQueryable。外部插件可经 AxsCapabilities.get(OnlineRewardsQueryable.class) 获取，模块未启用时返回 null。

使用示例（其他模块中）：

OnlineRewardsQueryable rewards = getCapability(OnlineRewardsQueryable.class);
if (rewards != null) {
    boolean signed = rewards.hasSignedToday(player.getUniqueId());
    int todayMinutes = rewards.todayOnlineMinutes(player.getUniqueId());
    // 给玩家增加 30 分钟在线时长
    rewards.addOnlineMinutes(player, 30);
}

数据清理与迁移

• /axs purge 支持按 UUID 或全量清理玩家在线奖励数据
• /axs migrate 支持跨源数据迁移

EventBus 事件

模块通过 EventBusCapability 发布事件，其他模块可订阅对应 Topic 接收事件。

axs.onlinerewards.server_goal_reached

全服签到目标达成时发布。

// 订阅示例
eventBus.subscribe("axs.onlinerewards.server_goal_reached", (player, payload) -> {
    String goalId = payload.get("goal_id");
    int signed = Integer.parseInt(payload.get("signed_count"));
    // 处理全服签到目标达成事件
});

跨服同步

跨服通道

当 cross-server.enabled 为 true 且使用 MySQL 共享数据库时，签到、补签、管理员调整在线时长/补签卡/离线储蓄等操作会自动通知其他子服刷新该玩家数据与界面。

跨服前提条件

1. storage.shared 必须为 true（共享 MySQL 数据库）
2. 宿主 config.yml 的 cross-server 节已正确配置
3. cross-server.enabled 设为 true

数据存储

模块将玩家在线时长、签到记录、补签卡、已领奖励与全服签到目标触发记录存储在数据库中（SQLite 或 MySQL）。表名前缀由 storage.mysql.table-prefix 控制，默认 axs_onlinerewards_，共享模式下无前缀。

与其他模块联动

Mail 模块

所有奖励（阶段奖励、签到奖励、周期奖励、时刻奖励、全服签到目标）均支持通过 mail.presets 字段发送邮件预设。填写 Mail 模块 mail/presets/*.yml 中的 preset.id，达成条件后自动发送邮件给玩家。

物品来源（ItemSourceRegistry）

所有奖励支持通过 item-rewards 字段发放物品。物品来源支持：

物品发放统一行为：放入背包 → 背包满转邮件 → 无邮件则掉落。详见 物品来源。

签到信号

签到成功后模块发送 signin_success 信号，EventPacket 等模块可监听该信号触发联动逻辑。

信号变量：

聊天卡片 / 字幕 / 称号 / QQ 广播

全服签到目标达成时支持向在线玩家发送聊天卡片（chat-cards 填卡片 ID）、播放字幕组（subtitle-groups 填字幕组 ID）、授予永久称号（title-ids 填称号 ID）、向 QQ 群广播消息。

客户端变量推送

模块向 ArcartX 客户端推送以下变量：

客户端 HUD 或其他 UI 可读取这些变量显示在线奖励进度。

配置版本迁移

模块支持配置版本自动迁移。当前配置版本为 4。

模块启动时自动检测 config-version 并执行迁移，无需手动干预。