itqop
/
hubmc_essentionals
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
hubmc_essentionals/TODO.md

20 KiB
Raw Permalink Blame History

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<CompletableFuture<T>>, int maxRetries, Predicate<Throwable> 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<HttpResponse<String>>
    • Метод 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<List>

  • Создать 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 <nick>:

    • Проверка пермишена hubmc.cmd.invsee
    • Проверка что игрок онлайн
    • Открытие инвентаря целевого игрока

  • EnderchestCommand /enderchest <nick>:

    • Проверка пермишена 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 <name>:

    • Проверка пермишена hubmc.cmd.kit
    • Проверка tier пермишена для конкретного кита
    • Проверка cooldown через CooldownService.checkCooldown(uuid, "kit|<name>")
    • Если 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 <create|list|delete|teleport> [name]:

    • /warp create <name> - hubmc.cmd.warp.create, БЕЗ cooldown
      • Вызов WarpService.createWarp()
    • /warp list - вывод списка warp'ов
      • Вызов WarpService.listWarps()
    • /warp delete <name> - удаление warp'а (если есть права)
    • /warp <name> - телепортация на 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 <effect> [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 <clear|storm|thunder>:

    • Проверка hubmc.cmd.weather
    • БЕЗ cooldown
    • Установка погоды

Этап 7: Custom /tp команда

  • CustomTpCommand - переопределение /tp:
    • Поддержка форматов:
      • /tp <player> - проверка hubmc.cmd.tp, cooldown "tp|<targetNick>"
      • /tp <player1> <player2> - проверка hubmc.cmd.tp.others, cooldown "tp|<targetNick>"
      • /tp <x> <y> <z> - проверка 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<UUID, LastLocation> в памяти
    • Метод 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 интеграция для всех проверок пермишенов