Массовое формирование счетов-фактур на комиссионное вознаграждение: архитектура, защита от дублей и пакетная обработка

От единичной операции к массовой задаче

В 1С:Бухгалтерии предприятия 3.0 счет-фактура на собственное комиссионное вознаграждение формируется на основании документа «Отчет комитенту (о продажах)».

Далее для краткости будем использовать:

БП — Бухгалтерия предприятия;
СФ — счет-фактура.

Когда отчетов два или три, штатный пользовательский сценарий вполне удобен:

открыть отчет -> проверить наличие СФ -> выписать СФ -> перейти к следующему отчету

Но если за месяц формируются десятки Отчетов комитенту, сама учетная операция не становится сложнее — многократно повторяется только пользовательская работа.

Получается типичная задача массовой обработки:

получить документы -> определить их текущее состояние -> выбрать нужные -> выполнить штатное действие -> проверить результат

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

Что именно нужно автоматизировать

Важно разделить две разные задачи.

Первая — организация массовой работы пользователя:

• выбор периода;
• получение списка документов;
• отбор по организации, контрагенту и договору;
• определение уже существующих СФ;
• выбор строк для обработки;
• массовый запуск;
• отображение результата каждой строки.

Вторая — собственно учетная логика формирования СФ:

• какие реквизиты должны быть заполнены;
• как учитывается документ-основание;
• какие правила действуют для конкретной хозяйственной операции;
• в каком режиме документ записывается и проводится;
• какие изменения типовой конфигурации необходимо учитывать в новом релизе.

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

А вторую Бухгалтерия предприятия уже решает сама.

Поэтому сначала стоит определить: требуется ли нам новое правило формирования СФ или только массовый интерфейс над уже существующим правилом.

Варианты реализации

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

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

Почему собственное заполнение СФ здесь избыточно

Самый очевидный программный путь может выглядеть примерно так:

СчетФактура = Документы.СчетФактураВыданный.СоздатьДокумент();

СчетФактура.Организация = ...;
СчетФактура.Контрагент = ...;
СчетФактура.ДоговорКонтрагента = ...;

// дальнейшее собственное заполнение

СчетФактура.Записать();

Технически такой подход возможен.

Но вместе с ним разработчик принимает на себя ответственность за правила заполнения документа.

Для тиражного или долгоживущего решения это означает, что при изменении типовой логики необходимо определить:

• не появился ли новый обязательный реквизит;
• не изменился ли порядок заполнения;
• не изменились ли правила конкретного вида операции;
• не появилась ли дополнительная обработка данных до или после записи;
• не изменился ли режим проведения;
• не требуется ли новая связанная типовая логика.

Если же конечный документ может быть создан тем же механизмом, который использует сама БП, внешнему коду не требуется копировать эти правила.

Его задача становится значительно уже:

найти основания -> определить состояние -> выбрать строки -> вызвать типовой механизм -> проверить фактический результат

Начинать нужно с точного вида операции

Сам факт, что документ имеет тип ОтчетКомитентуОПродажах, еще не означает, что он относится к нужному сценарию.

Для формирования СФ на комиссионное вознаграждение в рассматриваемой задаче нужны именно документы с видом операции «Отчет о продажах».

В выборке это можно зафиксировать явно:

Запрос.УстановитьПараметр(
    "ВидОперации",
    Перечисления.ВидыОперацийОтчетКомитентуОПродажах.ОтчетОПродажах);

и затем использовать условие:

Отчеты.ВидОперации = &ВидОперации

Это важный общий принцип массовых обработок: отбирать нужно не просто объекты нужного типа, а объекты именно того бизнес-сценария, для которого предназначена операция.

Сначала получить список, потом изменять данные

Полезно разделить массовую операцию на две фазы.

Фаза 1. Чтение и подготовка

Пользователь получает таблицу, в которой видит:

• дату и номер Отчета комитенту;
• признак проведения;
• организацию;
• контрагента;
• договор;
• сумму документа;
• сумму комиссионного вознаграждения;
• НДС с вознаграждения;
• уже существующий СФ;
• текущее состояние строки.

Фаза 2. Изменение

Пользователь отмечает только нужные строки и отдельно запускает массовое создание.

Так чтение не смешивается с записью, а пользователь до изменения базы видит, какие именно документы будут обработаны.

Как получить НДС вознаграждения без отдельного запроса для каждой строки

Если в рабочем месте нужно показывать НДС комиссионного вознаграждения, нет необходимости после получения каждого Отчета отдельно читать его табличную часть.

Сумму можно агрегировать сразу при формировании основной выборки:

ВЫБРАТЬ
    Товары.Ссылка КАК Ссылка,
    СУММА(Товары.СуммаНДСВознаграждения) КАК СуммаНДСВознаграждения
ИЗ
    Документ.ОтчетКомитентуОПродажах.Товары КАК Товары
СГРУППИРОВАТЬ ПО
    Товары.Ссылка

а затем присоединить результат к списку отчетов.

Это позволяет сразу получить рабочую таблицу без последующего обхода документов только ради отображения суммы.

Проверку существующих СФ лучше делать пакетно

После получения списка отчетов необходимо понять, по каким основаниям счет-фактура уже существует.

Наивный вариант:

1 запрос отчетов + отдельный поиск СФ для каждой строки

Так появляется известный паттерн N+1: после одной основной выборки выполняется еще один отдельный вызов на каждый полученный объект.

В типовом контуре БП предусмотрен групповой поиск подчиненных выданных счетов-фактур, которому можно передать массив оснований.

Сначала формируется массив:

МассивОснований =
    ИсходнаяТаблица.ВыгрузитьКолонку("Отчет");

Затем выполняется один пакетный поиск:

СчетаФактуры =
    УчетНДСПереопределяемый.
        НайтиПодчиненныеСчетаФактурыВыданныеНаРеализацию(
            МассивОснований,
            Неопределено,
            Ложь,
            СтруктураОтбораСФ);

В результате состояние всех строк можно определить до запуска изменения данных.

Важно: это внутренний типовой программный интерфейс конфигурации, поэтому при переносе решения на другой релиз точную сигнатуру метода следует проверять по коду целевой конфигурации.

Почему нельзя искать просто любой подчиненный СФ

У одного исходного комиссионного документа могут существовать разные связанные сценарии.

Поэтому условие «нашел любой подчиненный СчетФактураВыданный» слишком широкое.

Для СФ именно на собственное комиссионное вознаграждение типовой механизм использует дополнительный смысловой отбор:

СтруктураОтбораСФ =
    Новый Структура(
        "Продавец",
        Справочники.Контрагенты.ПустаяСсылка());

То есть мы не пытаемся отличить нужный документ по номеру, дате, строковому представлению или другому косвенному признаку.

Используется тот же предметный критерий, который заложен в типовой логике.

Статус в таблице — только снимок состояния

Это один из наиболее важных моментов массовой записи.

Предположим:

10:00 — пользователь сформировал список.
Для отчета № 125 СФ еще отсутствует.

10:02 — другой пользователь открыл этот отчет и выписал СФ штатным способом.

10:05 — первый пользователь запускает массовую обработку списка, сформированного пять минут назад.

Если алгоритм доверяет только сохраненному в строке статусу «Не выписан», он работает уже с устаревшим состоянием базы.

Строка формы описывает состояние на момент чтения. Перед записью состояние нужно проверить заново.

Поэтому перед обработкой каждой выбранной строки выполняется повторный поиск СФ.

Логика получается такой:

1. получить ссылку на исходный отчет;
2. проверить, существует ли сам отчет;
3. повторно найти СФ на комиссионное вознаграждение;
4. если СФ появился — установить результат «Уже выписан»;
5. только если СФ по-прежнему отсутствует — запускать создание.

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

Создание нужно передать типовому владельцу

Для создания выданного СФ Бухгалтерия предприятия использует структуру параметров.

Базовый вызов выглядит так:

ПараметрыСоздания =
    УчетНДСКлиентСервер.
        НовыеПараметрыСозданияВыданногоСчетаФактуры();

ПараметрыСоздания.Основание = Отчет;

УчетНДСВызовСервера.
    СоздатьСчетФактуруВыданныйНаОсновании(
        ПараметрыСоздания);

Внешний массовый механизм передает основание, но не начинает самостоятельно заполнять будущий СФ.

Дальнейшее создание остается внутри типового контура БП.

В конечной точке штатная логика создает объект СчетФактураВыданный, выполняет его заполнение по основанию и выбирает режим записи в зависимости от состояния исходного документа.

Это и есть важное разделение ответственности:

массовая обработка владеет последовательностью действий, БП владеет правилами формирования СФ

Отдельный нюанс серверного пакетного вызова

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

В отдельной серверной пакетной операции форма в этой цепочке не участвует.

В рассматриваемой реализации используется:

ПараметрыСоздания.УникальныйИдентификатор =
    Неопределено;

После этого вызывается штатное создание:

УчетНДСВызовСервера.
    СоздатьСчетФактуруВыданныйНаОсновании(
        ПараметрыСоздания);

Для исследованного типового контура это переводит связанную актуализацию в синхронную ветку, что важно для следующего шага — немедленной проверки фактически созданного документа.

Это не универсальное правило для любого вызова этого метода. Такой параметр имеет смысл устанавливать только после проверки конкретной реализации типовой функции на целевом релизе.

Успешный вызов еще не равен успешному результату

Есть соблазн считать операцию завершенной сразу после того, как типовой вызов не выбросил исключение.

Но для массового рабочего места полезнее проверять именно пользовательский результат.

Поэтому после создания выполняется еще один поиск:

проверить отсутствие -> создать штатно -> найти фактически созданный СФ -> вернуть ссылку пользователю

Если СФ найден, строка получает результат «Создан» и реальную ссылку на документ.

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

Почему не нужна одна общая транзакция на всю пачку

Представим, что пользователь выбрал 50 независимых Отчетов комитенту.

Первые 36 корректны, а в 37-м исходные данные не позволяют типовой логике завершить операцию.

Если рассматривать все 50 строк как одну неделимую бизнес-транзакцию, придется откатить уже успешно выполненную работу.

Но в данном сценарии документы независимы: создание СФ по одному отчету не требует атомарного создания СФ по всем остальным отчетам.

Поэтому обработку строки логично изолировать:

Для Каждого СтрокаТаблицы Из Таблица Цикл

    Если Не СтрокаТаблицы.Выбран Тогда
        Продолжить;
    КонецЕсли;

    Попытка

        // проверить исходный документ;
        // повторно проверить существующий СФ;
        // вызвать штатное создание;
        // проверить фактический результат.

    Исключение

        // записать ошибку только этой строки.

    КонецПопытки;

КонецЦикла;

Тогда одна проблемная строка не лишает пользователя результата по остальным.

Какие состояния полезно возвращать пользователю

Для массовой операции недостаточно сообщения «выполнено» после завершения цикла.

Результат лучше хранить непосредственно рядом с исходным документом.

Дополнительно полезны итоговые счетчики: сколько строк было выбрано, сколько создано, сколько уже существовало и сколько завершилось ошибкой.

Непроведенные Отчеты комитенту: запрещать или показывать?

Это уже не технический дефект, а проектное решение.

Можно пойти по двум путям.

Вариант 1. Исключать непроведенные Отчеты комитенту из массовой выборки.

Вариант 2. Показывать их вместе с остальными, явно выводить колонку «Проведен», а дальнейшее поведение оставлять штатному механизму БП.

Второй вариант меньше добавляет собственных бизнес-правил: обработка сообщает пользователю реальное состояние исходного документа, но не пытается самостоятельно переопределить допустимость стандартной операции.

Какой вариант выбирать, зависит от требований конкретного рабочего места.

Обновление списка и массовая запись — разные операции

Полезно не запускать запись автоматически сразу после получения документов.

Сценарий лучше разделить:

задать отбор -> обновить список -> проверить строки -> отметить нужные -> выполнить изменение

Так пользователь всегда видит состав массовой операции до ее запуска.

Дополнительный отбор по состоянию СФ — «Все», «Не выписан», «Выписан» — упрощает работу, но сам по себе не заменяет повторную серверную проверку перед записью.

Программная форма или форма, собранная в конфигураторе

Способ построения интерфейса не является частью учетной архитектуры, но для внешних обработок это практический вопрос.

Небольшое рабочее место можно собрать программно: создать реквизиты формы, команды и колонки таблицы при открытии.

Плюсы такого подхода:

• структура интерфейса целиком видна в BSL-коде;
• проще переносить компактную обработку как один логический модуль;
• динамические колонки можно создавать вместе с описанием их реквизитов.

Но есть и цена: программный интерфейс управляемой формы нужно проверять не только статически, но и реальным открытием формы.

Например, некоторые свойства элементов возвращают коллекцию, которую нужно изменять через методы коллекции, а не заменять присваиванием целиком.

Поэтому синтаксически корректный код формы еще не означает, что интерфейс гарантированно откроется без runtime-ошибки.

Совместимость: что можно и чего нельзя доказывать по исходному коду

Для внешней обработки, использующей внутренние методы типовой конфигурации, полезно разделять два утверждения.

Совместимость по программному интерфейсу означает, что необходимые объекты, методы и сигнатуры присутствуют в исследуемом релизе.

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

Это разные уровни доказательства.

Нельзя автоматически превращать наличие похожего метода в старом релизе в утверждение «все версии диапазона протестированы».

Для нижней или верхней границы поддерживаемого диапазона полезен короткий приемочный тест:

1. открыть обработку;
2. получить список Отчетов комитенту;
3. проверить пакетный поиск существующих СФ;
4. выполнить создание по одному тестовому основанию;
5. повторить операцию и убедиться, что второй СФ не создается;
6. открыть фактически найденный результат.

Для внутренних методов БП это надежнее, чем оценивать совместимость только по номеру релиза.

Минимальная матрица приемочных тестов

Для массового механизма полезно проверять не один «счастливый» сценарий, а несколько разных состояний базы.

Когда какой вариант реализации имеет смысл

Не любую повторяющуюся операцию необходимо превращать в отдельную разработку.

Если за месяц создается два счета-фактуры, типовой ручной сценарий может оставаться самым дешевым и простым вариантом.

Если пользователю обязательно нужна групповая команда непосредственно внутри стандартного списка документов, логичным кандидатом становится расширение.

Если требуется отдельное рабочее место с периодом, отборами, состояниями и протоколом результата, внешняя обработка позволяет решить задачу без изменения конфигурации.

Если же типовой механизм формирования конечного документа действительно не способен обеспечить требуемый результат, только тогда появляется основание переносить часть правил заполнения в собственный код.

То есть сначала стоит искать минимальный уровень вмешательства, достаточный для пользовательского результата.

Практический вариант реализации

Описанный подход был применен и в отдельной внешней обработке для Бухгалтерии предприятия 3.0 и Бухгалтерии предприятия КОРП 3.0.

В ней внешнее рабочее место отвечает за получение списка, отборы, пакетное определение существующих СФ, выбор строк, повторную проверку перед изменением, запуск штатного механизма и отображение фактического результата.

Логику заполнения самого счета-фактуры обработка не дублирует.

Интерфейс и описание реализации можно посмотреть в карточке:

Массовое формирование счетов-фактур на комиссионное вознаграждение по Отчетам комитенту

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

Вывод

В этой задаче основная сложность находится не в создании цикла и не в форме с кнопкой.

Нужно правильно определить границу ответственности.

Массовому механизму достаточно:

1. получить именно нужные документы;
2. пакетно определить их текущее состояние;
3. дать пользователю управляемый список;
4. перед каждой записью повторно проверить критическое условие;
5. передать создание владельцу типовой логики;
6. проверить фактический результат;
7. изолировать ошибку одной строки от остальных.

А заполнение самого СФ имеет смысл оставлять Бухгалтерии предприятия до тех пор, пока типовой механизм действительно способен сформировать требуемый документ.

Не переписывать типовую учетную логику ради массовости. Массовость должна оркестрировать существующую операцию, а не становиться ее вторым независимым владельцем.