BUH_bot/docs/BATCH_VALIDATION.md

# Валидация при массовой генерации

## Обзор

При массовой генерации документов каждая отгрузка проходит валидацию перед созданием XML. Отгрузки с критическими ошибками исключаются из генерации, а пользователь получает подробный отчет об ошибках.

## Процесс валидации

### 1. Автоматическая проверка

Для каждой отгрузки из списка выполняются следующие проверки:

**Обязательные поля организации:**
- ✓ Наименование организации
- ✓ ИНН организации (с проверкой контрольной суммы)
- ✓ Банковские реквизиты

**Обязательные поля контрагента:**
- ✓ Наименование контрагента
- ✓ ИНН контрагента (если юридическое лицо)

**Обязательные поля заказа:**
- ✓ Номер заказа
- ✓ Дата заказа
- ✓ Сумма заказа > 0
- ✓ Наличие товарных позиций

**Обязательные поля грузополучателя:**
- ✓ Наименование грузополучателя
- ✓ Адрес грузополучателя (критично для УПД)

**Позиции заказа:**
- ✓ Наименование товара
- ✓ Единица измерения
- ✓ Количество > 0
- ✓ Цена ≥ 0
- ✓ Корректная ставка НДС

### 2. Обработка результатов

#### Успешная валидация
Отгрузка добавляется в список для генерации XML.

#### Критические ошибки
Отгрузка исключается из генерации, информация об ошибках сохраняется в отчет.

#### Предупреждения (warnings)
Не блокируют генерацию, но включаются в отчет для информации.

## Отчет об ошибках

При обнаружении критических ошибок валидации пользователь получает текстовый файл с подробным отчетом.

### Структура отчета

```
ОТЧЕТ О ВАЛИДАЦИИ ОТГРУЗОК
==================================================
Дата: 06.11.2025 14:10:31
Всего обработано: 8
С ошибками валидации: 3

КРИТИЧЕСКИЕ ОШИБКИ ВАЛИДАЦИИ:

Отгрузка: 4926
----------------------------------------
  • counterparty.inn: ИНН контрагента некорректен
  • consignee.address: Не указан адрес грузополучателя

Отгрузка: 4927
----------------------------------------
  • organization.inn: ИНН организации некорректен

НЕ НАЙДЕНЫ:
----------------------------------------
  • 4928
  • 4929

ОШИБКИ ОБРАБОТКИ:
----------------------------------------
  • 4931: Connection timeout

Успешно прошли валидацию: 2
----------------------------------------
  ✓ 4932
  ✓ 4933
```

### Разделы отчета

1. **Заголовок и статистика**
   - Дата генерации отчета
   - Общее количество обработанных отгрузок
   - Количество отгрузок с ошибками

2. **Критические ошибки валидации**
   - Номер отгрузки
   - Список критических ошибок с указанием поля и описанием

3. **Не найденные отгрузки**
   - Номера отгрузок, которые не найдены в МойСклад

4. **Ошибки обработки**
   - Технические ошибки при получении данных из API

5. **Успешные отгрузки**
   - Список отгрузок, прошедших валидацию

## Примеры использования

### Пример 1: Все отгрузки валидны

**Ввод:**
```
4926,4927,4928
```

**Результат:**
- ✅ Все 3 отгрузки прошли валидацию
- Генерируется XML с тремя документами
- Отчет об ошибках не создается

### Пример 2: Есть ошибки валидации

**Ввод:**
```
4926,4927,4928,4929
```

**Сценарий:**
- 4926 - ✅ валидна
- 4927 - ❌ отсутствует ИНН организации
- 4928 - ❌ не найдена в системе
- 4929 - ✅ валидна

**Результат:**
1. Бот отправляет текстовый отчет с ошибками для 4927 и 4928
2. Генерируется XML только для отгрузок 4926 и 4929
3. Пользователь видит статистику:
   ```
   ❌ Обнаружены ошибки валидации
   
   📊 Статистика:
     • Обработано: 4
     • С ошибками: 1
     • Прошли валидацию: 2
     • Не найдено: 1
   ```

### Пример 3: Ни одна отгрузка не прошла валидацию

**Ввод:**
```
4926,4927,4928
```

**Сценарий:**
Все три отгрузки имеют критические ошибки

**Результат:**
1. Бот отправляет отчет с ошибками для всех трех отгрузок
2. XML не генерируется
3. Предлагается исправить ошибки и повторить попытку

## Типичные ошибки и решения

### Ошибка: "Не указан ИНН контрагента"

**Причина:** У контрагента-юридического лица не заполнен ИНН в МойСклад

**Решение:**
1. Откройте карточку контрагента в МойСклад
2. Заполните поле "ИНН"
3. Сохраните изменения
4. Повторите массовую генерацию

### Ошибка: "Не указан адрес грузополучателя"

**Причина:** Отсутствует адрес доставки, фактический или юридический адрес

**Решение:**
1. Откройте отгрузку в МойСклад
2. Укажите адрес доставки
3. Или заполните адрес в карточке контрагента
4. Повторите массовую генерацию

### Ошибка: "ИНН организации некорректен"

**Причина:** Ошибка в контрольной сумме ИНН или неверный формат

**Решение:**
1. Проверьте ИНН организации в МойСклад
2. Убедитесь, что ИНН состоит из 10 или 12 цифр
3. Проверьте правильность ввода
4. Исправьте и повторите генерацию

### Ошибка: "Заказ не содержит товарных позиций"

**Причина:** Отгрузка создана без товаров

**Решение:**
1. Откройте отгрузку в МойСклад
2. Добавьте товары/услуги
3. Сохраните изменения
4. Повторите массовую генерацию

## Технические детали

### Уровни валидации

```python
class ValidationLevel(Enum):
    VALID = "valid"        # Все проверки пройдены
    WARNING = "warning"    # Есть предупреждения
    CRITICAL = "critical"  # Критические ошибки
```

### Критерии блокировки

Отгрузка **исключается** из генерации, если имеет хотя бы одну ошибку уровня `CRITICAL`.

Отгрузка **включается** в генерацию, если:
- Нет критических ошибок
- Есть только предупреждения (`WARNING`)
- Все проверки пройдены (`VALID`)

### Формат отчета

- **Кодировка:** UTF-8
- **Формат файла:** .txt
- **Имя файла:** `validation_errors_YYYYMMDD_HHMMSS.txt`
- **Местоположение:** временная директория `temp_documents/`

### Производительность

- **Валидация одной отгрузки:** ~0.01-0.05 сек
- **Создание отчета:** ~0.05-0.1 сек
- **Отправка файла:** ~0.5-1 сек

Валидация не замедляет процесс массовой генерации значительно.

## Интеграция с другими функциями

### Одиночная генерация

Валидация также работает при генерации одного документа:
- Результаты валидации показываются в чате
- Пользователь может решить, генерировать XML или нет
- При критических ошибках генерация может быть заблокирована

### Формат XML

Валидация работает для обоих форматов XML:
- ✓ 1С EnterpriseData 1.20
- ✓ ВерсФорм 5.03 (УПД)

### Пакетная генерация

При выборе "Один файл (все документы)":
- Невалидные отгрузки исключаются
- Валидные отгрузки объединяются в один XML

При выборе "Отдельные файлы":
- Для каждой валидной отгрузки создается отдельный XML
- Невалидные отгрузки пропускаются

## Логирование

Все события валидации логируются:

```python
logger.warning(
    f"Отгрузка {order_num} не прошла валидацию: "
    f"{len(critical_errors)} критических ошибок"
)
```

Логи доступны в файле `logs/bot.log` для анализа и отладки.

## Рекомендации

### Для пользователей

1. **Проверьте данные заранее**
   - Используйте одиночную генерацию для проверки отгрузок
   - Исправьте ошибки до массовой генерации

2. **Заполняйте все обязательные поля**
   - ИНН/КПП организаций и контрагентов
   - Адреса доставки
   - Банковские реквизиты

3. **Сохраняйте отчеты об ошибках**
   - Отчеты помогут выявить типичные проблемы
   - Используйте их для улучшения данных в МойСклад

### Для разработчиков

1. **Расширение валидации**
   - Добавляйте новые проверки в `modules/validator.py`
   - Классифицируйте их по уровням (CRITICAL/WARNING)

2. **Кастомизация отчетов**
   - Формат отчета легко настраивается
   - Можно добавить HTML-отчеты или PDF

3. **Оптимизация**
   - Валидация выполняется асинхронно
   - Можно распараллелить для больших объемов

## См. также

- [Массовая генерация документов](BATCH_GENERATION.md)
- [Модуль валидации](validator_refactoring.md)
- [Формат EnterpriseData 1.20](XML_1C_FORMAT.md)
- [API МойСклад](https://dev.moysklad.ru/doc/api/remap/1.2/)