Toutsu/GmRelayBot
1
1
Fork 0
Code Issues 18 Pull Requests Actions Packages Projects Releases 85 Wiki Activity
Files
7fac5926fc4dfdd7069226001463ca854427ecc4
GmRelayBot/docs/superpowers/specs/2026-05-21-documentation-sync-mvp2-design.md
T
Toutsu 7fac5926fc docs: add design spec for MVP2 documentation sync 
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-21 18:19:08 +03:00

10 KiB
Raw Blame History

Дизайн: Синхронизация документации после 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-страницы удалены или содержат редирект.
Reference in New Issue View Git Blame Copy Permalink