Refactor/modules

docs/modules/events.md

@@ -1,3 +1,155 @@
 # Events
 
-TODO
+## Назначение
+
+Events отвечает за отложенную функциональность мероприятий Procollab. Модуль
+сохраняет модели, admin-управление, связанный список мероприятий пользователя и
+опциональную служебную автопубликацию в Telegram, но публичные endpoints
+`/events/` сейчас не подключены в корневом URLConf.
+
+## Статус модуля
+
+Модуль разрабатывался под задачу, которая перестала быть актуальной в процессе
+работы. Сейчас он не является активным продуктовым направлением. Чтобы
+неиспользуемые ручки не торчали наружу и не попадали в Swagger, `events.urls`
+не подключается в `procollab/urls.py`.
+
+Часть возможностей заложена в модели, но не имеет публичных endpoints. Это
+технический долг, который нужно решать только при возвращении мероприятий в
+активную продуктовую работу.
+
+Текущие тесты покрывают отключение публичных `/events/` endpoints, связанный
+endpoint пользователя, модель лайков, Telegram helpers и autoposting signal.
+
+## Основные возможности
+
+- хранение мероприятий в базе;
+- управление мероприятиями через Django admin;
+- хранение тегов мероприятия через `django-taggit`;
+- хранение зарегистрированных пользователей мероприятия;
+- получение списка мероприятий текущего пользователя через users endpoint;
+- опциональная автопубликация мероприятия в Telegram при настроенных
+  `AUTOPOSTING_ON`, `TELEGRAM_BOT_TOKEN` и `TELEGRAM_CHANNEL`.
+
+Заложено в модели, но сейчас не имеет отдельного публичного API:
+
+- список мероприятий;
+- карточка мероприятия;
+- создание, обновление и удаление мероприятия через `/events/`;
+- фильтрация мероприятий;
+- список зарегистрированных пользователей мероприятия;
+- список типов мероприятий;
+- избранное через `favorites`;
+- просмотры через `views`;
+- лайки через `LikesOnEvent`;
+- регистрация/отмена регистрации пользователя на мероприятие.
+
+## Архитектура
+
+- `events/models.py` - модели `Event` и `LikesOnEvent`.
+- `events/views.py` - неактивные HTTP endpoints для списка, деталей,
+  зарегистрированных пользователей и типов мероприятий.
+- `events/serializers.py` - request/response serializers для списка, деталей и
+  зарегистрированных пользователей.
+- `events/filters.py` - фильтры списка мероприятий.
+- `events/managers.py` - manager для лайков мероприятий.
+- `events/helpers.py` - низкоуровневые вызовы Telegram API.
+- `events/signals.py` - autoposting signal для Telegram.
+- `events/admin.py` - настройка Django admin.
+- `events/tests/` - regression-тесты отключенных публичных URL, связанного users
+  endpoint, модели лайков и Telegram-интеграции.
+
+## Основные сущности
+
+- `Event` - мероприятие.
+- `LikesOnEvent` - лайк мероприятия пользователем.
+- `favorites` - пользователи, добавившие мероприятие в избранное.
+- `registered_users` - пользователи, зарегистрированные на мероприятие.
+- `tags` - теги мероприятия.
+- `tg_message_id` - ID сообщения в Telegram для дальнейшего редактирования.
+
+## API
+
+Публичные endpoints модуля Events сейчас отключены на уровне
+`procollab/urls.py`. Эти URLs не должны быть доступны извне:
+
+- `/events/`;
+- `/events/<id>/`;
+- `/events/<id>/registered/`;
+- `/events/types/`.
+
+Активный связанный endpoint:
+
+- `GET /auth/users/current/events/` - мероприятия, на которые зарегистрирован
+  текущий пользователь.
+
+## Основные сценарии
+
+### 1. Управление мероприятиями
+
+Пока публичный API отключен, создание, обновление и удаление мероприятий
+остаются admin-сценарием.
+
+При создании и обновлении используются поля:
+
+- название;
+- полный текст;
+- короткое описание;
+- обложка;
+- дата проведения;
+- тип мероприятия;
+- сайт организатора;
+- награда;
+- теги;
+- избранное.
+
+### 2. Зарегистрированные пользователи
+
+Связь пользователей с мероприятием хранится в `Event.registered_users`.
+
+Для текущего пользователя список его мероприятий доступен через
+`/auth/users/current/events/`.
+
+### 3. Лайки, избранное и регистрация
+
+Модель поддерживает:
+
+- `favorites` как M2M между мероприятием и пользователем;
+- `LikesOnEvent` как отдельную модель лайка с флагом `is_liked`.
+
+Отдельных публичных endpoints для toggle-like, favorite или регистрации на
+мероприятие в `events/urls.py` сейчас нет.
+
+### 4. Telegram autoposting
+
+Если `AUTOPOSTING_ON = True`, при сохранении `Event` импортируются signals и
+срабатывает автопубликация:
+
+- при создании отправляется новое сообщение в Telegram;
+- при обновлении редактируется существующее сообщение по `tg_message_id`.
+
+В обычном локальном и тестовом режиме `AUTOPOSTING_ON` по умолчанию выключен,
+поэтому внешние HTTP-запросы в Telegram не выполняются.
+
+## Ограничения и правила
+
+- `/events/` endpoints не подключены в корневом URLConf.
+- `text`, `cover_url` и `datetime_of_event` обязательны при создании
+  мероприятия.
+- `short_text` ограничен 256 символами.
+- `tg_message_id` не редактируется вручную через API.
+- Telegram autoposting зависит от `AUTOPOSTING_ON`, `TELEGRAM_BOT_TOKEN` и
+  `TELEGRAM_CHANNEL`.
+- Интеграция с Telegram не должна выполняться без явно настроенных переменных
+  окружения.
+
+## Тесты
+
+Текущие тесты лежат в `events/tests/`.
+
+Они проверяют:
+
+- недоступность публичных `/events/` URLs;
+- `LikesOnEventManager`;
+- `/auth/users/current/events/`;
+- Telegram helpers и autoposting signal.