# Дизайн: Синхронизация документации после MVP2 (Discord + кросс-платформенность) **Дата:** 2026-05-21 **Версия проекта:** v2.7.2 **Статус:** Approved --- ## 1. Цель Привести всю проектную документацию в актуальное состояние после завершения MVP2: - Discord-интеграция (slash-команды, кнопки, RSVP, reschedule voting, DM-уведомления). - Кросс-платформенная архитектура (`IPlatformMessenger`, `SessionBatchViewBuilder`, platform-specific renderers). - Новые env-переменные (`DISCORD_BOT_TOKEN`), healthcheck на 8082, Docker Compose сервис `discord`. - Регрессионные тесты, обновлённый CI/CD. --- ## 2. Аудитории и каналы | Аудитория | Канал | Фокус | |---|---|---| | ГМы и игроки | Gitea Wiki | Как пользоваться ботом: команды, кнопки, уведомления, FAQ | | Разработчики и хостеры | `README.md` + `docs/` | Архитектура, сборка, деплой, env-переменные, ADR | **Принцип:** Wiki — только пользовательская документация. Технические детали (архитектура, БД, разработка) удаляются из Wiki и консолидируются в репозитории. --- ## 3. Wiki (пользовательская документация) ### Новая структура страниц 1. **Home** - Общее описание GM-Relay (Telegram + Discord). - Текущая версия v2.7.2. - Ссылки: Быстрый старт, Руководство ГМа, Руководство игрока. - Убираем: технический стек, ссылки на Архитектуру/БД/Разработка. 2. **Быстрый старт** - Шаг 1: Добавление Telegram-бота в группу. - Шаг 2: Приглашение Discord-приложения на сервер (scopes: bot, applications.commands). - Шаг 3: Создание первой группы (`/newgroup` в Telegram или через Web). - Шаг 4: Создание первого batch (`/newsession`). - Шаг 5: Публикация расписания (`/listsessions`). 3. **Руководство ГМа** - Telegram-команды: `/newgroup`, `/newsession`, `/listsessions`, `/exportcalendar`. - Discord slash-команды: `/newsession`, `/listsessions`. - Создание и управление batch: картинки, повторы, bulk-операции (Web). - Co-GM и делегирование. - Переносы (reschedule): как инициировать голосование, как работает дедлайн. - Шаблоны кампаний. - Статистика посещаемости (Web). - Управление очередью (waitlist, promote). 4. **Руководство игрока** - Telegram: запись через inline-кнопки, отмена. - Discord: кнопки Join/Leave в schedule message, RSVP (Confirm/Decline). - Уведомления: за 24ч, за 1ч, ссылка перед игрой, DM vs группа. - Лист ожидания: как попасть, как автоматически продвинуться. 5. **FAQ / Устранение неполадок** - Бот не отвечает: проверить права, перезапустить. - Кнопки не работают: проверить права Manage Messages / Embed Links. - Mini App не открывается: HTTPS, domain в BotFather. - Discord DM не приходят: privacy settings, бот не может писать first. - Reschedule голосование не завершилось: дедлайн, минимум голосов. ### Удаляемые Wiki-страницы (контент переходит в README/docs) - `Архитектура` → `docs/c4-system-context.md` + `docs/adr/` - `База данных` → `docs/adr/` (описание схемы) - `Разработка` → `README.md` (раздел для контрибьюторов) - `Развёртывание` → `README.md` (Docker Compose quick start) --- ## 4. README.md (разработчики и хостеры) ### Что обновить - **Версия:** с `v2.7.0` → `v2.7.2`. - **Key Features — Discord:** - Slash-команды `/newsession`, `/listsessions`. - Кнопки Join/Leave/RSVP с ephemeral-ответами. - DM-напоминания и ссылки (с fallback-логированием). - Reschedule voting с дедлайном. - Waitlist и auto-promote. - **Технологический стек:** - Добавить NetCord Gateway для Discord. - Уточнить: `GmRelay.DiscordBot` — это NetCord Gateway worker (не отдельный проект в solution, а runtime-роль внутри Bot/Web). - Добавить `IPlatformMessenger` в архитектурное описание. - **Структура репозитория:** - Убрать `GmRelay.DiscordBot` как отдельный проект (согласно CLAUDE.md, его нет; Discord-логика внутри `GmRelay.Bot`). - Добавить `GmRelay.ServiceDefaults`. - **Переменные окружения:** - Добавить `DISCORD_BOT_TOKEN`. - Добавить `DISCORD_BOT_CLIENT_ID` (для регистрации slash-команд). - **Docker Compose:** - Добавить сервис `discord` с healthcheck на `:8082`. - Уточнить multi-arch (AMD64/ARM64 для Raspberry Pi). - **Quick Start:** - Добавить шаг приглашения Discord-бота. - Добавить настройку домена для Mini App. ### Новый раздел (опционально) - **Для разработчиков:** - Краткое описание Vertical Slice + Native AOT. - Ссылка на `docs/adr/0001-...` и `docs/adr/002-...`. - Как добавить handler и зарегистрировать в Program.cs. - Как написать миграцию (DbUp). --- ## 5. `docs/` (архитектурная и техническая документация) ### `docs/c4-system-context.md` - **Level 1 (System Context):** Добавить Discord Gateway and REST API как external system. Добавить игрокам Discord-взаимодействие. - **Level 2 (Container):** Уточнить, что `GmRelay.Bot` содержит **оба** runtime-роли: Telegram long polling **и** Discord Gateway worker (или уточнить, что Discord worker — отдельный контейнер внутри той же сборки). Проверить текущую C4-диаграмму — она уже содержит `discordBot`, так что нужно только убедиться, что он соответствует `GmRelay.Bot` (а не `GmRelay.DiscordBot`). - **Level 3 (Component):** Уже содержит Discord-компоненты. Проверить актуальность: `DiscordSessionInteractionModule`, `DiscordPlatformMessenger`. Добавить `RescheduleVotingFinalizer` (shared). Добавить `DiscordHealthCheckHostedService`. ### `docs/adr/0001-use-vertical-slice-native-aot-and-aspire.md` - Добавить Discord-аспект: NetCord Gateway worker, slash-команды. - Уточнить, что Aspire оркестрирует **три** сервиса: Bot (Telegram + Discord), Web, PostgreSQL. ### `docs/adr/002-platform-neutral-batch-rendering.md` - Уже содержит Discord renderer. Дополнить: - Issue #30 (reschedule voting) использует `IPlatformMessenger`. - Issue #31 (scheduler notifications) тоже использует `IPlatformMessenger`. - Issue #32 (compose wiring) добавил Discord healthcheck. - Issue #33 (регрессионные тесты) покрывает оба renderer'а. ### Новый ADR (опционально, если есть время) - **ADR-003: Discord Integration Architecture** — почему NetCord (а не DSharpPlus), как Gateway events маршрутизируются в vertical slice handlers, как ephemeral-ответы работают. - Это необязательно, но полезно для будущих разработчиков. --- ## 6. Порядок выполнения 1. **Wiki Home** — обновить описание, версию, ссылки. 2. **Wiki Быстрый старт** — переписать с учётом Discord. 3. **Wiki Руководство ГМа** — добавить Discord-команды, reschedule voting, статистику. 4. **Wiki Руководство игрока** — новая страница (или раздел в Руководстве ГМа). 5. **Wiki FAQ** — новая страница. 6. **README.md** — версия, features, env, Docker, quick start. 7. **`docs/c4-system-context.md`** — Discord-компоненты, healthcheck. 8. **`docs/adr/0001-...`** — Discord-аспекты. 9. **Удалить устаревшие Wiki-страницы** (Архитектура, База данных, Разработка, Развёртывание) или заменить их редиректами на README. --- ## 7. Критерии готовности - [ ] Все wiki-страницы отражают текущую версию v2.7.2. - [ ] Все Discord-фичи задокументированы для пользователей. - [ ] README содержит актуальную версию, env-переменные, структуру репозитория. - [ ] C4-диаграмма и ADR'ы отражают Discord-архитектуру и `IPlatformMessenger`. - [ ] Нет противоречий между Wiki и README (например, версия, команды). - [ ] Устаревшие wiki-страницы удалены или содержат редирект.