# 🚫 Чёрный список ссылок — v1.2

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

---

## 📋 Описание

Автоматическая система защиты чата от спама и запрещённых ссылок. Бот проверяет все сообщения, удаляет спам, предупреждает нарушителей и банит при достижении лимита предупреждений.

---

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

- ✅ Проверка всех сообщений на запрещённые ссылки
- ✅ Чёрный список доменов, паттернов, ключевых слов
- ✅ Авто-удаление спам-сообщений
- ✅ Система предупреждений (3 → бан)
- ✅ Уведомление админа о каждом случае
- ✅ Гибкие настройки (удаление, предупреждения, бан)
- ✅ Исключения для админов

---

## 🛡️ Что блокируется

### 1. Домены из чёрного списка
```
spam.com
fake-giveaway.xyz
phishing-site.com
...
```

### 2. Паттерны ссылок
```
t.me/spam_
vk.com/scam_
bit.ly/spam
```

### 3. Ключевые слова
```
выигрыш в лотерею
бесплатный биткоин
заработок без вложений
гарантированный доход
```

---

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

### Управление доменами:

| Команда | Описание | Пример |
|---------|----------|--------|
| `/add_domain <домен>` | Добавить домен в ЧС | `/add_domain spam.com` |
| `/remove_domain <домен>` | Удалить домен из ЧС | `/remove_domain spam.com` |
| `/domains` | Показать все домены | `/domains` |

### Управление паттернами:

| Команда | Описание | Пример |
|---------|----------|--------|
| `/add_pattern <паттерн>` | Добавить паттерн в ЧС | `/add_pattern t.me/spam_` |
| `/remove_pattern <паттерн>` | Удалить паттерн из ЧС | `/remove_pattern t.me/spam_` |
| `/patterns` | Показать все паттерны | `/patterns` |

### Управление ключевыми словами:

| Команда | Описание | Пример |
|---------|----------|--------|
| `/add_keyword <слово>` | Добавить ключ в ЧС | `/add_keyword выигрыш` |
| `/remove_keyword <слово>` | Удалить ключ из ЧС | `/remove_keyword выигрыш` |
| `/keywords` | Показать все ключи | `/keywords` |

### Предупреждения:

| Команда | Описание | Пример |
|---------|----------|--------|
| `/warnings` | Пользователи с предупреждениями | `/warnings` |
| `/clear_warnings <ID>` | Сбросить предупреждения | `/clear_warnings 123456789` |
| `/antispam_stats` | Статистика анти-спама | `/antispam_stats` |
| `/reload_antispam` | Перезагрузить конфиг | `/reload_antispam` |

---

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

### Сценарий 1: Отправка запрещённой ссылки

**Пользователь пишет:**
```
Заходите на сайт! spam.com - там крутые предложения!
```

**Бот:**
1. ✅ Находит домен `spam.com` в чёрном списке
2. ✅ **Удаляет сообщение** из чата
3. ✅ Пишет нарушителю в личку:
   ```
   ⚠️ Предупреждение #1

   В вашем сообщении обнаружена запрещённая ссылка или спам.

   Причина: Запрещённый домен: spam.com

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

   При следующем нарушении будет публичное предупреждение.
   При достижении 3 предупреждений — бан.
   ```
4. ✅ Уведомляет админа:
   ```
   ⚠️ СПАМ В ЧАТЕ!

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

   Причина: Запрещённый домен: spam.com

   Предупреждений: 1 из 3
   ```

---

### Сценарий 2: Повторное нарушение

**Пользователь снова пишет:**
```
Ну тогда вот: t.me/spam_channel - заходите!
```

**Бот:**
1. ✅ Находит паттерн `t.me/spam_`
2. ✅ **Удаляет сообщение**
3. ✅ Пишет в личку (предупреждение #2)
4. ✅ Уведомляет админа

---

### Сценарий 3: Третье нарушение — БАН!

**Пользователь в третий раз:**
```
cryptoscam.io - бесплатный биткоин!
```

**Бот:**
1. ✅ Находит домен `cryptoscam.io`
2. ✅ **Удаляет сообщение**
3. ✅ Пишет в личку:
   ```
   🚫 ВЫ ЗАБАНЕНЫ

   Причина: Систематический спам (3 предупреждений).

   Вы больше не можете писать в чат.
   ```
4. ✅ **Удаляет из чата** (бан)
5. ✅ Помечает `is_banned=True` в БД
6. ✅ Уведомляет админа

---

### Сценарий 4: Добавление нового домена

**Админ видит спам:**
```
new-scam.xyz - заходите!
```

**Админ:**
```bash
/add_domain new-scam.xyz
```

**Бот:**
```
✅ Домен new-scam.xyz добавлен в чёрный список
```

**Теперь этот домен блокируется автоматически!**

---

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

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

**Бот:**
```
📊 Статистика анти-спама

📁 Чёрный список:
├─ Домены: 15
├─ Паттерны: 8
└─ Ключевые слова: 12

⚠️ Предупреждения:
├─ Активные: 5
└─ Забанено за спам: 2

⚙️ Настройки:
├─ Удалять сообщения: ✅
├─ Предупреждать пользователя: ✅
├─ Уведомлять админа: ✅
└─ Бан после 3 предупреждений
```

---

### Сценарий 6: Сброс предупреждений

**Админ видит:**
```bash
/warnings

# Ответ:
⚠️ Пользователи с предупреждениями

• Иван Иванов (кв. 45) — 2 предупр.
• Петр Петров (кв. 88) — 1 предупр.
```

**Админ хочет сбросить Петру:**
```bash
/clear_warnings 987654321
```

**Бот:**
```
✅ Предупреждения пользователя 987654321 сброшены
```

---

## ⚙️ Настройки

Файл: `data/bad_domains.json`

```json
{
  "settings": {
    "delete_message": true,      // Удалять спам-сообщения
    "warn_user": true,           // Предупреждать пользователя
    "notify_admin": true,        // Уведомлять админа
    "ban_after_warnings": 3,     // Бан после N предупреждений
    "exclude_verified": false,   // Исключить верифицированных
    "exclude_admins": true       // Исключить админов
  }
}
```

**Можно изменить вручную** в файле или через команду `/reload_antispam` после редактирования.

---

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

### Таблица `spam_warnings`:
```sql
CREATE TABLE spam_warnings (
    warning_id INTEGER PRIMARY KEY AUTOINCREMENT,
    user_id BIGINT NOT NULL,
    message_text TEXT,
    reason TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    is_active BOOLEAN DEFAULT 1,
    FOREIGN KEY (user_id) REFERENCES users(user_id)
)
```

### Поле в `users`:
```sql
ALTER TABLE users ADD COLUMN spam_warning_count INTEGER DEFAULT 0
```

---

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

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

#### 1. Добавление домена
```bash
# Админ:
/add_domain test-spam.com
/domains
```
- [ ] Домен добавлен
- [ ] Показывается в списке

#### 2. Блокировка ссылки
```bash
# С другого аккаунта:
Заходите на test-spam.com!
```
- [ ] Сообщение удалено
- [ ] В личку пришло предупреждение #1
- [ ] Админ получил уведомление

#### 3. Повторное нарушение
```bash
# Снова:
Ещё ссылка: test-spam.com
```
- [ ] Предупреждение #2
- [ ] Счётчик увеличился

#### 4. Третье нарушение — бан
```bash
# В третий раз:
test-spam.com
```
- [ ] Предупреждение #3
- [ ] Пользователь забанен
- [ ] Удалён из чата

#### 5. Сброс предупреждений
```bash
# Админ:
/warnings
/clear_warnings <ID>
```
- [ ] Предупреждения сброшены

---

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

| Файл | Изменения |
|------|-----------|
| `data/bad_domains.json` | Новый файл с ЧС |
| `services/antispam.py` | Новый сервис проверки |
| `handlers/antispam.py` | Новые хендлеры |
| `handlers/chat_monitor.py` | Добавлена проверка на спам |
| `database/models.py` | Модели SpamWarning + поле spam_warning_count |
| `database/migrate_add_spam_warnings.py` | Миграция БД |
| `handlers/__init__.py` | Импорт antispam_router |
| `main.py` | Регистрация antispam_router |

---

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

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

1. **Добавить спам-домен:**
   ```
   /add_domain spam.com
   ```

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

3. **Проверить предупреждения:**
   ```
   /warnings
   ```

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

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

**Если получил предупреждение:**
- Не отправляй ссылки из чёрного списка
- Если ссылка легальная — напиши админу

---

## 💡 Советы

### Какие домены добавлять:
- ✅ Спам-сайты
- ✅ Фишинг
- ✅ Мошеннические лотереи
- ✅ Фейковые магазины

### Какие паттерны добавлять:
- ✅ `t.me/spam_` — спам-каналы
- ✅ `vk.com/fake_` — фейковые страницы
- ✅ `bit.ly/scam` — сокращённые спам-ссылки

### Какие ключевые слова добавлять:
- ✅ «выигрыш в лотерею»
- ✅ «бесплатный биткоин»
- ✅ «заработок без вложений»

---

## 🔧 Отладка

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

SELECT * FROM spam_warnings ORDER BY created_at DESC LIMIT 10;
```

### Логи:
```bash
tail -f logs/bot.log | grep -i spam
```

### Перезагрузить конфиг:
```bash
/reload_antispam
```

---

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

| Было | Стало |
|------|-------|
| Спам в чате | **Авто-удаление** |
| Ручная модерация | **Бот работает 24/7** |
| Нет учёта нарушений | **3 предупреждения → бан** |
| Не видно кто спамит | **Статистика и логи** |
| Нет чёрного списка | **Домены + паттерны + ключи** |

---

**Защита от спама готова! 🛡️**

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