┌─────────────────────────────────────────────┐
│                  API 层                      │
│  (供其他插件/命令调用)                        │
├──────────┬──────────┬───────────────────────┤
│ 电网管理 │ 设备管理  │      库存管理           │
│ (网格)   │ (增删改查)│   (云仓库抽象)          │
├──────────┴──────────┴───────────────────────┤
│              核心引擎层                       │
│  · 供电范围计算                              │
│  · 电网拓扑更新                              │
│  · 能量流模拟                                │
├─────────────────────────────────────────────┤
│              数据层                          │
│  · 序列化/反序列化                           │
│  · 持久化存储                                │
│  · 缓存管理                                  │
└─────────────────────────────────────────────┘

我需要一个 Kotlin 类来管理 Minecraft 电网的连通性，使用并查集（Union-Find）数据结构。

需求：
1. 每个电网设备都有一个唯一 ID
2. 支持操作：addNode, union(id1, id2), findRoot(id), removeNode(id)
3. 当移除节点导致电网分裂时，能够正确识别新的连通分量
4. 线程安全

请提供完整实现，包含路径压缩和按秩合并优化。
同时给出使用示例，展示电线放置/移除的场景。

class DisjointSet<T> {
    private val parent = ConcurrentHashMap<T, T>()
    private val rank = ConcurrentHashMap<T, Int>()
    private val adjacency = ConcurrentHashMap<T, MutableSet<T>>()

    fun addNode(node: T) {
        parent.putIfAbsent(node, node)
        rank.putIfAbsent(node, 0)
        adjacency.putIfAbsent(node, ConcurrentHashMap.newKeySet())
    }

    fun find(node: T): T {
        val p = parent[node] ?: throw IllegalArgumentException("Node not found: $node")
        if (p != node) {
            val root = find(p)
            parent[node] = root
        }
        return parent[node]!!
    }

    fun union(nodeA: T, nodeB: T) {
        val rootA = find(nodeA)
        val rootB = find(nodeB)
        if (rootA == rootB) return

        val rankA = rank[rootA]!!
        val rankB = rank[rootB]!!

        when {
            rankA < rankB -> parent[rootA] = rootB
            rankA > rankB -> parent[rootB] = rootA
            else -> {
                parent[rootB] = rootA
                rank[rootA] = rankA + 1
            }
        }

        adjacency[nodeA]?.add(nodeB)
        adjacency[nodeB]?.add(nodeA)
    }

    fun removeNode(node: T): Set<Set<T>> {
        val neighbors = adjacency.remove(node) ?: return emptySet()
        for (neighbor in neighbors) {
            adjacency[neighbor]?.remove(node)
        }
        parent.remove(node)
        rank.remove(node)

        if (neighbors.size < 2) return neighbors.map { setOf(it) }.toSet()

        val visited = mutableSetOf<T>()
        val components = mutableSetOf<Set<T>>()
        for (start in neighbors) {
            if (start in visited) continue
            val component = bfsComponent(start, visited)
            components.add(component)
        }
        return components
    }

    private fun bfsComponent(start: T, visited: MutableSet<T>): Set<T> {
        val queue: ArrayDeque<T> = ArrayDeque()
        val component = mutableSetOf<T>()
        queue.add(start)
        while (queue.isNotEmpty()) {
            val current = queue.pollFirst()
            if (current in visited) continue
            visited.add(current)
            component.add(current)
            for (neighbor in adjacency[current] ?: emptySet()) {
                if (neighbor !in visited) queue.addLast(neighbor)
            }
        }
        return component
    }

    fun isConnected(nodeA: T, nodeB: T): Boolean = find(nodeA) == find(nodeB)

    fun getComponentSize(node: T): Int {
        val root = find(node)
        return parent.keys.count { find(it) == root }
    }
}

世界空间（无限大）
┌───┬───┬───┬───┬───┐
│   │   │ ● │   │   │  ← cellSize = 16
├───┼───┼───┼───┼───┤      每个 cell 存储该区域内的实体
│   │ ○ │   │ ○ │   │      ● = 供电桩
├───┼───┼───┼───┼───┤      ○ = 机器
│   │   │   │   │   │
├───┼───┼───┼───┼───┤
│   │   │   │   │   │
└───┴───┴───┴───┴───┘

查询 (x,y,z) 附近 7 格范围：
→ 只需检查周围 3×3×3 = 27 个 cell（通常只有 8 个非空）

我需要一个 Kotlin 类来实现空间哈希网格（Spatial Hash Grid），用于加速 3D 空间范围查询。

使用场景：Minecraft 插件中的供电系统，供电桩为周围 7x7x7 范围内的机器供电。

需求：
1. 世界被划分为固定大小的单元格（cellSize = 16 格）
2. 支持操作：insert, remove, queryNearby, updatePosition
3. 线程安全
4. 高效处理动态插入/删除

请提供完整实现，并说明如何集成到现有的供电系统中。
特别关注：当一个供电桩被破坏时，如何高效地通知所有受影响的机器。

class SpatialHashGrid<T>(
    private val cellSize: Int = 16,
    private val queryRadius: Int = 7
) {
    private data class CellKey(val x: Int, val y: Int, val z: Int)

    private val grid = ConcurrentHashMap<CellKey, CopyOnWriteArraySet<T>>()
    private val entityPositions = ConcurrentHashMap<T, Triple<Int, Int, Int>>()

    private fun toCellKey(x: Int, y: Int, z: Int) =
        CellKey(x / cellSize, y / cellSize, z / cellSize)

    fun insert(entity: T, x: Int, y: Int, z: Int) {
        val key = toCellKey(x, y, z)
        grid.computeIfAbsent(key) { CopyOnWriteArraySet() }.add(entity)
        entityPositions[entity] = Triple(x, y, z)
    }

    fun remove(entity: T) {
        val pos = entityPositions.remove(entity) ?: return
        val key = toCellKey(pos.first, pos.second, pos.third)
        grid[key]?.remove(entity)
        if (grid[key]?.isEmpty() == true) grid.remove(key)
    }

    fun updatePosition(entity: T, newX: Int, newY: Int, newZ: Int) {
        remove(entity)
        insert(entity, newX, newY, newZ)
    }

    fun queryNearby(centerX: Int, centerY: Int, centerZ: Int): Set<T> {
        val result = mutableSetOf<T>()
        val minCellX = (centerX - queryRadius) / cellSize
        val maxCellX = (centerX + queryRadius) / cellSize
        val minCellY = (centerY - queryRadius) / cellSize
        val maxCellY = (centerY + queryRadius) / cellSize
        val minCellZ = (centerZ - queryRadius) / cellSize
        val maxCellZ = (centerZ + queryRadius) / cellSize

        for (cx in minCellX..maxCellX) {
            for (cy in minCellY..maxCellY) {
                for (cz in minCellZ..maxCellZ) {
                    grid[CellKey(cx, cy, cz)]?.let { result.addAll(it) }
                }
            }
        }
        return result
    }

    fun getEntitiesInCell(cellX: Int, cellY: Int, cellZ: Int): Set<T>? =
        grid[CellKey(cellX, cellY, cellZ)]
}

                    ┌──────────────────┐
                    │   CloudWarehouse  │
                    │   （虚拟视图层）    │
                    └────────┬─────────┘
                             │
              ┌──────────────┼──────────────┐
              ↓              ↓              ↓
        ┌──────────┐  ┌──────────┐  ┌──────────┐
        │ Core #1  │  │ Core #2  │  │ Core #3  │
        │ 库存: A×64│  │ 库存: B×32│  │ 库存: C×16│
        └──────────┘  └──────────┘  └──────────┘

class CloudWarehouse(
    private val cores: List<EnergyCore>,
    private val cacheTtlMillis: Long = 1000L
) {
    private data class CachedView(
        val snapshot: Map<ItemStack, Int>,
        val version: Long,
        val timestamp: Long
    )

    @Volatile private var cachedView: CachedView? = null

    fun getTotalQuantity(itemType: ItemStack): Int {
        val view = getOrCreateView()
        return view.snapshot.entries
            .filter { it.key.isSimilar(itemType) }
            .sumOf { it.value }
    }

    private fun getOrCreateView(): CachedView {
        val current = cachedView
        if (current != null && System.currentTimeMillis() - current.timestamp < cacheTtlMillis) {
            return current
        }
        return buildFreshView().also { cachedView = it }
    }

    private fun buildFreshView(): CachedView {
        val aggregated = HashMap<ItemStack, Int>()
        for (core in cores) {
            for ((item, qty) in core.getInventorySnapshot()) {
                aggregated.merge(item, qty, Integer::sum)
            }
        }
        return CachedView(
            snapshot = aggregated,
            version = System.nanoTime(),
            timestamp = System.currentTimeMillis()
        )
    }
}

class WriteBuffer(
    private val flushIntervalMillis: Long = 500L,
    private val maxBatchSize: Int = 50
) {
    private data class PendingWrite(
        val coreId: UUID,
        val operation: WriteOperation,
        val timestamp: Long,
        val version: Long
    )

    private val buffer = ConcurrentLinkedQueue<PendingWrite>()
    private val scheduler = Executors.newSingleThreadScheduledExecutor()

    init {
        scheduler.scheduleAtFixedRate(
            { flush() },
            flushIntervalMillis,
            flushIntervalMillis,
            TimeUnit.MILLISECONDS
        )
    }

    fun enqueue(coreId: UUID, operation: WriteOperation, expectedVersion: Long) {
        buffer.offer(PendingWrite(coreId, operation, System.currentTimeMillis(), expectedVersion))
        if (buffer.size >= maxBatchSize) flush()
    }

    @Synchronized
    private fun flush() {
        val batch = mutableListOf<PendingWrite>()
        while (buffer.isNotEmpty() && batch.size < maxBatchSize) {
            buffer.poll()?.let { batch.add(it) }
        }
        if (batch.isEmpty()) return

        val grouped = batch.groupBy { it.coreId }
        for ((coreId, writes) in grouped) {
            applyBatch(coreId, writes)
        }
    }
}

class OptimisticCoreInventory {
    @Volatile private var version = 0L
    private val inventory = HashMap<ItemStack, Int>()

    @Synchronized
    fun withdraw(item: ItemStack, quantity: Int, expectedVersion: Long): Boolean {
        if (this.version != expectedVersion) return false

        val current = inventory[item] ?: 0
        if (current < quantity) return false

        inventory[item] = current - quantity
        this.version++
        return true
    }

    fun getCurrentVersion(): Long = version
}

Player 使用机器（例如：自动合成台）
    ↓
① Machine.requestPower(requestedAmount)
    │  检查自身电量是否充足
    ↓
② PowerSupplySystem.checkRange(machineLocation)
    │  通过 SpatialHashGrid.queryNearby() 查找附近供电桩
    │  时间复杂度：O(k)，k 为邻近 cell 内实体数（通常 8~27）
    ↓
③ PowerGrid.distributeEnergy(sourceId, targetId, amount)
    │  通过 DisjointSet.findRoot() 验证源和目标在同一电网内
    │  时间复杂度：O(α(n)) ≈ O(1)
    │  计算传输损耗、线缆负载
    ↓
④ Machine.consumePower(actualAmount)
    │  机器获得电力，开始工作
    ↓
⑤ CloudWarehouse.retrieveItem(requiredItem, quantity)
    │  ⑤a. 读取缓存视图（命中则直接返回，~0ms）
    │  ⑤b. 缓存未命中 → 聚合各核心库存（~5~20ms）
    │  ⑤c. 选定目标核心，发起乐观锁写入
    ↓
⑥ EnergyCore.updateInventory(delta)
    │  进入 WriteBuffer 排队
    │  下一个 flush 周期（≤500ms）批量写入
    ↓
⑦ 返回结果给 Machine → Player 看到合成结果

interface DeviceBehavior {
    val typeId: String
    fun onPowerReceived(device: Device, amount: Int)
    fun onTick(device: Device)
    fun serialize(device: Device): Map<String, Any>
    fun deserialize(data: Map<String, Any>): Device
}

object DeviceRegistry {
    private val behaviors = mutableMapOf<String, DeviceBehavior>()

    fun register(behavior: DeviceBehavior) {
        behaviors[behavior.typeId] = behavior
    }

    fun get(typeId: String): DeviceBehavior? = behaviors[typeId]

    fun getAllTypes(): Set<String> = behaviors.keys.toSet()
}

// 新增设备只需：
// class AutoCrafterBehavior : DeviceBehavior { ... }
// DeviceRegistry.register(AutoCrafterBehavior())

Chunk (0,0)          Chunk (1,0)          Chunk (0,1)
┌──────────┐        ┌──────────┐        ┌──────────┐
│  [发电机] ════════╗  [电线]   │        │          │
│           ║       │          │        │          │
│  [机器]   ║       │  [机器]   │        │  [机器]   │
└──────────╨────────┴──────────┘        └──────────┘
             ↑ 跨区块边界

class CrossChunkGridManager {
    private val chunkLoadedStatus = ConcurrentHashMap<ChunkCoord, Boolean>()

    fun onChunkUnload(coord: ChunkCoord) {
        chunkLoadedStatus[coord] = false
        val devicesInChunk = deviceRegistry.getByChunk(coord)
        devicesInChunk.forEach { it.state = DeviceState.UNLOADED }
    }

    fun onChunkLoad(coord: ChunkCoord) {
        chunkLoadedStatus[coord] = true
        val devicesInChunk = deviceRegistry.getByChunk(coord)
        devicesInChunk.forEach { it.state = DeviceState.ACTIVE }
        rebuildLocalTopology(coord)
    }

    private fun rebuildLocalTopology(coord: ChunkCoord) {
        val adjacentChunks = getAdjacentCoords(coord)
        val allDevices = adjacentChunks.flatMap { deviceRegistry.getByChunk(it) }
        for (device in allDevices) {
            for (neighbor in getNeighbors(device)) {
                if (isConnected(device, neighbor)) {
                    disjointSet.union(device.id, neighbor.id)
                }
            }
        }
    }
}

持久化策略：

┌─────────────────────────────────────────────────┐
│                   存储层                         │
├────────────────────┬────────────────────────────┤
│   全量快照          │     WAL 日志               │
│   (每 5 分钟)       │     (实时追加)              │
│   → pylon_snapshot │     → pylon_wal.log        │
│   .dat             │                            │
├────────────────────┴────────────────────────────┤
│  启动恢复流程：                                   │
│  1. 加载最近的全量快照                            │
│  2. 回放快照之后的所有 WAL 记录                   │
│  3. 截断已应用的 WAL 条目                         │
└─────────────────────────────────────────────────┘

class PersistenceManager(
    private val dataFolder: File,
    private val snapshotIntervalMinutes: Long = 5L
) {
    private val walFile = File(dataFolder, "pylon_wal.log")
    private val serializer = PylonSerializer()

    fun saveIncremental(change: GridChange) {
        walFile.appendText(serializer.serializeChange(change) + "\n")
    }

    fun saveFullSnapshot(gridState: GridState) {
        val snapshotFile = File(dataFolder, "pylon_snapshot_${System.currentTimeMillis()}.dat")
        snapshotFile.writeBytes(serializer.serializeSnapshot(gridState))
        trimOldSnapshots(retainLatest = 3)
        truncateWAL()
    }

    fun loadState(): GridState {
        val latestSnapshot = findLatestSnapshot() ?: return GridState.empty()
        var state = serializer.deserializeSnapshot(latestSnapshot)
        if (walFile.exists()) {
            val changes = walFile.readLines().map { serializer.deserializeChange(it) }
            for (change in changes) {
                state = state.applyChange(change)
            }
        }
        return state
    }
}