Create wiki page 'Development'

2026-04-24 10:58:53 +03:00
parent 70f0c65bff
commit a61575e00e
1 changed files with 104 additions and 0 deletions
@@ -0,0 +1,104 @@
+# Development
+
+Эта страница фиксирует текущие правила разработки GM-Relay.
+
+## Решение и проекты
+
+Работа ведётся из корня репозитория `D:\Projects\Game`.
+
+Основные проекты:
+
+- `src/GmRelay.AppHost` — Aspire orchestration.
+- `src/GmRelay.Bot` — Telegram worker.
+- `src/GmRelay.Web` — Blazor Server UI.
+- `src/GmRelay.Shared` — shared domain/rendering.
+- `src/GmRelay.ServiceDefaults` — shared Aspire defaults.
+- `tests/GmRelay.Bot.Tests` — xUnit-тесты.
+
+## Базовые команды
+
+```bash
+dotnet restore GM-Relay.slnx
+dotnet build GM-Relay.slnx -c Release
+dotnet test tests/GmRelay.Bot.Tests/GmRelay.Bot.Tests.csproj --collect:"XPlat Code Coverage"
+dotnet run --project src/GmRelay.AppHost
+```
+
+`Directory.Build.props` задаёт:
+
+- `Version`: `1.1.5`.
+- `TargetFramework`: `net10.0`.
+- `LangVersion`: `preview`.
+- `Nullable`: `enable`.
+- `ImplicitUsings`: `enable`.
+- `TreatWarningsAsErrors`: `true`.
+
+## Добавление bot-фичи
+
+Новая логика бота должна попадать в существующие vertical slices под `src/GmRelay.Bot/Features/*`.
+
+Обычный порядок:
+
+1. Создать handler или rules-класс рядом с соответствующей фичей.
+2. Если нужен новый Telegram callback или command, явно добавить маршрут в `Infrastructure/Telegram/UpdateRouter.cs`.
+3. Зарегистрировать handler в `src/GmRelay.Bot/Program.cs`.
+4. Для SQL-маппинга использовать явные DTO/record-типы, совместимые с Dapper.AOT.
+5. Добавить тесты в зеркальный путь внутри `tests/GmRelay.Bot.Tests/Features/*`.
+
+Assembly scanning и reflection-регистрация не используются, чтобы сохранять Native AOT совместимость.
+
+## Миграции
+
+SQL-миграции лежат в `src/GmRelay.Bot/Migrations` и встраиваются в bot assembly как embedded resources.
+
+Формат имени:
+
+```text
+V###__description.sql
+```
+
+Пример:
+
+```text
+V006__add_example_column.sql
+```
+
+Миграции применяются при старте бота через `DbMigrator` и DbUp.
+
+## Тесты
+
+Текущий набор тестов покрывает:
+
+- domain/status helpers;
+- parser `/newsession`;
+- RSVP flow rules;
+- reschedule time input и vote rules;
+- rendering batch-сообщений;
+- Telegram polling service behavior;
+- secret redaction;
+- Telegram auth в web;
+- authorization для web-сессий.
+
+Новые тесты стоит класть рядом с feature area, например:
+
+```text
+tests/GmRelay.Bot.Tests/Features/Sessions/CreateSession/NewSessionCommandParserTests.cs
+```
+
+## Web-разработка
+
+Blazor-компоненты находятся в `src/GmRelay.Web/Components`:
+
+- `Pages` — страницы `/`, `/login`, `/group/{id}`, `/session/edit/{id}` и служебные страницы.
+- `Layout` — layout, navigation, reconnect modal.
+
+Сервисный слой web-панели находится в `src/GmRelay.Web/Services`.
+
+Web-доступ должен проходить через `AuthorizedSessionService`, чтобы пользователь не мог читать или менять чужие группы и сессии.
+
+## Практические ограничения
+
+- Не хранить секреты в appsettings или wiki. Использовать `.env`, environment variables или user secrets.
+- Не добавлять dynamic SQL-mapping без DTO: это ломает предсказуемость Dapper.AOT.
+- Любое изменение статусов должно быть согласовано с `SessionStatus`, миграциями и renderer/UI.
+- Если web меняет данные сессии, нужно учитывать синхронизацию Telegram-сообщения через `SessionBatchRenderer`.