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

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

---

## 📋 Описание

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

---

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

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

---

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

**За что начисляются баллы:**
- 💬 **Сообщение в чате** — +1 балл

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

---

## 🔐 Доступ

**Видят рейтинг:**
- ✅ **Только администраторы**

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

---

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

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

**Показать свой рейтинг:**
```bash
/rating
```

**Показать рейтинг пользователя по ID:**
```bash
/rating 123456789
```

**Показать рейтинг по username:**
```bash
/rating @username
```

**Пример ответа:**
```
📊 РЕЙТИНГ ПОЛЬЗОВАТЕЛЯ

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

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

---

### 2. `/top` или `/топ`

**Топ-10 пользователей по рейтингу:**
```bash
/top
```

**Пример ответа:**
```
🏆 ТОП-10 ПО РЕЙТИНГУ

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

---

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

**Распределение по уровням:**
```bash
/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) — уровень, по умолчанию 'Новичок'

**Миграция:**
```bash
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
   ```

---

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