Robotail/BUH_bot
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
BUH_bot/README.md

14 KiB
Raw Blame History

Бот для бухгалтеров

Telegram-бот для автоматизации работы бухгалтеров: получение данных из МойСклад, валидация и генерация документов (УПД, ТН) в форматах XML (ВерсФорм 5.03, 1С EnterpriseData 1.20) и Excel.

🔐 Многопользовательская система

Каждый пользователь работает со своим личным кабинетом МойСклад!

  • Авторизация при первом запуске через /start
  • Учетные данные шифруются и хранятся безопасно
  • Возможность смены credentials через /change_credentials
  • Выход из аккаунта через /logout

📖 Подробнее: docs/MULTI_USER_AUTH.md

🚀 Возможности

  • 📦 Интеграция с МойСклад - автоматическое получение данных о заказах через API
  • ✅ Валидация данных - проверка обязательных и желательных полей (ИНН, КПП, адреса, товары)
  • 📄 Генерация XML - создание документов в форматах ВерсФорм 5.03 (УПД/ТН) и 1С EnterpriseData 1.20 (Реализация)
  • 📊 Генерация Excel - выгрузка в форматы УПД и ТОРГ-12
  • 🤖 Telegram интерфейс - удобное управление через бота

📋 Требования

  • Python 3.10+
  • Аккаунт МойСклад с API доступом
  • Telegram Bot Token

🛠️ Установка

Вариант 1: Docker (рекомендуется) 🐳

Development

Преимущества:

  • Изолированное окружение
  • Простое развертывание
  • Автоматический перезапуск
  • Управление ресурсами

Linux/Mac:

# Клонирование
git clone <repository_url>
cd BUH_bot

# Настройка
cp .env.example .env
nano .env  # Укажите TELEGRAM_BOT_TOKEN

# Запуск
chmod +x start.sh
./start.sh

Windows:

git clone <repository_url>
cd BUH_bot

copy .env.example .env
notepad .env

start.bat

📖 Подробная документация: docs/DOCKER_QUICKSTART.md
📚 Полное руководство: docs/DOCKER_GUIDE.md

Production 🚀

Для production используется docker-compose с готовыми образами, мониторингом и автообновлением:

Компоненты:

  • ✅ BUH Bot из registry (ghcr.io)
  • ✅ Nginx reverse proxy
  • ✅ Prometheus + Grafana мониторинг
  • ✅ Watchtower автообновление
  • ✅ Автоматический backup

Быстрый деплой:

# 1. Сборка и публикация образа
./build-image.sh

# 2. Настройка production
cp .env.prod.example .env.prod
nano .env.prod  # TELEGRAM_BOT_TOKEN и др.

# 3. Деплой
./deploy-prod.sh

Или через Makefile:

make prod-build  # Собрать образ
make prod-up     # Запустить production
make prod-logs   # Логи

Мониторинг:

  • 📊 Grafana: http://your-server:3000
  • 📈 Prometheus: http://your-server:9090
  • 🐳 cAdvisor: http://your-server:8080

📖 Production документация: docs/PRODUCTION_DEPLOYMENT.md

Вариант 2: Локальная установка

  1. Клонируйте репозиторий
git clone <repository_url>
cd BUH_bot
  1. Создайте виртуальное окружение
python -m venv venv
source venv/bin/activate  # Linux/Mac
# или
venv\Scripts\activate  # Windows
  1. Установите зависимости
pip install -r requirements.txt
  1. Настройте переменные окружения
cp .env.example .env

Отредактируйте .env и укажите:

  • TELEGRAM_BOT_TOKEN - токен Telegram бота

⚠️ ВАЖНО: MOYSKLAD_LOGIN и MOYSKLAD_PASSWORD больше не нужны!
Каждый пользователь вводит свои учетные данные МойСклад при первом запуске бота через /start.

  1. Создайте Telegram бота
    • Откройте @BotFather в Telegram
    • Отправьте команду /newbot
    • Следуйте инструкциям и получите токен
    • Вставьте токен в .env

🚀 Запуск

Docker (рекомендуется)

# Linux/Mac
./start.sh

# Windows
start.bat

# Или напрямую
docker-compose up -d

Управление:

# Логи
docker-compose logs -f

# Остановка
docker-compose down

# Перезапуск
docker-compose restart

Локальный запуск

python bot.py

Первое использование

  1. Отправьте /start боту в Telegram
  2. Введите ваш логин от МойСклад
  3. Введите ваш пароль от МойСклад (сообщение будет удалено)
  4. Бот проверит учетные данные и сохранит их в зашифрованном виде
  5. Начните работу!

Управление учетными данными

  • /change_credentials - сменить логин/пароль
  • /logout - выйти из аккаунта и удалить данные

📖 Использование

Команды бота

  • /start - Начало работы / авторизация в МойСклад
  • /help - Справка по использованию
  • /logout - Выход из аккаунта (удаление учетных данных)
  • /change_credentials - Смена логина/пароля МойСклад
  • 🔍 Поиск отгрузки - Найти отгрузку по номеру заказа
  • 📋 Список отгрузок - Показать последние отгрузки

Пример работы

  1. Первый запуск:

    • Отправьте /start
    • Введите логин МойСклад
    • Введите пароль МойСклад (сообщение удаляется автоматически)

  2. Поиск отгрузки:

    • Нажмите 🔍 Поиск отгрузки
    • Введите номер заказа (например: 951)

  3. Работа с отгрузкой:

    • Выберите отгрузку из списка
    • Просмотрите результаты валидации
    • Выберите формат документа: 📄 XML или 📊 Excel
    • Для Excel бот автоматически рекомендует УПД или ТН в зависимости от типа контрагента
    • Получите готовый файл

📁 Структура проекта

BUH_bot/
├── .env                          # Переменные окружения (только TELEGRAM_BOT_TOKEN)
├── .env.example                  # Пример настроек
├── .gitignore                    # Игнорируемые файлы
├── requirements.txt              # Зависимости Python
├── config.py                     # Конфигурация приложения
├── bot.py                        # Основной файл бота (точка входа)
├── users.json                    # Зашифрованные данные пользователей (не в Git!)
├── .encryption_key               # Ключ шифрования (не в Git!)
│
├── docs/                         # Документация
│   ├── MULTI_USER_AUTH.md        # Описание системы авторизации
│   ├── PROJECT_STRUCTURE.md      # Структура проекта
│   └── CHANGES_2025-11-03.md     # История изменений
│
├── modules/                      # Модули приложения
│   ├── __init__.py
│   ├── moysklad_client.py        # API клиент МойСклад
│   ├── validator.py              # Валидация данных заказов
│   ├── xml_generator.py          # Генерация XML (ВерсФорм 5.03)
│   └── user_manager.py           # ⭐ NEW: Управление пользователями и credentials
│
├── scripts/                      # Вспомогательные скрипты
│   └── __init__.py
│
└── temp_documents/               # Временные файлы (не в Git!)

🔍 Валидация данных

Бот проверяет следующие данные:

Обязательные поля (❌ CRITICAL)

  • Продавец: ИНН, КПП, наименование, юридический адрес
  • Покупатель: ИНН, КПП, наименование, юридический адрес
  • Товары: наименование, количество, цена, ставка НДС
  • Заказ: номер, дата, сумма

Желательные поля (⚠️ WARNING)

  • ОГРН/ОГРНИП
  • Расчетный счет и банк
  • Контактные данные
  • Единицы измерения товаров

Валидация форматов

  • ИНН: 10 цифр (юр. лица) или 12 цифр (ИП) + контрольная сумма
  • КПП: 9 цифр
  • ОГРН: 13 цифр (юр. лица) или 15 цифр (ИП)
  • НДС: корректные ставки (0%, 10%, 20%, без НДС)
  • Суммы: положительные числа, соответствие итогов

📄 Форматы документов

XML (ВерсФорм 5.03) - для ФНС

  • УПД - Универсальный передаточный документ (Счет-фактура + ТОРГ-12)
  • ТН - Товарная накладная (ТОРГ-12)

Соответствие приказу ФНС России для электронного документооборота.

XML (1С EnterpriseData 1.20) - для загрузки в 1С

  • Документ реализации товаров и услуг - прямая загрузка в конфигурации 1С

📖 Подробная документация: docs/XML_1C_FORMAT.md

Excel

  • УПД - Печатная форма с полными реквизитами
  • ТОРГ-12 - Товарная накладная

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

⚠️ Важно:

  • Никогда не коммитьте .env в репозиторий
  • Храните учетные данные в безопасности
  • Используйте HTTPS для всех API запросов
  • Регулярно обновляйте зависимости

🐛 Устранение неполадок

Ошибка авторизации в МойСклад

  • Проверьте правильность логина и пароля
  • Убедитесь, что у аккаунта есть API доступ
  • Проверьте подключение к интернету
  • Попробуйте /change_credentials для смены данных

Ошибка: "Invalid token" (Telegram)

  • Проверьте корректность токена в .env
  • Убедитесь, что бот активен в BotFather

Потеря доступа к данным

⚠️ Если файл .encryption_key был удален или поврежден:

  • Все сохраненные учетные данные станут недоступны
  • Пользователям нужно заново пройти авторизацию через /start

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

  • Убедитесь, что файл users.json доступен для записи
  • Проверьте, что .encryption_key существует
  • Смотрите логи бота для детальной информации

📚 Документация

🤝 Поддержка

При возникновении вопросов или проблем:

  1. Проверьте раздел "Устранение неполадок"
  2. Изучите PROJECT_PLAN.md для детального описания
  3. Проверьте логи в консоли

📝 Лицензия

MIT License

🎯 Roadmap

  • ✅ Многопользовательская система авторизации
  • ✅ Шифрование учетных данных пользователей
  • ✅ Интеграция с МойСклад API
  • ✅ Валидация данных отгрузок
  • ✅ Генерация XML (УПД 5.03)
  • ✅ Генерация Excel через API МойСклад
  • ✅ Умная рекомендация шаблонов (ТН для физ.лиц, УПД для юр.лиц/ИП)
  • База данных для истории генерации
  • Автоматические уведомления о новых заказах
  • Генерация PDF печатных форм
  • Электронная подпись XML документов
  • Интеграция с 1С:Бухгалтерия
  • OAuth авторизация МойСклад
  • Webhook режим для бота

Сделано с ❤️ для бухгалтеров