Warehouse 仓库系统

模块简介

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

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

• 模块 ID：warehouse
• 版本：1.4.4
• 配置版本：4（当前 schema）
• 源码主类：xuanmo.arcartxsuite.warehouse.WarehouseModule
• 配置文件：config.yml
• 消息文件：messages.yml

功能特性

依赖表

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

仓库架构详解

三套 AXUI 界面

Warehouse 模块注册三套独立的 ArcartX UI 界面，通过 PacketBridge 与客户端通信：

所有界面共享同一个客户端通信包 ID AXS_WAREHOUSE，通过 packetHandler 的 action 字段区分操作类型。

存储模型

仓库采用槽位聚合存储模型，核心数据结构为 SlotItemRecord：

warehouse_slots 表
├── owner_type: "personal" 或 "shared"
├── owner_id: 玩家 UUID（个人）或共享仓库 ID（共享）
├── warehouse_id: 仓库标识（如 "personal"）
├── slot: 槽位序号（从 0 开始）
├── item_hash: 物品序列化 SHA-256 哈希（用于堆叠匹配）
├── category_id: 分类 ID
├── display_name: 显示名称
├── material_id: 原版材质 ID
├── search_text / pinyin / initials: 搜索索引
├── item_data: Base64 序列化物品数据
├── item_json: JSON 格式物品展示数据
├── amount: 聚合数量（单槽上限 Integer.MAX_VALUE）
├── created_at / updated_at: 时间戳

存入流程：

1. 物品经黑名单 ItemMatcher 校验，命中规则则拒绝
2. 序列化物品并计算 SHA-256 哈希
3. 获取仓库级互斥锁（warehouseLocks），防止并发竞态
4. 遍历现有槽位，哈希匹配的槽位尝试合并（受 MAX_AGGREGATED_AMOUNT 限制）
5. 剩余物品写入第一个空闲槽位
6. 容量不足时返回失败

取出流程：

1. 校验二级密码会话（如已启用）
2. 获取仓库级互斥锁
3. 校验槽位存在性与数量
4. 构造 ItemStack 并放入玩家背包
5. 更新或删除槽位记录

仓库等级与容量

每个仓库定义包含多级容量配置，玩家可通过货币付费升级：

warehouses:
  personal:
    levels:
      "1":
        capacity: 1000        # 等级 1 容量
        upgrade:
          currency: "points"  # 升级货币
          amount: 500          # 升级费用
      "2":
        capacity: 2500
        upgrade:
          currency: "points"
          amount: 1200
      "3":
        capacity: 6000         # 最高级（无 upgrade 节）

容量即最大槽位数，每个槽位可聚合大量相同物品。

共享仓库架构

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

共享仓库的编辑锁通过 sharedEditLocks（ConcurrentMap<String, SharedEditLock>）实现互斥。启用跨服时，锁状态通过 CrossServer 通道广播至所有子服。

存储机制

数据库表结构

Warehouse 使用 7 张核心表（表名前缀可配置）：

存储模式

支持两种存储模式，通过 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 秒）控制落库间隔。玩家退出时自动保存其状态。