domovoy_bot/СПЕЦИФИКАЦИЯ_V3.1_УМНАЯ_РАССЫЛКА_ДАЙДЖЕСТ.md

Спецификация V3.1 - Умная рассылка + Еженедельный дайджест

Дата: 6 апреля 2026 г.
Статус: В разработке
Версия: 3.1

---

📢 Умная рассылка с прочтением

Архитектура

Новые таблицы БД:

• broadcast — рассылки

  • id (PK)
  • message_id (Telegram message ID)
  • chat_id
  • text (текст рассылки)
  • photo_file_id (опционально)
  • sent_at (timestamp)
  • sent_by (admin user ID)
  • total_sent (количество получателей)
  • has_read_button (boolean — показывать ли кнопку "Прочитал")
  • is_reminder_sent (было ли напоминание)
  • created_at

• broadcast_read — кто прочитал

  • id (PK)
  • broadcast_id (FK → broadcast)
  • user_id (FK → users)
  • read_at (timestamp)

Функционал

В Telegram:

• Рассылка с inline-кнопкой "✅ Прочитал"
• При нажатии — обновляется статус в БД
• Кнопка меняется на "✅ Прочитано" (неактивная)

В веб-панели:

• Список всех рассылок
• Статистика: отправлено / прочитано / не прочитано
• Кнопка "Показать кто прочитал"
• Кнопка "Показать кто НЕ прочитал"
• Кнопка "⚠️ Отправить напоминание непрочитавшим"
• Создание новой рассылки с опцией "Добавить кнопку прочтения"

Команды

• /broadcast — создать рассылку (админ)
• /broadcast_stats <id> — статистика по рассылке

---

📰 Еженедельный дайджест

Архитектура

Новые таблицы БД:

• digest — дайджесты
  • id (PK)
  • period_start (начало периода, дата)
  • period_end (конец периода, дата)
  • week_number (номер недели)
  • year (год)
  • content (JSON с данными дайджеста)
  • status — 'draft' | 'pending_approval' | 'approved' | 'rejected' | 'sent'
  • message_id (ID сообщения в Telegram, если отправлен)
  • created_at (автогенерация)
  • approved_at
  • approved_by (admin ID)
  • sent_at
  • rejected_by
  • rejection_reason (причина отклонения)

Генерация контента

Автоматический сбор данных (воскресенье 09:00):

1. События за неделю (из таблицы events)
2. Активные опросы (из polls)
3. Новые объявления (из ads)
4. Топ-5 активных жильцов (из users по rating)
5. Запланированные отключения (из schedule на следующую неделю)
6. Новые верификации (из verification_requests)
7. Статистика: всего сообщений, активных пользователей

Формирование текста:

digest_text = f"""
📰 ДАЙДЖЕСТ ДОМА ЗА НЕДЕЛЮ ({period_start} - {period_end})

🔔 События:
{events_list}

📊 Опросы:
{polls_list}

📢 Объявления: {ads_count} новых

🏆 Активные жильцы:
{top_users}

⏰ На следующей неделе:
{schedule_list}

📈 Статистика:
• Сообщений в чате: {messages_count}
• Активных жильцов: {active_users}
• Новых верификаций: {new_verifications}
"""

Процесс утверждения

Автоматический workflow:

1. Воскресенье 09:00 — бот генерирует дайджест

2. Сохраняет в БД со статусом pending_approval

3. Отправляет АДМИНУ в личку превью дайджеста:

   📰 Дайджест за неделю готов!
   
   [Просмотреть в веб-панели]
   
   Статус: ⏳ Ожидает утверждения
   

4. Админ заходит в веб-панель, видит:

   ┌─────────────────────────────────────┐
   │ 📰 Дайджест за 30.03 - 06.04       │
   │ Статус: ⏳ Ожидает утверждения      │
   ├─────────────────────────────────────┤
   │ [Предпросмотр текста]               │
   │                                     │
   │ [✅ Утвердить и отправить]          │
   │ [❌ Отклонить]                      │
   │ [✏️ Редактировать текст]            │
   └─────────────────────────────────────┘
   

5. Если утвердил:

   • Статус → approved → sent
   • Бот рассылает ВСЕМ верифицированным жильцам
   • В веб-панели: "✅ Отправлен в 14:32"
   • В чат (опционально): "📰 Дайджест за неделю опубликован!"

6. Если отклонил:

   • Статус → rejected
   • Можно указать причину
   • В БД сохраняется (история)

Хранение и архив

В веб-панели раздел "Архив дайджестов":

📰 Архив дайджестов

Фильтры: [За неделю] [За месяц] [За квартал] [За год] [Все]

┌──────┬──────────────┬──────────┬────────────┐
│ Нед  │ Период       │ Статус   │ Отправлен  │
├──────┼──────────────┼──────────┼────────────┤
│ #14  │ 30.03-06.04  │ ✅ Отпр  │ 06.04 14:32│
│ #13  │ 23.03-29.03  │ ✅ Отпр  │ 29.03 10:15│
│ #12  │ 16.03-22.03  │ ❌ Откл  │ -          │
│ ...  │ ...          │ ...      │ ...        │
└──────┴──────────────┴──────────┴────────────┘

[Экспорт в PDF] [Экспорт в CSV]

Генерация дайджеста за период:

• Квартальный: сумма недельных дайджестов
• Полугодовой: агрегация
• Годовой: полная статистика + тренды

Настройки в веб-панели

⚙️ Настройки дайджеста

[✓] Включить автоматическую генерацию
День недели: [Воскресенье ▼]
Время генерации: [09:00]
Время отправки (после утверждения): [10:00]

Содержимое:
[✓] События
[✓] Опросы
[✓] Объявления
[✓] Топ активных жильцов
[✓] Запланированные отключения
[✓] Статистика чата
[✓] Новые верификации

Дополнительно:
[✓] Отправлять превью админу
[ ] Публиковать автоматически (без утверждения)
[✓] Сохранять в архив

---

План реализации

Этап 1: База данных

• Модель Broadcast
• Модель BroadcastRead
• Модель Digest
• Миграция БД

Этап 2: Умная рассылка

• Handler /broadcast
• Inline кнопки "Прочитал"
• Callback обработчики
• Веб-панель: список рассылок
• Веб-панель: статистика
• Веб-панель: создание рассылки
• Напоминания непрочитавшим

Этап 3: Дайджест

• Сервис генерации контента
• APScheduler задача (воскресенье 09:00)
• Уведомление админу
• Веб-панель: утверждение/отклонение
• Веб-панель: редактирование текста
• Веб-панель: архив дайджестов
• Рассылка после утверждения
• Настройки дайджеста

Этап 4: Интеграция

• Обновить веб-сервер (новые роуты)
• Обновить меню админа
• Документация

---

Технические детали

Используемые технологии

• SQLAlchemy модели (async)
• aiogram inline keyboards
• APScheduler (cron trigger)
• FastAPI endpoints
• Jinja2 templates

Совместимость

• Не ломает существующий функционал
• Миграция БД обратима
• Feature flags для включения/выключения