事件 API

Storage 事件位于 emaki.jiuwu.craft.storage.api.event, 均为玩家 owner thread 上的同步可取消 Bukkit 事件. 字段是不可变事务快照, 不提供任何可修改的业务字段

事件	触发时机	取消效果	runtime 路径
StorageDepositEvent	capacity 预检后, 库存移除 (若有) 和 entry credit 前	阻止移除与仓库增加	transaction deposit, depositDirect, 包括 depositAsync(..., source=api), GUI/命令/action
StorageWithdrawEvent	计算可取数量后, entry debit 与物品交付前	阻止扣减与交付	StorageTransactionService.withdraw, 包括 withdrawAsync(..., source=api) 与 GUI/命令/action
StorageUnlockEvent	总价计算后, 货币/物品扣费与 purchased slots 增加前	阻止全部扣费和解锁	付费 unlock service; 管理型 grantSlotsAsync 不触发
StorageBatchEvent	批量原子操作提交前, 任何 escrow 扣除与写入前	阻止整批操作; 批内不再单独触发 Deposit/Withdraw 事件	applyBatchAsync

事件携带的字段固定: Deposit/withdraw/unlock 包含 playerId, 克隆并规范化的 template, requested amount, source; withdraw 另有 stored amount; unlock 包含 slots, 购买前数量和 currencyCost (仅货币成本, 物品代价不在此事件中反映). Batch 事件包含 playerId, 操作列表 (ops() 返回不可变的 List<StorageBatchOp>, 每个 template 都是 amount == 1 的副本), allOrNothing() 标志与 source. 访问器一律是 record 风格, 不带 get 前缀. 线程约定: 异步 facade 只负责提交/调度, 事件仍在实际 owner-thread transaction 中同步触发, future callback 不继承该线程保证

source 取值为运行时来源 id, 固定 5 种: gui / command / api / action / auto_pickup. 其中 auto_pickup 只会出现在存入事件上 (自动拾取走的是 direct deposit 路径); StorageUnlockEvent 当前只会带 gui, 因为付费扩容在插件内只有 GUI 一个入口

发出规则: 这些事件由 runtime 事务路径发出, bridge 不可用时不会伪造事件; 此时 future 形式的 facade 方法以结果对象回报明确失败