联动

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);
}

PlayerDataPurgeable

提供玩家数据清除能力，供本体统一清理模块数据。

DatabaseMigratable

提供数据库迁移能力，供本体统一迁移模块存储。

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"));
    // 处理全服签到目标达成事件
});

跨服同步

跨服通道

模块通过 CrossServerAPI.openChannel("onlinerewards", ...) 建立跨服通道。当 cross-server.enabled 为 true 且使用 MySQL 共享数据库时，以下操作会自动通知其他子服：

收到跨服消息后，服务端在主线程执行：清除该玩家缓存 → 重新加载状态 → 刷新菜单 → 刷新排行榜。

跨服前提条件

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

数据库表结构

模块使用 4 张表（表名前缀由 storage.mysql.table-prefix 控制，默认 axs_onlinerewards_，共享模式下无前缀）：

online_rewards_players

玩家运行时状态表，存储在线时长、签到、补签卡等全部可变状态。

online_rewards_sign_ins

签到记录表，每次签到/补签写入一条记录。

主键：(player_uuid, sign_in_date)

online_rewards_server_goals

全服签到目标触发记录表，防止同一目标同一天重复触发。

主键：(goal_date, goal_id)

online_rewards_schema_meta

迁移记录表，记录已完成的数据库迁移。

索引

与其他模块联动

Mail 模块

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

物品来源（ItemSourceRegistry）

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

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

SignalDispatchable

签到成功后，模块通过 SignalDispatchable.dispatchSignal("signin_success", player, variables) 发送信号，其他模块可监听该信号触发联动逻辑。

信号变量：

ChatCardSendable

全服签到目标达成时，通过 ChatCardSendable.sendChatCard(player, cardId, variables) 向在线玩家发送聊天卡片。chat-cards 字段填写卡片 ID。

SubtitlePlayable

全服签到目标达成时，通过 SubtitlePlayable.playGroup(player, groupId) 向在线玩家播放字幕组。subtitle-groups 字段填写字幕组 ID。

TitleGrantable

全服签到目标达成时，通过 TitleGrantable.giveTitle(uuid, titleId, "permanent", "OnlineRewards:ServerGoal") 向在线玩家授予标题。title-ids 字段填写标题 ID。

QQBotBroadcastable

全服签到目标达成时，通过 QQBotBroadcastable.sendToAllGroups(message) 向 QQ 群广播消息。

客户端变量推送

模块通过 ClientBridgeAPI.sendServerVariable 向 ArcartX 客户端推送以下变量：

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

配置版本迁移

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

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