# Домовой бот - Структура проекта

## 📁 Структура файлов

```
domovoy_bot/
├── config.py                 # Конфигурация (токены, настройки)
├── main.py                   # Точка входа
├── requirements.txt          # Зависимости
├── .env                      # Переменные окружения (не в git!)
├── .env.example              # Пример .env
├── .gitignore
│
├── database/
│   ├── __init__.py
│   ├── db.py                 # Подключение к БД
│   ├── models.py             # SQLAlchemy модели
│   └── init_db.py            # Скрипт инициализации БД
│
├── handlers/
│   ├── __init__.py
│   ├── admin.py              # Админские команды (статистика, шпионы)
│   ├── users.py              # Пользовательские команды
│   ├── verification.py       # Верификация жильцов
│   └── chat_monitor.py       # Мониторинг чата
│
├── services/
│   ├── __init__.py
│   ├── spy_detector.py       # Детект «шпионов» УК
│   ├── analytics.py          # Аналитика и экспорт JSON
│   ├── notifications.py      # Уведомления жильцам
│   └── scheduler.py          # Планировщик задач (cron)
│
├── keyboards/
│   ├── __init__.py
│   ├── inline.py             # Inline-кнопки
│   └── reply.py              # Reply-кнопки
│
├── utils/
│   ├── __init__.py
│   ├── validators.py         # Валидация данных
│   ├── formatters.py         # Форматирование сообщений
│   └── decorators.py         # Декораторы (admin_only и т.д.)
│
├── data/
│   ├── phones.json           # Телефоны экстренных служб
│   ├── spies_patterns.json   # Паттерны поведения шпионов
│   └── templates/            # Шаблоны сообщений
│
├── logs/                     # Логи бота
├── exports/                  # JSON экспорты чата
└── backups/                  # Бэкапы БД
```

---

## 🚀 Быстрый старт

```bash
# 1. Клонировать/создать структуру
cd domovoy_bot

# 2. Создать виртуальное окружение
python3 -m venv venv
source venv/bin/activate  # Linux
# или
venv\Scripts\activate     # Windows

# 3. Установить зависимости
pip install -r requirements.txt

# 4. Настроить окружение
cp .env.example .env
# Отредактировать .env, вставить токен бота

# 5. Инициализировать БД
python database/init_db.py

# 6. Запустить бота
python main.py
```

---

## 🔧 Зависимости (requirements.txt)

```
aiogram==3.6.0              # Telegram бот (асинхронный)
sqlalchemy==2.0.23          # Работа с БД
aiosqlite==0.19.0           # SQLite для начала
apscheduler==3.10.4         # Планировщик задач
python-dotenv==1.0.0        # Переменные окружения
pandas==2.1.4               # Аналитика данных
aiohttp==3.9.1              # HTTP запросы
```

---

## ⚙️ Конфигурация (.env)

```ini
# Telegram
BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
ADMIN_CHAT_ID=-1001234567890    # ID основного чата
ADMIN_USER_ID=123456789         # Твой Telegram ID

# База данных
DATABASE_PATH=./database/domovoy.db

# Экспорт
EXPORT_DIR=./exports
EXPORT_SCHEDULE=0 3 * * 0      # Каждое воскресенье в 03:00

# Детект шпионов
SPY_DETECTION_ENABLED=true
SPY_ALERT_USER_ID=123456789    # Куда слать тревоги

# Логирование
LOG_LEVEL=INFO
LOG_FILE=./logs/bot.log
```

---

## 📊 Админские функции (только тебе)

| Команда | Описание |
|---------|----------|
| `/admin` | Главное меню админа |
| `/stats` | Статистика чата за период |
| `/spies` | Подозрительные аккаунты |
| `/export` | Принудительный экспорт JSON |
| `/users` | Список всех жильцов |
| `/unverified` | Непроверенные участники |
| `/activity` | Рейтинг активности |
| `/broadcast` | Рассылка всем жильцам |

---

## 📱 Пользовательские команды (жильцам)

| Команда | Кнопка | Описание |
|---------|--------|----------|
| `/старт` | — | Регистрация |
| `/помощь` | 🔘 Помощь | Список команд |
| `/телефон` | 📞 Телефоны | Экстренные службы |
| `/мастера` | 🔘 Мастера | Сантехники/электрики |
| `/график` | 🔘 График | Отключения воды/света |
| `/объявления` | 🔘 Объявления | Новости дома |
| `/продам` | 🔘 Продать | Разместить объявление |
| `/моя_квартира` | 🔘 Моя квартира | Проверка привязки |

---

## 🕵️ Детект шпионов — алгоритм

Бот отслеживает в фоне и присваивает «рейтинг подозрительности» (0-100):

```
Факторы:
├─ Аккаунт создан < 7 дней: +20
├─ Нет аватарки: +10
├─ Ник вида user12345: +15
├─ Не прошёл верификацию > 24ч: +25
├─ Пишет только провокации: +30
├─ Активность 9:00-18:00 пн-пт: +15
├─ Мультиаккаунт (same device): +50
└─ Жалобы от жильцов: +10 за каждую

Пороги:
├─ 0-30: Норма (зелёный)
├─ 31-60: Подозрительно (жёлтый) → пометка в базе
└─ 61-100: Шпион! (красный) → уведомление админу
```

---

## 📈 Следующие шаги

1. ✅ Создать структуру файлов
2. ✅ Написать `config.py` и `requirements.txt`
3. ✅ Создать модели БД (`database/models.py`)
4. ✅ Написать базового бота (`main.py`)
5. ✅ Реализовать верификацию (`handlers/verification.py`)
6. ✅ Сделать админские команды (`handlers/admin.py`)
7. ✅ Детект шпионов (`services/spy_detector.py`)
8. ✅ Экспорт JSON (`services/analytics.py`)
9. ✅ Инлайн-меню для жильцов (`keyboards/inline.py`)
10. ✅ Телефоны служб (`data/phones.json`)

---

**Готов начать? Создаю файлы!**