# Руководство V3.1 - Умные рассылки и Еженедельные дайджесты > Дата: 6 апреля 2026 г. > Версия: 3.1 > Статус: ✅ Готово к использованию --- ## 📢 Умные рассылки с отслеживанием прочтения ### Что это? Обычная рассылка, но с возможностью **отслеживать кто прочитал** сообщение. Каждый получатель видит кнопку "✅ Прочитал", а админ видит статистику в реальном времени. ### Как использовать #### Из Telegram (для админа) **Быстрая рассылка:** ``` /broadcast_quick <текст сообщения> ``` **Пошаговое создание:** ``` /broadcast ``` 1. Бот попросит ввести текст 2. Выберете получателей (чат, все верифицированные, ИГ) 3. Подтвердите отправку **Просмотр статистики:** ``` /broadcast_stats ``` #### Из веб-панели Откройте: `http://localhost:8000/broadcasts` **Возможности:** - 📊 Статистика всех рассылок - 👥 Посмотреть кто прочитал - ⚠️ Посмотреть кто НЕ прочитал - 📬 Отправить напоминание непрочитавшим - 📈 Процент прочтений с прогресс-баром ### Как работает 1. Вы создаёте рассылку 2. Бот отправляет сообщение с кнопкой "✅ Прочитал" 3. Жилец нажимает кнопку 4. В БД сохраняется: user_id + broadcast_id + timestamp 5. В веб-панели вы видите: - Сколько прочитали (в абсолютных числах и %) - Кто конкретно прочитал - Кто НЕ прочитал - Можно отправить напоминание только непрочитавшим ### Пример ``` 📢 Объявление от администрации Завтра отключение горячей воды с 10:00 до 18:00! [✅ Прочитал] ``` **Статистика в веб-панели:** ``` Рассылка #42 Отправлено: 245 жильцам Прочитали: 187 (76.3%) Не прочитали: 58 [👥 Кто прочитал] [⚠️ Кто НЕ прочитал] [📬 Напоминание] ``` --- ## 📰 Еженедельный дайджест ### Что это? Автоматически сгенерированный отчёт за неделю со всей важной информацией: - События - Опросы - Объявления - Топ активных жильцов - Запланированные отключения - Статистика чата ### Автоматический процесс **Воскресенье 09:00:** 1. Бот собирает данные за неделю 2. Генерирует дайджест 3. Сохраняет в БД со статусом `pending_approval` 4. Отправляет админу превью в Telegram ### Утверждение #### Из Telegram Админ получает сообщение: ``` 📰 Дайджест за неделю готов! Неделя #14/2026 Период: 30.03 - 05.04.2026 [🌐 Утвердить в веб-панели] ``` #### Из веб-панели Откройте: `http://localhost:8000/digests` **Возможности:** - 👁️ Просмотреть текст дайджеста - ✅ Утвердить - ✏️ Редактировать текст - ❌ Отклонить с указанием причины - 📨 Отправить утверждённый дайджест - 📚 Архив всех дайджестов ### Содержимое дайджеста **Автоматически собирается:** 1. **🔔 События** - все события за неделю 2. **📊 Опросы** - активные и завершённые 3. **📢 Объявления** - количество новых и активных 4. **🏆 Топ-5 жильцов** - по активности в чате 5. **⏰ Отключения** - на следующую неделю 6. **✅ Верификации** - сколько новых верифицировано 7. **📈 Статистика** - сообщения, активные пользователи ### Пример дайджеста ``` 📰 ДАЙДЖЕСТ ДОМА ЗА НЕДЕЛЮ 🗓 30.03 - 05.04.2026 🔔 События: • Субботник 5 апреля — осталось 15 мест • Собрание жильцов 8 апреля в 19:00 📊 Опросы: • "Цвет фасада" — 89 голосов (✅ активен) • "Время уборки" — 156 голосов (🔴 завершён) 📢 Объявления: 12 новых Всего активных: 45 🏆 Активные жильцы: 🥇 Иванов Иван (кв. 42) — 87 сообщ. 🥈 Петрова Мария (кв. 15) — 65 сообщ. 🥉 Сидоров Алексей (кв. 78) — 54 сообщ. ⏰ На следующей неделе: 💧 Отключение ГВС — 07.04 10:00 до 18:00 ✅ Верификации: • Новых за неделю: 8 • Всего верифицировано: 237 📈 Статистика: • Сообщений в чате: 456 • Активных жильцов: 89 ``` ### Архив дайджестов Все дайджесты сохраняются в БД. Можно посмотреть: - Дайджест за любую неделю - Статус (отправлен/отклонён) - Кто утвердил - Когда отправлен **Команды для будущего:** ``` /digest_archive месяц # Дайджесты за месяц /digest_archive год # Дайджесты за год /digest_export # Экспорт всех дайджестов ``` --- ## 🔧 Технические детали ### Новые таблицы БД **broadcasts** - умные рассылки - id, message_id, text, photo_file_id - sent_at, sent_by, total_sent - has_read_button, is_reminder_sent - broadcast_type (manual, digest, emergency) **broadcast_reads** - кто прочитал - id, broadcast_id, user_id, read_at **digests** - еженедельные дайджесты - id, period_start, period_end - week_number, year, content (JSON) - digest_text, status - approved_at, approved_by, sent_at - rejection_reason ### Команды Telegram | Команда | Описание | |---------|----------| | `/broadcast` | Создать рассылку (пошагово) | | `/broadcast_quick <текст>` | Быстрая рассылка | | `/broadcast_stats` | Статистика рассылок | | `/digest` | Сгенерировать дайджест вручную | ### Веб-эндпоинты | URL | Описание | |-----|----------| | `/broadcasts` | Страница рассылок | | `/api/broadcast/readers/{id}` | Кто прочитал | | `/api/broadcast/non_readers/{id}` | Кто НЕ прочитал | | `/api/broadcast/send_reminder/{id}` | Отправить напоминание | | `/digests` | Страница дайджестов | | `/api/digest/{id}/approve` | Утвердить дайджест | | `/api/digest/{id}/reject` | Отклонить дайджест | | `/api/digest/{id}/send` | Отправить дайджест | | `/api/digest/{id}/update_text` | Редактировать текст | | `/digest_settings` | Настройки дайджеста | ### Расписание **Автоматические задачи:** | Задача | Когда | Что делает | |--------|-------|------------| | Генерация дайджеста | Воскресенье 09:00 | Собирает данные, сохраняет, уведомляет админа | --- ## 📋 План внедрения ### ✅ Реализовано - [x] Модели БД - [x] Миграция - [x] Обработчики умной рассылки - [x] Обработчики дайджеста - [x] Сервис генерации дайджеста - [x] APScheduler задача - [x] Веб-панель рассылок - [x] Веб-панель дайджестов - [x] Документация ### 🔜 В следующем релизе - [ ] Кнопка "Прочитал" с правильной идентификацией рассылки - [ ] Настройки дайджеста (что включать/исключать) - [ ] Экспорт дайджестов в PDF - [ ] Генерация квартального/годового дайджеста - [ ] A/B тестирование текстов рассылок - [ ] Лучшее время для отправки (аналитика) --- ## 🎯 Быстрый старт ### 1. Проверить миграцию ```bash cd /home/matrixhasyou/domovoy_bot source venv/bin/activate python database/migrate_v3_1_smart_broadcasts.py ``` ### 2. Перезапустить бота ```bash sudo systemctl restart domovoy-bot ``` ### 3. Протестировать рассылку ``` /broadcast_quick Тестовая рассылка V3.1 ``` ### 4. Открыть веб-панель ``` http://localhost:8000/broadcasts http://localhost:8000/digests ``` ### 5. Сгенерировать тестовый дайджест ``` /digest ``` --- ## 🐛 Известные особенности 1. **Кнопка "Прочитал"** - пока не идентифицирует конкретную рассылку (будет улучшено) 2. **Настройки дайджеста** - страница есть, но функционал в разработке 3. **Экспорт дайджестов** - планируется в V3.2 --- ## 📞 Поддержка При возникновении проблем: 1. Проверьте логи бота: `journalctl -u domovoy-bot -f` 2. Проверьте БД: таблицы `broadcasts`, `broadcast_reads`, `digests` 3. Откройте issue в Gitea --- **Версия:** V3.1 **Дата выхода:** 6 апреля 2026 г. **Автор:** Домовой Бот Team 🏠