# 🏆 Достижения жильцов — v1.12

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

---

## 📋 Описание

Система геймификации для жильцов. Пользователи получают достижения за активность в чате, верификацию, высокий рейтинг и другие действия. Есть топ пользователей по достижениям.

---

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

- ✅ 16 достижений в 9 категориях
- ✅ Авто-выдача достижений
- ✅ Уведомления о новых достижениях
- ✅ Топ пользователей по достижениям
- ✅ Просмотр своих достижений
- ✅ Просмотр достижений других (админ)

---

## 🏆 Список достижений

### 📝 Активность

| Достижение | Emoji | Описание |
|------------|-------|----------|
| **Новичок** | 🌱 | Первое сообщение в чате |
| **Активист 10** | 📝 | 10 сообщений в чате |
| **Активист 100** | ✍️ | 100 сообщений в чате |
| **Говорун 1000** | 🗣️ | 1000 сообщений в чате |

---

### ✅ Верификация

| Достижение | Emoji | Описание |
|------------|-------|----------|
| **Свой человек** | ✅ | Пройдена верификация |

---

### ⭐ Рейтинг

| Достижение | Emoji | Описание |
|------------|-------|----------|
| **Сосед** | 🏠 | Рейтинг 100 баллов |
| **Активист** | ⭐ | Рейтинг 500 баллов |
| **Лидер** | 👑 | Рейтинг 1000 баллов |

---

### ⏰ Время

| Достижение | Emoji | Описание |
|------------|-------|----------|
| **Жаворонок** | 🐦 | Сообщение в 6-7 утра |
| **Сова** | 🦉 | Сообщение после 23:00 |

---

### 📊 Опросы

| Достижение | Emoji | Описание |
|------------|-------|----------|
| **Участник опроса** | 📊 | Участие в опросе |

---

### 📢 Объявления

| Достижение | Emoji | Описание |
|------------|-------|----------|
| **Объявитель** | 📢 | Публикация объявления |

---

### 🤝 Социальные

| Достижение | Emoji | Описание |
|------------|-------|----------|
| **Помощник** | 🤝 | Получил благодарность |

---

### 🔒 Безопасность

| Достижение | Emoji | Описание |
|------------|-------|----------|
| **Охотник на шпионов** | 🕵️ | Сообщение о подозрительном поведении |

---

### 📅 Серии

| Достижение | Emoji | Описание |
|------------|-------|----------|
| **Недельный воин** | 📅 | Активность 7 дней подряд |
| **Месячный мастер** | 🗓️ | Активность 30 дней подряд |

---

## 📱 Команды

### Для всех:

| Команда | Описание | Пример |
|---------|----------|--------|
| `/achievements` | Показать свои достижения | `/achievements` |

### Для админов:

| Команда | Описание | Пример |
|---------|----------|--------|
| `/achievements_top` | Топ по достижениям | `/achievements_top` |
| `/all_achievements` | Все доступные достижения | `/all_achievements` |
| `/user_achievements <ID>` | Достижения пользователя | `/user_achievements 123456789` |

---

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

### Сценарий 1: Первое сообщение

**Пользователь пишет первое сообщение:**

**Бот:**
```
🏆 Новое достижение!

🌱 Новичок

Первое сообщение в чате

Продолжайте в том же духе!
```

---

### Сценарий 2: Просмотр своих достижений

**Пользователь:**
```
/achievements
```

**Бот:**
```
🏆 Ваши достижения

Всего: 5

📝 Активность
  🌱 Новичок
  📝 Активист 10
  ✍️ Активист 100

⭐ Рейтинг
  🏠 Сосед
  ⭐ Активист

⏰ Время
  🦉 Сова
```

---

### Сценарий 3: Топ по достижениям

**Админ:**
```
/achievements_top
```

**Бот:**
```
🏆 Топ по достижениям

🥇 Иван Иванов (кв. 45) — 12 достиж.
🥈 Петр Петров (кв. 88) — 10 достиж.
🥉 Анна Сидорова (кв. 12) — 8 достиж.
4. Мария Козлова (кв. 100) — 6 достиж.
5. Василий Смирнов (кв. 50) — 5 достиж.
```

---

### Сценарий 4: Все достижения

**Админ:**
```
/all_achievements
```

**Бот:**
```
🏆 Все достижения

Всего: 16

📝 Активность
  🌱 Новичок
     └─ Первое сообщение в чате
  📝 Активист 10
     └─ 10 сообщений в чате
  ...

⭐ Рейтинг
  🏠 Сосед
     └─ Рейтинг 100 баллов
  ...
```

---

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

### Таблица `achievements`:
```sql
CREATE TABLE achievements (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    user_id BIGINT NOT NULL,
    achievement_type TEXT NOT NULL,
    earned_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    metadata TEXT,  -- JSON с доп. данными
    FOREIGN KEY (user_id) REFERENCES users(user_id)
)
```

### Индексы:
- `ix_achievements_user` — по пользователю
- `ix_achievements_type` — по типу достижения

---

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

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

#### 1. Авто-выдача достижений
```bash
# Отправить несколько сообщений
# Проверить что пришли уведомления
```
- [ ] Новичок (1 сообщение)
- [ ] Активист 10 (10 сообщений)
- [ ] Жаворонок/Сова (по времени)

#### 2. Просмотр достижений
```bash
/achievements
```
- [ ] Достижения отображаются
- [ ] Группировка по категориям
- [ ] Emoji правильные

#### 3. Топ по достижениям
```bash
/achievements_top
```
- [ ] Топ отображается
- [ ] Медали у первых трёх
- [ ] Количество верное

#### 4. Все достижения
```bash
/all_achievements
```
- [ ] Все 16 достижений показаны
- [ ] Описания верные
- [ ] Группировка по категориям

---

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

| Файл | Изменения |
|------|-----------|
| `database/models.py` | Модель Achievement |
| `database/migrate_add_achievements.py` | Миграция БД |
| `services/achievements.py` | Сервис достижений |
| `handlers/achievements.py` | Хендлеры |
| `handlers/chat_monitor.py` | Авто-проверка достижений |
| `handlers/__init__.py` | Импорт achievements_router |
| `main.py` | Регистрация achievements_router |

---

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

### Для жильца:

1. **Посмотреть свои достижения:**
   ```
   /achievements
   ```

2. **Получать достижения автоматически:**
   - Пишите сообщения в чат
   - Пройдите верификацию
   - Набирайте рейтинг
   - Участвуйте в опросах
   - Публикуйте объявления

---

## 💡 Советы

### Как получить все достижения:

1. **Активность:**
   - Пишите сообщения регулярно
   - Достигните 1000 сообщений

2. **Рейтинг:**
   - Будьте активны ( +1 за сообщение)
   - Достигните 1000 баллов

3. **Время:**
   - Напишите утром (6-7) — Жаворонок
   - Напишите ночью (после 23) — Сова

4. **Социальные:**
   - Помогайте соседям
   - Получите благодарность

---

## 🔧 Отладка

### Посмотреть достижения в БД:
```bash
cd /home/matrixhasyou/domovoy_bot
source venv/bin/activate
sqlite3 database/domovoy.db

SELECT user_id, achievement_type, earned_at
FROM achievements
ORDER BY earned_at DESC
LIMIT 20;
```

### Логи:
```bash
tail -f logs/bot.log | grep -i "достижен\|achievement"
```

---

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

| Было | Стало |
|------|-------|
| Нет мотивации | **Достижения** |
| Нет геймификации | **16 достижений** |
| Нет топа | **Топ по достижениям** |
| Скучный чат | **Интересно участвовать** |

---

**Достижения готовы! 🏆**

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