diff --git a/README.md b/README.md new file mode 100644 index 0000000..cd2ef33 --- /dev/null +++ b/README.md @@ -0,0 +1,354 @@ +# Бот для бухгалтеров + +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 +cd BUH_bot + +# Настройка +cp .env.example .env +nano .env # Укажите TELEGRAM_BOT_TOKEN + +# Запуск +chmod +x start.sh +./start.sh +``` + +**Windows:** +```cmd +git clone +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 +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 режим для бота + +--- + +Сделано с ❤️ для бухгалтеров