# HubMC Essentials - План разработки ## Архитектура проекта ``` src/main/java/org/itqop/HubmcEssentials/ ├── HubmcEssentials.java # Main mod class ├── Config.java # Configuration ├── api/ │ ├── HubGWClient.java # HTTP client singleton (async) │ ├── dto/ # Data Transfer Objects │ │ ├── cooldown/ │ │ │ ├── CooldownCheckRequest.java │ │ │ ├── CooldownCheckResponse.java │ │ │ ├── CooldownCreateRequest.java │ │ │ └── CooldownCreateResponse.java │ │ ├── home/ │ │ │ ├── HomeData.java │ │ │ ├── HomeCreateRequest.java │ │ │ ├── HomeGetRequest.java │ │ │ └── HomeListResponse.java │ │ ├── warp/ │ │ │ ├── WarpData.java │ │ │ ├── WarpCreateRequest.java │ │ │ ├── WarpGetRequest.java │ │ │ └── WarpListResponse.java │ │ ├── teleport/ │ │ │ ├── TeleportHistoryEntry.java │ │ │ └── TeleportHistoryRequest.java │ │ └── kit/ │ │ ├── KitClaimRequest.java │ │ └── KitClaimResponse.java │ └── service/ │ ├── CooldownService.java # Cooldown API calls │ ├── HomeService.java # Home API calls │ ├── WarpService.java # Warp API calls │ ├── TeleportService.java # Teleport history API calls │ └── KitService.java # Kit API calls ├── command/ │ ├── CommandRegistry.java # Register all commands │ ├── general/ │ │ ├── SpecCommand.java │ │ ├── SetHomeCommand.java │ │ ├── HomeCommand.java │ │ ├── FlyCommand.java │ │ ├── VanishCommand.java │ │ ├── InvseeCommand.java │ │ ├── EnderchestCommand.java │ │ ├── KitCommand.java │ │ ├── ClearCommand.java │ │ ├── EcCommand.java │ │ └── HatCommand.java │ ├── vip/ │ │ ├── HealCommand.java │ │ ├── FeedCommand.java │ │ ├── RepairCommand.java │ │ ├── NearCommand.java │ │ ├── BackCommand.java │ │ └── RtpCommand.java │ ├── premium/ │ │ ├── WarpCommand.java │ │ ├── RepairAllCommand.java │ │ └── WorkbenchCommand.java │ ├── deluxe/ │ │ ├── TopCommand.java │ │ ├── PotCommand.java │ │ ├── TimeCommand.java │ │ └── WeatherCommand.java │ └── teleport/ │ └── CustomTpCommand.java # Override /tp command ├── permission/ │ ├── PermissionManager.java # LuckPerms integration │ └── PermissionNodes.java # Constants for permission nodes ├── util/ │ ├── MessageUtil.java # User messages (Russian) │ ├── LocationUtil.java # Location/teleport utilities │ ├── PlayerUtil.java # Player utilities │ └── RetryUtil.java # Retry logic for API calls └── storage/ └── LocationStorage.java # Store last location for /back ``` --- ## Этап 1: Базовая инфраструктура ### 1.1 Конфигурация - [ ] Обновить `Config.java`: - [ ] API base URL (String, default: "http://localhost:8000/api/v1") - [ ] API key (String) - [ ] Connection timeout (int, default: 2) - [ ] Read timeout (int, default: 5) - [ ] Max retries (int, default: 2) - [ ] Enable debug logging (boolean, default: false) ### 1.2 Permission система - [ ] Создать `PermissionNodes.java` с константами всех пермишенов - [ ] Создать `PermissionManager.java`: - [ ] Метод `hasPermission(ServerPlayer, String)` - проверка через LuckPerms - [ ] Метод `hasTier(ServerPlayer, String)` - проверка tier (vip/premium/deluxe) - [ ] Метод `getPlayerTier(ServerPlayer)` - получить высший tier игрока ### 1.3 Утилиты - [ ] Создать `MessageUtil.java`: - [ ] Метод `sendError(ServerPlayer, String)` - отправка сообщения об ошибке - [ ] Метод `sendSuccess(ServerPlayer, String)` - отправка успешного сообщения - [ ] Метод `sendInfo(ServerPlayer, String)` - информационное сообщение - [ ] Константы сообщений на русском - [ ] Создать `LocationUtil.java`: - [ ] Метод `toJsonLocation(ServerPlayer)` - конвертация позиции в JSON - [ ] Метод `teleportPlayer(ServerPlayer, world, x, y, z, yaw, pitch)` - телепорт - [ ] Метод `getSafeYLocation(ServerLevel, x, z)` - получить безопасную Y координату - [ ] Создать `PlayerUtil.java`: - [ ] Метод `getPlayerByName(MinecraftServer, String)` - поиск игрока по нику - [ ] Метод `isPlayerOnline(MinecraftServer, String)` - проверка онлайн - [ ] Создать `RetryUtil.java`: - [ ] Метод `retryAsync(Supplier>, int maxRetries, Predicate shouldRetry)` - [ ] Логика retry на 429/5xx ошибках --- ## Этап 2: API Client и сервисы ### 2.1 HTTP Client - [ ] Создать `HubGWClient.java`: - [ ] Singleton паттерн с `getInstance()` - [ ] Инициализация `HttpClient` с timeouts из Config - [ ] Circuit breaker для предотвращения спама логов - [ ] Метод `refreshFromConfig()` для обновления настроек - [ ] Базовый метод `makeRequest(method, path, body)` возвращающий `CompletableFuture>` - [ ] Метод `baseBuilder(path)` для создания HttpRequest с headers (X-API-Key) - [ ] Обработка ошибок с логированием ### 2.2 DTO классы #### Cooldowns - [ ] Создать `CooldownCheckRequest.java` (player_uuid, cooldown_type) - [ ] Создать `CooldownCheckResponse.java` (is_active, expires_at, remaining_seconds) - [ ] Создать `CooldownCreateRequest.java` (player_uuid, cooldown_type, cooldown_seconds OR expires_at) - [ ] Создать `CooldownCreateResponse.java` (message) #### Homes - [ ] Создать `HomeData.java` (id, player_uuid, name, world, x, y, z, yaw, pitch, is_public, created_at, updated_at) - [ ] Создать `HomeCreateRequest.java` (player_uuid, name, world, x, y, z, yaw, pitch, is_public) - [ ] Создать `HomeGetRequest.java` (player_uuid, name) - [ ] Создать `HomeListResponse.java` (homes[], total) #### Warps - [ ] Создать `WarpData.java` (id, name, world, x, y, z, yaw, pitch, is_public, description, created_at, updated_at) - [ ] Создать `WarpCreateRequest.java` (name, world, x, y, z, yaw, pitch, is_public, description) - [ ] Создать `WarpGetRequest.java` (name) - [ ] Создать `WarpListResponse.java` (warps[], total, page, size, pages) #### Teleport - [ ] Создать `TeleportHistoryEntry.java` (id, player_uuid, from_world, from_x/y/z, to_world, to_x/y/z, tp_type, target_name, created_at) - [ ] Создать `TeleportHistoryRequest.java` (player_uuid, from_world, from_x/y/z, to_world, to_x/y/z, tp_type, target_name) #### Kits - [ ] Создать `KitClaimRequest.java` (player_uuid, kit_name) - [ ] Создать `KitClaimResponse.java` (success, message, cooldown_remaining) ### 2.3 Service классы - [ ] Создать `CooldownService.java`: - [ ] `checkCooldown(playerUuid, cooldownType)` → CompletableFuture - [ ] `createCooldown(playerUuid, cooldownType, seconds)` → CompletableFuture - [ ] Использует HubGWClient для API вызовов - [ ] Создать `HomeService.java`: - [ ] `createHome(request)` → CompletableFuture - [ ] `getHome(playerUuid, name)` → CompletableFuture - [ ] `listHomes(playerUuid)` → CompletableFuture - [ ] Создать `WarpService.java`: - [ ] `createWarp(request)` → CompletableFuture - [ ] `getWarp(name)` → CompletableFuture - [ ] `listWarps()` → CompletableFuture - [ ] Создать `TeleportService.java`: - [ ] `logTeleport(request)` → CompletableFuture - [ ] `getHistory(playerUuid, limit)` → CompletableFuture> - [ ] Создать `KitService.java`: - [ ] `claimKit(playerUuid, kitName)` → CompletableFuture --- ## Этап 3: Команды - General (базовые) ### 3.1 Локальные команды (без API) - [ ] **SpecCommand** `/spec` `/spectator`: - [ ] Проверка пермишена `hubmc.cmd.spec` - [ ] Переключение gamemode на spectator/survival - [ ] **FlyCommand** `/fly`: - [ ] Проверка пермишена `hubmc.cmd.fly` - [ ] Включение/выключение полета - [ ] **VanishCommand** `/vanish`: - [ ] Проверка пермишена `hubmc.cmd.vanish` - [ ] Скрытие игрока от других (через NeoForge API) - [ ] **InvseeCommand** `/invsee `: - [ ] Проверка пермишена `hubmc.cmd.invsee` - [ ] Проверка что игрок онлайн - [ ] Открытие инвентаря целевого игрока - [ ] **EnderchestCommand** `/enderchest `: - [ ] Проверка пермишена `hubmc.cmd.enderchest` - [ ] Проверка что игрок онлайн - [ ] Открытие эндерчеста целевого игрока ### 3.2 API команды с cooldown - [ ] **SetHomeCommand** `/sethome [name]`: - [ ] Проверка пермишена `hubmc.cmd.sethome` - [ ] Получение текущей позиции - [ ] Вызов `HomeService.createHome()` - [ ] Обработка ответа (успех/ошибка) - [ ] **HomeCommand** `/home [name]`: - [ ] Проверка пермишена `hubmc.cmd.home` - [ ] Вызов `HomeService.getHome()` - [ ] Телепортация на позицию дома - [ ] Обработка 404 (дом не найден) - [ ] **KitCommand** `/kit `: - [ ] Проверка пермишена `hubmc.cmd.kit` - [ ] Проверка tier пермишена для конкретного кита - [ ] Проверка cooldown через `CooldownService.checkCooldown(uuid, "kit|")` - [ ] Если cooldown активен - показать сообщение "Команда доступна через N сек." - [ ] Вызов `KitService.claimKit()` - [ ] Установка cooldown через `CooldownService.createCooldown()` - [ ] Выдача предметов игроку (items из API response) - [ ] **ClearCommand** `/clear`: - [ ] Проверка пермишена `hubmc.cmd.clear` - [ ] Проверка cooldown `"clear"` - [ ] Очистка инвентаря - [ ] Установка cooldown - [ ] **EcCommand** `/ec`: - [ ] Проверка пермишена `hubmc.cmd.ec` - [ ] Проверка cooldown `"ec"` - [ ] Открытие enderchest - [ ] Установка cooldown - [ ] **HatCommand** `/hat`: - [ ] Проверка пермишена `hubmc.cmd.hat` - [ ] Проверка cooldown `"hat"` - [ ] Проверка что в руке предмет - [ ] Замена головного слота на предмет из руки - [ ] Установка cooldown --- ## Этап 4: VIP команды - [ ] **HealCommand** `/heal`: - [ ] Проверка `hubmc.cmd.heal` - [ ] Проверка cooldown `"heal"` - [ ] Восстановление здоровья и голода - [ ] Установка cooldown - [ ] **FeedCommand** `/feed`: - [ ] Проверка `hubmc.cmd.feed` - [ ] Проверка cooldown `"feed"` - [ ] Восстановление голода и saturation - [ ] Установка cooldown - [ ] **RepairCommand** `/repair`: - [ ] Проверка `hubmc.cmd.repair` - [ ] Проверка cooldown `"repair"` - [ ] Проверка что в руке инструмент/броня - [ ] Ремонт предмета в руке - [ ] Установка cooldown - [ ] **NearCommand** `/near [radius]`: - [ ] Проверка `hubmc.cmd.near` - [ ] Проверка cooldown `"near"` - [ ] Поиск игроков в радиусе - [ ] Вывод списка с расстояниями - [ ] Установка cooldown - [ ] **BackCommand** `/back`: - [ ] Проверка `hubmc.cmd.back` - [ ] Проверка cooldown `"back"` - [ ] Получение последней позиции из LocationStorage - [ ] Телепортация - [ ] Установка cooldown - [ ] **RtpCommand** `/rtp`: - [ ] Проверка `hubmc.cmd.rtp` - [ ] Проверка cooldown `"rtp"` - [ ] Генерация случайной позиции (безопасной) - [ ] Телепортация - [ ] Установка cooldown --- ## Этап 5: Premium команды - [ ] **WarpCommand** `/warp [name]`: - [ ] `/warp create ` - `hubmc.cmd.warp.create`, БЕЗ cooldown - [ ] Вызов `WarpService.createWarp()` - [ ] `/warp list` - вывод списка warp'ов - [ ] Вызов `WarpService.listWarps()` - [ ] `/warp delete ` - удаление warp'а (если есть права) - [ ] `/warp ` - телепортация на warp - [ ] **RepairAllCommand** `/repair all`: - [ ] Проверка `hubmc.cmd.repair.all` - [ ] Проверка cooldown `"repair_all"` - [ ] Ремонт всего инвентаря + броня - [ ] Установка cooldown - [ ] **WorkbenchCommand** `/workbench`: - [ ] Проверка `hubmc.cmd.workbench` - [ ] БЕЗ cooldown - [ ] Открытие crafting table GUI --- ## Этап 6: Deluxe команды - [ ] **TopCommand** `/top`: - [ ] Проверка `hubmc.cmd.top` - [ ] Проверка cooldown `"top"` - [ ] Поиск самого высокого блока по X/Z координатам игрока - [ ] Телепортация на него - [ ] Установка cooldown - [ ] **PotCommand** `/pot [duration] [amplifier]`: - [ ] Проверка `hubmc.cmd.pot` - [ ] Проверка cooldown `"pot"` - [ ] Применение эффекта - [ ] Установка cooldown - [ ] **TimeCommand** `/day` `/night` `/morning` `/evening`: - [ ] Проверка `hubmc.cmd.time` - [ ] Проверка cooldown `"time|day"` / `"time|night"` / `"time|morning"` / `"time|evening"` - [ ] Установка времени суток в мире - [ ] Установка cooldown - [ ] **WeatherCommand** `/weather `: - [ ] Проверка `hubmc.cmd.weather` - [ ] БЕЗ cooldown - [ ] Установка погоды --- ## Этап 7: Custom /tp команда - [ ] **CustomTpCommand** - переопределение `/tp`: - [ ] Поддержка форматов: - [ ] `/tp ` - проверка `hubmc.cmd.tp`, cooldown `"tp|"` - [ ] `/tp ` - проверка `hubmc.cmd.tp.others`, cooldown `"tp|"` - [ ] `/tp ` - проверка `hubmc.cmd.tp.coords`, cooldown `"tp|coords"` - [ ] Проверка cooldown через API - [ ] Сохранение текущей позиции в LocationStorage для /back - [ ] Выполнение телепортации - [ ] **ОБЯЗАТЕЛЬНО**: Логирование в teleport history через `TeleportService.logTeleport()` - [ ] Поля: player_uuid, from_world, from_x/y/z, to_world, to_x/y/z, tp_type, target_name - [ ] Установка cooldown через API --- ## Этап 8: Интеграция и регистрация - [ ] **LocationStorage** - хранение последней позиции для /back: - [ ] Map в памяти - [ ] Метод `saveLocation(player)` - сохранить позицию - [ ] Метод `getLastLocation(player)` - получить последнюю позицию - [ ] Автоматическое сохранение при телепортации - [ ] **CommandRegistry**: - [ ] Регистрация всех команд в NeoForge - [ ] Централизованное место для регистрации - [ ] **HubmcEssentials.java**: - [ ] В `commonSetup()`: - [ ] Инициализация HubGWClient - [ ] Инициализация всех сервисов - [ ] Регистрация команд через CommandRegistry - [ ] Логирование успешной инициализации --- ## Этап 9: Тестирование и отладка - [ ] Тестирование каждой команды: - [ ] Проверка пермишенов - [ ] Проверка cooldown системы - [ ] Проверка API интеграции - [ ] Проверка обработки ошибок (API недоступен) - [ ] Проверка сообщений пользователю - [ ] Тестирование edge cases: - [ ] Игрок не найден - [ ] Игрок оффлайн - [ ] HubGW API недоступен - [ ] Неверные координаты - [ ] Кит не существует - [ ] Дом не найден - [ ] Логирование: - [ ] Проверить что все ошибки логируются - [ ] Circuit breaker работает (не спамит логи) --- ## Этап 10: Финализация - [ ] Обновить CLAUDE.md с актуальной информацией об архитектуре - [ ] Проверить что все DTO классы properly serializable - [ ] Проверить что все async операции правильно обрабатывают ошибки - [ ] Финальный build и тест в игре - [ ] Документация по конфигурации --- ## Приоритеты разработки **P0 (критично):** 1. Базовая инфраструктура (Config, Permissions, Utils) 2. HTTP Client и Services 3. DTO классы **P1 (высокий):** 4. General команды 5. VIP команды 6. Custom /tp с teleport history **P2 (средний):** 7. Premium команды 8. Deluxe команды **P3 (низкий):** 9. Тестирование 10. Финализация --- ## Технические требования - Все API вызовы **АСИНХРОННЫЕ** через `CompletableFuture` - Все cooldown проверки **ТОЛЬКО через HubGW API** - никакого локального кеша - Retry логика: 2 ретрая на 429/5xx ошибках - Timeouts: 2s connect / 5s read - Circuit breaker для предотвращения спама логов - Все сообщения пользователю **на русском языке** - При ошибке API - **ОТКАЗАТЬ в выполнении команды** - LuckPerms интеграция для всех проверок пермишенов