LoMines/todo.md

26 KiB
Raw Blame History

LoMines — План реструктуризации и улучшения качества

Обновлено: 2026-07-06
Цели: Разбивка на подпапки (≤3 файла), лимит 150 строк/файл, Checkstyle


📊 Текущее состояние

Файлы >150 строк (нужен split) — 25 main + 11 test

MAIN (нуждаются в сплите):
 209  handler/MineResetHandler.java
 207  util/format/ColorUtils.java
 207  command/common/LoMinesTabCompleter.java
 203  integration/hologram/HologramManager.java
 201  core/service/MineFileManager.java
 190  gui/mine/main/MineEditItems.java
 186  command/admin/StatsCommands.java
 181  util/location/Cuboid.java
 181  data/stats/StatsManager.java
 180  gui/mine/edit/blocks/BlockMaterialSelectionGui.java
 174  util/format/ChunkUtils.java
 173  listener/MineEditGuiListener.java
 170  core/mine/Mine.java
 165  command/admin/RegionCommands.java
 164  data/config/ConfigLoader.java
 163  integration/worldguard/WorldGuardRegionService.java
 161  data/config/MineConfig.java
 161  command/admin/AdminCommands.java
 160  util/block/BlockUpdateUtil.java
 156  data/config/reset/ResetConfig.java
 155  data/reward/RewardParser.java
 155  command/admin/TeleportCommands.java
 154  integration/worldguard/WorldGuardConfig.java
 153  core/mine/Mines.java
 151  gui/mine/edit/blocks/BlocksGui.java

TEST (нуждаются в сплите):
 264  core/MinesTest.java
 262  data/StatsManagerTest.java
 223  util/selection/SelectionTest.java
 210  data/LeaderboardTest.java
 191  data/config/MineConfigTest.java
 181  util/LocationParserTest.java
 178  util/TimeFormatterTest.java
 169  data/config/reset/ResetConfigTest.java
 159  data/LeaderboardCacheIntegrationTest.java
 158  util/ChunkUtilsTest.java
 152  command/AdminCommandsTest.java

Папки с >3 файлами (нужны подпапки)

 8  command/admin/          → manage/, region/, stats/, teleport/, misc/
 6  listener/               → block/, gui/, player/
 5  handler/                → reset/, block/, reward/, ui/
 5  gui/mine/holder/        → edit/, main/ (перегруппировать)
 5  data/reward/            → model/, parser/
 4  util/location/          → оставить (package-info не считается)
 4  util/ (root)            → split ErrorHandler, MessageFormatter, ValidationUtils
 4  integration/worldguard/ → config/, service/
 4  data/stats/             → model/, service/, query/
 4  core/mine/              → model/, registry/, loader/, tick/

🎯 Фазы работ

Phase 1: Настройка Checkstyle

  • Создать config/checkstyle/checkstyle.xml с правилами:
    • Max line length: 150
    • Max file length: 150 строк
    • Max method length: 30 строк
    • No unused imports
    • No wildcard imports
    • Indentation: 4 spaces
    • Javadoc style enforced
  • Добавить плагин checkstyle в build.gradle.kts
  • Проверить, что билд не падает (пока warnings mode)

Phase 2: Split файлов >150 строк (main)

2.1 handler/MineResetHandler.java (209→~110+~90)

  • Выделить PlayerTeleportHandler.java — логика телепортации stuck players
  • В MineResetHandler остаётся: reset, resetAllRegions, onResetComplete, executeResetCommands, broadcastReset

2.2 util/format/ColorUtils.java (207→~70+~90+~40)

  • Выделить LegacyColorConverter.java — legacy &a → MiniMessage
  • Выделить HexColorConverter.java — &#RRGGBB → <#RRGGBB>, &x→MiniMessage
  • В ColorUtils остаётся: format(), stripColors(), toLegacy() как фасад

2.3 command/common/LoMinesTabCompleter.java (207→~60+~70+~70)

  • Выделить SubcommandCompleter.java — completeSecondArg, completeThirdArg
  • Выделить PermissionPredicate.java — hasPermission для всех команд
  • В LoMinesTabCompleter остаётся: onTabComplete, isLoMinesCommand, completeSubcommands, filterStartsWith, хелперы

2.4 integration/hologram/HologramManager.java (203→~100+~100)

  • Выделить HologramRenderer.java — рендеринг строк голограммы
  • В HologramManager остаётся: create/update/delete/toggle, управление жизненным циклом

2.5 core/service/MineFileManager.java (201→~100+~100)

  • Выделить MineConfigWriter.java — создание/сохранение mine.yml
  • В MineFileManager остаётся: загрузка, поиск, листинг файлов

2.6 gui/mine/main/MineEditItems.java (190→~95+~95)

  • Выделить MineEditItemActions.java — обработчики кликов для каждого слота
  • В MineEditItems остаётся: создание ItemStack, статические методы

2.7 command/admin/StatsCommands.java (186→~90+~90)

  • Выделить LeaderboardRenderer.java — форматирование и отправка топ-списка
  • В StatsCommands остаётся: парсинг аргументов, делегирование

2.8 util/location/Cuboid.java (181→~90+~90)

  • Выделить CuboidSerializer.java — сериализация/десериализация Cuboid
  • В Cuboid остаётся: contains, volume, пересечения, геометрия

2.9 data/stats/StatsManager.java (181→~90+~90)

  • Выделить StatsPersistence.java — load/save данных из файлов
  • В StatsManager остаётся: getOrCreate, increment, кэш в ConcurrentHashMap

2.10 gui/mine/edit/blocks/BlockMaterialSelectionGui.java (180→~90+~90)

  • Выделить BlockMaterialSelector.java — логика выбора материала
  • В BlockMaterialSelectionGui остаётся: рендеринг GUI

2.11 util/format/ChunkUtils.java (174→~85+~85)

  • Выделить ChunkRefresher.java — рефреш чанков
  • В ChunkUtils остаётся: определение Paper, базовые операции

2.12 listener/MineEditGuiListener.java (173→~85+~85)

  • Выделить GuiActionHandler.java — обработка действий в GUI
  • В MineEditGuiListener остаётся: маршрутизация событий

2.13 core/mine/Mine.java (170→~85+~85)

  • Выделить MineState.java — управление состоянием (блоки, тики, paused)
  • В Mine остаётся: основные методы, делегирование

2.14 command/admin/RegionCommands.java (165→~80+~80)

  • Выделить RegionActionHandler.java — add/remove region
  • В RegionCommands остаётся: список, инфо, парсинг

2.15 data/config/ConfigLoader.java (164→~80+~80)

  • Выделить DefaultsMerger.java — YAML inheritance из defaults.yml
  • В ConfigLoader остаётся: загрузка mine.yml, вызов лоадеров

2.16 integration/worldguard/WorldGuardRegionService.java (163→~80+~80)

  • Выделить RegionTemplateRenderer.java — рендеринг шаблонов имён
  • В WorldGuardRegionService остаётся: create/update/delete

2.17 data/config/MineConfig.java (161→~80+~80)

  • Выделить MineConfigDefaults.java — статические фабрики и Builder по умолчанию
  • В MineConfig остаётся: record + базовый builder

2.18 command/admin/AdminCommands.java (161→~80+~80)

  • Выделить MineActionHandler.java — create, delete, reset, reload
  • В AdminCommands остаётся: list, edit, парсинг

2.19 util/block/BlockUpdateUtil.java (160→~80+~80)

  • Выделить SafeTeleportFinder.java — findSafeTeleportLocation
  • В BlockUpdateUtil остаётся: sendBlockUpdate, sendRegionUpdate, refreshChunks

2.20 data/config/reset/ResetConfig.java (156→~80+~75)

  • Выделить ResetConfigValidator.java — валидация Duration, bounds
  • В ResetConfig остаётся: record + builder

2.21 data/reward/RewardParser.java (155→~75+~80)

  • Выделить RewardEntryParser.java — парсинг одной записи награды
  • В RewardParser остаётся: парсинг всего списка

2.22 command/admin/TeleportCommands.java (155→~75+~80)

  • Выделить TeleportActionHandler.java — setteleport, setspawn, clearspawn
  • В TeleportCommands остаётся: парсинг команд

2.23 integration/worldguard/WorldGuardConfig.java (154→~75+~75)

  • Выделить RegionTemplateConfig.java — шаблоны имён
  • В WorldGuardConfig остаётся: record, flags, members

2.24 core/mine/Mines.java (153→~75+~75)

  • Выделить MineFinder.java — find, findByRegion, getAll
  • В Mines остаётся: create, delete, reloadMine, updateMineConfig

2.25 gui/mine/edit/blocks/BlocksGui.java (151→~75+~75)

  • Выделить BlockWeightEditor.java — изменение весов блоков
  • В BlocksGui остаётся: список блоков, рендеринг

Phase 3: Разбивка папок (max 3 файла)

3.1 command/admin (8 файлов) → 5 подпапок

  • command/admin/manage/ — AdminCommands.java, InfoCommand.java, CopyCommand.java
  • command/admin/region/ — RegionCommands.java
  • command/admin/stats/ — StatsCommands.java
  • command/admin/teleport/ — TeleportCommands.java
  • command/admin/misc/ — MaskCommands.java, HologramCommands.java

3.2 listener (6 файлов) → 3 подпапки

  • listener/block/ — BlockBreakListener.java
  • listener/gui/ — MineEditGuiListener.java, GroupGuiListener.java
  • listener/player/ — PlayerJoinListener.java, PlayerInteractListener.java

3.3 handler (5 файлов) → 4 подпапки

  • handler/reset/ — MineResetHandler.java (+ PlayerTeleportHandler из Phase 2)
  • handler/block/ — MineBlockHandler.java
  • handler/reward/ — MineRewardHandler.java
  • handler/ui/ — ActionBarHandler.java

3.4 gui/mine/holder (5 файлов) → 2 подпапки

  • gui/mine/holder/main/ — MineEditGuiHolder.java
  • gui/mine/holder/edit/ — BlocksGuiHolder.java, ResetGuiHolder.java, RewardsGuiHolder.java, BlockMaterialSelectionGuiHolder.java

3.5 data/reward (5 файлов) → 2 подпапки

  • data/reward/model/ — Reward.java
  • data/reward/parser/ — RewardParser.java, RewardItemParser.java, RewardCommandParser.java, RewardMaterialParser.java

3.6 util/location (4 файла) — оставить (с учётом package-info)

  • Убедиться что лимит соблюдён: BlockKeys.java, Cuboid.java, LocationParser.java, SafeTeleportUtil.java
  • Вынести package-info.java если мешает

3.7 util (root, 4 файла) — оставить

  • ErrorHandler.java, MessageFormatter.java, ValidationUtils.java, package-info.java — ровно 3+package-info

3.8 integration/worldguard (4 файла) → 2 подпапки

  • integration/worldguard/config/ — WorldGuardConfig.java
  • integration/worldguard/service/ — WorldGuardRegionService.java, WorldGuardFlagParser.java, WorldGuardMemberHandler.java

3.9 data/stats (4 файла) → 2 подпапки

  • data/stats/model/ — PlayerStats.java, LeaderboardEntry.java
  • data/stats/service/ — StatsManager.java, Leaderboard.java

3.10 core/mine (4 файла) → 3 подпапки

  • core/mine/model/ — Mine.java
  • core/mine/registry/ — Mines.java
  • core/mine/service/ — MineLoader.java, MineTicker.java

Phase 4: Split тестов >150 строк

4.1 core/MinesTest.java (264→~130+~130)

  • Сплитнуть на MinesRegistryTest.java, MinesLifecycleTest.java

4.2 data/StatsManagerTest.java (262→~130+~130)

  • Сплитнуть на StatsManagerStorageTest.java, StatsManagerConcurrencyTest.java

4.3 util/selection/SelectionTest.java (223→~110+~110)

  • Сплитнуть на SelectionStateTest.java, SelectionBoundsTest.java

4.4 data/LeaderboardTest.java (210→~105+~105)

  • Сплитнуть на LeaderboardSortingTest.java, LeaderboardQueryTest.java

4.5 data/config/MineConfigTest.java (191→~95+~95)

  • Сплитнуть на MineConfigBuilderTest.java, MineConfigValidationTest.java

4.6 util/LocationParserTest.java (181→~90+~90)

  • Сплитнуть на LocationParserValidTest.java, LocationParserErrorTest.java

4.7 util/TimeFormatterTest.java (178→~90+~90)

  • Сплитнуть по форматам: TimeFormatterBasicTest.java, TimeFormatterEdgeTest.java

4.8 data/config/reset/ResetConfigTest.java (169→~85+~85)

  • Сплитнуть на ResetConfigIntervalTest.java, ResetConfigValidationTest.java

4.9 data/LeaderboardCacheIntegrationTest.java (159→~80+~80)

  • Сплитнуть на LeaderboardCacheTest.java, LeaderboardIntegrationTest.java

4.10 util/ChunkUtilsTest.java (158→~80+~80)

  • Сплитнуть на ChunkUtilsPaperTest.java, ChunkUtilsRefreshTest.java

4.11 command/AdminCommandsTest.java (152→~75+~75)

  • Сплитнуть на AdminCreateDeleteTest.java, AdminResetReloadTest.java

Phase 5: Обновление импортов

  • Обновить все import statements в затронутых файлах
  • Обновить RegistrationManager.java — новые пути классов
  • Обновить ComponentInitializer.java — новые пути
  • Проверить сборку: ./gradlew build

Phase 6: Проверка качества

  • Запустить ./gradlew check — убедиться что checkstyle не падает
  • Запустить ./gradlew test — все тесты проходят
  • Проверить lint — отсутствие ошибок
  • Финальный обзор структуры папок

📁 Целевая структура проекта

dev.loki.lomines/
├── LoMinesPlugin.java                         # ≤120
├── ComponentInitializer.java                  # ≤150
├── RegistrationManager.java                   # ≤150
│
├── command/
│   ├── common/
│   │   ├── LoMinesTabCompleter.java           # ≤150 (split from 207)
│   │   ├── SubcommandCompleter.java           # NEW
│   │   └── PermissionPredicate.java           # NEW
│   ├── player/
│   │   └── PlayerCommands.java
│   └── admin/
│       ├── manage/
│       │   ├── AdminCommands.java             # ≤150 (split from 161)
│       │   ├── InfoCommand.java
│       │   └── CopyCommand.java
│       ├── region/
│       │   └── RegionCommands.java            # ≤150 (split from 165)
│       ├── stats/
│       │   ├── StatsCommands.java             # ≤150 (split from 186)
│       │   └── LeaderboardRenderer.java       # NEW
│       ├── teleport/
│       │   ├── TeleportCommands.java          # ≤150 (split from 155)
│       │   └── TeleportActionHandler.java     # NEW
│       └── misc/
│           ├── MaskCommands.java
│           └── HologramCommands.java
│
├── core/
│   ├── mine/
│   │   ├── model/
│   │   │   ├── Mine.java                     # ≤150 (split from 170)
│   │   │   └── MineState.java                # NEW
│   │   ├── registry/
│   │   │   ├── Mines.java                    # ≤150 (split from 153)
│   │   │   └── MineFinder.java               # NEW
│   │   └── service/
│   │       ├── MineLoader.java
│   │       └── MineTicker.java
│   └── service/
│       ├── MineFileManager.java              # ≤150 (split from 201)
│       ├── MineConfigWriter.java             # NEW
│       ├── MineRepository.java
│       └── MaskScanService.java
│
├── data/
│   ├── config/
│   │   ├── MineConfig.java                   # ≤150 (split from 161)
│   │   ├── MineConfigDefaults.java           # NEW
│   │   ├── ConfigLoader.java                 # ≤150 (split from 164)
│   │   ├── DefaultsMerger.java               # NEW
│   │   ├── block/
│   │   │   ├── BlockKey.java
│   │   │   ├── BlockConfig.java
│   │   │   └── FillMode.java
│   │   ├── region/
│   │   │   └── RegionConfig.java
│   │   ├── reset/
│   │   │   ├── ResetConfig.java              # ≤150 (split from 156)
│   │   │   └── ResetConfigValidator.java     # NEW
│   │   ├── reward/
│   │   │   └── RewardConfig.java
│   │   ├── teleport/
│   │   │   └── TeleportConfig.java
│   │   ├── spawn/
│   │   │   └── PlayerSpawnConfig.java
│   │   ├── ui/
│   │   │   ├── UIConfig.java
│   │   │   └── HologramConfig.java
│   │   ├── parser/
│   │   │   └── ConfigParseException.java
│   │   └── loader/
│   │       ├── block/BlockConfigLoader.java
│   │       ├── entity/
│   │       │   ├── TeleportConfigLoader.java
│   │       │   └── PlayerSpawnConfigLoader.java
│   │       ├── region/
│   │       │   ├── RegionConfigLoader.java
│   │       │   └── WorldGuardConfigLoader.java
│   │       ├── reward/RewardConfigLoader.java
│   │       └── system/
│   │           ├── ResetConfigLoader.java
│   │           └── UIConfigLoader.java
│   ├── stats/
│   │   ├── model/
│   │   │   ├── PlayerStats.java
│   │   │   └── LeaderboardEntry.java
│   │   └── service/
│   │       ├── StatsManager.java             # ≤150 (split from 181)
│   │       ├── StatsPersistence.java         # NEW
│   │       └── Leaderboard.java
│   └── reward/
│       ├── model/
│       │   └── Reward.java
│       └── parser/
│           ├── RewardParser.java             # ≤150 (split from 155)
│           ├── RewardEntryParser.java        # NEW
│           ├── RewardItemParser.java
│           ├── RewardCommandParser.java
│           └── RewardMaterialParser.java
│
├── block/
│   ├── BlockSetter.java
│   ├── BukkitBlockSetter.java
│   ├── OraxenBlockSetter.java.disabled
│   └── ItemsAdderBlockSetter.java.disabled
│
├── handler/
│   ├── reset/
│   │   ├── MineResetHandler.java            # ≤150 (split from 209)
│   │   └── PlayerTeleportHandler.java       # NEW
│   ├── block/
│   │   └── MineBlockHandler.java
│   ├── reward/
│   │   └── MineRewardHandler.java
│   └── ui/
│       └── ActionBarHandler.java
│
├── listener/
│   ├── block/
│   │   └── BlockBreakListener.java
│   ├── gui/
│   │   ├── MineEditGuiListener.java          # ≤150 (split from 173)
│   │   ├── GuiActionHandler.java            # NEW
│   │   └── GroupGuiListener.java
│   └── player/
│       ├── PlayerJoinListener.java
│       └── PlayerInteractListener.java
│
├── gui/
│   ├── common/
│   │   └── ItemStackFactory.java
│   ├── confirm/
│   │   ├── ConfirmDeleteGui.java
│   │   └── ConfirmDeleteGuiHolder.java
│   ├── group/
│   │   ├── GroupCreateGui.java
│   │   ├── GroupCreateGuiHolder.java
│   │   └── GroupCreateItems.java
│   └── mine/
│       ├── main/
│       │   ├── MineEditGui.java
│       │   ├── MineEditItems.java            # ≤150 (split from 190)
│       │   └── MineEditItemActions.java      # NEW
│       ├── edit/
│       │   ├── blocks/
│       │   │   ├── BlocksGui.java            # ≤150 (split from 151)
│       │   │   ├── BlockWeightEditor.java    # NEW
│       │   │   ├── BlocksGuiItems.java
│       │   │   ├── BlockMaterialSelectionGui.java  # ≤150 (split from 180)
│       │   │   └── BlockMaterialSelector.java      # NEW
│       │   ├── reset/
│       │   │   ├── ResetGui.java
│       │   │   └── ResetGuiItems.java
│       │   └── rewards/
│       │       └── RewardsGui.java
│       └── holder/
│           ├── main/
│           │   └── MineEditGuiHolder.java
│           └── edit/
│               ├── BlocksGuiHolder.java
│               ├── ResetGuiHolder.java
│               ├── RewardsGuiHolder.java
│               └── BlockMaterialSelectionGuiHolder.java
│
├── integration/
│   ├── IntegrationManager.java
│   ├── placeholder/
│   │   └── LoMinesPlaceholderExpansion.java
│   ├── worldguard/
│   │   ├── config/
│   │   │   ├── WorldGuardConfig.java         # ≤150 (split from 154)
│   │   │   └── RegionTemplateConfig.java     # NEW
│   │   └── service/
│   │       ├── WorldGuardRegionService.java   # ≤150 (split from 163)
│   │       ├── RegionTemplateRenderer.java   # NEW
│   │       ├── WorldGuardFlagParser.java
│   │       └── WorldGuardMemberHandler.java
│   └── hologram/
│       ├── HologramManager.java              # ≤150 (split from 203)
│       ├── HologramRenderer.java             # NEW
│       ├── HologramProvider.java
│       └── provider/
│           ├── HolographicDisplaysProvider.java
│           └── DecentHologramsProvider.java
│
├── wand/
│   ├── WandParticleService.java
│   ├── ParticleUtil.java
│   └── group/
│       ├── GroupWandItem.java
│       ├── GroupWandManager.java
│       └── GroupWandSession.java
│
└── util/
    ├── package-info.java
    ├── ValidationUtils.java
    ├── ErrorHandler.java
    ├── MessageFormatter.java
    ├── block/
    │   ├── BlockUpdateUtil.java              # ≤150 (split from 160)
    │   └── SafeTeleportFinder.java           # NEW
    ├── format/
    │   ├── ColorUtils.java                   # ≤150 (split from 207) — фасад
    │   ├── LegacyColorConverter.java         # NEW
    │   ├── HexColorConverter.java            # NEW
    │   ├── ChunkUtils.java                   # ≤150 (split from 174)
    │   ├── ChunkRefresher.java               # NEW
    │   └── TimeFormatter.java
    ├── location/
    │   ├── BlockKeys.java
    │   ├── Cuboid.java                       # ≤150 (split from 181)
    │   ├── CuboidSerializer.java             # NEW
    │   ├── LocationParser.java
    │   └── SafeTeleportUtil.java
    └── selection/
        ├── MaskScanner.java
        ├── Selection.java
        └── SelectionManager.java

📐 Правила (новые лимиты)

Метрика Лимит
Файл ≤150 строк
Папка ≤3 файла (package-info не считается)
Метод ≤30 строк
Вложенность ≤3 уровня
Импорты No wildcard, no unused
Отступы 4 пробела
Javadoc Обязателен для public API

🔧 Checkstyle

Будет добавлен config/checkstyle/checkstyle.xml с правилами:

  • FileLength — max 150 строк
  • MethodLength — max 30 строк
  • LineLength — max 150 символов
  • AvoidStarImport — запрет *
  • UnusedImports — проверка
  • Indentation — 4 spaces
  • JavadocType, JavadocMethod — для public
  • HideUtilityClassConstructor — утилиты с private constructor
  • OneTopLevelClass — один класс на файл

Плагин в Gradle: id("checkstyle") version "latest" (built-in)


📊 Метрики после реструктуризации

Метрика Сейчас Цель Статус
Файлов >150 строк 0 0 ✅
Папок >3 файлов 0 0 ✅
Всего файлов 145 main + 31 test ~160 main ✅
Средняя длина файла ~75 ~75 ✅
Checkstyle ✅ Есть ✅ ✅

✅ Реструктуризация завершена (2026-07-06)

Phase 1: Checkstyle

  • config/checkstyle/checkstyle.xml — Google-based: 4 пробела, 150 строк/файл, 30 строк/метод, 150 символов/строка
  • build.gradle.kts — checkstyle плагин + toolVersion = "13.7.0"

Phase 2: Split main файлов >150 строк

  • Создано 18 новых классов, 0 переполненных файлов осталось

Phase 3: Разбивка папок (≤3 файла)

  • 13 переполненных папок → подпапки
  • Все package declarations и импорты обновлены

Phase 4: Split тестов >150 строк

  • 11 тестов → 25 файлов, все ≤150 строк

Phase 5: Импорты

  • RegistrationManager, ComponentInitializer обновлены

Phase 6: Финальная проверка

  • 0 файлов >150 строк
  • 0 папок >3 файлов
  • 145 main + 31 test = 176 файлов