Как программно ввести документ на основании в 1С

Автоматизация бизнес-процессов в платформе 1С:Предприятие часто требует создания цепочек взаимосвязанных документов. Самый классический пример — генерация "Реализации товаров и услуг" на основании "Заказа клиента". В типовой конфигурации пользователь просто нажимает кнопку "Создать на основании", но в кастомных разработках или при массовой обработке данных эту логику необходимо реализовать программно.

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

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

Базовые методы работы с документами-основаниями

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

Существует три основных способа взаимодействия с основанием. Первый — это метод Копировать(), который создает глубокую копию объекта в памяти. Второй — использование формы документа для вызова стандартного механизма создания. Третий — ручной перебор реквизитов и табличных частей, что дает максимальный контроль, но требует больше кода.

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

⚠️ Внимание: При программном создании документов всегда проверяйте права доступа текущего пользователя. Операция может завершиться ошибкой, если у пользователя нет прав на запись нового документа или чтение исходного.

Создание объекта через метод Копировать

Самый простой и быстрый способ получить новый документ — вызвать метод Копировать() у объекта-основания. Этот метод создает новый объект метаданных с тем же набором реквизитов, что и у оригинала. Однако важно понимать, что это именно копия, а не документ, сформированный по правилам подсистемы "Ввод на основании".

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

Рассмотрим пример кода, где мы создаем копию заказа и меняем дату:

ИсходныйДокумент = Документы.ЗаказКлиента.ПолучитьСсылку(Идентификатор);
НовыйДокумент = ИсходныйДокумент.ПолучитьОбъект().Копировать();
НовыйДокумент.Дата = ТекущаяДата();
НовыйДокумент.Записать();

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

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

Использование формы для ввода на основании

Более сложный, но функционально богатый подход — использование формы документа. Метод ПолучитьФорму() позволяет открыть форму нового документа в режиме создания на основании. Это запускает стандартные механизмы платформы, которые заполняют поля согласно настройкам конфигурации.

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

Ключевым моментом здесь является параметр КлючВнешнейОбработки или передача объекта основания в параметры формы. Синтаксис может варьироваться в зависимости от версии платформы и типа формы:

• 📄 Вызов формы через менеджер формы: Форма = ДокументОбъект.ПолучитьФорму("ФормаДокумента", ЭтотОбъект);
• 📄 Передача основания: Форма.Основание = ИсходныйДокумент;
• 📄 Открытие окна: Форма.ОткрытьМодально();

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

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

⚠️ Внимание: При работе с формами в фоновых заданиях убедитесь, что у сеанса есть права на открытие графического интерфейса, иначе выполнение кода прервется с ошибкой.

Стандартный механизм СформироватьНаОсновании

В современных конфигурациях 1С (особенно на базе БСП) существует универсальный механизм создания документов через обработку СформироватьНаОсновании. Этот подход является наиболее предпочтительным для типовой разработки, так как он использует единый центр регистрации правил ввода.

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

Для вызова используется общий модуль или метод объекта. Пример вызова через общий модуль:

Параметры = Новый Структура;
Параметры.Вставить("Объект", ИсходныйДокумент);
Параметры.Вставить("ВидОперации", "ВводНаОсновании");
Результат = Обработки.СформироватьНаОсновании.Создать().Выполнить(Параметры);

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

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

Почему механизм СформироватьНаОсновании считается лучшим?

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

Работа с табличными частями и реквизитами

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

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

Реквизит источника	Действие	Особенности
Номенклатура	Прямое присваивание	Проверить актуальность ссылки
Количество	Копирование или расчет	Учесть единицы измерения
Цена	Пересчет по курсу	Проверить тип валюты
Сумма	Автоматический расчет	Не копировать вручную

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

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

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

⚠️ Внимание: Никогда не копируйте уникальные идентификаторы (UUID) строк табличной части. У каждой строки нового документа должен быть свой уникальный идентификатор, генерируемый платформой автоматически.

Обработка ошибок и контроль целостности

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

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

Использование транзакций НачатьТранзакцию() и ЗафиксироватьТранзакцию() обязательно при создании групп документов. Это гарантирует атомарность операции: либо все документы будут созданы успешно, либо ни один из них не появится в базе.

Также следует реализовать проверку логической целостности. Например, убедиться, что сумма нового документа равна сумме основания (если это требуется), или что все товары доступны к отгрузке на момент создания.

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

Часто задаваемые вопросы (FAQ)

Как программно найти документ, который является основанием для текущего?

Для этого нужно обратиться к реквизиту Основание объекта документа. В коде это выглядит так: СсылкаНаОснование = ТекущийДокумент.Основание;. Если реквизит заполнен, вы получите ссылку на документ-источник, которую можно использовать для дальнейшего анализа.

Можно ли создать документ на основании другого документа другого вида?

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

Почему при копировании не переносятся данные в табличную часть?

Скорее всего, вы используете поверхностное копирование или неверно обращаетесь к табличной части. Убедитесь, что вы используете метод Копировать() для всего объекта документа, а не только для шапки. Для табличных частей необходимо циклическое копирование строк.

Как отследить цепочку документов (кто за кем следовал)?

Стандартный механизм 1С хранит только прямое основание. Для построения полной цепочки (дерева движений) необходимо рекурсивно подниматься по реквизиту Основание от каждого документа, пока не дойдете до документа без основания.