03. Коллекции и Документы

3.1. Общая концепция

Платформа оперирует двумя основными типами бизнес-объектов:

Тип	Назначение	Примеры	Генерирует движения
КОЛЛЕКЦИЯ	Справочник/НСИ (нормативно-справочная информация)	Клиенты, Сотрудники, Товары	Нет
ДОКУМЕНТ	Факт хозяйственной жизни (имеет дату, номер, проведение)	Заказ-наряд, Поступление товаров	Да (через ДВИЖЕНИЕ)

Ключевые отличия документов от коллекций:

• Документы имеют статус проведения (_posted)
• Документы нумеруются (автонумерация)
• Документы формируют движения по журналам
• Документы можно распроводить (отменить проведение)
• Документы имеют дату, которая влияет на последовательность учёта

3.2. Структура коллекции (справочника)

Минимальная коллекция

КОЛЛЕКЦИЯ Города
    ПОЛЕ Наименование СТРОКА ОБЯЗАТЕЛЬНОЕ
    
    КНОПКА "Записать" ЗАПИСАТЬ
    КНОПКА "Отмена" ЗАКРЫТЬ
КОНЕЦ

Что создаст платформа:

• Таблицу Города в БД с полями: id (первичный ключ), Наименование
• CRUD-интерфейс (список записей, карточка создания/редактирования)
• API-эндпоинты: GET /api/v1/Города, POST /api/v1/Города (если описан блок API)

Коллекция с разными типами полей

КОЛЛЕКЦИЯ Сотрудники
    # Автонумерация (создаёт поле ТабельныйНомер)
    АВТОНУМЕРАЦИЯ "EMP-{0000}" ПОЛЕ ТабельныйНомер
    
    # Основные поля
    ПОЛЕ Фамилия СТРОКА ОБЯЗАТЕЛЬНОЕ
    ПОЛЕ Имя СТРОКА ОБЯЗАТЕЛЬНОЕ
    ПОЛЕ Отчество СТРОКА
    
    # Вычисляемое поле (ФИО целиком)
    ПОЛЕ ПолноеИмя СТРОКА ВЫЧИСЛЯЕМОЕ "Фамилия + ' ' + Имя + ' ' + Отчество"
    
    # Числовое поле со значением по умолчанию
    ПОЛЕ Оклад ЧИСЛО ЗНАЧЕНИЕ_ПО_УМОЛЧАНИЮ 30000
    
    # Дата
    ПОЛЕ ДатаПриема ДАТАВРЕМЯ
    
    # Булево
    ПОЛЕ Работает БУЛЕВО ЗНАЧЕНИЕ_ПО_УМОЛЧАНИЮ ИСТИНА
    
    # Ссылка на другую коллекцию
    ПОЛЕ Должность ВЫБОР Должности ОБЯЗАТЕЛЬНОЕ
    
    # Ссылка на документ (можно)
    ПОЛЕ ТекущийЗаказ ВЫБОР ЗаказНаряд
    
    # Файл (фото, скан)
    ПОЛЕ Фотография ФАЙЛ
    
    # Табличная часть (подчинённая коллекция)
    ТАБЛИЧНАЯЧАСТЬ Дети
        КОЛОНКА ФИОРебенка СТРОКА ОБЯЗАТЕЛЬНОЕ
        КОЛОНКА ДатаРождения ДАТАВРЕМЯ
        КОЛОНКА СвидетельствоОРождении ФАЙЛ
    КОНЕЦ
    
    # Кнопки на форме
    КНОПКА "Сохранить" ЗАПИСАТЬ
    КНОПКА "Уволить" ВЫЗВАТЬ_ПРОЦЕДУРУ УволитьСотрудника
    КНОПКА "Закрыть" ЗАКРЫТЬ
КОНЕЦ

Что здесь важно:

• АВТОНУМЕРАЦИЯ — автоматически заполняет поле при создании новой записи
• ВЫЧИСЛЯЕМОЕ — поле не хранится в БД, вычисляется при чтении (удобно для ФИО, адресов)
• ТАБЛИЧНАЯЧАСТЬ — создаёт отдельную таблицу Сотрудники_Дети с внешним ключом parent_id

Коллекция с вложенными структурами (иерархия)

КОЛЛЕКЦИЯ Номенклатура
    АВТОНУМЕРАЦИЯ "ТОВ-{00000}" ПОЛЕ Артикул
    
    ПОЛЕ Наименование СТРОКА ОБЯЗАТЕЛЬНОЕ
    ПОЛЕ ЭтоГруппа БУЛЕВО ЗНАЧЕНИЕ_ПО_УМОЛЧАНИЮ 0
    
    # Самоссылка (папка/подпапка)
    ПОЛЕ РодительскаяГруппа ВЫБОР Номенклатура
    
    ПОЛЕ БазоваяЦена ЧИСЛО ЗНАЧЕНИЕ_ПО_УМОЛЧАНИЮ 0
    ПОЛЕ ЕдиницаИзмерения СТРОКА ЗНАЧЕНИЕ_ПО_УМОЛЧАНИЮ "шт"
    
    ПОЛЕ Картинка ФАЙЛ
    
    КНОПКА "Записать" ЗАПИСАТЬ
    КНОПКА "Копировать" ВЫЗВАТЬ_ПРОЦЕДУРУ СкопироватьТовар
КОНЕЦ

3.3. Структура документа

Минимальный документ

ДОКУМЕНТ ЗаявкаКлиента
    АВТОНУМЕРАЦИЯ "ЗАЯВ-{YYYY}-{0000}" ПОЛЕ Номер
    
    ПОЛЕ Номер СТРОКА
    ПОЛЕ Дата ДАТАВРЕМЯ ЗНАЧЕНИЕ_ПО_УМОЛЧАНИЮ ТЕКУЩАЯ_ДАТА_ВРЕМЯ
    
    # Основные поля
    ПОЛЕ Клиент ВЫБОР Клиенты ОБЯЗАТЕЛЬНОЕ
    ПОЛЕ Описание СТРОКА
    
    КНОПКА "Записать" ЗАПИСАТЬ
    КНОПКА "Отмена" ЗАКРЫТЬ
КОНЕЦ

Что создаст платформа:

• Таблицу ЗаявкаКлиента с полями: id, Номер, Дата, Клиент, Описание, _posted
• Статус _posted всегда 0 (непроведён) для новых документов
• API-эндпоинты для CRUD

Полноценный документ с табличными частями и движениями

ДОКУМЕНТ ПоступлениеЗапчастей
    # Автонумерация с годом и порядковым номером
    АВТОНУМЕРАЦИЯ "ПЗ-{YYYY}-{0000}" ПОЛЕ Номер
    
    # Шапка документа
    ПОЛЕ Номер СТРОКА
    ПОЛЕ Дата ДАТАВРЕМЯ ЗНАЧЕНИЕ_ПО_УМОЛЧАНИЮ ТЕКУЩАЯ_ДАТА_ВРЕМЯ
    ПОЛЕ Организация ВЫБОР Организации ОБЯЗАТЕЛЬНОЕ
    ПОЛЕ Склад ВЫБОР Склады ОБЯЗАТЕЛЬНОЕ
    ПОЛЕ Поставщик ВЫБОР Контрагенты ОБЯЗАТЕЛЬНОЕ
    
    # Итоговое поле (заполняется автоматически)
    ПОЛЕ СуммаДокумента ЧИСЛО
    
    # Табличная часть
    ТАБЛИЧНАЯЧАСТЬ Запчасти
        КОЛОНКА Номенклатура ВЫБОР Номенклатура ОБЯЗАТЕЛЬНОЕ
        КОЛОНКА Количество ЧИСЛО ОБЯЗАТЕЛЬНОЕ
        КОЛОНКА Цена ЧИСЛО ОБЯЗАТЕЛЬНОЕ
        КОЛОНКА Сумма ЧИСЛО
    КОНЕЦ
    
    # Кнопки
    КНОПКА "Записать" ЗАПИСАТЬ
    КНОПКА "Провести и закрыть" ПРОВЕСТИ
    КНОПКА "Отмена" ЗАКРЫТЬ
    
    # Бизнес-логика
    ЛОГИКА
        ПРИ СОЗДАНИИ
            ЗАПОЛНИТЬ data.Организация = Константы.ОсновнаяОрганизация
            ЗАПОЛНИТЬ data.Склад = Константы.ОсновнойСклад
        КОНЕЦ
        
        ПРИ ИЗМЕНЕНИИ Запчасти.Количество
            ВЫЧИСЛИТЬ Запчасти.Сумма = Запчасти.Цена * Запчасти.Количество
        КОНЕЦ
        
        ПРИ СОХРАНЕНИИ
            ВЫЧИСЛИТЬ data.СуммаДокумента = СУММА(data.Запчасти, "Сумма")
        КОНЕЦ
    КОНЕЦ
    
    # Движения по журналам
    ДВИЖЕНИЕ ОстаткиЗапчастей ПРИХОД 
        ПОЛЯ Организация = Организация, 
              Склад = Склад, 
              Номенклатура = Запчасти.Номенклатура, 
              Количество = Запчасти.Количество, 
              Сумма = Запчасти.Сумма
    
    ДВИЖЕНИЕ Проводки ДЕБЕТ 10 КРЕДИТ 60 
        ПОЛЯ Сумма = Запчасти.Сумма, 
              СубконтоДт1 = Запчасти.Номенклатура, 
              СубконтоКт1 = Поставщик
КОНЕЦ

3.4. Табличные части

Синтаксис:

ТАБЛИЧНАЯЧАСТЬ ИмяТабличнойЧасти
    КОЛОНКА ИмяКолонки ТИП_ДАННЫХ [ОБЯЗАТЕЛЬНОЕ]
    КОЛОНКА ИмяДругойКолонки ТИП_ДАННЫХ
    ...
КОНЕЦ

Особенности:

• Для каждой табличной части создаётся отдельная таблица в БД: ИмяДокумента_ИмяТабличнойЧасти
• Таблица содержит поле parent_id (ссылка на ID документа-владельца)
• При удалении документа платформа автоматически удаляет все строки его табличных частей
• В табличной части можно использовать любые типы данных, включая ВЫБОР

3.5. Механизм ВВОД_НА_ОСНОВАНИИ

ДОКУМЕНТ СчетНаОплату
    ВВОД_НА_ОСНОВАНИИ ЗаказНаряд
        ПЕРЕНЕСТИ Клиент → Клиент
        ПЕРЕНЕСТИ Организация → Организация
        ПЕРЕНЕСТИ ИтогоСумма → СуммаКОплате
    КОНЕЦ
КОНЕЦ

3.6. Системные поля документов

Имя	Тип	Назначение
id	ЧИСЛО	Первичный ключ
_posted	БУЛЕВО	Статус проведения (0/1)
_created_at	ДАТАВРЕМЯ	Дата создания записи
_updated_at	ДАТАВРЕМЯ	Дата последнего обновления
_created_by	ЧИСЛО	ID пользователя, создавшего запись
_updated_by	ЧИСЛО	ID пользователя, последнего изменившего запись

3.7. Кнопки на формах

Стандартные действия:

Ключевое слово	Действие
ЗАПИСАТЬ	Сохранить объект (без проведения)
ПРОВЕСТИ	Провести документ (формирует движения)
ЗАКРЫТЬ	Закрыть форму без сохранения
РАСПРОВЕСТИ	Отменить проведение (удаляет движения)

Вызов процедур:

КНОПКА "Проверить остатки" ВЫЗВАТЬ_ПРОЦЕДУРУ ПроверитьОстаткиПередЗаписью
КНОПКА "Отправить клиенту" ВЫЗВАТЬ_ПРОЦЕДУРУ ОтправитьПисьмоССчетом

Динамическая видимость кнопок:

КНОПКА "Создать акт" ВЫЗВАТЬ_ПРОЦЕДУРУ СоздатьАкт ПРИ_УСЛОВИИ _posted = 1
КНОПКА "Редактировать" ЗАПИСАТЬ ПРИ_УСЛОВИИ _posted = 0

3.8. Best Practices

• Всегда указывайте ОБЯЗАТЕЛЬНОЕ для ключевых полей (Наименование, Номер, Дата, ссылки на справочники). Это избавит от проблем с пустыми значениями.
• Используйте ЗНАЧЕНИЕ_ПО_УМОЛЧАНИЮ для полей со стандартными значениями, чтобы ускорить заполнение документов.
• Табличные части называйте во множественном числе (Товары, Услуги), чтобы было понятно, что это список.
• Не злоупотребляйте табличными частями. Если запись может быть одна — сделайте её обычным полем.
• Всегда объявляйте КНОПКА "Записать" ЗАПИСАТЬ — это стандарт для UI.
• Для документов с длинными табличными частями рассчитывайте итоги в ПРИ СОХРАНЕНИИ, а не при каждом изменении строки.
• Используйте ВЫЧИСЛЯЕМОЕ поле для отображения составных данных (ФИО, адрес) — это снижает дублирование.
• Перед удалением коллекции или документа проверьте, нет ли ссылающихся объектов.
• Именуйте поля понятно для конечного пользователя — они станут заголовками колонок в интерфейсе.
• Для иерархических справочников всегда добавляйте поле Родитель для построения дерева в UI.