# Проектное именование ## Связь с общими правилами именования Проектное именование дополняет общие правила именования GlobalFramework и применяется только к объектам, которые создаются в рамках проектной разработки. Общие правила именования базовых и прикладных сущностей описаны в общей документации по разработке GlobalFramework. Настоящая страница не заменяет эти правила и не описывает именование типовых объектов. Здесь фиксируются только проектные правила: - как выбирать проектный префикс; - как именовать проектные классы, атрибуты, характеристики, выборки, печатные формы и JEXL-скрипты; - как именовать коды проектных записей в справочниках, настройках и характеристиках; - как применять суффикс `_z` для проектных атрибутов; - как отделять проектные объекты и записи от типовой поставки; - как снижать риск конфликта с будущими объектами, атрибутами и значениями Global ERP. Если правило проектного именования не уточняет отдельный случай, применяется общее правило именования GlobalFramework. ## Проектный префикс Для проектных объектов используется проектный префикс. Он в обязательном порядке начинается с `Z`. В документе в качестве условного примера используется префикс `Zprj`. На реальном проекте вместо него закрепляется префикс, отражающий проект, заказчика или проектную область. Например, могут использоваться значения `Zsng`, `Zpha` или другие согласованные префиксы. Проектный префикс должен: - быть уникальным внутри системы; - не совпадать с префиксами типовых модулей; - быть коротким и понятным; - использоваться одинаково во всех проектных объектах в рамках выбранного правила именования; - фиксироваться в проектной документации до начала разработки. Проектный префикс используется не вместо общих правил именования, а как дополнительный признак проектного объекта. ## Именование проектных модулей Проектные модули именуются по общим правилам именования модулей и должны содержать проектный признак. Рекомендуемый шаблон: ```text z ``` Примеры: ```text zprjbs zprjstk zprjrpt ``` Где: - `z` — признак проектного модуля; - `prj` — код проекта; - `bs`, `stk`, `rpt` — функциональная область или базовый модуль, к которому относится проектная разработка. В именах классов и файлов тот же модульный префикс пишется с заглавной `Z`, а обозначение функциональной области или базового модуля внутри префикса сохраняется в нижнем регистре: `Zprjbs`, `Zprjstk`, `Zprjrpt`. ## Именование проектных классов Проектные классы именуются по общему шаблону именования классов GlobalFramework. Проектность класса отражается через имя проектного модуля или закрепленный проектный префикс. Рекомендуемый шаблон: ```text Z_ ``` Примеры: ```text Zprjbs_ContractExt Zprjstk_WarrantControl Zprjrpt_ReportRequest ``` Имя класса должно быть в единственном числе и отражать сущность, а не действие. Не рекомендуется использовать имена вида: ```text Zprjbs_NewClass Zprjbs_TestTable Zprjbs_TempData ``` Для временных, служебных и промежуточных объектов назначение должно быть явно отражено в имени: ```text Zprjbs_ImportBuffer Zprjbs_LoadSession Zprjbs_CalcResult ``` Если в проекте используется отдельная аббревиатура логического пакета, она указывается после символа `_` по общим правилам именования классов. ## Именование проектных коллекций Коллекции именуются по общим правилам именования классов. В имени должно быть понятно, что коллекция относится к мастер-классу или к конкретной проектной связи. Примеры: ```text Zprjbs_ContractExtDet Zprjstk_WarrantControlDet Zprjbs_ContractExtApproverDet ``` Если коллекций у одного мастер-класса несколько, в имени должно быть функциональное уточнение. ## Именование проектных атрибутов Проектные атрибуты именуются по общему шаблону именования атрибутов GlobalFramework: ```text _z ``` Где: - `` — префикс типа данных по общим правилам именования; - `` — смысловое имя атрибута; - `_z` — суффикс проектного атрибута. Суффикс `_z` используется для всех проектных атрибутов независимо от способа их добавления: - для атрибутов новых проектных классов; - для атрибутов, добавляемых в расширяемые или переопределяемые классы; - для объектных характеристик; - для универсальных характеристик; - для атрибутов, используемых в проектных JSON-структурах. Такое правило позволяет отличать проектные атрибуты от типовых атрибутов Global ERP и снижает риск конфликта с будущими атрибутами типовой поставки. Суффикс `_dz` зарезервирован для системных атрибутов и не должен использоваться в проектных атрибутах. Префикс типа данных выбирается по общим правилам именования атрибутов и переменных GlobalFramework. Примеры проектных атрибутов: ```text sComment_z nAmount_z dStart_z bConfirmed_z idContract_z jParams_z ``` Если поле содержит дату, не нужно дублировать слово `Date` в имени: ```text dStart_z // правильно dDateStart_z // не рекомендуется ``` Если атрибут является ссылкой на объект, имя должно отражать целевой объект: ```text idContract_z idPerson_z idWarehouse_z ``` ## Именование проектных характеристик Для проектных объектных и универсальных характеристик используется тот же принцип именования, что и для проектных атрибутов: ```text _z ``` Примеры: ```text sComment_z nLimit_z dValidFrom_z idPenalty_z jExtraParams_z ``` Для универсальных характеристик префикс `UC_` вручную не добавляется. Система добавляет его автоматически там, где это предусмотрено механизмом. ## Именование кодов проектных записей Если проектная запись создается в справочнике, настройке, характеристике или другой сущности, где используется системный код, мнемокод или аналогичный уникальный идентификатор, код проектной записи должен содержать проектный префикс. Это правило применяется к записям, которые могут находиться в одном наборе данных вместе с типовыми записями Global ERP. Проектный префикс позволяет отличить проектные записи от типовых и снижает риск конфликта с будущими значениями типовой поставки. Рекомендуемый шаблон: ```text _ ``` Примеры: ```text ZPRJ_DRIVER_LICENSE ZSNG_SPECIAL_DOC ZPHA_EXTERNAL_CONTRACT ``` Где: - `` — проектный префикс, закрепленный на проекте; - `` — функциональный код записи. Не рекомендуется использовать для проектных записей свободные числовые коды без проектного признака: ```text 2 3 4 ``` Такие коды могут пересечься с типовыми значениями, которые появятся в будущих версиях поставки. Если кодовое поле допускает только числовые значения, для проектных записей должен быть заранее выделен отдельный диапазон кодов. Диапазон фиксируется в проектной документации до начала заполнения справочника или настройки. ## Именование проектных выборок и отображений Проектные выборки именуются по общим правилам именования выборок GlobalFramework. Проектность выборки отражается через имя проектного модуля или закрепленный проектный префикс. Примеры: ```text Zprjbs_ContractExtAvi Zprjstk_WarrantControlAvi ``` Отображения именуются по общим правилам именования отображений. Имя отображения должно отражать его назначение или контекст использования. Примеры: ```text List Card List_idContract Card_Approval ``` Если отображение проектно переопределяет или дополняет типовой сценарий, в имени или описании должно быть понятно, для какого проектного сценария оно создано. ## Именование Api, Avi, Pkg и Lib Файлы прикладной логики именуются по общим правилам именования соответствующих сущностей GlobalFramework. Проектность файла отражается через имя проектного класса, проектного пакета или проектного модуля. Примеры: | Объект | Пример | |---|---| | Api | `Zprjbs_ContractExtApi.scala` | | Avi | `Zprjbs_ContractExtAvi.scala` | | Pkg | `Zprjbs_ContractExtPkg.scala` | | Lib | `Zprjbs_ContractExtLib.scala` | ## Именование наследующих файлов и проектных переопределений В проектной разработке различаются два подхода: наследование базовой логики и проектное переопределение. Для них применяются разные правила именования. ### Наследование базовой логики Наследование базовой логики используется, когда требуется дополнить типовую логику и применять наследующий класс локально, в отдельных проектных сценариях. В этом случае базовая логика не заменяется во всех местах системы. Наследующий файл именуется по шаблону: ```text <Имя проектного модуля переопределений>_<Имя базового класса без имени базового модуля> ``` Примеры: ```text Rpl_QueryAvi -> Zprjrpl_QueryAvi Bs_ContractsApi -> Zprjbs_ContractsApi ``` В имени наследующего файла используется имя проектного модуля переопределений и имя базового класса без префикса базового модуля. Например, для `Rpl_QueryAvi` имя наследующего файла формируется как `<Имя проектного модуля переопределений>_QueryAvi`. ### Проектное переопределение Проектное переопределение используется, когда требуется изменить поведение типовой логики в местах ее использования. В этом случае имя переопределяющего файла должно строго соответствовать имени базового объекта. Для проектного переопределения используется обязательный шаблон: ```text <Имя базового класса с именем базового модуля>Override ``` Где `Postfix` — тип переопределяемого объекта: `Api`, `Avi`, `Pkg` или `Lib`. Примеры: ```text Bs_GoodsApi -> Bs_GoodsOverrideApi Bs_GoodsAvi -> Bs_GoodsOverrideAvi ``` При именовании проектного переопределения имя текущего проектного модуля в имя класса не добавляется. В имя файла добавляется только суффикс `Override`, чтобы явно показать, что файл переопределяет типовую логику, а не является новым самостоятельным проектным объектом. Для проектных переопределений не допускается использовать произвольные варианты именования, например добавлять проектный префикс перед именем базового класса или менять порядок частей имени. Строгий нейминг нужен для однозначной связи переопределения с типовым объектом. Подробнее о механизме проектных переопределений см. в разделе [Проектные переопределения](https://help.globalerp.ru/books/GlobalServerAppGuide/SNAPSHOT/html/090_appendix/how_to/030_%D0%BF%D1%80%D0%BE%D0%B5%D0%BA%D1%82%D0%BD%D1%8B%D0%B5_%D0%BF%D0%B5%D1%80%D0%B5%D0%BE%D0%BF%D1%80%D0%B5%D0%B4%D0%B5%D0%BB%D0%B5%D0%BD%D0%B8%D1%8F.html). ## Именование проектных печатных форм Печатные формы именуются так, чтобы по системному имени было понятно, что форма относится к проектной поставке. Рекомендуемый шаблон: ```text __ ``` Примеры: ```text ZPRJ_BS_ContractAgreement ZPRJ_STK_WarrantAct ZPRJ_RPT_ReconciliationReport ``` Файл шаблона должен иметь то же функциональное имя и расширение используемого типа шаблона: ```text ZPRJ_BS_ContractAgreement.docx ZPRJ_STK_WarrantAct.xlsx ZPRJ_RPT_ReconciliationReport.jrxml ``` В наименовании печатной формы для пользователя не нужно указывать технический проектный префикс, если это не требуется регламентом проекта. ## Именование проектных JEXL-скриптов JEXL-скрипты именуются так, чтобы было понятно место применения и назначение скрипта. Рекомендуемый шаблон: ```text __.jexl ``` Примеры: ```text ZPRJ_State_CheckBeforeApprove.jexl ZPRJ_Print_FilterContractReport.jexl ZPRJ_Attr_DefaultPaymentDate.jexl ``` ## Именование универсальных справочников и интеграционных настроек Универсальные справочники и проектные интеграционные настройки именуются по проектному правилу, принятому для конкретного проекта или функционального направления. Рекомендуемый шаблон: ```text [issueNumber]_ ``` Где: - `DIRECTION` — функциональное направление или область; - `issueNumber` — номер задачи, если объект создается под конкретную доработку; - `FunctionalName` — функциональное имя в CamelCase. Примеры: ```text NSI001_FlatReference BS_CommonProperties INT025_MesData ``` Если объект используется несколькими доработками, номер задачи можно не указывать.