domovoy_bot/PROJECT_STRUCTURE.md

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

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

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/                  # Бэкапы БД

---

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

# 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)

# 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)

---

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