Avoid loading poll responses in list endpoint

docs/web-admin-integration.md

@@ -135,6 +135,12 @@ curl -X POST "http://127.0.0.1:8080/tokens" \
 | `PATCH` | `/promo-offers/templates/{id}` | Обновить текст, кнопки и параметры шаблона.
 | `GET` | `/promo-offers/logs` | Журнал операций с промо-предложениями (активации, списания, выключения).
 | `GET` | `/tokens` | Управление токенами доступа.
+| `GET` | `/polls` | Список опросов с постраничной навигацией.
+| `GET` | `/polls/{id}` | Детали опроса с вопросами и вариантами ответов.
+| `POST` | `/polls` | Создать опрос: заголовок, описание, вопросы и варианты.
+| `DELETE` | `/polls/{id}` | Удалить опрос целиком.
+| `GET` | `/polls/{id}/stats` | Сводная статистика по ответам и начисленным наградам.
+| `GET` | `/polls/{id}/responses` | Ответы пользователей с детализацией по вопросам.
 | `GET` | `/logs/monitoring` | Логи мониторинга бота с пагинацией и фильтрами по типу события.
 | `GET` | `/logs/monitoring/event-types` | Справочник доступных типов событий мониторинга.
 | `GET` | `/logs/support` | Журнал действий модераторов поддержки (блокировки, закрытия тикетов).
@@ -158,6 +164,65 @@ curl -X POST "http://127.0.0.1:8080/tokens" \
 
 Все эндпоинты защищены токеном API и возвращают структуру с общим количеством записей, текущим `limit`/`offset` и массивом объектов. Это упрощает реализацию таблиц и постраничной навигации во внешних административных интерфейсах.
 
+### Управление опросами
+
+Раздел **polls** в административном API позволяет создавать и анализировать опросы, которые бот рассылает пользователям.
+
+#### Список и детали
+
+- `GET /polls` — возвращает массив объектов с базовой информацией: название, описание, флаги награды, количество вопросов и ответов.
+- `GET /polls/{id}` — раскрывает структуру конкретного опроса, включая упорядоченные вопросы и варианты ответов. Подходит для предпросмотра перед публикацией.
+
+#### Создание опроса
+
+Для создания опроса отправьте JSON, соответствующий схеме:
+
+```json
+{
+  "title": "Оценка нового тарифа",
+  "description": "Помогите улучшить продукт — ответ займет до 2 минут",
+  "reward_enabled": true,
+  "reward_amount_kopeks": 1000,
+  "questions": [
+    {
+      "text": "Насколько вы довольны скоростью соединения?",
+      "options": [
+        { "text": "Очень доволен" },
+        { "text": "Скорее доволен" },
+        { "text": "Нейтрально" },
+        { "text": "Скорее недоволен" },
+        { "text": "Очень недоволен" }
+      ]
+    },
+    {
+      "text": "Какие улучшения вы ждёте?",
+      "options": [
+        { "text": "Стабильность" },
+        { "text": "Скорость" },
+        { "text": "Поддержка" }
+      ]
+    }
+  ]
+}
+```
+
+Требования валидации:
+
+- Заголовок (`title`) — от 1 до 255 символов, не пустой после обрезки пробелов.
+- Описание (`description`) — до 4000 символов, пробелы по краям удаляются.
+- Если `reward_enabled=true`, сумма вознаграждения (`reward_amount_kopeks`) должна быть положительной. При `false` значение автоматически сбрасывается в `0`.
+- Каждый вопрос содержит минимум два уникальных варианта ответа.
+
+В ответ API вернёт созданный опрос с назначенными идентификаторами и полем `reward_amount_rubles`, которое удобно показывать в интерфейсе.
+
+#### Удаление и статистика
+
+- `DELETE /polls/{id}` — удаляет опрос и связанные с ним вопросы/ответы. Используйте с осторожностью, операция необратима.
+- `GET /polls/{id}/stats` — агрегированная статистика: общее количество ответов, завершённых прохождений и сумма выданных наград. Для каждого вопроса возвращается количество выборов по вариантам.
+- `GET /polls/{id}/responses` — список ответов пользователей с пагинацией (`limit`, `offset`). Каждый элемент содержит временные метки (`sent_at`, `started_at`, `completed_at`), данные пользователя (ID, username, Telegram ID), информацию о выданной награде и массив ответов с текстами вопросов/вариантов.
+
+Такой формат позволяет без дополнительного запроса показать детализацию на фронтенде или выгрузить данные в CSV.
+
 ### RemnaWave интеграция
 
 После включения веб-API в Swagger (`WEB_API_DOCS_ENABLED=true`) появится раздел **remnawave**. Он объединяет эндпоинты для управления панелью RemnaWave и синхронизации данных бота: