Как программно отменить проведение документа в 1С 8.3 на управляемых формах?

← На главную

При работе с системой 1С:Предприятие 8.3 часто возникает необходимость программно управлять состоянием документов, в том числе отменять их проведение. Это может быть актуально при массовой обработке данных, корректировке ошибок, или реализации сложной бизнес-логики, требующей временной отмены проведения документов для последующего их перепроведения. Рассмотрим подробно, как мы можем реализовать отмену проведения документа из кода, используя стандартные механизмы платформы. Для этих целей есть массовое перепроведение и снятие с проведения документов.

Для программной отмены проведения документа в 1С 8.3 существуют два основных подхода: прямой вызов метода Записать() для объекта документа с указанием соответствующего режима, а также использование специализированных функций из Библиотеки стандартных подсистем (БСП), если она интегрирована в вашу конфигурацию. Разберем каждый из этих методов по шагам, выявим их особенности и оптимальные сценарии применения.

Метод 1: Прямое использование метода "Записать" с режимом отмены проведения

Этот способ является базовым и подходит для любых конфигураций, работающих на платформе 1С:Предприятие 8.3. Основная идея заключается в получении объекта документа из его ссылки и последующем вызове метода Записать(), передавая в него параметр РежимЗаписиДокумента.ОтменаПроведения. Чтобы избежать логических ошибок при написании собственных процедур обработки, рекомендуется использовать статический анализатор кода проектов, который поможет выявить недочеты еще на этапе разработки.

Получение объекта документа.

Первым и одним из наиболее важных шагов является получение самого объекта документа. Мы не можем работать с режимами записи напрямую со ссылкой на документ. Для этого нам понадобится метод ПолучитьОбъект(), который преобразует ссылку в объект документа.

Обратите внимание, что ПолучитьОбъект() возвращает Неопределено, если документ был удален или ссылка недействительна. Всегда следует проверять возвращаемое значение, чтобы избежать ошибок в работе нашей программы. Если документ по каким-либо причинам не может быть получен как объект, дальнейшие действия по отмене проведения будут невозможны.


&НаКлиенте
Процедура ОтменитьПроведениеДокументаПоСсылке(СсылкаНаДокумент)
    Если СсылкаНаДокумент = Неопределено Тогда
        Возврат;
    КонецЕсли;

    // Получаем объект документа
    ДокументОбъект = СсылкаНаДокумент.ПолучитьОбъект();

    Если ДокументОбъект = Неопределено Тогда
        Сообщить("Не удалось получить объект документа по ссылке " + СсылкаНаДокумент + ". Возможно, документ был удален.", СтатусСообщения.Важное);
        Возврат;
    КонецЕсли;
            
    // Вызываем процедуру отмены проведения на сервере
    ОтменитьПроведениеДокументаНаСервере(ДокументОбъект);
КонецПроцедуры

&НаСервереБезКонтекста
Процедура ОтменитьПроведениеДокументаНаСервере(ДокументОбъект)
    Попытка
        // Устанавливаем режим записи как ОтменаПроведения
        ДокументОбъект.Записать(РежимЗаписиДокумента.ОтменаПроведения);
        Сообщить("Документ " + ДокументОбъект + " успешно отменен.");
    Исключение
        Сообщить("Ошибка при отмене проведения документа " + ДокументОбъект + ": " + ОписаниеОшибки(), СтатусСообщения.Важное);
    КонецПопытки;
КонецПроцедуры

В примере мы разделили код на клиентскую и серверную части, так как работа с объектами базы данных (такими как ДокументОбъект.Записать()) должна выполняться на сервере. Клиентская процедура лишь передает ссылку или объект для дальнейшей обработки.

Вызов метода Записать().
После получения объекта документа мы вызываем его метод Записать(). Ключевым моментом здесь является параметр, который мы передаем: РежимЗаписиДокумента.ОтменаПроведения. Этот режим указывает системе 1С, что при записи документа необходимо выполнить отмену его проведения, то есть удалить движения, которые были сформированы при проведении документа, и установить флаг "Проведен" в значение "Ложь".

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

Пример использования метода Записать():
```
// Предполагаем, что ДокументОбъект уже получен
Попытка
    ДокументОбъект.Записать(РежимЗаписиДокумента.ОтменаПроведения);
    // Если все прошло успешно
    Сообщить("Документ " + ДокументОбъект.Представление + " успешно отменен.");
Исключение
    // Обработка ошибок, если отмена проведения не удалась
    Сообщить("Не удалось отменить проведение документа " + ДокументОбъект.Представление + ". Причина: " + ОписаниеОшибки(), СтатусСообщения.Важное);
КонецПопытки;
```
Проверка прав пользователя.
Для успешной отмены проведения документа у пользователя, под которым выполняется код, должны быть соответствующие права доступа. В частности, ему должны быть доступны права на изменение и интерактивное проведение/отмену проведения данного типа документов. Если прав недостаточно, система выдаст ошибку, которую также необходимо корректно обработать.

Метод 2: Использование функций Библиотеки стандартных подсистем (БСП)

Если в вашей конфигурации используется Библиотека стандартных подсистем (БСП), мы можем применить более высокоуровневый и универсальный подход к отмене проведения документов. БСП содержит общие функции, которые инкапсулируют сложную логику, связанную с проведением и отменой проведения, учитывая множество нюансов, таких как связанные движения, блокировки и контроль целостности данных. Для более глубокого понимания возможностей библиотеки рекомендуем использовать справочник по методам БСП (с примерами использования), который упростит поиск нужных процедур.

Для отмены проведения документа через БСП нам понадобится функция ПроведениеДокументов.ОтменитьПроведениеДокумента().

Подключение БСП.
Прежде чем использовать функции БСП, мы должны убедиться, что она действительно интегрирована в нашу конфигурацию. Если БСП отсутствует, данный метод не будет работать, и нам придется использовать первый подход.
Вызов функции ПроведениеДокументов.ОтменитьПроведениеДокумента().
Эта функция предоставляет более robust-ный (устойчивый) способ отмены проведения, так как она уже содержит логику обработки ошибок, уведомлений и зависимостей. Она принимает следующие параметры:
- СсылкаНаДокумент: Это обязательный параметр, представляющий собой ссылку на документ, который мы хотим отменить. В отличие от первого метода, нам не нужно предварительно получать объект документа.
- Отказ: Параметр типа Булево, который по умолчанию устанавливается в Неопределено или Ложь. Он используется для сигнализации об успешности или неуспешности операции внутри подсистемы. В большинстве случаев мы можем его не заполнять или передавать Неопределено.
- ОповеститьПриИзмененииСостояния: Это Булево значение, которое указывает, нужно ли системе оповещать другие подсистемы или формы об изменении состояния документа. Обычно мы устанавливаем его в Истина, чтобы обеспечить актуальность данных в интерфейсе и в связанных механизмах.
```
&НаКлиенте
Процедура ОтменитьПроведениеДокументаБСППоСсылке(СсылкаНаДокумент)
    Если СсылкаНаДокумент = Неопределено Тогда
        Возврат;
    КонецЕсли;

    // Вызываем процедуру отмены проведения на сервере
    ОтменитьПроведениеДокументаБСПНаСервере(СсылкаНаДокумент);
КонецПроцедуры

&НаСервереБезКонтекста
Процедура ОтменитьПроведениеДокументаБСПНаСервере(СсылкаНаДокумент)
    // Проверяем наличие БСП
    Если Не ОбщегоНазначения.ПодсистемаВключена("СтандартныеПодсистемы.ПроведениеДокументов") Тогда
        Сообщить("Функционал БСП 'ПроведениеДокументов' не доступен. Используйте прямой метод Записать().", СтатусСообщения.Важное);
        Возврат;
    КонецЕсли;

    Попытка
        // Вызов функции БСП
        ПроведениеДокументов.ОтменитьПроведениеДокумента(СсылкаНаДокумент, Неопределено, Истина);
        Сообщить("Документ " + СсылкаНаДокумент.Представление + " успешно отменен через БСП.");
    Исключение
        Сообщить("Ошибка при отмене проведения документа " + СсылкаНаДокумент.Представление + " через БСП: " + ОписаниеОшибки(), СтатусСообщения.Важное);
    КонецПопытки;
КонецПроцедуры
```
Использование этой функции предпочтительнее в случаях, когда мы работаем в конфигурациях с БСП, так как она снижает вероятность возникновения непредвиденных ошибок, связанных с особенностями платформы или конфигурации.

Сравнение методов и рекомендации

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

Простота и универсальность: Метод с ДокументОбъект.Записать(РежимЗаписиДокумента.ОтменаПроведения) является более простым для понимания и применим в любой конфигурации 1С 8.3, независимо от наличия БСП. Он идеально подходит для точечной работы с документами или в конфигурациях без БСП.
Надежность и комплексность: Функция ПроведениеДокументов.ОтменитьПроведениеДокумента() из БСП более надежна и учитывает многие внутренние механизмы платформы и конфигурации. Она идеально подходит для типовых решений на основе БСП, а также для массовой обработки, где важна стабильность и корректная обработка всех возможных зависимостей. Если в вашей конфигурации есть БСП, мы настоятельно рекомендуем использовать именно этот метод.
Обработка ошибок: Оба метода требуют обработки исключений. Однако функции БСП часто уже содержат дополнительную логику по протоколированию ошибок и более "мягкому" реагированию на проблемы, что делает их использование удобнее в сложных системах. При прямом вызове Записать() вся логика обработки ошибок ложится на нас.

Важные аспекты и лучшие практики

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

Управление транзакциями. Если мы отменяем проведение нескольких документов подряд или выполняем другие операции с базой данных, мы должны рассмотреть использование транзакций. Оборачивание операций в транзакцию позволяет обеспечить атомарность: либо все изменения будут применены, либо ни одно из них. Если в процессе отмены проведения одного из документов произойдет ошибка, мы можем откатить все изменения до начала транзакции.
```
НачатьТранзакцию();
Попытка
    // Здесь перебираем ссылки на документы и отменяем их проведение
    // Например, ОтменитьПроведениеДокументаНаСервере(ДокументОбъект);
    // Или ПроведениеДокументов.ОтменитьПроведениеДокумента(СсылкаНаДокумент, ...);

    ФиксироватьТранзакцию();
    Сообщить("Массовая отмена проведения документов успешно завершена.");
Исключение
    ОтменитьТранзакцию();
    Сообщить("Произошла ошибка при массовой отмене проведения. Все изменения отменены: " + ОписаниеОшибки(), СтатусСообщения.Важное);
КонецПопытки;
```
Использование транзакций особенно критично при массовых операциях, где важно сохранить консистентность данных.
Производительность. Программная отмена проведения документов, особенно массовая, может быть ресурсоемкой операцией, так как она включает в себя удаление движений по регистрам. При работе с большим объемом данных мы должны оптимизировать наш код, например, реализовав конвейер обработки задач, что позволит выполнять операции в фоне и избежать "зависаний" интерфейса у пользователей.
Контроль целостности данных. Система 1С автоматически контролирует целостность данных при отмене проведения, но всегда стоит помнить о возможных логических связях, которые могут быть не учтены типовыми механизмами. Например, ручные корректировки движений или специфические доработки могут создавать неочевидные зависимости. Для уверенности в отсутствии конфликтов вызовов процедур и целостности расширений полезно выполнять анализ конфигураций на наличие ошибок. Нам также следует тщательно тестировать наш код на различных сценариях.
Пользовательский опыт и уведомления. При выполнении длительных или массовых операций мы должны информировать пользователя о ходе процесса. Используйте Сообщить() или механизм длительных операций для обратной связи. Это помогает пользователю понимать, что программа работает, а не зависла. В процессе разработки и тестирования таких механизмов сэкономить время поможет помощник отладки (мини Vanessa), избавляющий от необходимости каждый раз вручную воспроизводить условия запуска.
Версионирование объектов. Если в конфигурации включено версионирование объектов, отмена проведения также будет зафиксирована как изменение версии документа. Это полезно для аудита и восстановления данных. Мы должны это учитывать при анализе истории изменений документов.

Таким образом, программная отмена проведения документа в 1С 8.3 — это стандартная задача, которая может быть решена несколькими способами — а фиксировать такие действия поможет быстрый журнал изменений документов 1С. Выбор конкретного метода зависит от наличия БСП в конфигурации, требований к надежности и сложности обрабатываемых сценариев. Внимательное отношение к деталям, таким как получение объекта, обработка ошибок, управление транзакциями и права пользователя, позволит нам создать надежный и эффективный код.