domovoy_bot/ОБЛАКО_ТЕГОВ.md

☁️ Облако тегов тем чата — v1.8

Версия: v1.8 Дата: 26 февраля 2026 г. Статус: ✅ Реализовано

---

📋 Описание

Анализ тем чата с автоматической классификацией сообщений. Бот определяет тему каждого сообщения (лифты, парковка, уборка, соседи и т.д.), формирует облако тегов, показывает статистику и тренды тем.

---

🎯 Возможности

• ✅ 18 тем для классификации (лифты, парковка, уборка, соседи, вода, свет...)
• ✅ Авто-классификация каждого сообщения
• ✅ Облако тегов с процентами
• ✅ Топ тем за период
• ✅ Статистика по конкретной теме
• ✅ Еженедельный отчёт
• ✅ Тренды тем по дням

---

📱 Команды

Для администраторов:

Команда	Описание	Пример
/topics [дни]	Облако тегов	/topics 7
/top_topics [дни] [лимит]	Топ тем	/top_topics 7 5
/topic_stats <тема>	Статистика темы	/topic_stats лифты
/weekly_report	Еженедельный отчёт	/weekly_report
/topics_list	Список всех тем	/topics_list

---

🎯 Темы для классификации

Тема	Emoji	Ключевые слова
🛗 Лифты	🛗	лифт, лифты, кабина, шахта
🚗 Парковка	🚗	парковк, машина, автомобиль, шлагбаум
🧹 Уборка	🧹	уборк, грязн, мусор, подъезд
👥 Соседи	👥	сосед, шум, громко, музыка, ремонт
💧 Вода	💧	вод, кран, труб, протечк, засор
⚡ Электричество	⚡	свет, электричеств, розетк, проводк
🔥 Отопление	🔥	отоплен, батаре, радиатор, тепло
🔑 Домофон	🔑	домофон, ключ, карта, доступ
🗑️ Мусор	🗑️	мусор, контейнер, баки, вывоз
👶 Дети	👶	ребенок, дети, коляск, площадк
🐕 Животные	🐕	собак, кошк, питомец, лают
📢 Объявления	📢	объявлен, продам, куплю, отдам
😠 Жалобы	😠	жалоб, недовольн, возмущен, требую
🙏 Благодарности	🙏	спасиб, благодар, молодец, хорошо
❓ Вопросы	❓	вопрос, подскажите, помогите, кто знает
💡 Предложения	💡	предлагаю, давайте, идея
📅 Собрание	📅	собран, встреч, голосован, опрос
🏢 УК	🏢	ук, управляющ, жкх, диспетчер

---

🎯 Сценарии использования

Сценарий 1: Облако тегов

Админ:

/topics

Бот:

☁️ Облако тем чата (за 7 дн.)

Всего сообщений: 500
Распознано: 400 (80%)

🛗 Лифты: ████████████░░░░░░ 60% (240)
🚗 Парковка: ██████░░░░░░░░░░░░ 30% (120)
🧹 Уборка: ████░░░░░░░░░░░░░░ 20% (80)
👥 Соседи: ██░░░░░░░░░░░░░░░░ 10% (40)
💧 Вода: ██░░░░░░░░░░░░░░░░ 10% (40)

---

Сценарий 2: Топ тем

Админ:

/top_topics 7 5

Бот:

🔥 Топ тем за 7 дн.

1. 🛗 Лифты: 60% (240 сообщ.)
2. 🚗 Парковка: 30% (120 сообщ.)
3. 🧹 Уборка: 20% (80 сообщ.)
4. 👥 Соседи: 10% (40 сообщ.)
5. 💧 Вода: 10% (40 сообщ.)

---

Сценарий 3: Статистика темы

Админ:

/topic_stats лифты

Бот:

🛗 Статистика темы: Лифты

📊 За 7 дней:
├─ Сообщений: 240
└─ Доля: 60%

📈 За 14 дней:
└─ Сообщений: 450

📅 По дням:
  20.02: 35 сообщ.
  21.02: 40 сообщ.
  22.02: 30 сообщ.
  23.02: 45 сообщ.
  24.02: 50 сообщ.
  25.02: 40 сообщ.
  26.02: 35 сообщ.

---

Сценарий 4: Еженедельный отчёт

Админ:

/weekly_report

Бот:

📊 Еженедельный отчёт по темам чата

Период: последние 7 дней

🔥 Топ тем недели:

1. 🛗 Лифты: 60% (240 сообщ.)
2. 🚗 Парковка: 30% (120 сообщ.)
3. 🧹 Уборка: 20% (80 сообщ.)

📈 Динамика:

↗️ Лифты: +50 (🛗)
↗️ Парковка: +30 (🚗)
↘️ Уборка: -10 (🧹)

💡 Используйте /topics для детальной статистики

---

Сценарий 5: Список тем

Админ:

/topics_list

Бот:

📋 Список тем для классификации

🛗 Лифты
   └─ Ключевые слова: лифт, лифты, лифтовая, кабина...
🚗 Парковка
   └─ Ключевые слова: парковк, машина, автомобиль...
🧹 Уборка
   └─ Ключевые слова: уборк, грязн, мусор...
...

💡 Всего тем: 18

---

🗄️ База данных

Поле в messages:

ALTER TABLE messages ADD COLUMN topic TEXT
CREATE INDEX ix_messages_topic ON messages(topic)

---

🧪 Тестирование

Чек-лист проверки:

1. Облако тегов

# Админ:
/topics

• Облако отображается
• Проценты считаются верно
• Emoji правильные

2. Топ тем

/top_topics 7 5

• Топ отображается
• Лимит работает

3. Статистика темы

/topic_stats лифты

• Статистика по теме отображается
• Тренд по дням показан

4. Еженедельный отчёт

/weekly_report

• Отчёт формируется
• Динамика считается

---

📁 Изменённые файлы

Файл	Изменения
database/models.py	Поле topic в Message
database/migrate_add_topic_field.py	Миграция БД
services/topics_analyzer.py	Сервис анализа тем
handlers/topics.py	Хендлеры
handlers/chat_monitor.py	Авто-классификация
handlers/__init__.py	Импорт topics_router
main.py	Регистрация topics_router

---

🚀 Как использовать

Для админа:

1. Посмотреть облако тегов:

   /topics
   

2. Посмотреть топ тем:

   /top_topics 7 5
   

3. Проверить тему:

   /topic_stats лифты
   

4. Получить отчёт:

   /weekly_report
   

---

💡 Советы

Настройка тем:

В services/topics_analyzer.py:

'новая_тема': {
    'keywords': ['ключевое', 'слова'],
    'emoji': '🎯'
}

Точность классификации:

• 80%+ — отличный результат
• 60-80% — хороший результат
• <60% — добавьте больше ключевых слов

Еженедельный отчёт:

Добавьте в scheduler.py:

# Каждое воскресенье в 10:00
CronTrigger.from_crontab('0 10 * * 0')

---

🔧 Отладка

Посмотреть темы в БД:

cd /home/matrixhasyou/domovoy_bot
source venv/bin/activate
sqlite3 database/domovoy.db

SELECT topic, COUNT(*) as count
FROM messages
WHERE topic IS NOT NULL
GROUP BY topic
ORDER BY count DESC;

Логи:

tail -f logs/bot.log | grep -i "тем\|topic"

---

✅ Преимущества

Было	Стало
Не понятно что волнует жильцов	Облако тегов
Ручной анализ	Авто-классификация
Нет статистики	Топ тем, тренды
Нет отчётов	Еженедельный отчёт

---

Облако тегов готово! ☁️

Следующий шаг: тестирование на тестовой группе и фиксация версии v1.8