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. Повторите массовую генерацию

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

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

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
• Невалидные отгрузки пропускаются

Логирование

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

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. Оптимизация

   • Валидация выполняется асинхронно
   • Можно распараллелить для больших объемов

См. также

• Массовая генерация документов
• Модуль валидации
• Формат EnterpriseData 1.20
• API МойСклад