Warehouse 仓库系统

模块简介

Warehouse 是 Suite 的仓库与银行模块，通过 ArcartX UI 提供个人仓库、共享仓库、多货币银行、定期存款、二级密码等完整功能。所有业务操作均在 AXUI 界面内完成，玩家通过 /warehouse（别名 /wh、/axswarehouse）打开主界面。

模块采用槽位聚合存储模型——相同物品（基于序列化哈希匹配）自动堆叠到同一槽位，单槽聚合上限为 Integer.MAX_VALUE，配合多级容量升级实现近乎无限的存储空间。物品分类基于 NBT/PDC 路径匹配，支持拼音/首字母搜索，排序方案可自定义。

功能特性

依赖表

物品库为可选功能，黑名单的 mythic-item-ids / neige-item-ids / overture-item-ids 按需依赖对应插件：

仓库界面

Warehouse 模块提供三套独立的 ArcartX UI 界面：

存取行为

存入：物品经黑名单校验（命中规则拒绝）→ 相同物品自动合并到已有槽位 → 剩余写入空闲槽位 → 容量不足时失败。

取出：启用二级密码时先校验会话 → 校验槽位与数量 → 物品放入背包 → 更新槽位。

仓库槽位与容量

个人仓库采用逐格解锁模型：玩家从 base-slots（默认 32）格起步，按 slot-price 逐格付费购买至 max-slots（默认 999）。

warehouses:
  personal:
    base-slots: 32            # 初始解锁槽位数
    max-slots: 999            # 可购买槽位上限
    slot-price:
      currency: "points"      # 每格所需货币
      amount: 100             # 每格价格

容量即最大槽位数，每个槽位可聚合大量相同物品。共享仓库仍使用 shared.levels 等级制升级，不受本模型影响。

共享仓库

共享仓库支持多人协作，核心概念：

启用跨服时编辑锁状态自动同步至所有子服。

存储模式

数据存储支持 SQLite 与 MySQL，通过 storage.shared 配置：

迁移提示：配置版本 2→3 的迁移会自动将旧的 storage.mode（sqlite/mysql）重映射为 storage.shared（true/false）。

原子操作

银行余额的增减使用数据库原子操作，避免并发超扣：

• creditBankBalance：INSERT ... ON CONFLICT DO UPDATE SET balance = balance + ?（SQLite）/ ON DUPLICATE KEY UPDATE balance = balance + VALUES(balance)（MySQL）
• debitBankBalance：UPDATE ... SET balance = balance - ? WHERE balance >= ?，仅余额充足时成功
• claimFixedDepositAtomic：事务内 SELECT ... FOR UPDATE（MySQL）或条件 UPDATE（SQLite），标记 claimed 并本息入账

数据落库

仓库数据采用延迟落库策略，通过 settings.flush-interval-ticks（默认 100 ticks = 5 秒）控制落库间隔。玩家退出时自动保存其状态。