167 lines
10 KiB
Markdown
167 lines
10 KiB
Markdown
# Дизайн: Синхронизация документации после 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-страницы удалены или содержат редирект.
|