domovoy_bot/БЛАГОДАРНОСТИ.md

# 🙏 Система благодарностей — v1.13

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

---

## 📋 Описание

Система благодарностей позволяет жильцам благодарить друг друга за помощь. Получатель благодарности получает +10 к рейтингу и достижение "Помощник" (если первое).

---

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

- ✅ Отправка благодарностей по @username или ID
- ✅ Ограничение: 1 благодарность в день одному пользователю
- ✅ +10 к рейтингу получателю
- ✅ Достижение "Помощник" при первой благодарности
- ✅ Топ пользователей по благодарностям
- ✅ История благодарностей
- ✅ Статистика полученных/отправленных

---

## 📱 Команды

### Для всех:

| Команда | Описание | Пример |
|---------|----------|--------|
| `/thank @username` | Поблагодарить пользователя | `/thank @ivanov` |
| `/thank <user_id>` | Поблагодарить по ID | `/thank 123456789` |
| `/my_thanks` | Мои благодарности | `/my_thanks` |
| `/thanks_top` | Топ по благодарностям | `/thanks_top` |
| `/thanks_history` | История благодарностей | `/thanks_history` |

---

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

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

**Пользователь:**
```
/thank @ivanov
```

**Бот:**
```
🙏 Благодарность для Иван Иванов

Отправьте текст благодарности (необязательно) или "пропустить":
```

**Пользователь:**
```
Спасибо за помощь с сантехником!
```

**Бот (отправителю):**
```
✅ Благодарность отправлена!

Получатель: Иван Иванов
Сообщение: Спасибо за помощь с сантехником!
```

**Бот (получателю в личку):**
```
🙏 Вам благодарность!

От: Петр Петров
Сообщение: Спасибо за помощь с сантехником!

+10 к рейтингу!
```

**Если первая благодарность — ещё и достижение:**
```
🏆 Новое достижение!

🤝 Помощник

Получил благодарность от соседа

Продолжайте помогать!
```

---

### Сценарий 2: Ответ на сообщение

**Пользователь отвечает на сообщение командой:**
```
/thank
```

**Бот:**
```
🙏 Благодарность для [имя отвечаемого]

Отправьте текст благодарности или "пропустить":
```

---

### Сценарий 3: Повторная благодарность

**Пользователь пытается поблагодарить второй раз за день:**

**Бот:**
```
⚠️ Вы уже благодарили этого пользователя сегодня!
Можно поблагодарить только один раз в день.
```

---

### Сценарий 4: Мои благодарности

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

**Бот:**
```
🙏 Ваши благодарности

✅ Получено: 5
📤 Отправлено: 3

Последние полученные:
  • От user123: Спасибо за консультацию!
  • От user456: Спасибо!
  • От user789: Очень помог!
```

---

### Сценарий 5: Топ по благодарностям

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

**Бот:**
```
🙏 Топ по благодарностям

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

---

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

### Таблица `thanks`:
```sql
CREATE TABLE thanks (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    from_user_id BIGINT NOT NULL,  -- Кто поблагодарил
    to_user_id BIGINT NOT NULL,    -- Кого поблагодарили
    message TEXT,                   -- Текст благодарности
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (from_user_id) REFERENCES users(user_id),
    FOREIGN KEY (to_user_id) REFERENCES users(user_id)
)
```

### Индексы:
- `ix_thanks_from` — по отправителю
- `ix_thanks_to` — по получателю
- `ix_thanks_created` — по времени

---

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

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

#### 1. Отправка благодарности
```bash
/thank @username
# Отправить текст
```
- [ ] Благодарность сохранена
- [ ] Получатель уведомлён
- [ ] +10 к рейтингу начислено

#### 2. Первая благодарность
```bash
# Получить первую благодарность
```
- [ ] Достижение "Помощник" выдано
- [ ] Уведомление о достижении пришло

#### 3. Повторная благодарность
```bash
# Попытаться поблагодарить второй раз за день
```
- [ ] Бот блокирует повторную благодарность

#### 4: Мои благодарности
```bash
/my_thanks
```
- [ ] Статистика отображается
- [ ] Последние полученные показаны

#### 5: Топ
```bash
/thanks_top
```
- [ ] Топ отображается
- [ ] Медали у первых трёх

---

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

| Файл | Изменения |
|------|-----------|
| `database/models.py` | Модель Thank |
| `database/migrate_add_thanks.py` | Миграция БД |
| `services/thanks.py` | Сервис благодарностей |
| `services/achievements.py` | Достижение "Помощник" |
| `handlers/thanks.py` | Хендлеры благодарностей |
| `handlers/__init__.py` | Импорт thanks_router |
| `main.py` | Регистрация thanks_router |

---

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

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

1. **Поблагодарить:**
   ```
   /thank @ivanov
   ```

2. **Посмотреть свои благодарности:**
   ```
   /my_thanks
   ```

3. **Посмотреть топ:**
   ```
   /thanks_top
   ```

---

## 💡 Советы

### Ограничения:

- **1 благодарность в день** — одному пользователю
- **Нельзя себе** — нельзя поблагодарить самого себя
- **+10 к рейтингу** — за каждую благодарность

### Когда благодарить:

- ✅ Сосед помог с ремонтом
- ✅ Подсказали по вопросам ЖКХ
- ✅ Помогли с доставкой
- ✅ Поделились контактами мастеров
- ✅ Любая другая помощь

---

## 🔧 Отладка

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

SELECT from_user_id, to_user_id, message, created_at
FROM thanks
ORDER BY created_at DESC
LIMIT 20;
```

### Логи:
```bash
tail -f logs/bot.log | grep -i "благодар\|thank"
```

---

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

| Было | Стало |
|------|-------|
| Нет способа сказать спасибо | **Система благодарностей** |
| Нет мотивации помогать | **+10 к рейтингу** |
| Нет признания | **Достижение "Помощник"** |
| Не видно кто помогает | **Топ по благодарностям** |

---

**Система благодарностей готова! 🙏**

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