Коды сущностей (блоки, компоненты, свойства) — латиница, единственное число, без пробелов/кириллицы; для компонентов — префикс sf.link

В SIMAI Framework 4 (SF4) “код” почти всегда становится частью технического идентификатора: имени папки, ключа в конфиге, параметра в API, либо участка URL/пути. Поэтому базовая цель конвенции — сделать коды предсказуемыми и переносимыми: один и тот же код одинаково читается в конфиге, в коде и в структуре каталогов.

Для компонентов SF4 закреплён префикс sf. в названии компонента (в вызове Bitrix это выглядит как simai:sf.*). Такая форма хорошо масштабируется: сразу видно принадлежность к SF4 и “семейство” компонентов, а в коде и шаблонах не приходится гадать, что является системным, а что — проектным.

Пара коротких примеров “как это выглядит вживую”:

<?php

declare(strict_types=1);

// Примеры имён компонентов (как они используются в Bitrix):
// simai:sf.wizard
// simai:sf.wizard.stage

<?php

declare(strict_types=1);

// Пример кода области (по сути — путь внутри area/):
// sidebar/right

Путь/файлы — без пробелов/кириллицы; использовать нижнее подчеркивание при необходимостиlink

С файлами и каталогами лучше сразу договориться о “чистом” формате, потому что эти пути участвуют в автоматическом поиске областей, шаблонов и ресурсов. Пробелы и кириллица в путях почти всегда ухудшают переносимость: сложнее писать, сложнее URL-кодировать, проще ошибиться при копировании, а некоторые инструменты/скрипты начинают вести себя нестабильно.

Если нужно визуально разделять части имени файла — используйте подчёркивание (_) или дефис (-), но последовательно в рамках проекта. Главное — чтобы итоговый путь был однозначным и “набираемым”.

Показательный пример проектной области в simai.data (структура “папка области → template.php”):

/ru/simai.data/template/area/sidebar/right/template.php

Коды использовать в конфигурациях и API (не ID) — правила см. file-functional.mdlink

Практический смысл правила простой: ID зависят от окружения, а коды — это “имена”, которые вы контролируете и которые легче переносить между стендами, копиями сайта и разными проектами.

В SF4 этот подход хорошо виден на примере кеширования инфоблоков: подсистема SIMAI\Main\Configuration\Iblock хранит соответствие CODE → ID в сессии и при необходимости умеет найти ID по коду. То есть “код” выступает как первичный ключ для обращения в прикладном коде, а ID — как техническая деталь выполнения.

Пример использования (когда вам нужен ID инфоблока, но вы хотите опираться на код):

<?php

declare(strict_types=1);

use SIMAI\Main\Configuration\Iblock;

$iblockId = Iblock::getValue('catalog'); // 'catalog' — код инфоблока

if ($iblockId === null)
{
    // обработайте ситуацию: инфоблок с таким кодом не найден
}

Та же логика “код важнее ID” обычно применяется и к другим сущностям: свойствам, пользовательским полям, конфигам, блокам/вьюхам — везде, где вам важно, чтобы конфигурация “переживала” перенос и не требовала ручного перепривязывания после импорта/копирования.