10 KiB
10 KiB
Руководство V3.1 - Умные рассылки и Еженедельные дайджесты
Дата: 6 апреля 2026 г.
Версия: 3.1
Статус: ✅ Готово к использованию
📢 Умные рассылки с отслеживанием прочтения
Что это?
Обычная рассылка, но с возможностью отслеживать кто прочитал сообщение. Каждый получатель видит кнопку "✅ Прочитал", а админ видит статистику в реальном времени.
Как использовать
Из Telegram (для админа)
Быстрая рассылка:
/broadcast_quick <текст сообщения>
Пошаговое создание:
/broadcast
- Бот попросит ввести текст
- Выберете получателей (чат, все верифицированные, ИГ)
- Подтвердите отправку
Просмотр статистики:
/broadcast_stats
Из веб-панели
Откройте: http://localhost:8000/broadcasts
Возможности:
- 📊 Статистика всех рассылок
- 👥 Посмотреть кто прочитал
- ⚠️ Посмотреть кто НЕ прочитал
- 📬 Отправить напоминание непрочитавшим
- 📈 Процент прочтений с прогресс-баром
Как работает
- Вы создаёте рассылку
- Бот отправляет сообщение с кнопкой "✅ Прочитал"
- Жилец нажимает кнопку
- В БД сохраняется: user_id + broadcast_id + timestamp
- В веб-панели вы видите:
- Сколько прочитали (в абсолютных числах и %)
- Кто конкретно прочитал
- Кто НЕ прочитал
- Можно отправить напоминание только непрочитавшим
Пример
📢 Объявление от администрации
Завтра отключение горячей воды с 10:00 до 18:00!
[✅ Прочитал]
Статистика в веб-панели:
Рассылка #42
Отправлено: 245 жильцам
Прочитали: 187 (76.3%)
Не прочитали: 58
[👥 Кто прочитал] [⚠️ Кто НЕ прочитал] [📬 Напоминание]
📰 Еженедельный дайджест
Что это?
Автоматически сгенерированный отчёт за неделю со всей важной информацией:
- События
- Опросы
- Объявления
- Топ активных жильцов
- Запланированные отключения
- Статистика чата
Автоматический процесс
Воскресенье 09:00:
- Бот собирает данные за неделю
- Генерирует дайджест
- Сохраняет в БД со статусом
pending_approval - Отправляет админу превью в Telegram
Утверждение
Из Telegram
Админ получает сообщение:
📰 Дайджест за неделю готов!
Неделя #14/2026
Период: 30.03 - 05.04.2026
[🌐 Утвердить в веб-панели]
Из веб-панели
Откройте: http://localhost:8000/digests
Возможности:
- 👁️ Просмотреть текст дайджеста
- ✅ Утвердить
- ✏️ Редактировать текст
- ❌ Отклонить с указанием причины
- 📨 Отправить утверждённый дайджест
- 📚 Архив всех дайджестов
Содержимое дайджеста
Автоматически собирается:
- 🔔 События - все события за неделю
- 📊 Опросы - активные и завершённые
- 📢 Объявления - количество новых и активных
- 🏆 Топ-5 жильцов - по активности в чате
- ⏰ Отключения - на следующую неделю
- ✅ Верификации - сколько новых верифицировано
- 📈 Статистика - сообщения, активные пользователи
Пример дайджеста
📰 ДАЙДЖЕСТ ДОМА ЗА НЕДЕЛЮ
🗓 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 | Собирает данные, сохраняет, уведомляет админа |
📋 План внедрения
✅ Реализовано
- Модели БД
- Миграция
- Обработчики умной рассылки
- Обработчики дайджеста
- Сервис генерации дайджеста
- APScheduler задача
- Веб-панель рассылок
- Веб-панель дайджестов
- Документация
🔜 В следующем релизе
- Кнопка "Прочитал" с правильной идентификацией рассылки
- Настройки дайджеста (что включать/исключать)
- Экспорт дайджестов в PDF
- Генерация квартального/годового дайджеста
- A/B тестирование текстов рассылок
- Лучшее время для отправки (аналитика)
🎯 Быстрый старт
1. Проверить миграцию
cd /home/matrixhasyou/domovoy_bot
source venv/bin/activate
python database/migrate_v3_1_smart_broadcasts.py
2. Перезапустить бота
sudo systemctl restart domovoy-bot
3. Протестировать рассылку
/broadcast_quick Тестовая рассылка V3.1
4. Открыть веб-панель
http://localhost:8000/broadcasts
http://localhost:8000/digests
5. Сгенерировать тестовый дайджест
/digest
🐛 Известные особенности
- Кнопка "Прочитал" - пока не идентифицирует конкретную рассылку (будет улучшено)
- Настройки дайджеста - страница есть, но функционал в разработке
- Экспорт дайджестов - планируется в V3.2
📞 Поддержка
При возникновении проблем:
- Проверьте логи бота:
journalctl -u domovoy-bot -f - Проверьте БД: таблицы
broadcasts,broadcast_reads,digests - Откройте issue в Gitea
Версия: V3.1
Дата выхода: 6 апреля 2026 г.
Автор: Домовой Бот Team 🏠