# 📦 Версии домового бота

**Проект:** Домовой Бот для чата многоквартирного дома
**Репозиторий:** `/home/matrixhasyou/domovoy_bot`

---

## 🎯 План развития (Roadmap 2.0)

### Функции для реализации (приоритетные):

| № | Функция | Статус | Версия | Дата |
|---|---------|--------|--------|------|
| 1 | **Опросы и голосования** | ✅ Реализовано | v1.1 | 26.02.2026 |
| 2 | **Чёрный список ссылок** | ✅ Реализовано | v1.2 | 26.02.2026 |
| 3 | **Анти-спам (лимиты сообщений)** | ✅ Реализовано | v1.3 | 26.02.2026 |
| 4 | **Расписание отключений (вода/свет)** | ✅ Реализовано | v1.4 | 26.02.2026 |
| 5 | **Доска объявлений (соседская)** | ✅ Реализовано | v1.5 | 26.02.2026 |
| 6 | **Напоминания о платежах ЖКХ** | ✅ Реализовано | v1.6 | 26.02.2026 |
| 7 | **Детект мультиаккаунтов** | ✅ Реализовано | v1.7 | 26.02.2026 |
| 8 | **Облако тегов тем чата** | ✅ Реализовано | v1.8 | 26.02.2026 |
| 9 | **Рейтинг токсичности** | ✅ Реализовано | v1.9 | 26.02.2026 |
| 10 | **История версий профиля** | ✅ Реализовано | v1.10 | 26.02.2026 |
| 11 | **Веб-интерфейс админа** | ✅ Реализовано | v1.11 | 27.02.2026 |
| 12 | **Достижения жильцов** | ✅ Реализовано | v1.12 | 27.02.2026 |
| 13 | **Система благодарностей** | ✅ Реализовано | v1.13 | 27.02.2026 |
| 14 | **Календарь событий дома** | ✅ Реализовано | v1.14 | 27.02.2026 |
| 15 | **AI-Юрист (NotebookLM)** | 🔮 Будущее | v2.0 | — |

---

## 📋 Текущая версия: v1.0 MVP

**Дата фиксации:** 26 февраля 2026 г.
**Статус:** ✅ Готов к эксплуатации
**Бекап:** `backups/versions/v1.0_mvp_2026-02-26/`

### ✅ Реализованный функционал v1.0:

#### 1. База данных и архитектура
- [x] SQLite + SQLAlchemy (асинхронный)
- [x] 6 таблиц: User, Message, Service, VerificationRequest, SpyLog, Announcement
- [x] Миграции БД
- [x] Автоматическое создание таблиц при старте

#### 2. Пользователи и верификация
- [x] Регистрация через `/start`
- [x] Верификация по номеру квартиры
- [x] Профиль с квартирой и телефоном
- [x] Управление телефоном (`/myphone`, `/add_phone`, `/edit_phone`, `/remove_phone`)
- [x] Несколько жильцов на квартиру (метка 🏠(N))
- [x] Команды `/apt`, `/apt_stats`, `/find`

#### 3. Рейтинг и уровни
- [x] +1 балл за каждое сообщение
- [x] Уровни: Новичок (0-99), Сосед (100-499), Активист (500-999), Лидер (1000+)
- [x] Команды: `/rating`, `/top`, `/rank`
- [x] Только для админов в личке

#### 4. Безопасность
- [x] Детект шпионов (Score 0-100, 8 факторов)
- [x] Анти-мат (3 предупреждения → бан)
- [x] Чёрный список слов (~50 слов)
- [x] Бан/разбан (`/ban`, `/unban`)
- [x] Отзыв верификации (`/unverify`)
- [x] Авто-удаление через 7 дней без верификации
- [x] Логирование подозрительных (`/log_spy`)

#### 5. Админ-панель
- [x] Только в личке (`/admin`)
- [x] Кнопки меню: Статистика, Шпионы, Пользователи, Рассылка, Рейтинг
- [x] Рассылка объявлений (чат + лички)
- [x] Статистика чата (`/stats`)
- [x] Экспорт JSON (`/export`)

#### 6. Телефоны и контакты
- [x] Экстренные службы (103, 101, 102, 104, 112)
- [x] УК и аварийные службы
- [x] Мастера (сантехники, электрики)
- [x] Участковый
- [x] Личные телефоны жильцов

#### 7. Планировщик задач (APScheduler)
- [x] Еженедельный экспорт JSON (воскресенье 03:00)
- [x] Ежедневная проверка шпионов (02:00)
- [x] Обновление активности (ежечасно)

#### 8. Мониторинг чата
- [x] Перехват всех сообщений
- [x] Подсчёт message_count
- [x] Обновление last_seen
- [x] Уведомления о новых участниках

#### 9. Инфраструктура
- [x] Прокси (socks5 через xray)
- [x] Логирование в `logs/bot.log`
- [x] Скрипты управления: `run.sh`, `start.sh`, `stop.sh`
- [x] Виртуальное окружение (venv)

---

## 📁 Структура проекта v1.0

```
domovoy_bot/
├── config.py                 # Конфигурация (токен, админы, прокси)
├── main.py                   # Точка входа
├── requirements.txt          # Зависимости (8 пакетов)
├── .env                      # Переменные окружения
├── .env.example              # Пример .env
├── VERSIONS.md               # Этот файл
│
├── database/
│   ├── __init__.py
│   ├── db.py                 # Асинхронная сессия
│   ├── models.py             # Модели (6 таблиц)
│   └── init_db.py            # Инициализация БД
│
├── handlers/                 # Роутеры aiogram (9 файлов)
│   ├── __init__.py
│   ├── admin.py              # Админ-команды
│   ├── users.py              # Пользовательские команды
│   ├── phones.py             # Телефоны
│   ├── verification.py       # Верификация
│   ├── chat_monitor.py       # Мониторинг чата
│   ├── security.py           # Безопасность
│   ├── apartments.py         # Квартиры
│   └── antimat.py            # Анти-мат
│
├── services/
│   ├── __init__.py
│   ├── spy_detector.py       # Детект шпионов
│   ├── analytics.py          # Аналитика и экспорт
│   └── scheduler.py          # Планировщик
│
├── utils/
│   ├── __init__.py
│   ├── decorators.py         # @admin_only
│   ├── formatters.py         # Форматирование
│   └── validators.py         # Валидация
│
├── keyboards/
│   ├── __init__.py
│   ├── inline.py             # Inline-кнопки
│   ├── admin_menu.py         # Админ-меню
│   └── reply.py              # Reply-кнопки
│
├── data/
│   ├── phones.json           # Телефоны служб
│   ├── bad_words.json        # Чёрный список слов
│   └── spies_patterns.json   # Паттерны шпионов
│
├── logs/                     # Логи
├── exports/                  # JSON экспорты
├── backups/
│   └── versions/             # Версионные бекапы
└── venv/                     # Виртуальное окружение
```

---

## 📊 Метрики проекта v1.0

| Показатель | Значение |
|------------|----------|
| **Строк кода** | ~3500 |
| **Файлов Python** | 25+ |
| **Таблиц БД** | 6 |
| **Хендлеров** | 30+ |
| **Команд бота** | 25+ |
| **Зависимостей** | 8 основных |

---

## 🔄 История версий

### v1.5 — Доска объявлений — 26 февраля 2026

**Статус:** ✅ Реализовано
**Бекап:** `backups/versions/v1.5_ads_2026-02-26/`

**Реализовано:**
- Модель `Ad` — объявления жильцов
- 6 категорий (продам, куплю, отдам, потеряно, нашлось, услуга)
- Пошаговое создание объявлений (/ad)
- Просмотр всех объявлений (/ads)
- Удаление своих объявлений (/ad_del)
- Авто-удаление через 7 дней
- Модерация для админов
- Только для верифицированных

**Файлы:**
- `database/models.py` — модель Ad
- `database/migrate_add_ads.py` — миграция
- `handlers/ads.py` — хендлеры
- `keyboards/inline.py` — клавиатуры
- `services/scheduler.py` — авто-удаление
- `ДОСКА_ОБЪЯВЛЕНИЙ.md` — документация

**Изменения:**
- 11 таблиц БД (было 10)
- +1 хендлер (ads_router)
- +4 команды

---

### v1.4 — Расписание отключений — 26 февраля 2026

**Статус:** ✅ Реализовано
**Бекап:** `backups/versions/v1.4_schedule_2026-02-26/`

**Реализовано:**
- Модель `Schedule` — события отключений
- 6 типов отключений (вода, свет, отопление, газ, лифт, общее)
- Пошаговое создание событий (/schedule_add)
- Просмотр расписания (/график, /schedule)
- Удаление событий (/schedule_del)
- Авто-напоминания за 1 час до начала
- Inline-меню для выбора типа

**Файлы:**
- `database/models.py` — модель Schedule
- `database/migrate_add_schedules.py` — миграция
- `handlers/schedule.py` — хендлеры
- `keyboards/inline.py` — клавиатуры
- `services/scheduler.py` — напоминания
- `РАСПИСАНИЕ_ОТКЛЮЧЕНИЙ.md` — документация

**Изменения:**
- 10 таблиц БД (было 9)
- +1 хендлер (schedule_router)
- +4 команды

---

### v1.3 — Анти-спам лимиты — 26 февраля 2026

**Статус:** ✅ Реализовано
**Бекап:** `backups/versions/v1.3_rate_limits_2026-02-26/`

**Реализовано:**
- Сервис `RateLimiter` — подсчёт сообщений за период
- Авто-удаление сообщений при превышении лимита (10 за 60 сек)
- Система предупреждений (2 → мут на 30 мин)
- Автоматическая проверка истечения мута
- Команды: `/mute`, `/unmute`, `/check_mute`, `/muted`
- Команды: `/rate_stats`, `/user_rate`, `/clear_rate_warnings`

**Файлы:**
- `services/rate_limiter.py` — сервис лимитов
- `handlers/ratelimit.py` — хендлеры
- `handlers/chat_monitor.py` — проверка лимитов
- `database/models.py` — модель MessageRate
- `database/migrate_add_rate_limits.py` — миграция
- `АНТИ-СПАМ_ЛИМИТЫ.md` — документация

**Изменения:**
- 9 таблиц БД (было 8)
- +1 сервис (rate_limiter)
- +1 хендлер (ratelimit_router)
- +7 команд

---

### v1.2 — Чёрный список ссылок — 26 февраля 2026

**Статус:** ✅ Реализовано
**Бекап:** `backups/versions/v1.2_antispam_2026-02-26/`

**Реализовано:**
- Чёрный список доменов (`data/bad_domains.json`)
- Чёрный список паттернов (t.me/spam_, vk.com/scam_)
- Чёрный список ключевых слов (спам-фразы)
- Авто-удаление спам-сообщений
- Система предупреждений (3 → бан)
- Уведомление админа о каждом случае
- Команды: `/add_domain`, `/remove_domain`, `/domains`, `/patterns`, `/keywords`
- Команды: `/warnings`, `/clear_warnings`, `/antispam_stats`

**Файлы:**
- `data/bad_domains.json` — чёрный список
- `services/antispam.py` — сервис проверки
- `handlers/antispam.py` — хендлеры
- `handlers/chat_monitor.py` — проверка ссылок
- `database/models.py` — модель SpamWarning
- `database/migrate_add_spam_warnings.py` — миграция
- `ЧЁРНЫЙ_СПИСОК_ССЫЛОК.md` — документация

**Изменения:**
- 8 таблиц БД (было 7)
- +1 сервис (antispam)
- +1 хендлер (antispam_router)
- +12 команд

---

### v1.1 — Опросы и голосования — 26 февраля 2026

**Статус:** ✅ Зафиксировано
**Бекап:** `backups/versions/v1.0_mvp_2026-02-26/`

**Реализовано:**
- Полный MVP функционал
- Безопасность (анти-мат, детект шпионов)
- Рейтинг пользователей
- Админ-панель с рассылкой
- Учёт квартир и жильцов
- Телефоны служб и мастеров

**Известные ограничения:**
- Нет точной даты создания аккаунта Telegram (API не отдаёт)
- Детект офисных часов требует доработки
- AI-юрист отложен на v2.0

---

## 📝 Процесс разработки

### Рабочий цикл:
1. **Фиксация версии** → бекап текущей версии
2. **Реализация функции** → код + тесты
3. **Проверка** → тестирование на пустой группе (админ + 1 пользователь)
4. **Приёмка** → подтверждение от заказчика
5. **Документирование** → обновление VERSIONS.md
6. **Бекап** → копия в `backups/versions/vX.X/`

### Тестовое окружение:
- **Группа:** Тестовая (2 участника)
- **Админ:** matrixhasyou
- **Пользователь:** друг (тестовый аккаунт)

### Критерии приёмки функции:
- [ ] Функция работает в тестовой группе
- [ ] Нет ошибок в логах
- [ ] Админ получает уведомления
- [ ] Пользователь получает обратную связь
- [ ] Документация обновлена

---

## 🎯 Следующая версия: v1.2

**План:** Чёрный список ссылок

**Функционал:**
- Файл `data/bad_domains.json` со списком доменов
- Проверка всех сообщений на наличие ссылок
- Авто-удаление сообщений со спам-доменами
- Предупреждение пользователю в личку
- Учёт предупреждений (3 → бан)
- Команды: `/add_domain`, `/remove_domain`, `/domains`

**Статус:** ⏳ Ожидает реализации

---

**Дата последнего обновления:** 26 февраля 2026 г.
**Версия документа:** 1.0