domovoy_bot/РЕЙТИНГ.md

🏆 Система рейтинга пользователей

Дата добавления: 24 февраля 2026
Статус: ✅ Готово

---

📋 Описание

Система рейтинга активности жильцов в чате. Только администраторы могут видеть и управлять рейтингом.

---

🎯 Уровни пользователей

Уровень	Баллы	Иконка
🌱 Новичок	0-99	🌱
🏠 Сосед	100-499	🏠
⭐ Активист	500-999	⭐
👑 Лидер	1000+	👑

---

💰 Начисление баллов

За что начисляются баллы:

• 💬 Сообщение в чате — +1 балл

Автоматическое обновление:

• Уровень обновляется автоматически при изменении рейтинга
• Баллы начисляются за каждое сообщение в чате

---

🔐 Доступ

Видят рейтинг:

• ✅ Только администраторы

Где видят:

• ✅ Только в личных сообщениях с ботом
• ❌ В общий чат ничего не отправляется

---

📱 Команды для админа

1. /rating или /рейтинг

Показать свой рейтинг:

/rating

Показать рейтинг пользователя по ID:

/rating 123456789

Показать рейтинг по username:

/rating @username

Пример ответа:

📊 РЕЙТИНГ ПОЛЬЗОВАТЕЛЯ

👤 Петр Петров (кв. 88)
ID: 123456789

⭐ Уровень: Активист
🏆 Рейтинг: 567 баллов
💬 Сообщений: 543
📈 До следующего уровня: 433 баллов

---

2. /top или /топ

Топ-10 пользователей по рейтингу:

/top

Пример ответа:

🏆 ТОП-10 ПО РЕЙТИНГУ

🥇 Петр Петров (кв. 88)
   └─ Рейтинг: 567 | Уровень: Активист
🥈 Анна Иванова (кв. 45)
   └─ Рейтинг: 432 | Уровень: Сосед
🥉 Иван Сидоров (кв. 12)
   └─ Рейтинг: 298 | Уровень: Сосед
4. Мария Козлова
   └─ Рейтинг: 156 | Уровень: Сосед
...

---

3. /rank или /ранг

Распределение по уровням:

/rank

Пример ответа:

📊 РАСПРЕДЕЛЕНИЕ ПО УРОВНЯМ

Всего пользователей: 50

👑 Лидер: 2 (4.0%)
⭐ Активист: 8 (16.0%)
🏠 Сосед: 25 (50.0%)
🌱 Новичок: 15 (30.0%)

Уровни:
🌱 Новичок: 0-99 баллов
🏠 Сосед: 100-499 баллов
⭐ Активист: 500-999 баллов
👑 Лидер: 1000+ баллов

---

🖱️ Кнопки в меню админа

Главное меню:

• 🏆 Рейтинг — показывает Топ-10

Меню рейтинга:

• 🏆 Топ-10 — топ пользователей
• 📊 Уровни — распределение по уровням
• 🔙 Назад — в главное меню

---

🛡️ Защита

Все команды защищены:

1. ✅ Только администраторы — декоратор @admin_only
2. ✅ Только в личке — проверка message.chat.type != 'private'
3. ✅ В общий чат не отправляется — уведомление если не в личке

Если не админ пытается:

❌ Команда недоступна

Если в чате (не в личке):

⚠️ Команда доступна только в личных сообщениях!
Напишите боту в личку: /top

---

📊 База данных

Новые поля в таблице users:

• rating (INTEGER) — баллы активности, по умолчанию 0
• level (TEXT) — уровень, по умолчанию 'Новичок'

Миграция:

cd ~/domovoy_bot
python database/migrate_add_rating.py

---

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

Тест 1: Начисление баллов

1. Отправь сообщение в чат
2. Проверь рейтинг через /rating <твой_ID>
3. Ожидай: +1 балл

Тест 2: Топ пользователей

1. В личку боту: /top
2. Ожидай: список топ-10

Тест 3: Распределение

1. В личку боту: /rank
2. Ожидай: проценты по уровням

Тест 4: Защита в чате

1. В общем чате: /top
2. Ожидай: "Команда доступна только в личных сообщениях"

Тест 5: Кнопка Рейтинг

1. В личку: /admin
2. Нажми "🏆 Рейтинг"
3. Ожидай: топ-10 + кнопки "Топ-10", "Уровни"

---

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

Файл	Изменения
database/models.py	Добавлены поля rating, level
database/migrate_add_rating.py	Скрипт миграции
handlers/chat_monitor.py	Начисление +1 балл за сообщение
handlers/admin.py	Команды /rating, /top, /rank
keyboards/admin_menu.py	Кнопка "🏆 Рейтинг"

---

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

Для админа:

1. Проверить свой рейтинг:

   /rating
   

2. Проверить рейтинг жильца:

   /users  # Найти ID
   /rating 123456789
   

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

   /top
   

   Или через меню: /admin → "🏆 Рейтинг"

4. Посмотреть уровни:

   /rank
   

---

Система рейтинга готова! 🎉