diff --git a/docs/superpowers/specs/2026-05-21-documentation-sync-mvp2-design.md b/docs/superpowers/specs/2026-05-21-documentation-sync-mvp2-design.md new file mode 100644 index 0000000..99e1ce9 --- /dev/null +++ b/docs/superpowers/specs/2026-05-21-documentation-sync-mvp2-design.md @@ -0,0 +1,166 @@ +# Дизайн: Синхронизация документации после 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-страницы удалены или содержат редирект.