A1sDocs — документы от создания до проведения

// Намерение: Проверяет, является ли значение документом (ссылка или объект).
// Граница: Обязательные параметры: Value
// Результат: Boolean.

Успешно = A1sDocs.IsDocument(Value);

// Намерение: Проверяет, является ли значение ссылкой на документ.
// Граница: Обязательные параметры: Value
// Результат: Boolean.

Успешно = A1sDocs.IsRef(Value);

// Намерение: Проверяет, является ли значение объектом документа.
// Граница: Обязательные параметры: Value
// Результат: Boolean.

Успешно = A1sDocs.IsObject(Value);

// Намерение: Возвращает объект документа из ссылки или объекта.
// Граница: Обязательные параметры: Value
// Результат: DocumentObject | Undefined.

Результат = A1sDocs.GetObject(Value);

// Намерение: Возвращает ссылку на документ из ссылки или объекта.
// Граница: Обязательные параметры: Value
// Результат: DocumentRef | Undefined.

Ссылка = A1sDocs.GetRef(Value);

// Намерение: Создаёт новый документ и заполняет шапку из структуры.
// Граница: Обязательные параметры: Name
// Результат: DocumentObject.

Док = A1sDocs.Of("ВыпускПродукцииУслуг", A1sDS.Of(
      "Дата", '20260201',
      "Организация", МояОрг,
      "Комментарий", "Квартиры"));

// Намерение: Создаёт документ и заполняет шапку с авторазрешением строк в ссылки. Комбинирует Of + FillAuto. Используется транслятором DSL когда шапка содержит строковые значения реквизитов-справочников.
// Граница: Обязательные параметры: Name
// Результат: DocumentObject.

// DSL: INTO Doc "ОтчетПроизводства"
  //      HEADER
  //        Организация = "ООО Ромашка"   ← строка, будет разрешена
  //        Склад       = PARAM:Склад      ← уже ссылка, копируется как есть
  Dok
          = A1sDocs.OfAuto(
                  "ОтчетПроизводства",
                  A1sDS.Of(
                          "Организация", "ООО Ромашка",
                          "Склад",       СкладСсылка,
                          "Дата",        ТекущаяДата()));  //✏

// Намерение: Создаёт новый документ на основании другого документа (через платформенный Fill).
// Граница: Обязательные параметры: Name, Base
// Результат: DocumentObject.

Счёт = A1sDocs.OfBase("СчётНаОплатуПокупателю", ЗаказСсылка,
      A1sDS.Of("Комментарий", "Сформирован автоматически"));

// Намерение: Копирует существующий документ с возможностью переопределения реквизитов.
// Граница: Обязательные параметры: DocRef
// Результат: DocumentObject.

Копия = A1sDocs.Copy(ДокументСсылка, A1sDS.Of("Дата", '20260301'));

// Намерение: Подключается к существующему документу: из ссылки возвращает объект, объект возвращает как есть. Симметрична Of() — та создаёт, эта подключает.
// Граница: Обязательные параметры: DocOrRef
// Результат: DocumentObject.

Результат = A1sDocs.OfRef(Документ);

// Намерение: Заполняет реквизиты шапки документа из структуры.
// Граница: Обязательные параметры: Doc, Data
// Результат: DocumentObject.

A1sDocs.Fill(ДокОбъект, A1sDS.Of("Организация", Орг, "Комментарий", "Тест"));

// Намерение: Заполняет реквизиты шапки с автоматическим разрешением строк в ссылки. Аналог AddRowAuto для шапки документа — типы берутся из метаданных реквизитов.
// Граница: Обязательные параметры: Doc, Data
// Результат: DocumentObject.

// Транслятор DSL генерирует этот вызов когда в HEADER есть строковые значения:
  // HEADER
  //   Организация = "ООО Ромашка"    ← строка → ENSURE автоматически
  //   Склад       = "Основной"        ← строка → ENSURE автоматически
  //   Дата        = TODAY             ← не строка → как есть
  A1sDocs.FillAuto(
          Dok,
          A1sDS.Of(
                  "Организация", "ООО Ромашка",
                  "Склад",       "Основной",
                  "Дата",        ТекущаяДата()));  //▶️

// Намерение: Устанавливает значение одного реквизита документа.
// Граница: Обязательные параметры: Doc, Key, Value
// Результат: DocumentObject.

A1sDocs.Set(ДокОбъект, "Комментарий", "Обновлённый комментарий");

// Намерение: Обновляет реквизиты существующего записанного документа.
// Граница: Обязательные параметры: DocRef, Fields
// Результат: Boolean.

A1sDocs.Update(ДокСсылка, A1sDS.Of("Комментарий", "Исправлено", "Ответственный", Сотрудник));

// Намерение: Добавляет строку в табличную часть документа из структуры.
// Граница: Обязательные параметры: Doc, TabName, RowData
// Результат: TabularSectionRow.

A1sDocs.AddRow(Док, "Продукция", A1sDS.Of(
      "Номенклатура", Квартира1Ссылка,
      "Количество", 1,
      "Сумма", 3500000));

// Намерение: Добавляет несколько строк в ТЧ из ТаблицыЗначений или массива структур.
// Граница: Обязательные параметры: Doc, TabName, Source
// Результат: Number.

// Из ТаблицыЗначений:
  A1sDocs.AddRows(Док, "Продукция", ТЗКвартиры);

  // Из массива структур:
  Строки = A1sAR.Of(
      A1sDS.Of("Номенклатура", Кв1, "Количество", 1, "Сумма", 50.5),
      A1sDS.Of("Номенклатура", Кв2, "Количество", 1, "Сумма", 60.0));
  A1sDocs.AddRows(Док, "Продукция", Строки);

  // С маппингом колонок:
  A1sDocs.AddRows(Док, "Продукция", ТЗИмпорта,
      A1sDS.Of("НазваниеТовара", "Номенклатура", "Кол", "Количество"));

// Намерение: Очищает табличную часть документа.
// Граница: Обязательные параметры: Doc, TabName
// Результат: DocumentObject.

Результат = A1sDocs.ClearRows(Документ, "Товары");

// Намерение: Заменяет содержимое ТЧ: очищает и заполняет заново.
// Граница: Обязательные параметры: Doc, TabName, Source
// Результат: Number.

A1sDocs.SetRows(Док, "Продукция", НовыеДанные);

// Намерение: Экспортирует ТЧ документа в массив структур.
// Граница: Обязательные параметры: Doc, TabName
// Результат: Array.

Строки = A1sDocs.ExportRows(ДокСсылка, "Товары", "Номенклатура,Количество,Цена");

// Намерение: Количество строк в табличной части.
// Граница: Обязательные параметры: Doc, TabName
// Результат: Number.

Результат = A1sDocs.RowCount(Документ, "Товары");

// Намерение: Добавляет строку в ТЧ, автоматически разрешая строковые значения в ссылки по типам реквизитов табличной части (через A1sCatalogs.EnsureByType). Код обработки не знает имён справочников — документ сам описывает свою схему.
// Граница: Обязательные параметры: Doc, TabName, RawData
// Результат: TabularSectionRow.

// "Квартира 101" — строка; AddRowAuto увидит что поле "Номенклатура" — это
  // СправочникСсылка.Номенклатура и вызовет Ensure автоматически
  A1sDocs.AddRowAuto(
          Док,
          "Продукция",
          A1sDS.Of(
                  "Номенклатура",     "Квартира 101",
                  "ЕдиницаИзмерения", "шт",
                  "Количество",       1,
                  "Сумма",            3500000));  //▶️

// Намерение: Массово загружает массив структур в ТЧ документа с автоматическим разрешением ссылок. Убирает инфраструктурный цикл из кода обработки: вместо "Для Каждого... AddRow..." — одна строка.
// Граница: Обязательные параметры: Doc, TabName, Rows
// Результат: Number.

// Создать документ и загрузить все строки — три строки кода вместо цикла с маппингом
  Док
          = A1sDocs.Of(
                  "ОтчётПроизводства",
                  A1sDS.Of("Дата", ТекущаяДата(), "Организация", МояОрг));  //✏

  // LoadRows прогонит каждую строку через AddRowAuto:
  // строки → ссылки, числа и даты → как есть
  A1sDocs.LoadRows(Dok, "Продукция", МассивСтрокИзJSON);  //▶️

  A1sDocs.Post(Dok);  //▶️

// Намерение: Очищает табличную часть и загружает строки из массива структур.
// Граница: Обязательные параметры: Doc, TabName, Rows
// Результат: Number.

Результат = A1sDocs.SetLoadRows(Документ, "Товары", Rows);

// Намерение: Загружает строки с переименованием полей источника и авторазрешением ссылок. Объединяет A1sDS.RenameFields + LoadRows в один вызов. Нужен когда имена полей в источнике (JSON/CSV) отличаются от имён реквизитов ТЧ.
// Граница: Обязательные параметры: Doc, TabName, Rows, FieldMapping
// Результат: Number.

// JSON содержит поля "item", "unit", "qty" —
  // а в ТЧ "Продукция" поля "Номенклатура", "ЕдиницаИзмерения", "Количество"
  A1sDocs.LoadRowsMapped(
          Dok,
          "Продукция",
          МассивИзJSON,
          A1sDS.Of(
                  "item", "Номенклатура",
                  "unit", "ЕдиницаИзмерения",
                  "qty",  "Количество"));  //▶️

// Намерение: Очищает ТЧ и загружает строки с переименованием и авторазрешением ссылок.
// Граница: Обязательные параметры: Doc, TabName, Rows, FieldMapping
// Результат: Number.

Результат = A1sDocs.SetLoadRowsMapped(Документ, "Товары", Rows, "Наименование");

// Намерение: Ядро для FillRows. Заполняет ТЧ по маппингу полей. Поддерживает: ТаблицаЗначений, Массив Структур, Массив Соответствий (JSON).
// Граница: Обязательные параметры: Объект, TableName, Data, Map
// Результат: —.

A1sDocs.AddRowsMap(Объект, "Справочник.Номенклатура", Параметры, Map);

// Намерение: Записывает документ.
// Граница: Обязательные параметры: Doc
// Результат: DocumentRef.

Ссылка = A1sDocs.Write(Документ);

// Намерение: Проводит документ.
// Граница: Обязательные параметры: Doc
// Результат: DocumentRef.

Ссылка = A1sDocs.Post(Документ);

// Намерение: Отменяет проведение документа.
// Граница: Обязательные параметры: Doc
// Результат: DocumentRef.

Ссылка = A1sDocs.Unpost(Документ);

// Намерение: Помечает документ на удаление.
// Граница: Обязательные параметры: DocRef
// Результат: Boolean.

Успешно = A1sDocs.MarkForDeletion(Документ);

// Намерение: Проводит массив документов. Возвращает результат {Success, Failed}.
// Граница: Обязательные параметры: Docs
// Результат: Structure.

Результат = A1sDocs.PostAll(МассивСсылок);
  Сообщить("Проведено: " + Результат.Success.Количество());

// Намерение: Отменяет проведение массива документов.
// Граница: Обязательные параметры: Docs
// Результат: Structure.

Данные = A1sDocs.UnpostAll(Документ);

// Намерение: Универсальная пакетная обработка документов.
// Граница: Обязательные параметры: Docs, Action
// Результат: Structure.

Данные = A1sDocs.ProcessAll(Документ, "Action");

// Намерение: Обновляет реквизиты у массива документов.
// Граница: Обязательные параметры: Docs, Fields
// Результат: Structure.

A1sDocs.UpdateAll(МассивСсылок, A1sDS.Of("Ответственный", НовыйОтветственный));

// Намерение: Находит документ по номеру.
// Граница: Обязательные параметры: Name, Number
// Результат: DocumentRef.

Ссылка = A1sDocs.ByNumber("Name", 10);

// Намерение: Находит документ по значению реквизита.
// Граница: Обязательные параметры: Name, AttrName, Value
// Результат: DocumentRef.

Ссылка = A1sDocs.ByAttr("Name", "Наименование", Value);

// Намерение: Находит документ по GUID.
// Граница: Обязательные параметры: Name, GUIDStr
// Результат: DocumentRef.

Ссылка = A1sDocs.ByGUID("Name", Идентификатор);

// Намерение: Возвращает соответствие Номер → ссылка документа.
// Граница: Обязательные параметры: DocName, Numbers
// Результат: Map.

Данные = A1sDocs.MapByNumber(Документ, 10);

// Намерение: Возвращает соответствие Номер|Дата → ссылка документа.
// Граница: Обязательные параметры: DocName, Pairs
// Результат: Map.

Данные = A1sDocs.MapByNumberDate(Документ, Pairs);

// Намерение: Возвращает Соответствие (ЗначениеРеквизита → Ссылка) для документов. Один запрос — эффективно для массовых операций.
// Граница: Обязательные параметры: DocName, AttrName, Values
// Результат: Map.

Данные = A1sDocs.MapByAttr(Документ, "Наименование", Значения);

// Намерение: Найти или создать документ по Номер+Дата (upsert). Если документ найден — может обновить реквизиты. Если не найден — создаёт новый.
// Граница: Обязательные параметры: DocName, Номер, Дата
// Результат: DocumentRef.

Ссылка = A1sDocs.EnsureByNumberDate(
      "РеализацияТоваровУслуг",
      "INV-001",
      Дата,
      A1sDS.Of("Контрагент", Контрагент)
  );

// Намерение: Upsert документа (найти или создать) по Номер+Дата. Может обновлять реквизиты и проводить документ.
// Граница: Обязательные параметры: DocName, Номер, Дата
// Результат: DocumentRef | DocumentObject.

Ссылка = A1sDocs.EnsureDocument(Документ, Номер, Дата);

// Намерение: Возвращает Соответствие (Номер|Дата → Ссылка): ищет или создаёт документы. Все переданные пары Номер+Дата гарантированно присутствуют в результате.
// Граница: Обязательные параметры: DocName, Pairs
// Результат: Map.

Пары = Новый Массив;
  Пары.Добавить(Новый Структура("Номер,Дата", "INV-1", '20260101'));
  Пары.Добавить(Новый Структура("Номер,Дата", "INV-2", '20260102'));

  Документы = A1sDocs.EnsureMapByNumberDate(
      "РеализацияТоваровУслуг",
      Пары,
      A1sDS.Of("Организация", Организация)
  );

  // Использование:
  Ссылка = Документы["INV-1|20260101"];

// Намерение: Все документы в периоде с опциональным фильтром.
// Граница: Обязательные параметры: DocName, StartDate, EndDate
// Результат: Array.

Реализации = A1sDocs.AllInPeriod("РеализацияТоваровУслуг",
      НачалоМесяца, КонецМесяца,
      A1sDS.Of("Контрагент", КонтрагентСсылка));

// Намерение: Все проведённые документы в периоде.
// Граница: Обязательные параметры: DocName, StartDate, EndDate
// Результат: Array.

Массив = A1sDocs.AllPosted(Документ, StartDate, EndDate);

// Намерение: Все непроведённые документы в периоде.
// Граница: Обязательные параметры: DocName, StartDate, EndDate
// Результат: Array.

Массив = A1sDocs.AllUnposted(Документ, StartDate, EndDate);

// Намерение: Все документы по документу-основанию.
// Граница: Обязательные параметры: DocName, BaseDoc
// Результат: Array.

СчетаФактуры = A1sDocs.AllByBase("СчётФактураВыданный", РеализацияСсылка);

// Намерение: Выбирает документы по значениям реквизита (IN-запрос).
// Граница: Обязательные параметры: DocName, AttrName, Values
// Результат: Array.

Реализации = A1sDocs.PickByAttr("РеализацияТоваровУслуг", "Контрагент",
      A1sAR.Of(Контрагент1, Контрагент2, Контрагент3));

// Намерение: Получить массив ссылок по условию.
// Граница: Обязательные параметры: Name
// Результат: Array.

Ссылки = A1sDocs.Refs("РеализацияТоваровУслуг",
      "НЕ ПометкаУдаления И Организация = &Орг",
      A1sDS.Of("Орг", ОргСсылка), "Дата УБЫВ");

// Намерение: Подсчитать количество документов по условию.
// Граница: Обязательные параметры: Name
// Результат: Number.

Результат = A1sDocs.Count("Name");

// Намерение: Проверить существование документов по условию.
// Граница: Обязательные параметры: Name
// Результат: Boolean.

Успешно = A1sDocs.Exists("Name");

// Намерение: Проверяет, проведён ли документ.
// Граница: Обязательные параметры: DocRef
// Результат: Boolean.

Успешно = A1sDocs.IsPosted(Документ);

// Намерение: Проверяет, является ли значение пустой ссылкой документа.
// Граница: Обязательные параметры: Name, Value
// Результат: Boolean.

Успешно = A1sDocs.IsEmpty("Name", Value);

// Намерение: Детальная информация о документе в виде структуры.
// Граница: Обязательные параметры: DocRef
// Результат: Structure.

Данные = A1sDocs.Details(Документ);

// Намерение: Находит непроведённые документы из массива.
// Граница: Обязательные параметры: Docs
// Результат: Array.

Массив = A1sDocs.UnpostedDocs(Документ);

// Намерение: Тип реквизита шапки документа.
// Граница: Обязательные параметры: DocName, AttrName
// Результат: TypeDescription.

// Разрешить строку "ООО Ромашка" в ссылку на контрагента
  // не зная заранее имени справочника
  Тип = A1sDocs.AttrType("РеализацияТоваровУслуг", "Контрагент");
  Ссылка = A1sCatalogs.EnsureByType(Тип, "ООО Ромашка");

// Намерение: Схема всех реквизитов шапки документа. Каждый элемент: {Имя, Тип, ТипСтрока, ЭтоСправочник, ИмяСсылки}.
// Граница: Обязательные параметры: DocName
// Результат: Array.

// Готовое описание шапки для ТЗ — без открытия конфигуратора
  Схема = A1sDocs.AttrSchema("РеализацияТоваровУслуг");
  Для Каждого Поле Из Схема Цикл
      Если Поле.ЭтоСсылка Тогда
          Сообщить(Поле.Имя + " → " + Поле.ВидСсылки + "." + Поле.ИмяСсылки);
      Иначе
          Сообщить(Поле.Имя + " → " + Поле.ТипСтрока);
      КонецЕсли;
  КонецЦикла;

// Намерение: Тип реквизита табличной части документа.
// Граница: Обязательные параметры: DocName, TabName, AttrName
// Результат: TypeDescription.

// Получить тип поля ТЧ и сразу разрешить строку в ссылку
  Тип
          = A1sDocs.TabAttrType(
                  "ОтчётПроизводства",
                  "Продукция",
                  "Номенклатура");  //✏
  Ссылка
          = A1sCatalogs.EnsureByType(
                  Тип,
                  "Квартира 101");  //▶️

// Намерение: Схема всех реквизитов табличной части документа. Каждый элемент: {Имя, Тип, ТипСтрока, ЭтоСправочник, ИмяСсылки}. Используется для генерации ТЗ, валидации источника данных и диагностики.
// Граница: Обязательные параметры: DocName, TabName
// Результат: Array.

// Валидация: проверить что все справочниковые поля есть в источнике JSON
  Схема = A1sDocs.TabSchema("ОтчётПроизводства", "Продукция");
  Для Каждого Поле Из Схема Цикл
      Если Поле.ЭтоСсылка И НЕ ДанныеJSON[0].Свойство(Поле.Имя) Тогда
          Сообщить("ВНИМАНИЕ: поле " + Поле.Имя + " отсутствует в источнике");
      КонецЕсли;
  КонецЦикла;

// Намерение: Менеджер документа по имени.
// Граница: Обязательные параметры: Name
// Результат: DocumentManager.

Результат = A1sDocs.Manager("Name");

// Намерение: Пустая ссылка документа.
// Граница: Обязательные параметры: Name
// Результат: DocumentRef.

Ссылка = A1sDocs.Empty("Name");

// Намерение: Количество видов документов в конфигурации.
// Граница: Параметров нет.
// Результат: Number.

Результат = A1sDocs.MetaCount();

// Намерение: Массив имён всех документов конфигурации.
// Граница: Параметров нет.
// Результат: Array.

Массив = A1sDocs.MetaNames();

// Намерение: Имена табличных частей документа.
// Граница: Обязательные параметры: Name
// Результат: Array.

Массив = A1sDocs.TabNames("Name");

// Намерение: Имена реквизитов табличной части документа.
// Граница: Обязательные параметры: DocName, TabName
// Результат: Array.

Массив = A1sDocs.TabColumnNames(Документ, "Товары");

// Намерение: Создаёт fluent-обёртку для цепочечных вызовов.
// Граница: Обязательные параметры: DocName
// Результат: DataProcessorObject.A1sDP_Docs.

// Создание нового документа:
  Ссылка = A1sDocs.On("ВыпускПродукцииУслуг", A1sDS.Of(
          "Дата", '20260201', "Организация", МояОрг))
      .Set("Комментарий", "Квартиры — корпус А")
      .AddRows("Продукция", ТЗКвартиры)
      .Post();

  // Обёртка существующего:
  A1sDocs.On(ДокументСсылка)
      .ClearRows("Товары")
      .AddRows("Товары", НовыеДанные)
      .Post();

// Намерение: Подключается к СУЩЕСТВУЮЩЕМУ документу и возвращает fluent-обёртку.
// Граница: Обязательные параметры: DocOrRef
// Результат: DataProcessorObject.A1sDP_Docs.

Ссылка = A1sDocs.OnRef(СсылкаДокумента).Set("Комментарий", "Обновлено").Write();

// Намерение: Самотест модуля A1sDocs (без реальной БД — проверяет хелперы).
// Граница: Параметров нет.
// Результат: Boolean.

Успешно = A1sDocs.SelfTest();