Self_Storage

Данный проект представляет собой Telegram-бот для сервиса хранения вещей (Self Storage). Бот поддерживает клиентские сценарии (оформление хранения, забор вещей, напоминания), а также операторские сценарии (обработка заявок, подтверждение/отмена, отчеты и ручные уведомления).

Основные возможности

• Оформление хранения: самопривоз или забор курьером
• Согласие на обработку персональных данных (PDF)
• Выбор объема, срока хранения в днях, промокода
• Сценарии для уже действующей аренды: частичный/полный забор, возврат в ячейку
• Генерация QR-кода для выдачи вещей
• Email + Telegram напоминания по срокам аренды
• Операторские команды: новые заявки, подтверждение, отмена с причиной, завершение, отчеты
• Услуги для юрлиц (стеллажи по фиксированной цене)

Архитектура проекта

Программа состоит из оркестратора и вспомогательных модулей:

main.py                     # Основной оркестратор (бот, FSM-сценарии, команды оператора)

utils/db_utils.py           # Работа с database.json, синхронизация занятости ячеек
utils/helpers.py            # Вспомогательные функции (валидация, расчеты, форматирование)
utils/get_qr.py             # Генерация PNG QR-кода для выдачи
utils/keyboards.py          # Reply-клавиатуры
utils/mailer.py             # Отправка email (в т.ч. с детальной диагностикой ошибок)
utils/reminders.py          # Автоматические напоминания по аренде
utils/ui_helpers.py         # Дополнительные клавиатуры и UI-хелперы
utils/states.py             # (Опционально) Enum состояний

Данные и хранилище

Используется файл database.json как локальная БД. Ключевые сущности:

• users
• cells
• rental_agreements
• delivery_requests
• items
• reminders
• overdue_tariffs

Настройка переменных окружения

Создайте .env в корне проекта:

# Telegram
TG_TOKEN='ваш_токен_бота'
TG_CHAT_ID='telegram_id_оператора_для_уведомлений'
ADMIN_TG_ID='telegram_id_админа'

# Email (Yandex SMTP)
YANDEX_LOGIN='ваш_ящик@yandex.ru'
YANDEX_TOKEN='пароль_приложения_яндекса'

Важно:

• YANDEX_TOKEN должен быть именно паролем приложения, а не обычным паролем аккаунта.

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

pip install -r requirements.txt
python main.py

Клиентский сценарий (кратко)

1. /start
2. Хочу хранить вещи
3. Необходимо забрать или Отвезу сам
4. Согласие на ПД
5. Адрес, телефон, email
6. Объем
7. Срок хранения (в днях)
8. Промокод (или пропуск)
9. Сезонные вещи (да/нет; если да — список вещей текстом)
10. Подтверждение заявки

Операторские команды

/orders                                  # Количество договоров аренды
/pending_orders                          # Список новых заявок (pending)
/approve_order <id>                      # Подтвердить заявку
/reject_order <id> <причина>             # Отклонить заявку с причиной
/approved_orders                         # Список активных подтвержденных договоров
/complete_order <id>                     # Завершить заявку (для full_takeout освобождает ячейку)
/overdue_calls                           # Просроченные аренды для обзвона
/ads_report                              # Отчет по источникам рекламы (/start <source>)
/run_reminders                           # Ручной запуск авто-напоминаний
/operator_reminder <qr_code> <days_left> # Ручное напоминание клиенту (TG + email)

Также в админ-меню есть кнопка Команды оператора с памяткой и примерами.

Напоминания

Автоматические напоминания отправляются:

• за 30/14/7/3 дня до окончания аренды
• при просрочке: в 1-й день и затем каждые 30 дней
• отдельное уведомление на 180-й день просрочки

Канал отправки:

• Telegram клиенту
• Email клиенту (если email заполнен)

QR-коды

При сценариях самовывоза для полного/частичного забора бот отправляет QR-код и информацию по выдаче:

• договор
• ячейка
• адрес склада

Mind map

Mind карту можно открыть через draw.io:

• https://www.drawio.com/
• https://drive.google.com/file/d/1DQEvq8WbMg-lwlx0_VHDJxjORkHve8Qq/view?usp=sharing