# 🚦 Анти-спам лимиты — v1.3

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

---

## 📋 Описание

Защита от флуда (спама сообщениями). Бот подсчитывает количество сообщений от каждого пользователя за период времени. При превышении лимита — предупреждает, при повторных нарушениях — мутит.

---

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

- ✅ Подсчёт сообщений за период (10 за 60 сек)
- ✅ Авто-удаление сообщений при превышении лимита
- ✅ Система предупреждений (2 → мут)
- ✅ Мут на 30 минут (настраивается)
- ✅ Уведомление админа о нарушениях
- ✅ Команды мута/размута вручную
- ✅ Проверка истечения мута

---

## ⚙️ Настройки по умолчанию

| Параметр | Значение |
|----------|----------|
| **Макс. сообщений** | 10 |
| **За период** | 60 секунд |
| **Предупреждений до мута** | 2 |
| **Длительность мута** | 30 минут |
| **Исключать админов** | ✅ Да |

---

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

### Мут/размут:

| Команда | Описание | Пример |
|---------|----------|--------|
| `/mute <ID> [минуты]` | Замутить пользователя | `/mute 123456789 30` |
| `/unmute <ID>` | Размутить пользователя | `/unmute 123456789` |
| `/check_mute <ID>` | Проверить статус мута | `/check_mute 123456789` |
| `/muted` | Список замученных | `/muted` |

### Статистика:

| Команда | Описание | Пример |
|---------|----------|--------|
| `/rate_stats` | Статистика лимитов | `/rate_stats` |
| `/user_rate <ID>` | Статистика пользователя | `/user_rate 123456789` |
| `/clear_rate_warnings <ID>` | Сбросить предупреждения | `/clear_rate_warnings 123456789` |

---

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

### Сценарий 1: Превышение лимита (флуд)

**Пользователь быстро отправляет 10 сообщений:**
```
Привет!
Как дела?
Что нового?
Кто сегодня будет?
Во сколько встреча?
Где встреча?
Нужно взять что-то?
Сколько стоит?
Кто организует?
Можно с детьми?
```

**Бот:**
1. ✅ Находит превышение лимита (10 за 60 сек)
2. ✅ **Удаляет 11-е сообщение**
3. ✅ Пишет нарушителю в личку:
   ```
   ⚠️ Предупреждение #1

   Вы превысили лимит сообщений!

   📊 Ваши нарушения: 1 из 2

   Лимит: 10 сообщений за 60 сек.
   Вы отправили: 10 сообщ.

   При достижении 2 предупреждений вы будете замучены на 30 мин.
   ```
4. ✅ Уведомляет админа:
   ```
   ⚠️ ФЛУД В ЧАТЕ!

   Пользователь: Иван Иванов
   ID: 123456789
   Квартира: 45

   Сообщений: 10 (лимит: 10)
   Предупреждений: 1 из 2
   ```

---

### Сценарий 2: Повторный флуд — МУТ

**Пользователь снова флудит через 5 минут:**

**Бот:**
1. ✅ Находит превышение
2. ✅ **Удаляет сообщение**
3. ✅ Пишет предупреждение #2
4. ✅ **Мутит на 30 минут**
5. ✅ Пишет пользователю:
   ```
   🔇 ВЫ ЗАМУЧЕНЫ

   Причина: Превышение лимита сообщений (2 предупреждений).

   Мут до: 26.02.2026 17:30

   Вы не сможете писать в чат до указанного времени.
   ```

---

### Сценарий 3: Ручной мут админом

**Админ видит что пользователь нарушает:**

**Админ:**
```bash
/mute 123456789 60
```

**Бот:**
```
🔇 Пользователь замучен

Пользователь: Иван Иванов
ID: 123456789
До: 26.02.2026 18:00

Пользователь не сможет писать в чат до указанного времени.
```

---

### Сценарий 4: Истечение мута

**Через 30 минут:**

**Бот автоматически:**
1. ✅ Проверяет истёк ли мут
2. ✅ **Размучивает пользователя**
3. ✅ Следующее сообщение пользователя **пропускается**

---

### Сценарий 5: Проверка статуса мута

**Админ:**
```bash
/check_mute 123456789
```

**Бот:**
```
⏳ Мут активен

Пользователь: Иван Иванов
ID: 123456789
Осталось: 15 мин.
До: 26.02.2026 17:30
```

**Или если мут истёк:**
```
✅ Мут истёк

Пользователь: Иван Иванов
ID: 123456789

Пользователь размучен автоматически.
```

---

### Сценарий 6: Список всех замученных

**Админ:**
```bash
/muted
```

**Бот:**
```
🔇 Замученные пользователи

• Иван Иванов (кв. 45) — ещё 25 мин.
• Петр Петров (кв. 88) — ещё 10 мин.
```

---

### Сценарий 7: Статистика лимитов

**Админ:**
```bash
/rate_stats
```

**Бот:**
```
📊 Статистика лимитов сообщений

⚙️ Настройки:
├─ Максимум сообщений: 10
├─ За период: 60 сек
├─ Длительность мута: 30 мин
└─ Предупреждений перед мутом: 2

🔥 Нарушители (3)

⚠️ Иван Иванов — 8 сообщ.
⚠️ Петр Петров — 6 сообщ.
🔇 Василий Сидоров — 12 сообщ.
```

---

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

### Таблица `message_rates`:
```sql
CREATE TABLE message_rates (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    user_id BIGINT NOT NULL,
    timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (user_id) REFERENCES users(user_id)
)
```

### Поля в `users`:
```sql
ALTER TABLE users ADD COLUMN is_muted BOOLEAN DEFAULT 0
ALTER TABLE users ADD COLUMN mute_until TIMESTAMP
ALTER TABLE users ADD COLUMN rate_limit_warnings INTEGER DEFAULT 0
```

---

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

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

#### 1. Быстрая отправка сообщений
```bash
# С другого аккаунта:
# Отправить 10 сообщений за 1 минуту
```
- [ ] 11-е сообщение удалено
- [ ] Пришло предупреждение #1 в личку
- [ ] Админ получил уведомление

#### 2. Повторный флуд
```bash
# Через 5 минут снова отправить 10 сообщений
```
- [ ] Предупреждение #2
- [ ] Пользователь замучен
- [ ] Сообщения удаляются

#### 3. Проверка мута
```bash
# Админ:
/check_mute <ID>
/muted
```
- [ ] Показывает правильный статус
- [ ] Оставшееся время верно

#### 4. Истечение мута
```bash
# Подождать 30 минут
# Отправить сообщение
```
- [ ] Сообщение прошло
- [ ] Мут снят автоматически

#### 5. Ручной мут/размут
```bash
# Админ:
/mute <ID> 10
/unmute <ID>
```
- [ ] Мут работает
- [ ] Размут работает

---

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

| Файл | Изменения |
|------|-----------|
| `services/rate_limiter.py` | Новый сервис лимитов |
| `handlers/ratelimit.py` | Новые хендлеры |
| `handlers/chat_monitor.py` | Проверка лимитов |
| `database/models.py` | Модели MessageRate + поля |
| `database/migrate_add_rate_limits.py` | Миграция БД |
| `handlers/__init__.py` | Импорт ratelimit_router |
| `main.py` | Регистрация ratelimit_router |

---

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

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

1. **Посмотреть статистику:**
   ```
   /rate_stats
   ```

2. **Замутить нарушителя:**
   ```
   /mute 123456789 30
   ```

3. **Проверить пользователя:**
   ```
   /user_rate 123456789
   ```

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

**Ничего делать не нужно!** Бот работает автоматически.

**Если получил предупреждение:**
- Не отправляй много сообщений подряд
- Подожди минуту перед новой серией

---

## 💡 Советы

### Настройка лимитов:

**Для активного чата (100+ сообщений/мин):**
- Увеличь лимит: `max_messages = 15`
- Уменьшь период: `period_seconds = 30`

**Для спокойного чата:**
- Уменьшь лимит: `max_messages = 5`
- Увеличь период: `period_seconds = 120`

### Когда мутить вручную:

- ✅ Троллинг
- ✅ Оскорбления
- ✅ Намеренный флуд
- ✅ Спам ссылками (вместе с чёрным списком)

---

## 🔧 Отладка

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

SELECT user_id, COUNT(*) as msg_count, MAX(timestamp) as last_msg
FROM message_rates
WHERE timestamp > datetime('now', '-1 minute')
GROUP BY user_id
ORDER BY msg_count DESC;
```

### Логи:
```bash
tail -f logs/bot.log | grep -i "флуд\|мут"
```

---

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

| Было | Стало |
|------|-------|
| Флуд в чате | **Авто-удаление** |
| Нет защиты | **Лимит 10 сообщ./мин** |
| Ручной контроль | **Авто-мут** |
| Нет статистики | **/rate_stats** |

---

**Защита от флуда готова! 🛡️**

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