326 lines
10 KiB
Markdown
326 lines
10 KiB
Markdown
# Руководство 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 🏠
|