Раскладка репозитория

Файл про устройство репозитория. Опорные точки модуля — в CLAUDE.md, процесс — в CONTRIBUTING.md, сборка — в build-and-install.md.

В статье:

Файл про устройство репозитория. Опорные точки модуля — в CLAUDE.md, процесс — в CONTRIBUTING.md, сборка — в build-and-install.md.

Модуль лежит в корне, и это вынужденно

Composer разворачивает в целевой каталог корень пакета целиком и подкаталоги выбирать не умеет. Поэтому lib/, install/, lang/ лежат прямо в корне репозитория, рядом с build.sh и .github/.

Плата за это — два списка в шапке build.sh:

  • SHIP — уезжает на портал и в Composer-пакет;
  • KEEP — остаётся в репозитории.

Файл, не попавший ни в один список, роняет сборку. Тот же список продублирован в .gitattributes через export-ignore; списки обязаны совпадать, сверяется автоматически, см. check_gitattributes.

Что где лежит

путьчто это
install/index.phpSHIPустановщик, класс shef_problems extends CModule
install/version.phpSHIPVERSION и VERSION_DATE — источник истины о версии
install/js/shef-problems/SHIPстили вывода PrHtml; установщик раскладывает их в /bitrix/js
admin/menu.phpSHIPменю «Учёт проблем»; ядро подключает его само, из каталога модуля
admin/logs.phpSHIPстраница просмотра логов; открывается заглушкой /bitrix/admin/shef_problems_logs.php, которую пишет установщик (Main\AdminPage)
.settings.phpSHIPзависимости, события, раскладка, сервисы-логгеры, откуда брать Monolog
include.phpSHIPточка входа: def-functions.php, потом autoload.php — порядок важен
autoload.phpSHIPподключает shef.options и регистрирует Monolog
def-functions.phpSHIP_pr(), _log(), _log1()
default_option.phpSHIPумолчания настроек
options.php, options_conf.phpSHIPстраница настроек на ShOptionsConfig из shef.options
lib/SHIPклассы модуля, имена файлов строго строчными
lang/ru/SHIPязыковые файлы, зеркалят структуру lib/
vendor/monolog/monolog/SHIPсвоя копия Monolog для установки архивом
README.md, CHANGELOG.md, LICENSESHIP
composer.jsonSHIPманифест пакета bxshef/problems
docs/KEEPвся документация, пример настроек logrotate
build.shKEEPсборка и проверки
tests/KEEPтесты и заглушки ядра
examples/KEEPзапускаемые примеры
.claude/skills/KEEPнавыки агента — копия из bx-shef/options, раскладывает sync.sh
.github/KEEPCI и релиз
CONTRIBUTING.md, CLAUDE.mdKEEPпроцесс и памятка агенту
.gitattributes, .gitignoreKEEP
.php-cs-fixer.dist.phpKEEPправила линтера, @PSR12
composer.lockKEEPдержит зависимости линтера; пакету не нужен — Composer читает lock только у корневого проекта
vendor-dev/—инструменты разработчика из composer install, в .gitignore

Нижний регистр в lib/ обязателен

Bitrix\Main\Loader отображает класс в путь строчными, разбирая первые два сегмента namespace как id модуля: Shef\Problems\Main\Utils ищется как bitrix/modules/shef.problems/lib/main/utils.php. Поэтому свой namespace в registerNamespace не нужен — там только Monolog. Отсюда же и трейты в lib/factory/trait/: сегмент Trait в namespace PHP 8 принимает.

На macOS заглавная буква сходит с рук, на боевом Linux класс просто не найдётся. Проверяется в build.sh, check_lowercase, и в tests/autoload_test.php.

У vendor/ соглашение своё — PSR-4 с заглавными, путь задаёт .settings.php.

Фронт

install/js/shef-problems/monolog-pr-html/        -> /bitrix/js/shef-problems/monolog-pr-html/
install/js/shef-problems/monolog-pr-html-admin/  -> /bitrix/js/shef-problems/monolog-pr-html-admin/

Каталог модуля браузеру недоступен, поэтому стили копирует установщик — карта в .settings.php, ключ installDir. Расширения находятся ядром по имени shef-problems.monolog-pr-html: каталог через дефис — требование имён расширений. Имена живут в одном месте, Constants::EXTENSION_PR_HTML и EXTENSION_PR_HTML_ADMIN; сходимость с раскладкой проверяет tests/assets_test.php.

style.min.css рядом со style.css — минифицированная копия, её ядро берёт при включённой оптимизации css. Правите стиль — пересоберите и её. *.min.min.* — мусор сборщиков, его отсекает .gitignore.

Документация не едет на портал

Документация живёт в репозитории. В поставке остаётся только README.md — как readme пакета, — и все ссылки из него ведут на GitHub. Скриншоты, которые до 2.0.0 раскладывались в /bitrix/images/shef.problems, ушли вместе с документацией; каталог на обновлённых порталах убирает деинсталляция.

Источник: problems/docs/module-structure.md — правки туда, сайт пересобирается сам.
CtrlI