# Volunteer Center Bot (Волонтерский Центр НИЯУ МИФИ Бот)

## Описание

Этот проект представляет собой Telegram-бота, разработанного для Волонтерского Центра НИЯУ МИФИ. Бот предоставляет функционал для регистрации пользователей, управления рассылками и взаимодействия с администраторами.

## Основной функционал:

1.  **Регистрация пользователей:**
    *   Позволяет новым пользователям зарегистрироваться в системе бота.
    *   Данные пользователей сохраняются в базе данных.

2.  **Подписка/Отписка от рассылки:**
    *   Пользователи могут подписываться на рассылку сообщений от администраторов.
    *   Пользователи могут отписываться от рассылки в любое время.

3.  **Рассылка сообщений:**
    *   Администраторы могут отправлять сообщения пользователям, подписанным на рассылку.
    *   Поддерживаются два формата сообщений: короткий и длинный.

4.  **Статистика рассылки:**
    *   Предоставляет администраторам информацию об объеме рассылки (например, количество получателей).

## Технологии:

*   **Python:** Основной язык программирования.
*   **aiogram:** Библиотека для создания Telegram-ботов.
*   **SQLAlchemy:** ORM для работы с базой данных.
*   **PostgreSQL:** Используется в качестве базы данных.
*   **dotenv:** Для управления переменными окружения.
*   **FSM (Finite State Machine):** Для управления состояниями бота.
* **MemoryStorage:** Хранилище состояний в оперативной памяти.

## Структура проекта:

*   **`main.py`:** Основной файл, запускающий бота.
*   **`handlers/`:** Директория, содержащая обработчики событий (хендлеры) для различных типов пользователей (обычные пользователи, администраторы) и callback-запросов.
    *   `user.py`: Обработчики для обычных пользователей.
    *   `admin.py`: Обработчики для администраторов.
    *   `admin_adv.py`: Обработчики для рассылки сообщений администраторами.
    *   `adv_callbacks.py`: Обработчики для callback-запросов, связанных с рассылкой.
*   **`database/`:** Директория, содержащая код для работы с базой данных.
    *   `__init__.py`: Инициализация модуля.
*   **`.env`:** Файл с переменными окружения (например, токен бота).
*   **`README.md`:** Этот файл.

## Установка и запуск:

1.  **Клонируйте репозиторий:**
    ```bash
    git clone https://github.com/ada-dmitry/vol_bot
    cd vol_bot
    ```

2.  **Создайте виртуальное окружение (рекомендуется):**
    ```bash
    python3 -m venv venv
    source venv/bin/activate  # Linux/macOS
    venv\Scripts\activate  # Windows
    ```

3.  **Установите зависимости:**
    ```bash
    pip install -r requirements.txt
    ```
    (Если у вас нет файла `requirements.txt`, то установите зависимости вручную: `pip install aiogram python-dotenv sqlalchemy`)

4.  **Создайте файл `.env`:**
    *   Скопируйте содержимое файла `.env.example` в новый файл `.env`.
    *   Замените `BOT_TOKEN` на токен вашего бота, полученный от BotFather.

5.  **Запустите бота:**
    ```bash
    python main.py
    ```

## Разработка:

*   Для добавления нового функционала создавайте новые обработчики в соответствующих файлах директории `handlers/`.
*   Для работы с базой данных используйте SQLAlchemy.
*   Для управления состояниями бота используйте FSM.

## Планы по развитию:

*   Добавление новых команд и функций.
*   Улучшение интерфейса взаимодействия с пользователем.
*   Расширение возможностей администраторов.
*   Добавление логирования.
*   Добавление тестов.

## Контакты
Другие проекты: [GitHub](https://github.com/ada-dmitry)  
По вопросам и предложениям обращайтесь: [TG - Дмитрий](https://t.me/ada_dmitry)