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`:
```sql
ALTER TABLE messages ADD COLUMN topic TEXT
CREATE INDEX ix_messages_topic ON messages(topic)
```

---

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

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

#### 1. Облако тегов
```bash
# Админ:
/topics
```
- [ ] Облако отображается
- [ ] Проценты считаются верно
- [ ] Emoji правильные

#### 2. Топ тем
```bash
/top_topics 7 5
```
- [ ] Топ отображается
- [ ] Лимит работает

#### 3. Статистика темы
```bash
/topic_stats лифты
```
- [ ] Статистика по теме отображается
- [ ] Тренд по дням показан

#### 4. Еженедельный отчёт
```bash
/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`:
```python
'новая_тема': {
    'keywords': ['ключевое', 'слова'],
    'emoji': '🎯'
}
```

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

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

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

Добавьте в scheduler.py:
```python
# Каждое воскресенье в 10:00
CronTrigger.from_crontab('0 10 * * 0')
```

---

## 🔧 Отладка

### Посмотреть темы в БД:
```bash
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;
```

### Логи:
```bash
tail -f logs/bot.log | grep -i "тем\|topic"
```

---

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

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

---

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

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