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

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

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

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

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

📖 Подробнее: [docs/MULTI_USER_AUTH.md](docs/MULTI_USER_AUTH.md)

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

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

## Windows-приложение и обновления

Установщик Windows-приложения доступен в [релизах Gitea](https://git.robotail.pro/Robotail/BUH_bot/releases). После первой установки текущая версия видна в верхней части окна. Кнопка **«Проверить обновления»** сообщает о новом релизе, загружает установщик по выбору пользователя, проверяет его SHA-256 и запускает установку. Доступ к Gitea из локальной сети необходим для проверки и загрузки.

Сборка следующих версий описана в [инструкции по релизам](docs/WINDOWS_RELEASE.md).

## 📋 Требования

- 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)

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

### XML (1С EnterpriseData 1.20) - для загрузки в 1С
- **Документ реализации товаров и услуг** - прямая загрузка в конфигурации 1С

📖 Подробная документация: [docs/XML_1C_FORMAT.md](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` существует
- Смотрите логи бота для детальной информации

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

- [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 режим для бота

---

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