Интеллектуальный Telegram-ассистент для автоматизации учета заказов в Google Таблицах.
Бот позволяет превращать неструктурированные текстовые или голосовые сообщения в четкие записи в таблице, используя мощь нейросетей OpenAI. Больше не нужно заполнять ячейки вручную — просто скажите боту детали заказа.
- 🤖 AI-парсинг (GPT-4.1-nano): Извлекает дату, время, адрес, имя клиента и суть проблемы из любого свободного описания.
- 🎙 Голосовой ввод: Поддержка распознавания речи через Whisper API.
- 🔄 Живой интерфейс: Сообщения об обработке автоматически редактируются в карточки заказов с кнопками подтверждения.
- 📝 Умное редактирование: Изменяйте существующие заказы по их номеру, просто написав «измени время на 18:00».
- 📊 Синхронизация с Google Sheets: Мгновенная запись данных в облачную таблицу.
- 💾 Надежное хранение: Состояние пользователя и контекст заказов сохраняются в PostgreSQL.
- Framework: aiogram 3.x (Polling/Webhook)
- API Layer: FastAPI (для Webhook-режима)
- AI Engine: OpenAI SDK (Responses API)
- Database: PostgreSQL + asyncpg
- Cloud Storage: Google Sheets API (gspread)
- Environment: Pydantic Settings
Убедитесь, что у вас установлен Python 3.11 или выше.
# Клонирование репозитория
git clone https://github.com/QurusX/OrderAssistant.git
cd OrderAssistant
# Создание и активация виртуального окружения
python -m venv .venv
source .venv/bin/activate # Для Linux/Mac
.venv\Scripts\activate # Для Windows
# Установка зависимостей
pip install -r requirements.txtСамый простой способ запустить базу данных — использовать Docker. Мы используем порт 5433, чтобы не конфликтовать с другими проектами.
docker run -d \
--name postgres-orderassistant \
-p 5433:5432 \
-e POSTGRES_PASSWORD=postgres \
-e POSTGRES_DB=orderassistant \
postgres:15Создайте файл .env в корне проекта и заполните его:
# Telegram
TELEGRAM_BOT_TOKEN=your_bot_token_from_botfather
# База данных (порт 5433 для локального Docker)
POSTGRES_DSN=postgresql://postgres:postgres@localhost:5433/orderassistant
# Google Sheets
GSHEETS_DOC_ID=1x7MTA5y7bRRNS2jb2Y9WoxNVozgk9nu9RmQc8YVSqDA
# Весь JSON сервисного аккаунта одной строкой или путь к файлу
GSHEETS_CREDENTIALS_JSON={"type": "service_account", ...}
# OpenAI (Официальный API)
OPENAI_API_KEY=sk-proj-your_official_key- Создайте сервисный аккаунт в Google Cloud Console.
- Скачайте JSON-ключ и добавьте его в
.env. - Скопируйте
client_emailиз этого JSON. - Откройте вашу Google Таблицу и нажмите Поделиться (Share).
- Добавьте email сервисного аккаунта с правами Редактор.
Запустите бота в режиме опроса (polling):
python run_local.py/startили/menu— Показать приветствие и инструкцию./add_order— Начать добавление нового заказа (пришлите текст или голос)./edit_order— Редактировать существующий заказ (бот попросит номер заказа).
OrderAssistant/
├── app/
│ ├── bot/
│ │ ├── handlers.py # Логика обработки команд и сообщений
│ │ ├── keyboards.py # Инлайн-клавиатуры
│ │ └── texts.py # Все тексты и шаблоны сообщений
│ ├── services/
│ │ ├── llm_service.py # Работа с OpenAI Responses API
│ │ ├── stt_service.py # Распознавание голоса (Whisper)
│ │ ├── order_service.py # Бизнес-логика заказов
│ │ └── user_service.py # Управление состоянием пользователей
│ ├── db.py # Асинхронный клиент PostgreSQL
│ ├── sheets.py # Клиент Google Sheets
│ ├── models.py # Pydantic модели данных
│ └── config.py # Валидация настроек через Pydantic
├── run_local.py # Скрипт для локального запуска (Polling)
├── requirements.txt # Список зависимостей
└── .env # Конфиденциальные данные (не для git)
Для развертывания в облаке (например, Amvera) используйте:
python -m app.mainНе забудьте указать WEBHOOK_URL в переменных окружения.
Разработано с ❤️ для автоматизации бизнеса.
