# Руководство 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 🏠
