# Общие положения

## Назначение раздела

Раздел описывает правила проектирования и разработки проектных расширений Global ERP.

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

Основная цель раздела — задать единые правила, по которым проектные команды добавляют новые сущности, атрибуты, выборки, печатные формы, JEXL-скрипты, серверную логику и настройки. Эти правила должны снижать риск конфликтов с типовой поставкой и будущими обновлениями Global ERP.

Раздел отвечает на практические вопросы проектного разработчика:

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

## Область применения

Раздел применяется при разработке и сопровождении проектных расширений Global ERP.

Раздел обязателен для:

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

Раздел рекомендуется для ознакомления:

- функциональным консультантам;
- аналитикам;
- администраторам системы;
- специалистам сопровождения.

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

## Связанные разделы документации

Настоящий раздел не дублирует общую документацию по разработке, именованию сущностей, Git, релизам, SQL и оптимизации кода.

При выполнении проектной разработки дополнительно используются следующие разделы документации:

- `Организация разработки` — структура проекта, `project.yaml`, работа с модулями, релизы, миграционные пакеты, Git и рабочее место разработчика;
- `Оптимизация работы системы` — ревью Scala-кода, оптимизация Scala-кода, работа с данными и кэшем, ревью SQL-запросов, оптимизация SQL-запросов;
- `JEXL-скрипты в Global ERP` — правила написания и применения JEXL-скриптов;
- справочные разделы по классам, выборкам, типам объектов, печатным формам и универсальному фильтру.

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

## Основные термины

**Типовая поставка** — стандартные модули, классы, выборки, пакеты, настройки и другие объекты Global ERP, поставляемые в составе продукта.

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

**Модификация** — изменение типового компонента Global ERP. Модификация выполняется только по согласованному решению и должна попадать в поставку продукта или отдельный согласованный комплект обновления.

**Конфигурационное расширение** — изменение поведения системы через настройки, не требующее изменения программного кода. Например, настройка типа объекта, объектных характеристик, печатных форм, переходов состояний, JEXL-скриптов или правил проверки.

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

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

**Проектный префикс** — буквенный идентификатор проекта или заказчика, используемый в системных именах проектных модулей и объектов.

**Проектный атрибут** — атрибут, характеристика или поле, добавленное проектной командой и не входящее в типовую поставку Global ERP.

## Общие принципы проектной разработки

### Приоритет стандартной функциональности

Проектная разработка выполняется только после проверки, что требование невозможно или нецелесообразно реализовать стандартными средствами Global ERP.

Перед началом разработки необходимо проверить:

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

Если требование закрывается настройкой, разработка в коде не выполняется.

### Разделение типовой и проектной части

Проектные изменения должны быть отделены от типовой поставки.

Проектная команда не должна изменять типовые файлы, типовые ODM/ORM-разметки, типовые DataInstall-скрипты и типовые настройки напрямую, если для этого нет отдельного согласованного решения.

Для проектной разработки используются:

- проектные модули;
- проектные классы;
- проектные выборки и отображения;
- проектные пакеты, библиотеки, Api и Avi;
- проектные печатные формы;
- проектные JEXL-скрипты;
- объектные и универсальные характеристики;
- проектные настройки типов объектов;
- точки расширения;
- проектные переопределения.

### Сохраняемость при обновлениях

Проектные расширения должны сохраняться при обновлении версии Global ERP.

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

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

Если обновление затрагивает используемую проектную логику, необходимо выполнить регрессионное тестирование соответствующих бизнес-процессов.