Warehouse 仓库银行

付费模块

本模块为付费模块。授权由云端平台统一管理：在 cloud.021209.xyz 购买/领取授权后，于「装备模块」页面勾选到对应服务器即可，无需填写 password 或 license.yml。

Warehouse 模块提供完整的个人仓库、共享仓库与多货币银行系统，所有交互通过 ArcartX 客户端 UI 完成，支持 SQLite / MySQL 双存储后端。

功能概览

子系统	核心功能
个人仓库	多仓库、多等级容量体系、NBT 自动分类、搜索排序、黑名单过滤、自动拾取存入
共享仓库	创建/删除/转让、成员权限（所有者/成员/观众）、等级扩充、编辑锁互斥
银行系统	多货币活期存款、定期存款产品、阶梯利率、权限专属产品、原子领取
安全系统	PBKDF2 二级密码、会话有效期、管理员密码重置
展示系统	仓库展示卡片/可点击消息、只读预览、冷却控制

操作指南

以下按 UI 界面分步说明每个功能的操作方式。所有交互均在 ArcartX 客户端 UI 中完成，无需输入命令。

1. 打开仓库

方式	操作
命令	输入 `/warehouse` 或 `/wh`
命令别名	`/wh open`
管理员代开	`/axs warehouse open <玩家名>`

打开后默认进入仓库存取主界面（warehouse_storage.yml）。界面右上角有导航按钮可在「仓库 / 管理 / 银行」三个子界面间切换。

2. 仓库存取主界面

界面分为四个区域：

顶部：仓库名称、管理/银行/刷新按钮、个人/共享仓库切换栏
左侧：搜索框 + 分类筛选列表
中右：仓库物品网格（9×6 = 54 格）
底部：已选槽位信息、数量输入框、操作按钮、背包网格

2.1 存入物品（从背包到仓库）

方式一：双击快捷存入（推荐）

在界面右下角的背包网格中找到要存入的物品槽位
双击鼠标左键该槽位 → 该槽位的全部物品立即存入当前仓库
若仓库已满或物品命中黑名单，会收到提示且物品保留在背包

方式二：选择 + 数量存入

在背包网格中单击要存入的物品槽位 → 槽位会高亮（蓝色边框），表示已选中
在底部「数量输入框」中输入要存入的数量（留空默认为 1）
点击底部操作栏的**「存入」**按钮 → 按指定数量存入
若输入数量大于实际堆叠数，按实际数量存入

方式三：一键存入全部背包物品

点击背包网格上方的**「全部存入」**按钮
系统会遍历背包主库存（9~44 槽），将可存入物品全部移入仓库
命中黑名单或仓库已满的物品会自动跳过并提示

存入规则

相同物品（NBT 哈希一致）会自动合并到同一格，单格上限由服务端配置决定
黑名单物品、只读仓库、未解锁二级密码时均无法存入

2.2 取出物品（从仓库到背包）

方式一：双击快捷取出（推荐）

在仓库物品网格中找到要取出的物品
双击鼠标左键该物品 → 该物品的全部数量立即取出到背包
若背包已满，会按 Minecraft 堆叠上限（64/16/1）分批给予，满后停止

方式二：选择 + 数量取出

在仓库网格中单击要取出的物品 → 物品格会高亮（蓝色背景），表示已选中
在底部「数量输入框」中输入要取出的数量（留空默认为 1）
点击底部操作栏的**「取出」**按钮 → 按指定数量取出到背包

方式三：全部取出

先单击选中仓库中的某物品
点击底部操作栏的**「全部取出」**按钮 → 该格全部数量取出

二级密码限制

若界面底部提示「提现和领取需要先解锁二级密码」，需先在密码框输入二级密码并点击「解锁」。解锁后 10 分钟内（可在配置中调整）无需再次输入。

2.3 搜索与分类筛选

搜索物品

在左侧「搜索框」中输入关键词（支持物品名称、拼音、首字母）
按 Enter 键或点击「搜索」按钮执行搜索
仓库网格会只显示匹配结果；点击「重置」清空搜索恢复全览

分类筛选

在左侧「分类列表」中点击目标分类（如「装备」「消耗品」「材料」）
仓库网格会只显示该分类下的物品
再次点击同一分类或「全部」可取消筛选

分类由服务端配置文件的 categories 节定义，默认按物品 NBT 标签（pdc:arcartx:item_category）自动归类，未匹配到的归入「其它」。

2.4 分页切换

仓库物品超过 54 格时会自动分页。

点击仓库网格下方的**「上一页」/「下一页」**按钮翻页
页码显示在按钮旁（如 1/3）

2.5 切换仓库（个人 / 共享）

个人仓库切换

在顶部「仓库切换栏」中左右滚动（鼠标滚轮）
点击目标个人仓库按钮（如「个人 Lv.1」）→ 切换到该仓库

共享仓库切换

在切换栏中滚动到共享仓库区域
点击目标共享仓库按钮 → 首次进入时默认只读模式
若你是该共享仓库的「所有者」或「成员」，底部会出现**「编辑」**按钮；点击后若无人占用编辑锁，即可进入编辑模式进行存取

共享仓库编辑锁

同一共享仓库同一时间只允许一人编辑。若他人正在编辑，你打开时界面为只读，并提示「该共享仓库正在被 XXX 编辑」。

2.6 仓库升级

切换到你拥有的个人仓库
若底部提示栏显示升级信息（如「下一级容量 2500，消耗 5000 金币」）
确保背包内有足够货币，点击底部「升级」按钮（若配置有升级消耗）
升级成功后容量立即扩展，已存物品不受影响

3. 仓库管理界面

点击主界面右上角**「管理」**按钮进入（warehouse_manage.yml）。界面分为：自动拾取设置、仓库列表、删除/重命名/转让、成员管理。

3.1 自动拾取设置

在「自动拾取」卡片中有三个开关：

自动入库：拾取地面物品时自动存入个人仓库（默认开启）
怪物战利品：击杀 MythicMobs 等怪物时掉落物品自动存入（默认关闭）
入库通知：自动存入后在屏幕左下角显示提示（默认开启）

点击对应按钮即可切换开关状态；绿色 = 开，灰色 = 关。

3.2 创建共享仓库

在左侧「仓库列表」上方输入框填写共享仓库名称
点击**「创建」**按钮
若配置有创建费用（如 10000 金币），需确保背包余额充足
创建成功后自动出现在列表中，你成为「所有者」

共享仓库数量上限

每个玩家可创建的共享仓库数量受权限等级限制（默认配置下普通玩家 1 个，VIP 玩家 3 个等）。

3.3 删除共享仓库

在左侧列表中单击要删除的共享仓库 → 该仓库被选中
中间「删除共享仓库」卡片中点击**「删除」**按钮
界面会要求输入二级密码进行二次确认
输入密码后再次点击确认 → 仓库删除（内部物品一并清除，不可恢复）

只有所有者可以删除共享仓库。

3.4 重命名共享仓库

在左侧列表中选中目标共享仓库
在「重命名」卡片中输入新名称
点击**「重命名」**按钮

3.5 转让共享仓库

在左侧列表中选中目标共享仓库
在「转让」卡片中输入接收玩家的名字（该玩家必须是该仓库的成员）
点击**「转让」**按钮 → 你降为成员，对方成为所有者

3.6 成员管理

邀请成员

选中左侧的共享仓库
在「成员管理」卡片中输入玩家名
选择角色：成员（可存取）或观众（仅查看）
点击**「邀请」**按钮 → 对方立即获得权限

修改角色 / 移除成员

选中共享仓库后，右侧会显示当前成员列表
点击成员项：
- 选择「设为成员」或「设为观众」可修改角色
- 点击「移除」可将对方移出仓库

成员上限由权限等级决定（默认普通玩家 6 人，VIP 10 人）。

4. 银行界面

点击主界面右上角**「银行」**按钮进入（warehouse_bank.yml）。界面分为：活期余额、定期产品、我的定期。

4.1 活期存款与提现

存款

在「账户余额」卡片中点击要操作的货币（如「金币」「点券」）→ 选中项高亮
在「金额」输入框中填写要存入的数额
点击**「存入」**按钮 → 从玩家背包/账户扣除对应金额存入银行

提现

选中目标货币，输入金额
点击**「提现」**按钮 → 从银行余额转出到玩家账户

WARNING

提现需要先解锁二级密码。若未解锁，界面顶部会提示「提现和领取需要先解锁二级密码」。

4.2 购买定期存款

在「定期产品」卡片中浏览可购买的产品列表（如「七日定期」）
点击选中目标产品 → 项高亮
在「金额」输入框中填写存入金额
点击**「购买」**按钮
系统扣除活期余额（若余额不足会提示），生成一笔定期记录

定期产品参数（利率、期限、最低金额等）由服务端配置文件的 bank.deposit-products 定义。

4.3 领取到期定期

在「我的定期」卡片中查看当前持有的所有定期记录
已到期的记录显示为可领取状态（绿色或带提示）
点击目标定期记录 → 自动计算本息并转入活期余额
领取后该记录消失

定期本息计算

本息 = 本金 × (1 + 利率)。利率按金额阶梯匹配（如 100~9999 为 1%，10000 以上为 2%），在配置文件的 interest-tiers 中定义。

5. 二级密码（安全设置）

二级密码用于保护仓库取出、银行提现、共享仓库删除等敏感操作。

5.1 首次设置

首次打开仓库时，底部会显示密码输入框，提示「点击输入二级密码」
输入 4~32 位密码
点击**「设置」**按钮 → 密码设置成功

5.2 解锁会话

在底部密码框输入已设置的密码
点击**「解锁」**按钮 → 会话有效期默认 10 分钟
在有效期内进行取出、提现等操作无需再次输入

5.3 手动锁定

点击底部**「锁定」**按钮可立即结束当前会话，再次操作敏感功能需重新输入密码。

5.4 清除密码

在管理界面的「清除密码」卡片中输入当前密码并确认，即可移除二级密码（之后无需解锁即可操作）。

密码存储安全

二级密码使用 PBKDF2WithHmacSHA256 + 120000 次迭代 + 随机 salt 存储，服务端不保存明文。管理员可通过 allow-admin-password-reveal + admin-reveal-secret 配置解密密码（用于密码找回场景）。

6. 仓库展示

向服务器其他玩家展示自己的仓库物品列表。

确保仓库内有物品
输入命令 /wh showcase
系统会向公屏发送一条可点击消息（或聊天卡片，取决于配置）
其他玩家点击该消息即可预览你的仓库（只读模式，无法操作）

展示有冷却时间（默认 60 秒），防止刷屏。

7. 预览他人仓库

输入 /wh preview <玩家UUID> [仓库ID]
或以只读模式打开对方的仓库展示链接
界面与正常仓库相同，但所有操作按钮不可用
可自由翻页、搜索、查看分类，但无法存取或修改

8. 跨服共享仓库（多子服场景）

若服务器采用 BungeeCord / Velocity 群组架构且配置了 MySQL + Redis：

各子服共享同一套仓库数据，在任何子服存入的物品，切服后可见
共享仓库编辑锁跨服同步：A 服玩家编辑时，B 服玩家打开同一仓库为只读
详见 Warehouse 多服 MySQL 部署

依赖

依赖	是否必须	用途
ArcartX	✅ 必须	UI 渲染 + 数据包通信
PlaceholderAPI	✅ 必须	`%axswarehouse_*%` 占位符输出
Vault / PlayerPoints	可选	金币/点券货币支持
MythicMobs / MythicBukkit	可选	自动存入 Mythic 掉落、物品识别、黑名单
NeigeItems / MMOItems	可选	物品分类、黑名单、展示识别
MySQL	可选	多服共享仓库/银行数据（默认 SQLite）

命令

玩家命令（别名 `/wh`）

命令	权限	说明
`/warehouse` 或 `/wh`	`arcartxsuite.warehouse.use`	打开仓库主界面
`/wh open`	`arcartxsuite.warehouse.use`	同上
`/wh showcase`	`arcartxsuite.warehouse.showcase`	向公屏展示自己的仓库
`/wh preview <UUID\|玩家名> [仓库ID]`	`arcartxsuite.warehouse.admin`	以只读模式预览指定玩家的仓库（管理员）
`/wh spreview <UUID\|玩家名> [仓库ID]`	`arcartxsuite.warehouse.use`	以只读模式预览指定玩家的仓库（通过展示链接）
`/wh transfer <confirm\|reject> <sharedId>`	`arcartxsuite.warehouse.use`	确认或拒绝共享仓库转让

管理员命令

命令	权限	说明
`/axs warehouse status`	`arcartxsuite.admin`	查看模块状态（缓存玩家数、货币列表、跨服锁等）
`/axs warehouse reload`	`arcartxsuite.admin`	提示重载（实际通过 `/axs config apply warehouse` 生效）
`/axs warehouse open <玩家>`	`arcartxsuite.admin`	为在线玩家打开仓库界面
`/axs warehouse info <玩家>`	`arcartxsuite.admin`	查看玩家仓库概览（使用量、共享数、定期数）
`/axs warehouse view <玩家> <仓库ID>`	`arcartxsuite.admin`	查看指定玩家指定个人仓库的槽位物品清单
`/axs warehouse delete <玩家> <仓库ID> confirm`	`arcartxsuite.admin`	删除指定玩家的指定个人仓库（需带 `confirm`）
`/axs warehouse bank <玩家> <货币ID> <set\|add\|take> <金额>`	`arcartxsuite.admin`	管理玩家银行余额

权限

权限节点	默认	说明
`arcartxsuite.warehouse.use`	true	使用仓库基本功能
`arcartxsuite.warehouse.showcase`	true	使用 `/wh showcase` 展示仓库
`arcartxsuite.admin`	op	管理员命令

PAPI 占位符

前缀：%axswarehouse_*%

占位符	说明
`%axswarehouse_total_items%`	仓库物品总数（所有个人仓库合计）
`%axswarehouse_personal_used%`	个人仓库已使用格子数
`%axswarehouse_personal_capacity%`	个人仓库总容量
`%axswarehouse_shared_owned_count%`	拥有的共享仓库数量
`%axswarehouse_shared_joined_count%`	加入的他人共享仓库数量（含拥有）
`%axswarehouse_category_<分类ID>_amount%`	指定分类的物品数量
`%axswarehouse_bank_balance_<货币ID>%`	指定货币的银行活期余额
`%axswarehouse_bank_fixed_active_<货币ID>%`	活跃（未领取）定期存款笔数
`%axswarehouse_bank_fixed_matured_<货币ID>%`	已到期且未领取的定期存款笔数

配置文件

主配置 `ArcartXWarehouse.yml`

yaml

# 通用设置
settings:
  debug: false                      # 调试日志开关
  flush-interval-ticks: 100         # 数据刷新间隔（tick）
  # 共享仓库转让确认等待时长（小时），<=0 表示永不过期。
  transfer-confirm-expire-hours: 24

# 跨服共享仓库编辑锁；MySQL 共享库 + 多子服时建议开启。连接参数见宿主 config.yml cross-server 节。
cross-server:
  enabled: false

# UI 设置
ui:
  id: "AXS:warehouse_storage"         # 仓库 UI ID
  manage-id: "AXS:warehouse_manage" # 共享管理 UI ID
  bank-id: "AXS:warehouse_bank"     # 银行 UI ID
  packet-id: "AXS_WAREHOUSE"        # 客户端包 ID
  register-ui-on-enable: true         # 启动时自动注册 UI
  overwrite-ui-files: false         # 是否覆盖已存在的 UI 文件
  page-size: 54                     # 仓库网格每页显示的槽位数量

# 存储设置
storage:
  mode: "sqlite"                    # sqlite / mysql
  sqlite:
    file: "warehouse.db"
  mysql:
    host: "127.0.0.1"
    port: 3306
    database: "arcartxsuite"
    username: "root"
    password: ""
  pool-size: 4                      # 连接池大小（SQLite 建议 1，MySQL 建议 4+）

# 安全设置
security:
  min-length: 4                     # 二级密码最小长度
  max-length: 32                    # 二级密码最大长度
  unlock-session-ms: 600000         # 解锁会话有效期（毫秒，默认 10 分钟）
  allow-admin-password-reveal: false # 是否允许管理员通过 secret 解密密码
  admin-reveal-secret: ""           # AES-GCM 解密密钥（留空则禁止解密）

# 自动拾取设置
pickup:
  auto-store-on-pickup: true        # 拾取时自动存入仓库
  auto-store-mythic-loot: false     # 自动存入 MythicMobs 掉落
  notify-on-auto-store: true        # 自动存入后发送通知

# 搜索设置
search:
  page-size: 18                     # 搜索结果显示分页大小
  default-sort: "time"              # 默认排序方案 ID

# 仓库定义
warehouses:
  personal:
    display-name: "&6个人仓库"
    default-owned: true             # 新玩家是否默认拥有
    default-level: 1
    levels:
      "1":
        capacity: 1000              # 格子容量
        upgrade:                    # 升级消耗
          currency: "points"
          amount: 500
      "2":
        capacity: 2500
        upgrade:
          currency: "points"
          amount: 1200
      "3":
        capacity: 6000

# 物品分类定义
categories:
  equipment:
    display-name: "装备"
    priority: 10                    # 优先级越小越靠前
    nbt:
      path: "pdc:arcartx:item_category"    # NBT 路径
      values: ["equipment", "weapon", "armor"]
  material:
    display-name: "材料"
    priority: 20
    nbt:
      path: "pdc:arcartx:item_category"
      values: ["material"]
  consumable:
    display-name: "消耗品"
    priority: 30
    nbt:
      path: "pdc:arcartx:item_category"
      values: ["consumable", "food", "potion"]
  other:
    display-name: "其它"
    priority: 9999
    default: true                   # fallback 分类（未匹配到的物品归入此类）

# 银行货币定义
# currencies 为全局货币 ID 子集列表，定义必须存在于宿主 config.yml 的 currencies 中。
# 未在全局池定义的 ID 会在加载时告警并跳过。
bank:
  currencies:
    - money
    - points

  # 定期存款产品
  deposit-products:
    money_stable_1d:
      enabled: true
      display-name: "稳健 1 日"
      description: "低门槛短期定存。"
      currency: "money"
      duration-seconds: 86400       # 1 天
      min-amount: 100
      max-amount: 0                  # 0 = 无上限
      permission: ""                # 空 = 无权限限制
      interest-tiers:
        tier_1:
          min: 100
          max: 9999
          rate: 0.01                # 1%
        tier_2:
          min: 10000
          max: 99999
          rate: 0.015               # 1.5%
        tier_3:
          min: 100000
          max: 0
          rate: 0.02                # 2%
    money_vip_7d:
      enabled: true
      display-name: "贵宾 7 日"
      description: "权限专属较高收益定存。"
      currency: "money"
      duration-seconds: 604800      # 7 天
      min-amount: 1000
      max-amount: 0
      permission: "ArcartXSuite.warehouse.bank.vip"
      interest-tiers:
        tier_1:
          min: 1000
          max: 49999
          rate: 0.04                # 4%
        tier_2:
          min: 50000
          max: 0
          rate: 0.06                # 6%
    points_3d:
      enabled: true
      display-name: "点券 3 日"
      description: "点券定期产品。"
      currency: "points"
      duration-seconds: 259200      # 3 天
      min-amount: 50
      max-amount: 0
      permission: ""
      interest-tiers:
        tier_1:
          min: 50
          max: 999
          rate: 0.02
        tier_2:
          min: 1000
          max: 0
          rate: 0.03

# 共享仓库设置
shared:
  enabled: true
  create-cost:                      # 创建消耗
    currency: "points"
    amount: 1000
  default-level: 1
  levels:                           # 共享仓库等级
    "1":
      capacity: 2000
      upgrade:
        currency: "points"
        amount: 800
    "2":
      capacity: 5000
      upgrade:
        currency: "points"
        amount: 1800
    "3":
      capacity: 10000
  role-names:                       # 角色显示名称
    owner: "所有者"
    member: "成员"
    viewer: "观众"
  permission-tiers:                 # 按权限节点分层限制
    default:
      permission: ""
      priority: 0
      max-owned: 1                  # 可创建的共享仓库数量上限
      max-members: 6                # 每个共享仓库的成员上限
    vip:
      permission: "ArcartXSuite.warehouse.shared.vip"
      priority: 10
      max-owned: 3
      max-members: 12

# 排序方案定义
sort-profiles:
  time:
    fields:
      - "updated:desc"             # 按更新时间降序
      - "name:asc"
  name:
    fields:
      - "name:asc"                 # 按名称升序
  amount:
    fields:
      - "amount:desc"              # 按数量降序
      - "updated:desc"

# 展示设置
showcase:
  enabled: true
  cooldown-seconds: 60              # 展示冷却（秒），最短 5 秒
  max-items: 9                      # 展示列表最大物品数，最少 1 个
  card-id: ""                      # 留空使用可点击聊天消息；填写则使用 ArcartX 聊天卡片 ID
  permission: "arcartxsuite.warehouse.showcase"

# 物品黑名单（禁止存入仓库的物品匹配规则）
blacklist:
  material-ids: []                  # 原版 Material ID 列表，如 ["BEDROCK", "COMMAND_BLOCK"]
  mythic-item-ids: []               # MythicMobs Internal Name 列表
  neige-item-ids: []                # NeigeItems ID 列表
  overture-item-ids: []             # Overture 物品 ID 列表
  kinds: []                         # 物品种类（kind）列表
  name-contains:                    # 物品显示名包含任意关键词即拦截
    - "绑定不可存"
  lore-contains:                    # 物品 Lore 包含任意关键词即拦截
    - "不可存入仓库"
  name-regex: []                    # 物品显示名匹配任意正则即拦截
  lore-regex: []                    # 物品 Lore 匹配任意正则即拦截
  nbt-keys: []                      # PDC 或原始 NMS NBT 中存在任意 key 即禁止存入

跨服共享仓库与编辑锁

Warehouse 支持多子服共用同一 MySQL 库实现共享仓库数据同步（storage.mode: mysql + 各子服指向同一 database）。SQLite 仅适合单服。

共享仓库进入编辑模式时采用互斥锁：同一时刻只允许一名成员编辑，其余成员以只读打开。单服时锁保存在本进程内存；多子服时可通过 CrossServer SDK 广播锁状态：

条件	说明
`shared.enabled: true`	启用共享仓库功能
`storage.mode: mysql`	各子服共用同一仓库库
宿主 `config.yml` → `cross-server` 已启用	Redis 或 Proxy 通道可用

频道：warehouse
Payload：LOCK\t{sharedId}\t{playerUuid}\t{playerName}\t{nodeId} / UNLOCK\t{sharedId}\t{playerUuid}\t{nodeId}

行为摘要：

玩家在本服抢到编辑锁后，向其他子服广播 LOCK
他服若已有玩家正在编辑同一共享仓库，会被降级为只读并刷新 UI，提示「玩家名（nodeId）正在编辑」
关闭 UI、切换只读、退出服务器时在本服释放锁并广播 UNLOCK
/axs warehouse status 可查看跨服通道与当前活跃锁数量

详见跨服架构与跨服部署速查。完整多子服 MySQL + 跨服锁部署清单见 Warehouse 多服 MySQL 部署。

配置字段详解

仓库等级字段

字段	类型	必填	默认值	说明
`capacity`	Long	✅	—	该等级的格子容量
`upgrade.currency`	String	❌	—	升级消耗的货币 ID
`upgrade.amount`	Decimal	❌	`0`	升级消耗金额，`0` 或留空表示免费升级

分类字段

字段	类型	必填	默认值	说明
`display-name`	String	✅	—	UI 中显示的分类名称
`priority`	Int	❌	`9999`	排序优先级，数字越小越靠前
`nbt.path`	String	❌	`""`	NBT 读取路径
`nbt.values`	List	❌	`[]`	匹配值列表
`default`	Boolean	❌	`false`	是否为 fallback 分类（未匹配物品归于此）

NBT 路径语法：

material — 匹配 Bukkit Material 名称
display-name / name — 匹配物品显示名
custom-model-data — 匹配 CustomModelData 整数值
pdc:namespace:key — 读取 PersistentDataContainer 中的 STRING/INTEGER/LONG 值

货币字段

银行货币在 bank.currencies 中以字符串列表形式声明，引用宿主 config.yml → currencies 中已定义的货币 ID。货币的 provider、display-name、scale 等字段在宿主配置中定义，不在本模块配置中重复。

字段	类型	必填	说明
`bank.currencies`	`List<String>`	❌	银行展示的货币 ID 子集，必须已在宿主 `config.yml` 的 `currencies` 中定义

定期产品字段

字段	类型	必填	默认值	说明
`currency`	String	✅	—	关联的货币 ID
`duration-seconds`	Long	❌	`86400`	定期时长（秒）
`min-amount`	Decimal	❌	`1`	最低存入金额
`max-amount`	Decimal	❌	`0`	最高存入金额，`0` = 无上限
`permission`	String	❌	`""`	购买该产品所需权限
`interest-tiers`	Map	✅	—	利率阶梯，按 `min` 升序匹配，金额落入区间内适用对应 `rate`

利率阶梯字段

字段	类型	必填	默认值	说明
`min`	Decimal	❌	`0`	区间下限（含）
`max`	Decimal	❌	`0`	区间上限（含），`0` = 无上限
`rate`	Decimal	✅	—	利率（如 `0.05` = 5%），到期本息 = 本金 × (1 + rate)

排序字段

字段	类型	必填	说明
`fields`	`List<String>`	✅	排序键列表，如 `name:desc` 表示按名称降序。可用键：`name` / `amount` / `updated` / `created` / `material` / `category` / `warehouse`

黑名单字段

字段	类型	说明
`material-ids`	`List<String>`	Bukkit Material 枚举名，匹配即禁止存入
`mythic-item-ids`	`List<String>`	MythicMobs Internal Name
`neige-item-ids`	`List<String>`	NeigeItems ID
`overture-item-ids`	`List<String>`	Overture 物品 ID
`kinds`	`List<String>`	物品种类（kind）列表
`name-contains`	`List<String>`	物品显示名包含任意关键词即拦截
`lore-contains`	`List<String>`	物品 Lore 包含任意关键词即拦截
`name-regex`	`List<String>`	物品显示名匹配任意正则即拦截
`lore-regex`	`List<String>`	物品 Lore 匹配任意正则即拦截
`nbt-keys`	`List<String>`	PDC 或原始 NMS NBT 中存在任意 key 即禁止存入

黑名单优先级

自动存入时若物品命中任一黑名单规则，则跳过存入并向玩家提示。存入单件和存入全部均会检查黑名单。

UI 文件

模块自带三套 AXUI 定义文件，会在启用时自动导出到 plugins/ArcartX-Suite/ui/：

资源文件	导出路径	用途
`arcartx/ui/warehouse_storage.yml`	`ui/warehouse_storage.yml`	仓库存取主界面
`arcartx/ui/warehouse_manage.yml`	`ui/warehouse_manage.yml`	共享管理 + 设置界面
`arcartx/ui/warehouse_bank.yml`	`ui/warehouse_bank.yml`	银行活期/定期界面

UI 文件路径由模块内部硬编码，通过 ui.overwrite-ui-files 控制是否覆盖用户修改。

存储结构

自动创建以下数据表：

表名	用途
`warehouse_personal`	个人仓库列表（等级、自定义名称）
`warehouse_slots`	物品槽位（个人/共享共用，owner_type + owner_id 区分）
`warehouse_bank_balances`	玩家各货币活期余额
`warehouse_fixed_deposits`	定期存款记录
`warehouse_shared`	共享仓库基本信息
`warehouse_shared_members`	共享仓库成员关系与角色
`warehouse_security`	玩家二级密码（salt + PBKDF2 hash）

客户端包协议

包 ID：AXS_WAREHOUSE

所有操作由客户端 UI 控件通过 Packet.send("AXS_WAREHOUSE", action, ...) 发起，服务端处理后回发更新包。

界面导航

action	参数	说明
`open` / `storage`	—	打开仓库存取界面
`manage`	—	打开共享管理界面
`bank`	—	打开银行界面
`refresh`	—	刷新当前全部界面

仓库操作

action	参数	说明
`page`	`页码`	切换分页
`warehouse`	`仓库ID`	切换个人仓库
`shared`	`共享仓库ID`	切换到指定共享仓库
`shared_mode`	`readonly` / `edit`	切换共享仓库只读/编辑模式
`category`	`分类ID`	切换物品分类筛选
`search`	`关键词`	设置搜索关键词（支持名称/拼音/首字母）
`select`	`显示槽位`	选择仓库中的物品
`deposit_slot`	`背包原始槽位`, `数量`	存入指定背包槽位的物品；数量 `0` 表示全部存入
`deposit_all_backpack`	—	一键存入背包全部物品（跳过黑名单和已满格）
`withdraw`	`显示槽位`, `数量`	取出指定数量的物品
`withdraw_all`	`显示槽位`	取出该槽位全部物品
`warehouse_upgrade`	—	扩充当前仓库到下一等级

银行操作

action	参数	说明
`bank_deposit`	`货币ID`, `金额`	从玩家背包货币存入银行
`bank_withdraw`	`货币ID`, `金额`	从银行提现到玩家
`fixed_create`	`产品ID`, `金额`	购买定期存款产品
`fixed_claim`	`存款ID`	领取到期定期本息

共享仓库管理

action	参数	说明
`shared_create`	`名称`	创建共享仓库
`shared_rename`	`共享ID`, `新名称`	重命名共享仓库（仅所有者）
`shared_delete`	`共享ID`, `二级密码`	删除共享仓库（需密码确认）
`shared_invite`	`共享ID`, `玩家名`, `角色`	邀请/修改成员角色（viewer/member）
`shared_remove`	`共享ID`, `玩家名`	移除共享成员
`shared_transfer`	`共享ID`, `目标玩家名`	将共享仓库转让给成员（目标必须是 member 角色）

安全与设置

action	参数	说明
`password_set`	`密码`	设置二级密码
`password_unlock`	`密码`	解锁二级密码会话
`password_lock`	—	立即锁定会话
`password_clear`	`密码`	清除二级密码
`toggle_auto_pickup`	—	切换自动拾取存入
`toggle_auto_mythic`	—	切换 Mythic 掉落自动存入
`toggle_auto_notify`	—	切换自动存入通知

预览模式限制

预览模式下仅支持 page、category、search、select、refresh，其余操作会提示"预览模式下无法执行此操作"。

配置诊断

Warehouse 模块声明了以下配置校验规则：

字段	类型	约束
`storage.mode`	STRING	必填，枚举 `sqlite` / `mysql`
`storage.pool-size`	INT	范围 1–100
`settings.flush-interval-ticks`	INT	≥ 1
`security.min-length`	INT	范围 1–32
`security.max-length`	INT	范围 4–64

动态节（用户可自由增删，不被结构同步覆盖）：

warehouses
categories
bank.currencies
bank.deposit-products
shared
sort-profiles

架构

WarehouseModule (AbstractAXSModule)
├── WarehouseService (门面，协调所有业务逻辑)
│   ├── 个人仓库：存取、升级、分类、搜索、排序
│   ├── 共享仓库：创建、成员、权限、编辑锁
│   ├── 银行：活期、定期、阶梯利率、原子领取
│   ├── 二级密码：PBKDF2 hash、会话管理
│   ├── 自动拾取：EntityPickupItemEvent 监听
│   └── 展示/预览：聊天卡片 / 可点击消息
├── JdbcWarehouseRepository (SQLite / MySQL 持久化)
├── WarehouseModuleConfiguration (配置聚合)
├── WarehouseAdminCommand (/axs warehouse)
├── WarehousePlayerCommand (/warehouse, /wh)
└── WarehousePlaceholderExpansion (PAPI)

安全说明

二级密码使用 PBKDF2WithHmacSHA256，120,000 次迭代，256 位输出，随机 16 字节 salt
密码验证通过 MessageDigest.isEqual() 进行恒定时间比较，防止时序攻击
若开启 allow-admin-password-reveal，管理员可使用 admin-reveal-secret 通过 AES/GCM 解密密码（用于密码找回场景）
共享仓库编辑采用互斥锁：同一时间只有一个成员可进入编辑模式，其他人以只读方式打开；多子服场景下通过 CrossServer SDK 同步锁状态（见上文「跨服共享仓库与编辑锁」）
所有银行扣款/存款操作使用原子数据库操作，失败自动回滚
定期存款领取为原子操作：claimFixedDepositAtomic 在数据库层面标记 claimed 并计算本息入账，避免并发重复领取

本轮功能补充

接收人真实存在校验

共享仓库成员邀请和所有权转让的接收人必须是真实玩家：在线玩家，或 OfflinePlayer.hasPlayedBefore() 为 true 的离线玩家。不存在或从未进服时会拒绝操作。

管理员查看与删除指定个人仓库

权限节点：arcartxsuite.warehouse.admin

text

/axs warehouse view <玩家> <仓库ID>
/axs warehouse delete <玩家> <仓库ID> confirm

view 输出指定玩家指定个人仓库的槽位物品清单；delete 必须带 confirm 才执行删除。

黑名单 `nbt-keys`

yaml

blacklist:
  nbt-keys: []

匹配只判断配置的 key 是否存在，不比较 value；同一个 key 只要出现在 Bukkit PersistentDataContainer（PDC）或物品的原始 NMS NBT 复合标签中即会命中黑名单。原始 NBT 会递归检查顶层及嵌套 compound、list 中的 compound，因此可覆盖部分 mod 物品和老旧物品库；配置 key 沿用现有归一化规则，兼容纯 key 名与 namespaced key。原始 NBT 通过版本容错反射读取，反射失败时安全降级为不命中原始 NBT，不会中断存入流程。

共享仓库转让两步确认

owner 发起转让后先生成 pending 记录，接收人使用：

text

/warehouse transfer confirm <sharedId>
/warehouse transfer reject <sharedId>

接收人登录时会收到待确认提示。确认时会重新校验发起人仍是 owner、接收人仍是 member，通过后才完成所有权变更。

yaml

settings:
  transfer-confirm-expire-hours: 24

默认 24 小时；<=0 表示不过期。pending 采用惰性清理，确认、拒绝、过期访问以及删除共享仓库时会清理对应记录。

Warehouse 仓库银行 ​

功能概览 ​

操作指南 ​

1. 打开仓库 ​

2. 仓库存取主界面 ​

2.1 存入物品（从背包到仓库） ​

2.2 取出物品（从仓库到背包） ​

2.3 搜索与分类筛选 ​

2.4 分页切换 ​

2.5 切换仓库（个人 / 共享） ​

2.6 仓库升级 ​

3. 仓库管理界面 ​

3.1 自动拾取设置 ​

3.2 创建共享仓库 ​

3.3 删除共享仓库 ​

3.4 重命名共享仓库 ​

3.5 转让共享仓库 ​

3.6 成员管理 ​

4. 银行界面 ​

4.1 活期存款与提现 ​

4.2 购买定期存款 ​

4.3 领取到期定期 ​

5. 二级密码（安全设置） ​

5.1 首次设置 ​

5.2 解锁会话 ​

5.3 手动锁定 ​

5.4 清除密码 ​

6. 仓库展示 ​

7. 预览他人仓库 ​

8. 跨服共享仓库（多子服场景） ​

依赖 ​

命令 ​

玩家命令（别名 /wh） ​

管理员命令 ​

权限 ​

PAPI 占位符 ​

配置文件 ​

主配置 ArcartXWarehouse.yml ​

跨服共享仓库与编辑锁 ​

配置字段详解 ​

仓库等级字段 ​

分类字段 ​

货币字段 ​

定期产品字段 ​

利率阶梯字段 ​

排序字段 ​

黑名单字段 ​

UI 文件 ​

存储结构 ​

客户端包协议 ​

界面导航 ​

仓库操作 ​

银行操作 ​

共享仓库管理 ​

安全与设置 ​

预览模式限制 ​

配置诊断 ​

架构 ​

安全说明 ​

本轮功能补充 ​

接收人真实存在校验 ​

管理员查看与删除指定个人仓库 ​

黑名单 nbt-keys ​

共享仓库转让两步确认 ​

Warehouse 仓库银行

功能概览

操作指南

1. 打开仓库

2. 仓库存取主界面

2.1 存入物品（从背包到仓库）

2.2 取出物品（从仓库到背包）

2.3 搜索与分类筛选

2.4 分页切换

2.5 切换仓库（个人 / 共享）

2.6 仓库升级

3. 仓库管理界面

3.1 自动拾取设置

3.2 创建共享仓库

3.3 删除共享仓库

3.4 重命名共享仓库

3.5 转让共享仓库

3.6 成员管理

4. 银行界面

4.1 活期存款与提现

4.2 购买定期存款

4.3 领取到期定期

5. 二级密码（安全设置）

5.1 首次设置

5.2 解锁会话

5.3 手动锁定

5.4 清除密码

6. 仓库展示

7. 预览他人仓库

8. 跨服共享仓库（多子服场景）

依赖

命令

玩家命令（别名 `/wh`）

管理员命令

权限

PAPI 占位符

配置文件

主配置 `ArcartXWarehouse.yml`

跨服共享仓库与编辑锁

配置字段详解

仓库等级字段

分类字段

货币字段

定期产品字段

利率阶梯字段

排序字段

黑名单字段

UI 文件

存储结构

客户端包协议

界面导航

仓库操作

银行操作

共享仓库管理

安全与设置

预览模式限制

配置诊断

架构

安全说明

本轮功能补充

接收人真实存在校验

管理员查看与删除指定个人仓库

黑名单 `nbt-keys`

共享仓库转让两步确认