01. Лексическая структура и базовые типы данных

1.1. Структура DSL-файла

DSL-файл — это обычный текстовый файл с расширением .3erp. Платформа создает его автоматически в папке с программой при первом запуске, в дальнейшем использует при каждом старте программы и применяет все изменения к базе данных (SQLite) и формирует структуру вашей конфигурации. Этот файл рекомендуется сохранять в кодировке UTF-8. Этот файл может редактироваться разработчиком в соответствии с данным руководством для настройки персональной конфигурации пользователя.

# Это комментарий. Платформа игнорирует всё, что идёт после # до конца строки
# Можно использовать многострочные блоки --- для визуального разделения

# ============================================
# ЗОНА: ПОЛЬЗОВАТЕЛИ И РОЛИ
# ============================================

РОЛЬ Администратор
    ДОСТУП ... 
КОНЕЦ_РОЛИ

# ============================================
# ЗОНА: БИЗНЕС-ОБЪЕКТЫ
# ============================================

КОЛЛЕКЦИЯ Клиенты
    ПОЛЕ ...
КОНЕЦ

1.2. Ключевые слова (зарезервированные)

Эти слова нельзя использовать как имена полей, коллекций или переменных:

Объявления сущностей:

• РОЛЬ, КОНЕЦ_РОЛИ
• ПОЛЬЗОВАТЕЛЬ, КОНЕЦ_ПОЛЬЗОВАТЕЛЯ
• КОЛЛЕКЦИЯ, ДОКУМЕНТ, ЖУРНАЛ, КОНЕЦ
• ОТЧЁТ, КОНЕЦ_ОТЧЕТА
• ПРОЦЕДУРА, КОНЕЦ_ПРОЦЕДУРЫ
• API, КОНЕЦ_API
• РАСПИСАНИЕ, КОНЕЦ_РАСПИСАНИЯ
• ШАБЛОН, КОНЕЦ_ШАБЛОНА
• СХЕМА_ДАННЫХ
• ПЛАН_СЧЕТОВ, КОНЕЦ_ПЛАНА_СЧЕТОВ

Внутри блоков:

• ДОСТУП, ОГРАНИЧЕНИЕ_ДОСТУПА, ГДЕ
• ПОЛЕ, ТАБЛИЧНАЯЧАСТЬ, КОЛОНКА
• КНОПКА
• ЛОГИКА, ПРИ_СОЗДАНИИ, ПРИ_ИЗМЕНЕНИИ, ПРИ_СОХРАНЕНИИ, ПРИ_ПРОВЕДЕНИИ
• ДВИЖЕНИЕ, ПРИХОД, РАСХОД, ДЕБЕТ, КРЕДИТ
• ИЗМЕРЕНИЕ, РЕСУРС, СУБКОНТО
• ВЫЧИСЛИТЬ, ПРИСВОИТЬ, ЗАПОЛНИТЬ
• ЕСЛИ, ТО, ИНАЧЕ, КОНЕЦ_ЕСЛИ
• ЦИКЛ, ПО, КАК, КОНЕЦ_ЦИКЛА
• ПОПЫТКА, ИСКЛЮЧЕНИЕ, КОНЕЦ_ПОПЫТКИ

Системные функции (частично, полный список в разделе 15):

• СОЗДАТЬ, ПРОЧИТАТЬ, ЗАПИСАТЬ, УДАЛИТЬ_ОБЪЕКТ
• НАЙТИ, НАЙТИ_ВСЕ, СУММА, КОЛИЧЕСТВО
• ТЕКУЩАЯ_ДАТА_ВРЕМЯ, ТЕКУЩИЙПОЛЬЗОВАТЕЛЬ, ТЕКУЩАЯ_ОРГАНИЗАЦИЯ
• HTTP_ЗАПРОС, ЗАПРОС (SQL)
• ПУСТО, ВОЗВРАТ

1.3. Типы данных для полей

При объявлении ПОЛЕ в коллекциях, документах и схемах данных используются следующие типы:

Тип	Ключевое слово	Пример значения в коде	SQLite тип	Примечание
Строка	СТРОКА	"Иванов"	TEXT	Макс. длина не ограничена
Число	ЧИСЛО	100.50	REAL	Хранит целые и дробные
Дата/Время	ДАТАВРЕМЯ	2024-01-15 14:30:00	TEXT (ISO)	Формат YYYY-MM-DD HH:MM:SS
Булево	БУЛЕВО	ИСТИНА или 1	INTEGER (0/1)	Можно писать ИСТИНА/ЛОЖЬ
Выбор ссылки	ВЫБОР ИмяКоллекции	123 (ID записи)	INTEGER	Хранит id из указанной коллекции
Файл	ФАЙЛ	URL строкой	TEXT	Путь или URL к загруженному файлу

Примеры объявлений полей:

КОЛЛЕКЦИЯ Сотрудники
    ПОЛЕ ФИО СТРОКА ОБЯЗАТЕЛЬНОЕ           # Обязательное поле (не может быть пустым)
    ПОЛЕ Возраст ЧИСЛО ЗНАЧЕНИЕ_ПО_УМОЛЧАНИЮ 18
    ПОЛЕ ДатаПриема ДАТАВРЕМЯ
    ПОЛЕ Активен БУЛЕВО ЗНАЧЕНИЕ_ПО_УМОЛЧАНИЮ ИСТИНА
    ПОЛЕ Организация ВЫБОР Организации      # Ссылка на запись из коллекции "Организации"
    ПОЛЕ Фотография ФАЙЛ
КОНЕЦ

1.4. Модификаторы полей

Модификатор	Назначение	Пример
ОБЯЗАТЕЛЬНОЕ	Поле нельзя оставить пустым при сохранении	ПОЛЕ Наименование СТРОКА ОБЯЗАТЕЛЬНОЕ
ЗНАЧЕНИЕ_ПО_УМОЛЧАНИЮ	Значение, если поле не заполнено	ПОЛЕ Статус СТРОКА ЗНАЧЕНИЕ_ПО_УМОЛЧАНИЮ "Новый"

1.5. Специальные возможности для полей

Автонумерация (только для ДОКУМЕНТ и КОЛЛЕКЦИЯ):

ДОКУМЕНТ ЗаказНаряд
    АВТОНУМЕРАЦИЯ "ЗН-{YYYY}-{0000}" ПОЛЕ Номер
    ПОЛЕ Номер СТРОКА   # Будет автоматически заполнено: ЗН-2024-0012
    ...
КОНЕЦ

Доступные макросы: {YYYY} (год), {MM} (месяц), {DD} (день), {0000} (порядковый номер с нулями).

1.6 Многострочное поле (textarea) ТЕКСТОВОЕ_ПОЛЕ

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

ДОКУМЕНТ ТаскСервис
    ПОЛЕ Наименование СТРОКА ОБЯЗАТЕЛЬНОЕ
    ПОЛЕ Дата ДАТАВРЕМЯ ЗНАЧЕНИЕ_ПО_УМОЛЧАНИЮ ТЕКУЩАЯ_ДАТА_ВРЕМЯ
    ТЕКСТОВОЕ_ПОЛЕ Таск СТРОКА ОБЯЗАТЕЛЬНОЕ
    ТАБЛИЧНАЯЧАСТЬ СписокТасков
        КОЛОНКА Исполнитель ВЫБОР Сотрудники ОБЯЗАТЕЛЬНОЕ
        # Для поддержки многострочного ввода
        ТЕКСТОВАЯ_КОЛОНКА Задача СТРОКА ОБЯЗАТЕЛЬНОЕ
        # Стандартная колонка для прикрепления картинок/файлов в таблицу:
        КОЛОНКА Картинка ФАЙЛ
        КОЛОНКА СтатусЗадачи СТРОКА ЗНАЧЕНИЕ_ПО_УМОЛЧАНИЮ "Новая"
        КОЛОНКА ДатаДедлайн ДАТАВРЕМЯ ЗНАЧЕНИЕ_ПО_УМОЛЧАНИЮ ТЕКУЩАЯ_ДАТА_ВРЕМЯ
    КОНЕЦ
    КНОПКА "Записать" ЗАПИСАТЬ
    КНОПКА "Отмена" ЗАКРЫТЬ
КОНЕЦ

КОНЕЦ1.7. Best Practices

• Именование коллекций и полей: Всегда используйте осмысленные имена на русском (так как платформа генерирует UI на основе этих названий). Избегайте пробелов — пишите слитно или используйте заглавные буквы: Сотрудники, ДатаПриема.
• Комментирование: Обязательно комментируйте сложную логику, особенно в блоках ЛОГИКА и ПРОЦЕДУРА. Комментарии сохраняются и помогают другим разработчикам.
• Порядок объявлений: Рекомендуемый порядок в файле (для читаемости):
  1. Роли и пользователи
  2. Настройки (КОЛЛЕКЦИЯ СистемныеКонстанты)
  3. Справочники (коллекции без ссылок на документы)
  4. Документы (могут ссылаться на справочники)
  5. Журналы
  6. Отчёты, API, процедуры, расписания
• Изменение структуры: Если добавили новое поле в существующую коллекцию — просто перезапустите платформу. ALTER TABLE выполнится автоматически. Удаление полей не поддерживается (лучше сделать поле скрытым или игнорировать).
• Резервное копирование: Перед любыми изменениями в DSL, особенно добавлением новых коллекций или документов, обязательно сделайте бэкап файла базы данных (erp.db в папке платформы). При ошибке в синтаксисе платформа не стартует, но база не повреждается.