Игорь Надеин
e24ef22337
- Implement per-user МойСклад credentials storage - Add Fernet encryption for passwords (AES-128) - Add UserManager module for credential management - Add /logout and /change_credentials commands - Update bot.py with AUTH_LOGIN/AUTH_PASSWORD states - Each user works with their own МойСклад account - Credentials stored in encrypted users.json
355 lines
14 KiB
Markdown
355 lines
14 KiB
Markdown
# Бот для бухгалтеров
|
||
|
||
Telegram-бот для автоматизации работы бухгалтеров: получение данных из МойСклад, валидация и генерация документов (УПД, ТН) в форматах XML (ВерсФорм 5.03) и Excel.
|
||
|
||
## 🔐 Многопользовательская система
|
||
|
||
**Каждый пользователь работает со своим личным кабинетом МойСклад!**
|
||
|
||
- Авторизация при первом запуске через `/start`
|
||
- Учетные данные шифруются и хранятся безопасно
|
||
- Возможность смены credentials через `/change_credentials`
|
||
- Выход из аккаунта через `/logout`
|
||
|
||
📖 Подробнее: [docs/MULTI_USER_AUTH.md](docs/MULTI_USER_AUTH.md)
|
||
|
||
## 🚀 Возможности
|
||
|
||
- 📦 **Интеграция с МойСклад** - автоматическое получение данных о заказах через API
|
||
- ✅ **Валидация данных** - проверка обязательных и желательных полей (ИНН, КПП, адреса, товары)
|
||
- 📄 **Генерация XML** - создание документов в формате ВерсФорм 5.03 (УПД/ТН)
|
||
- 📊 **Генерация Excel** - выгрузка в форматы УПД и ТОРГ-12
|
||
- 🤖 **Telegram интерфейс** - удобное управление через бота
|
||
|
||
## 📋 Требования
|
||
|
||
- Python 3.10+
|
||
- Аккаунт МойСклад с API доступом
|
||
- Telegram Bot Token
|
||
|
||
## 🛠️ Установка
|
||
|
||
### Вариант 1: Docker (рекомендуется) 🐳
|
||
|
||
#### Development
|
||
|
||
**Преимущества:**
|
||
- Изолированное окружение
|
||
- Простое развертывание
|
||
- Автоматический перезапуск
|
||
- Управление ресурсами
|
||
|
||
**Linux/Mac:**
|
||
```bash
|
||
# Клонирование
|
||
git clone <repository_url>
|
||
cd BUH_bot
|
||
|
||
# Настройка
|
||
cp .env.example .env
|
||
nano .env # Укажите TELEGRAM_BOT_TOKEN
|
||
|
||
# Запуск
|
||
chmod +x start.sh
|
||
./start.sh
|
||
```
|
||
|
||
**Windows:**
|
||
```cmd
|
||
git clone <repository_url>
|
||
cd BUH_bot
|
||
|
||
copy .env.example .env
|
||
notepad .env
|
||
|
||
start.bat
|
||
```
|
||
|
||
📖 Подробная документация: [docs/DOCKER_QUICKSTART.md](docs/DOCKER_QUICKSTART.md)
|
||
📚 Полное руководство: [docs/DOCKER_GUIDE.md](docs/DOCKER_GUIDE.md)
|
||
|
||
#### Production 🚀
|
||
|
||
Для production используется docker-compose с готовыми образами, мониторингом и автообновлением:
|
||
|
||
**Компоненты:**
|
||
- ✅ BUH Bot из registry (ghcr.io)
|
||
- ✅ Nginx reverse proxy
|
||
- ✅ Prometheus + Grafana мониторинг
|
||
- ✅ Watchtower автообновление
|
||
- ✅ Автоматический backup
|
||
|
||
**Быстрый деплой:**
|
||
```bash
|
||
# 1. Сборка и публикация образа
|
||
./build-image.sh
|
||
|
||
# 2. Настройка production
|
||
cp .env.prod.example .env.prod
|
||
nano .env.prod # TELEGRAM_BOT_TOKEN и др.
|
||
|
||
# 3. Деплой
|
||
./deploy-prod.sh
|
||
```
|
||
|
||
**Или через Makefile:**
|
||
```bash
|
||
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](docs/PRODUCTION_DEPLOYMENT.md)
|
||
|
||
### Вариант 2: Локальная установка
|
||
|
||
1. **Клонируйте репозиторий**
|
||
```bash
|
||
git clone <repository_url>
|
||
cd BUH_bot
|
||
```
|
||
|
||
2. **Создайте виртуальное окружение**
|
||
```bash
|
||
python -m venv venv
|
||
source venv/bin/activate # Linux/Mac
|
||
# или
|
||
venv\Scripts\activate # Windows
|
||
```
|
||
|
||
3. **Установите зависимости**
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
4. **Настройте переменные окружения**
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
Отредактируйте `.env` и укажите:
|
||
- `TELEGRAM_BOT_TOKEN` - токен Telegram бота
|
||
|
||
⚠️ **ВАЖНО:** `MOYSKLAD_LOGIN` и `MOYSKLAD_PASSWORD` больше не нужны!
|
||
Каждый пользователь вводит свои учетные данные МойСклад при первом запуске бота через `/start`.
|
||
|
||
5. **Создайте Telegram бота**
|
||
- Откройте [@BotFather](https://t.me/BotFather) в Telegram
|
||
- Отправьте команду `/newbot`
|
||
- Следуйте инструкциям и получите токен
|
||
- Вставьте токен в `.env`
|
||
|
||
## 🚀 Запуск
|
||
|
||
### Docker (рекомендуется)
|
||
|
||
```bash
|
||
# Linux/Mac
|
||
./start.sh
|
||
|
||
# Windows
|
||
start.bat
|
||
|
||
# Или напрямую
|
||
docker-compose up -d
|
||
```
|
||
|
||
**Управление:**
|
||
```bash
|
||
# Логи
|
||
docker-compose logs -f
|
||
|
||
# Остановка
|
||
docker-compose down
|
||
|
||
# Перезапуск
|
||
docker-compose restart
|
||
```
|
||
|
||
### Локальный запуск
|
||
|
||
```bash
|
||
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)
|
||
|
||
Соответствие приказу ФНС России для электронного документооборота.
|
||
|
||
### Excel
|
||
- **УПД** - Печатная форма с полными реквизитами
|
||
- **ТОРГ-12** - Товарная накладная
|
||
|
||
## 🔐 Безопасность
|
||
|
||
⚠️ **Важно**:
|
||
- Никогда не коммитьте `.env` в репозиторий
|
||
- Храните учетные данные в безопасности
|
||
- Используйте HTTPS для всех API запросов
|
||
- Регулярно обновляйте зависимости
|
||
|
||
## 🐛 Устранение неполадок
|
||
|
||
### Ошибка авторизации в МойСклад
|
||
- Проверьте правильность логина и пароля
|
||
- Убедитесь, что у аккаунта есть API доступ
|
||
- Проверьте подключение к интернету
|
||
- Попробуйте `/change_credentials` для смены данных
|
||
|
||
### Ошибка: "Invalid token" (Telegram)
|
||
- Проверьте корректность токена в `.env`
|
||
- Убедитесь, что бот активен в BotFather
|
||
|
||
### Потеря доступа к данным
|
||
⚠️ Если файл `.encryption_key` был удален или поврежден:
|
||
- Все сохраненные учетные данные станут недоступны
|
||
- Пользователям нужно заново пройти авторизацию через `/start`
|
||
|
||
### Проблемы с многопользовательским доступом
|
||
- Убедитесь, что файл `users.json` доступен для записи
|
||
- Проверьте, что `.encryption_key` существует
|
||
- Смотрите логи бота для детальной информации
|
||
|
||
## 📚 Документация
|
||
|
||
- [API МойСклад](https://dev.moysklad.ru/)
|
||
- [Форматы ФНС](https://www.nalog.gov.ru/)
|
||
- [Telegram Bot API](https://core.telegram.org/bots/api)
|
||
|
||
## 🤝 Поддержка
|
||
|
||
При возникновении вопросов или проблем:
|
||
1. Проверьте раздел "Устранение неполадок"
|
||
2. Изучите `PROJECT_PLAN.md` для детального описания
|
||
3. Проверьте логи в консоли
|
||
|
||
## 📝 Лицензия
|
||
|
||
MIT License
|
||
|
||
## 🎯 Roadmap
|
||
|
||
- [x] ✅ Многопользовательская система авторизации
|
||
- [x] ✅ Шифрование учетных данных пользователей
|
||
- [x] ✅ Интеграция с МойСклад API
|
||
- [x] ✅ Валидация данных отгрузок
|
||
- [x] ✅ Генерация XML (УПД 5.03)
|
||
- [x] ✅ Генерация Excel через API МойСклад
|
||
- [x] ✅ Умная рекомендация шаблонов (ТН для физ.лиц, УПД для юр.лиц/ИП)
|
||
- [ ] База данных для истории генерации
|
||
- [ ] Автоматические уведомления о новых заказах
|
||
- [ ] Генерация PDF печатных форм
|
||
- [ ] Электронная подпись XML документов
|
||
- [ ] Интеграция с 1С:Бухгалтерия
|
||
- [ ] OAuth авторизация МойСклад
|
||
- [ ] Webhook режим для бота
|
||
|
||
---
|
||
|
||
Сделано с ❤️ для бухгалтеров
|