📬 Почтовое Бюро - Telegram Bot & Web App

📖 Описание проекта

Почтовое Бюро — это современный Telegram бот с Web App интерфейсом, предназначенный для организации встреч, приема писем и управления заказами. Проект сочетает в себе удобство Telegram бота с мощью Web приложений для создания полноценной системы почтовых услуг.

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

• 📅 Организация встреч — гибкое планирование встреч по временным диапазонам.
• 💌 Прием писем — отправка различных типов открыток с уникальными характеристиками.
• 📋 Управление заказами — полный цикл от оформления до доставки.
• 👥 Система ролей — динамическое присвоение ролей пользователям.
• 📊 Аналитика — подробная статистика и графики.
• 📱 Mobile-first дизайн — адаптивный интерфейс для всех устройств.

🚀 Основные функции

Для пользователей

📲 Web App Интерфейс

• Выбор даты и времени встречи — интуитивный календарь с доступными слотами.
• Оформление открыток — 3 типа открыток с разными характеристиками:
  • 🔴 Красные - срочные письма с приоритетной доставкой.
  • 🔵 Синие - стандартные письма с обычной доставкой.
  • 🟢 Зеленые - секретные письма с дополнительной защитой.
• Персонализация — выбор места встречи, анонимная отправка, задержка доставки.
• История заказов — просмотр всех отправленных писем и их статусов.

🤖 Telegram Bot

• Команды: /start, /help.
• Кнопки:
  • 📅 Записаться на встречу
  • 📬 Мои письма
  • 👑 Админ панель (для администраторов)

Для администраторов

👑 Админ панель

• Управление временем — создание, настройка и активация временных слотов для встреч.
• Управление локациями — добавление и редактирование мест встреч.
• Управление заказами — просмотр, фильтрация, подтверждение и отмена заказов с уведомлением пользователей.
• Аналитика — дашборд с ключевыми метриками, графиками и статистикой.

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

project/
├── 📁 database/         # База данных SQLite и схема
├── 📁 handlers/         # Обработчики Telegram бота (user, admin)
├── 📁 web_app/          # Web App интерфейс (HTML, CSS, JS)
├── 📁 services/         # Сервисные модули (заказы, статистика, уведомления)
├── 📁 keyboards/        # Клавиатуры Telegram
├── 📁 utils/            # Утилиты (QR, время, валидация)
├── web_app_server.py     # Flask сервер для Web App
├── config.py             # Конфигурация
├── requirements.txt      # Зависимости Python
└── main.py               # Точка входа бота

🛠️ Технологии

Категория Технология

• Backend Python 3.11, Aiogram 3.3, Flask 2.3, SQLite 3, Aiosqlite
• Frontend HTML5, CSS3, Vanilla JavaScript, Telegram Web App API
• Инструменты Ngrok, Matplotlib, APScheduler

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

Требования

Python 3.11+
Ngrok (для локальной разработки)
Docker (опционально)

1. Клонирование репозитория

git clone <repository-url>
cd postal-bureau

2. Установка зависимостей

python -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate    # Windows
pip install -r requirements.txt

3. Настройка конфигурации

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

BOT_TOKEN=ваш_токен_бота
ADMIN_IDS=ваш_telegram_id
WEB_APP_URL=https://ваш_домен.ngrok.io
DATABASE_PATH=database/bot.db

4. Запуск

# 1. Запустите туннель Ngrok и скопируйте HTTPS URL в WEB_APP_URL
ngrok http 8080

# 2. Запустите Web App сервер в одном терминале
python web_app_server.py

python main.py

🎨 Дизайн и UX

• Mobile-first подход: Адаптивный дизайн, touch-friendly интерфейс и - оптимизированные формы.
• Визуальные элементы: Современный градиентный фон, карточки контента для четкой структуры, цветовая кодировка статусов и плавные анимации.

🔒 Безопасность

• Аутентификация: Идентификация по Telegram ID и защита админ-панели.
• Защита данных: Использование параметризованных запросов (защита от - SQL-инъекций), CORS политики и валидация данных на стороне сервера.

📈 Аналитика и роли

• Дашборд администратора: Ключевые метрики (заказы, пользователи) и графики (динамика заказов, популярность локаций).
• Система ролей: Динамическое присвоение ролей пользователям в зависимости от их активности: 📬 Почемар → 📮 Старший почемар → 📭 Почтальон → 👑 Почтмейстер