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

453 lines
20 KiB
Markdown
Raw Permalink Normal View History

First commit
2025-11-12 09:35:38 +01:00
# 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<CooldownCheckResponse>
- [ ] `createCooldown(playerUuid, cooldownType, seconds)` → CompletableFuture<Boolean>
- [ ] Использует HubGWClient для API вызовов
- [ ] Создать `HomeService.java`:
- [ ] `createHome(request)` → CompletableFuture<HomeData>
- [ ] `getHome(playerUuid, name)` → CompletableFuture<HomeData>
- [ ] `listHomes(playerUuid)` → CompletableFuture<HomeListResponse>
- [ ] Создать `WarpService.java`:
- [ ] `createWarp(request)` → CompletableFuture<WarpData>
- [ ] `getWarp(name)` → CompletableFuture<WarpData>
- [ ] `listWarps()` → CompletableFuture<WarpListResponse>
- [ ] Создать `TeleportService.java`:
- [ ] `logTeleport(request)` → CompletableFuture<Boolean>
- [ ] `getHistory(playerUuid, limit)` → CompletableFuture<List<TeleportHistoryEntry>>
- [ ] Создать `KitService.java`:
- [ ] `claimKit(playerUuid, kitName)` → CompletableFuture<KitClaimResponse>
---
## Этап 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 интеграция для всех проверок пермишенов