From d9f9d0f0c2b0c326d2e84d385cb700822fc9fb04 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=94=D0=BC=D0=B8=D1=82=D1=80=D0=B8=D0=B9?= Date: Tue, 3 Nov 2026 10:50:11 +0500 Subject: [PATCH] docs: add module catalogue implementation report --- MODULE_CATALOG_IMPLEMENTATION_REPORT.md | 178 ++++++++++++++++++++++++ 1 file changed, 178 insertions(+) create mode 100644 MODULE_CATALOG_IMPLEMENTATION_REPORT.md diff --git a/MODULE_CATALOG_IMPLEMENTATION_REPORT.md b/MODULE_CATALOG_IMPLEMENTATION_REPORT.md new file mode 100644 index 0000000..af6074a --- /dev/null +++ b/MODULE_CATALOG_IMPLEMENTATION_REPORT.md @@ -0,0 +1,178 @@ +# Отчёт об интеграции публичного каталога AzerothCore в Modules V2 + +**Проект:** CoA Server Manager (CSM) +**Ветка:** `preview/modules-v2` +**Рабочая директория:** `C:\games\coa-server-manager-preview` +**Дата реализации:** Ноябрь 2026 г. + +--- + +## 1. Резюме выполненных работ + +В существующую архитектуру системы **Modules V2** успешно интегрирован официальный публичный каталог модулей AzerothCore (`azerothcore.org/data/catalogue.json`). + +Реализация строго следует принципу **непереизобретения колеса**: +- Полностью сохранён существующий конвейер Modules V2: + - GitHub Intake & Source Cache (`analyzer.rs`) + - Compatibility Analyzer (`analyze_github_module_for_realm`) + - Controlled DLL Builder на базе MSVC, CMake, Ninja и `IPlugin` (`build_engine.rs`) + - Transactional Installer (`preview.rs`) + - Plugin Registry & Manifest Storage (`plugins.rs`) + - Server Stop-Gate и SQL Review Gate +- Главное UX-требование выполнено: + - **Группа A (Recommended for CoA)** всегда отображается на самом верху каталога. Все существующие проверенные модули (включая официальные компоненты ядра и динамические DLL) сохранены в полном объёме с их текущими действиями. + - **Группа B (AzerothCore Community Modules)** отображается ниже и предоставляет доступ к 500+ модулям сообщества с информацией о звёздах, форках, тегах, статусе совместимости CoA и кнопкой установки, передающей URL репозитория в готовый конвейер `runAnalysis(url)`. +- Блокировка несовместимых модулей (например, `azerothcore/mod-ahbot`) защищена на трёх уровнях: в UI, в анализаторе AST/исходного кода и в сборочном движке (невозможно обойти даже прямой вставкой URL в инпут). + +--- + +## 2. Архитектура и источники данных + +### 2.1 Источник каталога +В ходе исследования было установлено, что файл `catalogue.json` в репозитории `azerothcore.github.io` является устаревшим статическим срезом (185 модулей). Реальным актуальным источником каталога AzerothCore является: +- **URL:** `https://www.azerothcore.org/data/catalogue.json` +- **Количество модулей:** 545+ репозиториев +- **Периодичность обновления:** каждые 30 минут через GitHub Actions на Cloudflare Pages CDN +- **Машиночитаемый формат:** JSON-объект с полями `categories` и `repos` (`id`, `name`, `owner`, `html_url`, `stargazers_count`, `forks_count`, `topics`, `category`, `license`, `pushed_at`). + +### 2.2 Кэширование, ETag и автономный режим +Реализован движок в `crates/coa-core/src/catalogue.rs`: +1. **HTTP Conditional Requests:** При сетевом запросе отправляется заголовок `If-None-Match: `. При получении ответа `304 Not Modified` парсинг сетевого тела не производится, обновляется лишь метка времени кэша. +2. **TTL (12 часов):** Если локальный файл кэша свежее 12 часов и пользователь не нажал кнопку принудительного обновления, каталог отдаётся из локального дискового кэша мгновенно без блокирующих сетевых задержек. +3. **Атомарная запись:** Сохранение на диск осуществляется через `fsx::atomic_write_json` в `%LOCALAPPDATA%/coa-manager/catalogue/catalogue_cache.json`. +4. **Offline Fallback:** В случае отсутствия интернета, сбоя DNS или недоступности CDN сервер возвращает последнюю сохранённую копию кэша с флагом `is_offline = true`. В интерфейсе появляется информационная плашка с датой кэша и кнопкой повтора. + +### 2.3 Нормализация и дедупликация +Функция `normalize_repo_slug` корректно приводит к единому виду `owner/repo`: +- URL с протоколом: `https://github.com/azerothcore/mod-npc-buffer.git` → `azerothcore/mod-npc-buffer` +- SSH-ссылки: `git@github.com:azerothcore/mod-npc-buffer.git` → `azerothcore/mod-npc-buffer` +- Ссылки на поддиректории: `https://github.com/Corfirean/azerothcore-wotlk-coa/tree/coa-bots/...` + +--- + +## 3. Кураторский оверлей CoA (CoA Modules Overlay) + +В `crates/coa-core/src/coa-modules-overlay.json` создан структурированный оверлей совместимости с ядром Conquest of Azeroth. + +### 3.1 Статусы совместимости +1. `Recommended` — модуль оптимизирован для CoA и проверен на практике. +2. `Verified` — динамический плагин DLL компилируется и функционирует штатно. +3. `RequiresAdapter` — требует генерации адаптера точки входа `IPlugin`. +4. `Unverified` — сторонний модуль сообщества (по умолчанию). +5. `Incompatible` — содержит известные конфликты с механизмами CoA. +6. `Blocked` — модуль категорически запрещён к установке из-за разрушения специфики CoA (например, конфликтующие боты аукциона или параллельные реализации companion AI). + +### 3.2 Защита на уровне движка +В `crates/coa-core/src/analyzer.rs` и `crates/coa-core/src/build_engine.rs` добавлена проверка `catalogue::is_blocked_repo`: +- Анализатор немедленно фиксирует критическое замечание (`CRITICAL`) с причиной блокировки и присваивает статус `SourceIncompatible`. +- Сборочный движок `build_engine::build_module_from_source` прерывает сборку до вызова MSVC/CMake с понятной ошибкой: `Module '...' is blocked for Conquest of Azeroth: ...`. + +--- + +## 4. Tauri IPC и клиентский API + +1. **Команда Tauri (`src-tauri/src/lib.rs`):** + ```rust + #[tauri::command] + async fn get_public_module_catalog( + force_refresh: Option, + ) -> std::result::Result { + let cache_dir = data_dir().join("catalogue"); + let force = force_refresh.unwrap_or(false); + blocking(move || { + coa_core::catalogue::fetch_or_load_catalogue(&cache_dir, force) + }) + .await + } + ``` + Команда зарегистрирована в `invoke_handler!`. + +2. **Клиентский API (`src/lib/api.ts`):** + - Добавлены TypeScript-интерфейсы `PublicCatalogueItem`, `PublicCatalogueResponse`, `CoaCompatibilityStatus`. + - Экспортирован типизированный метод: + ```typescript + getPublicModuleCatalog: (forceRefresh = false) => + invoke("get_public_module_catalog", { forceRefresh }), + ``` + +--- + +## 5. Пользовательский интерфейс (`ModulesPage.tsx`) + +### 5.1 Иерархия отображения +1. **Группа A — Рекомендовано для CoA:** + - 13 модулей `VERIFIED_CATALOG` отображаются в самом начале. + - Имеют золотой бейдж `★ CoA Recommended` / `CoA Verified`. + - Сохраняют все быстрые действия: для официальных — включение/выключение в ядре, для динамических DLL — прямая сборка и установка. +2. **Группа B — Каталог сообщества AzerothCore:** + - Все остальные модули каталога azerothcore.org (за вычетом модулей из группы A во избежание дублирования). + - Информативная карточка: название, автор, описание, звёзды GitHub, форки, категория, лицензия SPDX, теги topics. + - Бейдж статуса CoA (`CoaStatusBadge`): + - `Recommended` (золотой) + - `Verified` (зелёный) + - `RequiresAdapter` (голубой) + - `Community AC` (нейтральный) + - `Incompatible` (янтарный с предупреждением) + - `Blocked` (красный с причиной блокировки) +3. **Действия с модулями сообщества:** + - Для уже установленных: индикатор `✓ Установлен` и кнопка `Настроить`. + - Для заблокированных: заблокированная кнопка `⛔ Заблокирован` с подсказкой причины. + - Для доступных модулей: кнопка `Собрать и установить`, которая устанавливает `githubUrl`, запускает `runAnalysis(url)` и переводит пользователя на контролируемую сборку `startControlledBuild(url)`. + - Кнопка `Подробнее`: открывает модальное окно с полным набором метаданных репозитория, лицензией, веткой, историей обновлений и инженерными комментариями. + +### 5.2 Поиск, фильтры и сортировка +- **Поиск:** фильтрация по названию, репозиторию, автору, описанию и тегам. +- **Фильтры:** + - `Все` (сумма групп A и B) + - `Рекомендовано CoA` + - `Официальные ядра` + - `Проверенные DLL` + - `Сообщество AC` + - `Несовместимые / Блок` +- **Сортировка модулей сообщества:** + - `★ По звёздам` (по умолчанию) + - `🕒 По дате обновления` + - `🔤 По имени (A-Z)` +- **Пагинация (Load More):** отображение порциями по 24 модуля с кнопкой `Показать ещё (+24)` и счётчиком показанных элементов. +- **Счётчик вкладки:** бейдж на вкладке «Каталог модулей» отображает общее число доступных модулей (`publicCatalog.total_count` ~ 545). + +--- + +## 6. Тестирование и верификация + +### 6.1 Модульные тесты бэкенда (`coa-core`) +Успешно пройдены все тесты каталога и смежных подсистем: +- `catalogue::tests::test_slug_normalization` — проверка нормализации URL, SSH-алиасов и суффиксов `.git` +- `catalogue::tests::test_overlay_loading_and_blocked_detection` — корректность загрузки оверлея и выявление блокированных модулей (`azerothcore/mod-ahbot`) +- `catalogue::tests::test_official_json_parsing_and_normalization` — парсинг структуры `catalogue.json` и применение оверлея +- `catalogue::tests::test_disk_caching_and_offline_fallback` — проверка ETag, TTL и возврата из автономного кэша +- `analyzer::tests::*` (17 тестов) — отсутствие регрессий в AST-анализаторе +- `build_engine::tests::test_controlled_build_cohort_t01_t04` и `test_controlled_build_ah_bot` — успешная проверка сборочного движка + +### 6.2 Проверка фронтенда +- `tsc --project tsconfig.json --noEmit` — **0 ошибок, полная типизация**. +- `vite build` — **успешная сборка production-бандла** клиента за 4.12 сек. +- `cargo check` — **чистая компиляция Tauri бэкенда** без предупреждений. + +--- + +## 7. Локальные коммиты в ветке `preview/modules-v2` + +Все изменения закоммичены локально в рабочей ветке `preview/modules-v2` четырьмя атомарными коммитами: + +1. `4e661e6` — `feat(core): implement AzerothCore module catalogue engine, overlay and caching` + - Создан `crates/coa-core/src/catalogue.rs` + - Создан `crates/coa-core/src/coa-modules-overlay.json` + - Зарегистрирован модуль в `crates/coa-core/src/lib.rs` + - Добавлен план интеграции `MODULE_CATALOG_V2_INTEGRATION_PLAN.md` +2. `6bbdef1` — `feat(analyzer): enforce CoA module blocklist in analyzer and build engine` + - Добавлена блокировка в `crates/coa-core/src/analyzer.rs` + - Добавлена проверка безопасности в `crates/coa-core/src/build_engine.rs` +3. `c53fc64` — `feat(ipc): expose public module catalogue Tauri command and API client` + - Зарегистрирована Tauri команда `get_public_module_catalog` в `src-tauri/src/lib.rs` + - Экспортированы типы и API-метод в `src/lib/api.ts` +4. `d0c57f9` — `feat(ui): integrate dual-group public AzerothCore catalogue into ModulesPage` + - Реализованы две группы (Группа A: Рекомендовано для CoA, Группа B: Сообщество AzerothCore) + - Добавлены бейджи статусов, поиск, фильтры, сортировка, пагинация, модальное окно деталей, плашка офлайн-режима и вызов `runAnalysis` + +**Внимание:** В соответствии с инструкцией слияние в `master`, создание PR и push во внешний репозиторий **не выполнялись**. Все изменения готовы к локальному тестированию и ревью.